@taloswork/ose-shared 0.1.8 → 0.1.10

package/skills/document/bin/pdf-render.cjs

@@ -47,20 +47,22 @@ function die(msg, code = 1) {
   process.exit(code);
 }
 function parsePages(spec) {
-  const m = /^(\d+)(?:-(\d+))?$/.exec(spec.trim());
-  if (!m) die(`bad page spec: ${spec} (use N or N-M)`, 64);
-  const from = Number(m[1]);
-  const to = m[2] ? Number(m[2]) : from;
-  if (from < 1 || to < from) die(`bad page range: ${spec}`, 64);
-  const pages = [];
-  for (let p = from; p <= to; p++) pages.push(p);
-  return pages;
+  const pages = /* @__PURE__ */ new Set();
+  for (const part of spec.split(",")) {
+    const m = /^(\d+)(?:-(\d+))?$/.exec(part.trim());
+    if (!m) die(`bad page spec: ${spec} (use N, N-M or a list like 3,7-8)`, 64);
+    const from = Number(m[1]);
+    const to = m[2] ? Number(m[2]) : from;
+    if (from < 1 || to < from) die(`bad page range: ${part.trim()}`, 64);
+    for (let p = from; p <= to; p++) pages.add(p);
+  }
+  return [...pages].sort((a, b) => a - b);
 }
 async function main() {
   const file = process.argv[2];
   const spec = process.argv[3];
   const scaleArg = process.argv[4];
-  if (!file || !spec) die("usage: pdf-render <file.pdf> <pages|all> [scale]", 64);
+  if (!file || !spec) die("usage: pdf-render <file.pdf> <pages|all> [scale]  (pages: N | N-M | 3,7-8)", 64);
   let scale = 2;
   if (scaleArg !== void 0) {
     scale = Number(scaleArg);

package/skills/document/bin/pptx-clone.cjs

@@ -9855,14 +9855,14 @@ function unescXml(s) {
         return "'";
       default: {
         const n = code.startsWith("#x") || code.startsWith("#X") ? parseInt(code.slice(2), 16) : parseInt(code.slice(1), 10);
-        return Number.isFinite(n) ? String.fromCodePoint(n) : whole;
+        return Number.isInteger(n) && n >= 0 && n <= 1114111 ? String.fromCodePoint(n) : whole;
       }
     }
   });
 }
-function visualWidth(text3) {
+function visualWidth(text) {
   let w = 0;
-  for (const ch of text3) {
+  for (const ch of text) {
     const cp = ch.codePointAt(0);
     if (ch === " " || ch === "	")
       w += 0.35;
@@ -9891,9 +9891,9 @@ function replaceTextAcrossRuns(xml, find, replacement, opts) {
     const segs = [];
     let flat = "";
     for (const m of para.matchAll(textRe)) {
-      const text3 = unescXml(m[2]);
-      segs.push({ el: m[0], attrs: m[1] ?? "", text: text3, start: flat.length });
-      flat += text3;
+      const text = unescXml(m[2]);
+      segs.push({ el: m[0], attrs: m[1] ?? "", text, start: flat.length });
+      flat += text;
     }
     if (!flat.includes(find))
       return para;
@@ -9936,28 +9936,30 @@ function replaceTextAcrossRuns(xml, find, replacement, opts) {
   return { xml: rewritten, count };
 }
 
-// packages/core/dist/document/pptx-register-slide.js
-var SLIDE_CT = "application/vnd.openxmlformats-officedocument.presentationml.slide+xml";
-var SLIDE_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide";
-async function text(zip, path) {
+// packages/core/dist/document/pptx-parts.js
+async function readPptxPart(zip, path) {
   const f = zip.file(path);
   if (!f)
     throw new Error(`not a PowerPoint file (${path} missing)`);
   return f.async("string");
 }
+
+// packages/core/dist/document/pptx-register-slide.js
+var SLIDE_CT = "application/vnd.openxmlformats-officedocument.presentationml.slide+xml";
+var SLIDE_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide";
 async function registerSlidePart(zip, newNum, newXmlPath) {
   const ctPath = "[Content_Types].xml";
-  const ct = await text(zip, ctPath);
+  const ct = await readPptxPart(zip, ctPath);
   if (!ct.includes(`PartName="/${newXmlPath}"`)) {
     zip.file(ctPath, ct.replace("</Types>", `<Override PartName="/${newXmlPath}" ContentType="${SLIDE_CT}"/></Types>`));
   }
   const presRelsPath = "ppt/_rels/presentation.xml.rels";
-  const presRels = await text(zip, presRelsPath);
+  const presRels = await readPptxPart(zip, presRelsPath);
   const maxRid = Math.max(0, ...[...presRels.matchAll(/Id="rId(\d+)"/g)].map((m) => Number(m[1])));
   const newRid = `rId${maxRid + 1}`;
   zip.file(presRelsPath, presRels.replace("</Relationships>", `<Relationship Id="${newRid}" Type="${SLIDE_REL_TYPE}" Target="slides/slide${newNum}.xml"/></Relationships>`));
   const presPath = "ppt/presentation.xml";
-  const pres = await text(zip, presPath);
+  const pres = await readPptxPart(zip, presPath);
   const maxSldId = Math.max(255, ...[...pres.matchAll(/<p:sldId id="(\d+)"/g)].map((m) => Number(m[1])));
   const updated = pres.replace("</p:sldIdLst>", `<p:sldId id="${maxSldId + 1}" r:id="${newRid}"/></p:sldIdLst>`);
   if (updated === pres)
@@ -9998,12 +10000,6 @@ function capacityWarning(slideXml, token, value) {
     return void 0;
   return `${token}: replacement is ~${Math.ceil(width)} width-units, slot fits ~${Math.floor(capacity)} (${Math.round(widthPt)}\xD7${Math.round(heightPt)}pt box @ ${fontPt}pt) \u2014 likely overflow. Shorten the wording; do NOT shrink the font to make it fit.`;
 }
-async function text2(zip, path) {
-  const f = zip.file(path);
-  if (!f)
-    throw new Error(`not a PowerPoint file (${path} missing)`);
-  return f.async("string");
-}
 async function clonePptxSlide(bytes, slideNumber, replacements = {}) {
   if (!Number.isInteger(slideNumber) || slideNumber < 1) {
     throw new Error(`slide number must be a positive integer, got ${slideNumber}`);
@@ -10023,7 +10019,7 @@ async function clonePptxSlide(bytes, slideNumber, replacements = {}) {
   const newNum = Math.max(...slideNums) + 1;
   const srcXmlPath = `ppt/slides/slide${slideNumber}.xml`;
   const newXmlPath = `ppt/slides/slide${newNum}.xml`;
-  let slideXml = await text2(zip, srcXmlPath);
+  let slideXml = await readPptxPart(zip, srcXmlPath);
   const replaced = [];
   const missing = [];
   const warnings = [];
@@ -10076,7 +10072,7 @@ async function removePptxSlide(bytes, slideNumber) {
   const xmlPath = `ppt/slides/slide${slideNumber}.xml`;
   const relsPath = `ppt/slides/_rels/slide${slideNumber}.xml.rels`;
   const presRelsPath = "ppt/_rels/presentation.xml.rels";
-  const presRels = await text2(zip, presRelsPath);
+  const presRels = await readPptxPart(zip, presRelsPath);
   const targetRe = new RegExp(`Target="(/ppt/)?slides/slide${slideNumber}\\.xml"`);
   const relMatch = findElement(presRels, "Relationship", (r) => r.includes(SLIDE_REL_TYPE) && targetRe.test(r));
   if (!relMatch)
@@ -10086,19 +10082,19 @@ async function removePptxSlide(bytes, slideNumber) {
     throw new Error(`slide ${slideNumber}'s relationship carries no Id (corrupt deck?)`);
   zip.file(presRelsPath, presRels.replace(relMatch, ""));
   const presPath = "ppt/presentation.xml";
-  const pres = await text2(zip, presPath);
+  const pres = await readPptxPart(zip, presPath);
   const sld = removeElement(pres, "p:sldId", (el) => el.includes(`r:id="${rId}"`));
   if (!sld.removed)
     throw new Error(`slide ${slideNumber} (${rId}) not found in the slide list (corrupt deck?)`);
   zip.file(presPath, sld.xml);
-  const slideRels = zip.file(relsPath) ? await text2(zip, relsPath) : "";
+  const slideRels = zip.file(relsPath) ? await readPptxPart(zip, relsPath) : "";
   const notesTarget = /<Relationship\b[^>]*Type="[^"]*\/notesSlide"[^>]*Target="\.\.\/(notesSlides\/notesSlide\d+\.xml)"/.exec(slideRels)?.[1];
   const removedParts = [xmlPath, relsPath];
   if (notesTarget) {
     const otherSlideRels = Object.keys(zip.files).filter((p) => /^ppt\/slides\/_rels\/slide\d+\.xml\.rels$/.test(p) && p !== relsPath);
     let shared = false;
     for (const p of otherSlideRels) {
-      if ((await text2(zip, p)).includes(notesTarget)) {
+      if ((await readPptxPart(zip, p)).includes(notesTarget)) {
         shared = true;
         break;
       }
@@ -10106,7 +10102,7 @@ async function removePptxSlide(bytes, slideNumber) {
     if (!shared)
       removedParts.push(`ppt/${notesTarget}`, `ppt/notesSlides/_rels/${notesTarget.split("/")[1]}.rels`);
   }
-  let ct = await text2(zip, "[Content_Types].xml");
+  let ct = await readPptxPart(zip, "[Content_Types].xml");
   for (const part of removedParts) {
     zip.remove(part);
     ct = removeElement(ct, "Override", (el) => el.includes(`PartName="/${part}"`)).xml;

package/skills/document/bin/pptx-embed-fonts.cjs

@@ -9826,14 +9826,16 @@ function escXml(s) {
   return s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;" })[c]);
 }
 
-// packages/core/dist/document/pptx-fonts.js
-var FONT_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/font";
-async function text(zip, path) {
+// packages/core/dist/document/pptx-parts.js
+async function readPptxPart(zip, path) {
   const f = zip.file(path);
   if (!f)
     throw new Error(`not a PowerPoint file (${path} missing)`);
   return f.async("string");
 }
+
+// packages/core/dist/document/pptx-fonts.js
+var FONT_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/font";
 async function embedFonts(bytes, fonts) {
   if (!fonts.length)
     return bytes;
@@ -9843,13 +9845,13 @@ async function embedFonts(bytes, fonts) {
   } catch (e) {
     throw new Error(`not a readable .pptx: ${e.message}`);
   }
-  let ct = await text(zip, "[Content_Types].xml");
+  let ct = await readPptxPart(zip, "[Content_Types].xml");
   if (!ct.includes('Extension="fntdata"')) {
     ct = ct.replace("</Types>", `<Default Extension="fntdata" ContentType="application/x-fontdata"/></Types>`);
     zip.file("[Content_Types].xml", ct);
   }
   const relsPath = "ppt/_rels/presentation.xml.rels";
-  let rels = await text(zip, relsPath);
+  let rels = await readPptxPart(zip, relsPath);
   let rid = Math.max(0, ...[...rels.matchAll(/Id="rId(\d+)"/g)].map((m) => Number(m[1])));
   let fontNo = Object.keys(zip.files).filter((p) => /^ppt\/fonts\/font\d+\.fntdata$/.test(p)).length;
   const byFace = /* @__PURE__ */ new Map();
@@ -9875,7 +9877,7 @@ async function embedFonts(bytes, fonts) {
   }
   zip.file(relsPath, rels);
   const presPath = "ppt/presentation.xml";
-  let pres = await text(zip, presPath);
+  let pres = await readPptxPart(zip, presPath);
   if (!/<p:presentation\b[^>]*\bembedTrueTypeFonts=/.test(pres)) {
     pres = pres.replace(/<p:presentation\b/, '<p:presentation embedTrueTypeFonts="1"');
   }

package/skills/document/bin/pptx-slide.cjs

@@ -9821,28 +9821,30 @@ var import_promises = require("node:fs/promises");
 // packages/core/dist/document/pptx-slide.js
 var import_jszip = __toESM(require_lib3(), 1);
 
-// packages/core/dist/document/pptx-register-slide.js
-var SLIDE_CT = "application/vnd.openxmlformats-officedocument.presentationml.slide+xml";
-var SLIDE_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide";
-async function text(zip, path) {
+// packages/core/dist/document/pptx-parts.js
+async function readPptxPart(zip, path) {
   const f = zip.file(path);
   if (!f)
     throw new Error(`not a PowerPoint file (${path} missing)`);
   return f.async("string");
 }
+
+// packages/core/dist/document/pptx-register-slide.js
+var SLIDE_CT = "application/vnd.openxmlformats-officedocument.presentationml.slide+xml";
+var SLIDE_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide";
 async function registerSlidePart(zip, newNum, newXmlPath) {
   const ctPath = "[Content_Types].xml";
-  const ct = await text(zip, ctPath);
+  const ct = await readPptxPart(zip, ctPath);
   if (!ct.includes(`PartName="/${newXmlPath}"`)) {
     zip.file(ctPath, ct.replace("</Types>", `<Override PartName="/${newXmlPath}" ContentType="${SLIDE_CT}"/></Types>`));
   }
   const presRelsPath = "ppt/_rels/presentation.xml.rels";
-  const presRels = await text(zip, presRelsPath);
+  const presRels = await readPptxPart(zip, presRelsPath);
   const maxRid = Math.max(0, ...[...presRels.matchAll(/Id="rId(\d+)"/g)].map((m) => Number(m[1])));
   const newRid = `rId${maxRid + 1}`;
   zip.file(presRelsPath, presRels.replace("</Relationships>", `<Relationship Id="${newRid}" Type="${SLIDE_REL_TYPE}" Target="slides/slide${newNum}.xml"/></Relationships>`));
   const presPath = "ppt/presentation.xml";
-  const pres = await text(zip, presPath);
+  const pres = await readPptxPart(zip, presPath);
   const maxSldId = Math.max(255, ...[...pres.matchAll(/<p:sldId id="(\d+)"/g)].map((m) => Number(m[1])));
   const updated = pres.replace("</p:sldIdLst>", `<p:sldId id="${maxSldId + 1}" r:id="${newRid}"/></p:sldIdLst>`);
   if (updated === pres)
@@ -9853,12 +9855,6 @@ async function registerSlidePart(zip, newNum, newXmlPath) {
 // packages/core/dist/document/pptx-slide.js
 var LAYOUT_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideLayout";
 var BLANK_SLIDE_XML = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n<p:sld xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main"><p:cSld><p:spTree><p:nvGrpSpPr><p:cNvPr id="1" name=""/><p:cNvGrpSpPr/><p:nvPr/></p:nvGrpSpPr><p:grpSpPr/></p:spTree></p:cSld><p:clrMapOvr><a:masterClrMapping/></p:clrMapOvr></p:sld>';
-async function text2(zip, path) {
-  const f = zip.file(path);
-  if (!f)
-    throw new Error(`not a PowerPoint file (${path} missing)`);
-  return f.async("string");
-}
 async function load(bytes) {
   try {
     return await import_jszip.default.loadAsync(Buffer.from(bytes));
@@ -9908,7 +9904,7 @@ async function addBlankSlide(bytes, opts = {}) {
 async function reorderPptxSlides(bytes, order) {
   const zip = await load(bytes);
   const presPath = "ppt/presentation.xml";
-  const pres = await text2(zip, presPath);
+  const pres = await readPptxPart(zip, presPath);
   const listMatch = /(<p:sldIdLst\b[^>]*>)([\s\S]*?)(<\/p:sldIdLst>)/.exec(pres);
   if (!listMatch)
     throw new Error("no <p:sldIdLst> in presentation.xml (corrupt deck?)");
@@ -9974,14 +9970,14 @@ function unescXml(s) {
         return "'";
       default: {
         const n = code.startsWith("#x") || code.startsWith("#X") ? parseInt(code.slice(2), 16) : parseInt(code.slice(1), 10);
-        return Number.isFinite(n) ? String.fromCodePoint(n) : whole;
+        return Number.isInteger(n) && n >= 0 && n <= 1114111 ? String.fromCodePoint(n) : whole;
       }
     }
   });
 }
-function visualWidth(text4) {
+function visualWidth(text) {
   let w = 0;
-  for (const ch of text4) {
+  for (const ch of text) {
     const cp = ch.codePointAt(0);
     if (ch === " " || ch === "	")
       w += 0.35;
@@ -10010,9 +10006,9 @@ function replaceTextAcrossRuns(xml, find, replacement, opts) {
     const segs = [];
     let flat = "";
     for (const m of para.matchAll(textRe)) {
-      const text4 = unescXml(m[2]);
-      segs.push({ el: m[0], attrs: m[1] ?? "", text: text4, start: flat.length });
-      flat += text4;
+      const text = unescXml(m[2]);
+      segs.push({ el: m[0], attrs: m[1] ?? "", text, start: flat.length });
+      flat += text;
     }
     if (!flat.includes(find))
       return para;
@@ -10088,12 +10084,6 @@ function capacityWarning(slideXml, token, value) {
     return void 0;
   return `${token}: replacement is ~${Math.ceil(width)} width-units, slot fits ~${Math.floor(capacity)} (${Math.round(widthPt)}\xD7${Math.round(heightPt)}pt box @ ${fontPt}pt) \u2014 likely overflow. Shorten the wording; do NOT shrink the font to make it fit.`;
 }
-async function text3(zip, path) {
-  const f = zip.file(path);
-  if (!f)
-    throw new Error(`not a PowerPoint file (${path} missing)`);
-  return f.async("string");
-}
 async function clonePptxSlide(bytes, slideNumber, replacements = {}) {
   if (!Number.isInteger(slideNumber) || slideNumber < 1) {
     throw new Error(`slide number must be a positive integer, got ${slideNumber}`);
@@ -10113,7 +10103,7 @@ async function clonePptxSlide(bytes, slideNumber, replacements = {}) {
   const newNum = Math.max(...slideNums) + 1;
   const srcXmlPath = `ppt/slides/slide${slideNumber}.xml`;
   const newXmlPath = `ppt/slides/slide${newNum}.xml`;
-  let slideXml = await text3(zip, srcXmlPath);
+  let slideXml = await readPptxPart(zip, srcXmlPath);
   const replaced = [];
   const missing = [];
   const warnings = [];
@@ -10166,7 +10156,7 @@ async function removePptxSlide(bytes, slideNumber) {
   const xmlPath = `ppt/slides/slide${slideNumber}.xml`;
   const relsPath = `ppt/slides/_rels/slide${slideNumber}.xml.rels`;
   const presRelsPath = "ppt/_rels/presentation.xml.rels";
-  const presRels = await text3(zip, presRelsPath);
+  const presRels = await readPptxPart(zip, presRelsPath);
   const targetRe = new RegExp(`Target="(/ppt/)?slides/slide${slideNumber}\\.xml"`);
   const relMatch = findElement(presRels, "Relationship", (r) => r.includes(SLIDE_REL_TYPE) && targetRe.test(r));
   if (!relMatch)
@@ -10176,19 +10166,19 @@ async function removePptxSlide(bytes, slideNumber) {
     throw new Error(`slide ${slideNumber}'s relationship carries no Id (corrupt deck?)`);
   zip.file(presRelsPath, presRels.replace(relMatch, ""));
   const presPath = "ppt/presentation.xml";
-  const pres = await text3(zip, presPath);
+  const pres = await readPptxPart(zip, presPath);
   const sld = removeElement(pres, "p:sldId", (el) => el.includes(`r:id="${rId}"`));
   if (!sld.removed)
     throw new Error(`slide ${slideNumber} (${rId}) not found in the slide list (corrupt deck?)`);
   zip.file(presPath, sld.xml);
-  const slideRels = zip.file(relsPath) ? await text3(zip, relsPath) : "";
+  const slideRels = zip.file(relsPath) ? await readPptxPart(zip, relsPath) : "";
   const notesTarget = /<Relationship\b[^>]*Type="[^"]*\/notesSlide"[^>]*Target="\.\.\/(notesSlides\/notesSlide\d+\.xml)"/.exec(slideRels)?.[1];
   const removedParts = [xmlPath, relsPath];
   if (notesTarget) {
     const otherSlideRels = Object.keys(zip.files).filter((p) => /^ppt\/slides\/_rels\/slide\d+\.xml\.rels$/.test(p) && p !== relsPath);
     let shared = false;
     for (const p of otherSlideRels) {
-      if ((await text3(zip, p)).includes(notesTarget)) {
+      if ((await readPptxPart(zip, p)).includes(notesTarget)) {
         shared = true;
         break;
       }
@@ -10196,7 +10186,7 @@ async function removePptxSlide(bytes, slideNumber) {
     if (!shared)
       removedParts.push(`ppt/${notesTarget}`, `ppt/notesSlides/_rels/${notesTarget.split("/")[1]}.rels`);
   }
-  let ct = await text3(zip, "[Content_Types].xml");
+  let ct = await readPptxPart(zip, "[Content_Types].xml");
   for (const part of removedParts) {
     zip.remove(part);
     ct = removeElement(ct, "Override", (el) => el.includes(`PartName="/${part}"`)).xml;

package/skills/document/bin/pptx-theme.cjs

@@ -9852,18 +9852,6 @@ function fontFace(fontScheme, which) {
   const ea = /<a:ea typeface="([^"]*)"/.exec(seg)?.[1];
   return latin || ea || void 0;
 }
-function masterSize(master, block) {
-  const seg = new RegExp(`<p:${block}>([\\s\\S]*?)</p:${block}>`).exec(master)?.[1];
-  const lvl1 = seg && /<a:lvl1pPr[\s\S]*?<a:defRPr[^>]*\bsz="(\d+)"/.exec(seg)?.[1];
-  return lvl1 ? Number(lvl1) / 100 : void 0;
-}
-function clamp(v, lo, hi, label, warnings) {
-  if (v < lo || v > hi) {
-    warnings.push(`${label} ${v}pt is outside the generated-deck band [${lo}, ${hi}] \u2014 clamped`);
-    return Math.min(hi, Math.max(lo, v));
-  }
-  return v;
-}
 async function extractPptxTheme(bytes) {
   let zip;
   try {
@@ -9905,10 +9893,6 @@ async function extractPptxTheme(bytes) {
   const fontScheme = /<a:fontScheme[\s\S]*?<\/a:fontScheme>/.exec(themeXml)?.[0] ?? "";
   const heading = fontFace(fontScheme, "majorFont");
   const body = fontFace(fontScheme, "minorFont");
-  const masterFile = zip.file("ppt/slideMasters/slideMaster1.xml") ?? zip.file(/^ppt\/slideMasters\/slideMaster\d+\.xml$/)[0];
-  const master = masterFile ? await masterFile.async("string") : "";
-  const rawTitle = masterSize(master, "titleStyle");
-  const rawBody = masterSize(master, "bodyStyle");
   const theme = {
     ...heading || body ? { fonts: { ...heading ? { heading } : {}, ...body ? { body } : {} } } : {},
     colors: {
@@ -9922,10 +9906,7 @@ async function extractPptxTheme(bytes) {
     pptx: {
       background: lt1,
       titleColor: accent1,
-      textColor: dk1,
-      ...rawTitle ? { titleSize: clamp(rawTitle, 20, 40, "master title size", warnings) } : {},
-      ...rawBody ? { bodySize: clamp(rawBody, 12, 20, "master body size", warnings) } : {},
-      slideNumber: true
+      textColor: dk1
     }
   };
   return { theme, warnings };

package/skills/document/bin/pptx-tokenize.cjs

@@ -9837,7 +9837,7 @@ function unescXml(s) {
         return "'";
       default: {
         const n = code.startsWith("#x") || code.startsWith("#X") ? parseInt(code.slice(2), 16) : parseInt(code.slice(1), 10);
-        return Number.isFinite(n) ? String.fromCodePoint(n) : whole;
+        return Number.isInteger(n) && n >= 0 && n <= 1114111 ? String.fromCodePoint(n) : whole;
       }
     }
   });

package/skills/document/bin-reference.md

@@ -0,0 +1,35 @@
+# Script reference (L3)
+
+Every bin in `bin/`, with its full contract. SKILL.md lists them one line each;
+read the entry here before the first call of a bin you have not used in this task.
+
+- `bin/doc-scan.cjs <file.pdf>` — per-page signals as JSON.
+- `bin/doc-text.cjs <file.pdf>` — extract a PDF's text layer.
+- `bin/pdf-render.cjs <file.pdf> <pages|all> [scale]` — render pages to PNG for vision (`pages` = `3` | `2-5` | `3,7-8` | `all`). `scale` (default `2` ≈ 144dpi) trades resolution for vision tokens: pass `1` (≈72dpi, ¼ the pixels ≈ ¼ the tokens) for slide-composition/layout QA; keep `2` when fine print must stay legible (formulas/tables). Reading previews is the priciest step in the deck loop — render cheap + read only what changed (a deck's final Office pass hands you its images: `deck-qa --final`).
+- `bin/pdf-images.cjs <file.pdf> [pages]` — extract EMBEDDED images at native resolution with page placement (`pages` = `N` | `N-M` | `all`, default all). Prints a JSON manifest (page/index/bbox/size/path). Use this — not a full-page `pdf-render` — when you need the original figures/photos as their own files (e.g. rebuilding a deck). Vector/text-only pages yield nothing → fall back to `pdf-render`.
+- `bin/pdf-tables.cjs <file.pdf> [page] [minCols]` — recover text-layer tables as rows (ruled/scanned tables need render + vision instead).
+- `bin/ocr.cjs <image.png|jpg> [lang]` — read text off a scanned image (tesseract.js). For a scanned PDF, `pdf-render` a page first, then OCR the PNG. Language data downloads on first use / set `$TALOS_TESSDATA` for offline. **Prefer vision** when a vision model is available; OCR is the text-only fallback.
+- `bin/xlsx-query.cjs <file> [--summary | --agg <sheet> <col> <op> | --sample <sheet> [n]]` — spreadsheet compute.
+- `bin/doc-gen.cjs <docx|xlsx|pdf> <out> <spec.json> [--theme <theme.json>] [--topic <subject> | --palette <id>] [--no-preview]` — generate documents from scratch. DOCX/PDF body fields are exactly `paragraphs` and/or `blocks` (never `sections`); in a PDF, any http(s) URL written in body text, list items or table cells becomes a clickable link and wraps inside the page on its own — never split a URL by hand (there is no other link syntax); unknown fields and empty bodies fail with `DOC_SPEC_INVALID` before any output is written (`allowCoverOnly:true` is the explicit title-only opt-in). Correct the reported JSON path and rerun. `--theme` applies a presentation theme (colors/fonts/cover/header/footer — see rewrite.md "Themes"; built-ins in `themes/`). **`--topic <subject>` (when no `--theme`) picks a topic-adaptive palette** instead of the same default every time. `doc-gen pptx` exits 64: decks are built with html2pptx. `--palette <id>` forces a specific palette (`doc-gen --list-palettes` prints them). **`--accent <#hex>` / `--style <skin>` (docx/pdf)**: white-paper-black-text base with ONE brand color on H1/H2 + a faint table-header tint — the practical doc shape (a document is read/printed/edited, not projected, so body text stays near-black). `--accent` takes a literal hex; `--style <skin>` pulls just the `--accent` from `styles/<skin>/skin.css` (the deck skin's full palette is NOT carried onto paper). Precedence: `--theme` > spec `"theme"` > `--accent`/`--style` > `--palette`/`--topic` > default.
+- `bin/doc-convert.cjs <in.docx|pptx|xlsx> <out.pdf> [--cache-dir <dir>]` — faithful docx/pptx/xlsx → PDF conversion. Engine precedence (best fidelity first, each downgrade tagged on stdout `[pdf (…)]` + warned on stderr): (1) **LibreOffice** if a system `soffice` is found — true layout render (page geometry, headers/footers, text-box positions, native charts), offline; (2) **LibreOffice sidecar** if `TALOS_OFFICE_URL` is set — same true-layout fidelity via a remote converter (e.g. Gotenberg), needs network; (3) **Chromium** — reconstructed HTML, content/structure/images preserved but in-document layout is not (pptx = one page per slide): the app's service in-app, else a headless Chromium; with none of these it exits 69 — say the PDF could not be made. `--cache-dir` (or `TALOS_OFFICE_CACHE_DIR`) reuses a content-hashed local LibreOffice result for the exact same immutable artifact; caching is opt-in so document bytes are not retained by default. Surface the resulting `[pdf (engine)]` caveat to the user. NOTE: spreadsheets (xlsx/xls/ods) render ONLY via (1)–(2), a real LibreOffice; Chromium does not rebuild spreadsheets, so with no LibreOffice available the command errors (never a degraded text-only sheet).
+- `bin/doc-validate.cjs <file.docx|pptx|xlsx|pdf> [--strict] [--design-lint]` — structural validation gate: OOXML zip/parts/rels/Content_Types/XML well-formedness; a PDF must parse and hold at least one page (reports `pages` and a `pdf-parse-only` warning — how it looks is render-and-look's job; `--strict` / `--design-lint` are OOXML-only; `--strict` on a PDF adds a `strict-not-applicable` warning). Run after every generation or edit; exit 1 = broken, fix before delivering. `--strict` adds full ECMA-376 schema (XSD) validation of every recognised part — REQUIRED after custom-code (doc-run/html2pptx) or raw-XML output; a strict failure means the file is non-standard even if Office opens it. `--design-lint` (pptx only) adds an ADVISORY design pass — flags `text-only-slide` (a wall of text with no visual anchor), `low-contrast-text`, `placeholder-text` (a layout pasted but never filled — 替换为…/占位/Lorem still in the slide), `font-mismatch` (CJK text set in a Latin-only font → 豆腐; expected language defaults to the system locale, override with `TALOS_DECK_LANG`), `off-canvas`, `tiny-font`, `shape-overlap`; findings are warnings (never change the exit code) but are real design bugs — fix them. See deck-design.md "Design principles".
+- `bin/deck-qa.cjs <file.pptx> [--json] [--rendered <office.pdf> | --final [--cache-dir <dir>]]` — MECHANICAL design QA (deterministic, token-free): reads slide XML and flags `off-canvas` (content clipped past the edge), `tiny-font` (<10pt), `shape-overlap` (colliding text), plus `text-only-slide` / `low-contrast-text` / `placeholder-text` / `font-mismatch` (CJK text in a Latin-only font → 豆腐). Advisory (exit 0 even with findings). `--json` → `{ok,findings:[{slide,code,message}]}` for the visual-QA loop. It is the CHEAP GATE before spending vision tokens — run it every QA round and fix all findings first; then do the vision critic + per-slide regeneration (deck-design.md "Verify before delivering"). `html2pptx` already prints this lint as `qa` after every build. **`--final` is the deck's delivery sign-off in one call**: strict XSD validation (failure exits 1), the lint, an Office render through `doc-convert` (cached), `render-overflow` / `render-collision` where Office re-laid the native text past its box, and `review` + `previews` — the only slides (findings + native charts) to look at again, already rendered at ≈72dpi (deck-design.md "Verify before delivering"). `--rendered <pdf>` is the same render check against a PDF you converted yourself; a page count that differs from the deck exits 1.
+- `bin/doc-xml.cjs unpack <file> <dir>` / `pack <dir> <out>` — raw-XML escape hatch (pretty-printed unpack → edit → repack); always doc-validate afterwards. `replace <in.docx> <out.docx> <find> <replacement>` — cross-run character-offset replace (finds text even when Word split it over runs, preserves formatting; covers body + headers/footers) — try this FIRST for plain text edits before unpacking. `merge-runs <in.docx> <out.docx>` repairs run fragmentation when you do need manual XML edits.
+- `bin/pptx-clone.cjs <template.pptx> <slideNo> <out.pptx> [replacements.json]` — clone a styled template slide once per data item, replacing `{{tokens}}` in the clone only (tokens split across runs are still found); `pptx-clone remove <in> <slideNo> <out>` drops a slide (e.g. the leftover token template). CAPACITY warnings on stderr mean the text likely overflows its slot — shorten the wording, never shrink the font. See rewrite.md.
+- `bin/pptx-slide.cjs add <in.pptx> <out.pptx> [--layout N]` / `dup <in> <slideNo> <out>` / `remove <in> <slideNo> <out>` / `reorder <in> <order> <out>` — slide-lifecycle surgery on an EXISTING deck WITHOUT a `{{token}}` template: append a blank slide bound to a layout (inherits the deck's master/theme), duplicate or drop a slide, or permute deck order (`pptx-slide reorder in.pptx 3,1,2 out.pptx` — comma-list of current 1-based positions in the new sequence). Lossless & structural — parts/rels/Content_Types are bookkept for you, but in-slide TEXT/content edits still go through doc-xml. Always doc-validate.
+- `bin/pptx-embed-fonts.cjs <in.pptx> <out.pptx> --font "<Typeface>=<path.ttf>" [--bold …] [--italic …]` — EMBED fonts into a deck (OOXML font embedding) so it looks identical on a machine lacking the font. Full-font embed → use for SMALL custom/brand fonts; NOT big CJK fonts (openers have system CJK, and the file would balloon). `<Typeface>` must match the deck's text-run font name. doc-validate after.
+- `bin/pptx-theme.cjs <ref.pptx> [out.json]` — extract a theme.json (palette/fonts) from an existing deck, then `html2pptx --theme` (or `doc-gen --theme` for a matching docx/pdf) it: new content in that deck's look. Palette only — reusing actual layouts is pptx-clone/doc-fill territory.
+- `bin/doc-fill.cjs <template.docx|pptx|xlsx> <values.json> <out>` — fill `{{placeholders}}` in an existing template, preserving its styling (see rewrite.md).
+- `bin/pptx-tokenize.cjs <user.pptx> <template.pptx> [schema.json]` — turn a user's UPLOADED deck into a reusable `{{token}}` template: keeps its exact layouts/master/brand, replaces each content slot's text with a clean single-run token, and emits a `schema.json` cataloging every token (slide/role/type/multiline/original/capacity). Plain text boxes (no `<p:ph>`) are tokenized too. Then `doc-fill` it — fill EVERY token (pass `original` for slots you keep, else they blank). The B2 "reuse their layout" path; see rewrite.md.
+- `bin/pptx-set-image.cjs <in.pptx> <slideNo> <rId> <image> <out.pptx>` — swap the picture behind a slide's `rId` (from pptx-tokenize's image tokens) with a new image, keeping the frame (position/size) put. add-and-repoint (old media orphaned). Aspect-mismatch STRETCHES — pre-crop to the slot ratio. Always doc-validate.
+- `bin/docx-annotate.cjs comment <in.docx> <out.docx> <comments.json>` / `suggest <in.docx> <out.docx> <author> <text>` / `accept <in.docx> <out.docx>` / `redline-check <original.docx> <edited.docx>` — add Word comments (paragraph-anchored, threaded replies via `replyTo`), a tracked insertion (reviewer suggestion), accept ALL tracked changes, or PROVE an edited file changed nothing outside tracked changes (run after every redline edit; non-zero exit = an untracked content change slipped in).
+- `bin/pdf-form.cjs list <in.pdf>` / `fill <in.pdf> <values.json> <out.pdf> [--flatten]` / `overlay <filled.pdf> <out.pdf>` — inspect/fill PDF forms; `overlay` boxes every field in red for a render-and-look fill check (see pdf.md).
+- `bin/pdf-ops.cjs merge <out> <in…>` / `split <in> <from-to> <out>` / `rotate <in> <deg> <out> [pages]` / `watermark <in> <text> <out>` / `stamp <in.pdf> <stamps.json> <out.pdf>` / `encrypt <in> <out> <user-pw> [owner-pw]` / `decrypt <in> <pw> <out>` — PDF page ops, coordinate text stamping onto a flat (non-form) PDF (see pdf.md), and AES-256 password protection.
+- `bin/xlsx-recalc.cjs <in.xlsx> <out.xlsx>` — re-evaluate all formulas (HyperFormula) and cache the results, keeping the formulas. Use when a spreadsheet's formula cells show stale/blank values.
+- `bin/doc-run.cjs <script.js> [args…]` — run a custom Node script with the engine's libraries bundled in (`require("pptxgenjs"|"docx"|"xlsx"|"exceljs"|"pdf-lib"|"jszip"|"pizzip"|"hyperformula")` guaranteed on any machine; `--list` prints the registry; nothing else is installed). For a **formatted workbook** (fills, font colors, borders, merged cells) use `exceljs` — `xlsx` (SheetJS community) writes no cell styles at all and drops them without an error; `doc-gen xlsx` covers only a bold header, column widths, number formats and formulas. The long-tail escape hatch when no verb fits — see rewrite.md "Custom scripts"; ALWAYS doc-validate the output.
+- `bin/html2pptx.cjs <deck.html|snapshot.layout.json> [out.pptx|out.pdf] [--style <id>] [--theme-v2] [--media-style <id>] [--backdrop <variant>] [--editable] [--rasterize] [--preview-dir <dir>] [--preview-pages <all|N,N-M>]` — **THE deck path**: write slide HTML (`<section class="slide" data-layout="…">` on a 1280×720 canvas), Chromium lays it out → NATIVE editable pptx. An `out.pdf` prints the same styled deck instead: one 16:9 vector page per slide, text selectable, links clickable (HTML input only; not with `--editable`/`--rasterize`/`--notes-doc`). `--preview-dir` is a preview-only fast path that writes slide PNGs directly from the styled HTML and skips PPTX/LibreOffice; use all pages once, then `--preview-pages` for changed pages. `--theme-v2` composes the selected family's existing paint with its semantic component profile, default media style and bound art direction; `--media-style` overrides only the media treatment. Entries in a `classic-v1` catalog collection reject both flags; omit them for the frozen V1 path. `--backdrop <variant>` picks a signature backdrop. **DEFAULT = hybrid**: each slide's visuals bake into a full-fidelity raster backdrop with native EDITABLE text on top; auto-falls back to plain native if backdrop capture is unavailable. `--editable` = plain native only (effects flatten). `--rasterize` = full image slides (ZERO editability — tell the user). Advisory warnings on hardcoded brand colors + repeated layouts (P3). Runs in the app's Chromium OR bundled headless Chromium (Playwright) — works off-app (CI/cloud); layout JSON works anywhere. **Tailwind + `size="1".."7"` scale available** (vendored offline). See theme-system.md + deck-design.md + layouts/README.md. `[--theme <theme.json>]` is a separate legacy document recolor path.
+- `bin/deck-build.cjs <spec.json> <deck.html>` — **THE FAST deck path** for catalog slides: emit a COMPACT spec with `style`, independent `layoutPack`, and per-slide `intent` + `layout` + content. Modern entries add `themeVersion:2` plus optional `mediaStyle`/`decorRhythm`; frozen `classic-v1` entries must omit those fields and use only pre-V2 layouts. Use `layouts/profiles.json` to match content intent before selecting geometry; under V2 the same intent derives the art scene and deck-level decoration rhythm. The CLI warns on an intent/layout mismatch and errors on an unknown intent. `scenario` (the confirmed scenario) decides whether the family's motion preset is applied — read decks (内审/报告/培训…) get none, `motion: true|false` overrides, and the result JSON reports `motion: {on, reason}` (deck-design.md "Motion"). `layoutPack:"none"` forces shared layouts; omitting `layoutPack` preserves the old behavior where a `kind:"pack"` style implicitly uses its same-name layouts. `slots`, `rows`, and `chart` are still validated against `layouts/slots.json`; any unknown layout/slot/field or missing figure input exits 1 and writes nothing. See theme-system.md for the full schema and compatibility contract.
+
+All scripts are Node and print a machine-readable result plus a human note. On a
+missing dependency or unreadable file they exit non-zero with a clear message —
+report that to the user, do not fabricate content.

package/skills/document/content-pipeline.md

@@ -269,24 +269,23 @@ that matches its content structure (by P1/P2/P3, `layouts/README.md`), **copy th
 content** — leave color to the skin (never hardcode a brand hex). Render
 `bin/html2pptx.cjs deck.html out.pptx --style <skin>`. Where the catalog doesn't fit
 (bespoke hero covers, layered architecture, magazine) author bespoke HTML per
-**deck-design.md** (still using the skin's semantic classes). Fall back to
-`doc-gen … --theme` archetypes only when headless with no browser or a
-structured-spec deck is wanted.
+**deck-design.md** (still using the skin's semantic classes). With no browser at
+all, say so and stop — there is no spec-deck fallback.
 
 ### 4.1 Content structure → layout
 
 | Content structure | Core elements | → `layouts/*` (P1/P2/P3) |
 |---|---|---|
-| **Data / Trend** | 数据标题 + 指标 + 一句数据故事 | `chart-kpi` (`kpiCards`+`chart` / `timeline`) |
-| **Single impact** | 一个关键数字 + 上下文 | `big-stat` (`bigStat`) |
-| **Argument / Concept+visual** | 论点/定义 + 3–4 证据/组件 | `split-two-col` (`cards`/`iconList`+`quote`) |
-| **Cards (并列要点)** | 3 个并列要点 | `cards-3` (`cards` accentBar/numbered) |
-| **Comparison** | 框架 + 2–3 选项 × 维度 + 推荐 | bespoke (deck-design.md) / `comparison` |
-| **Process** | 目标 + 3–5 步骤 | bespoke / `steps` |
-| **Framework/Matrix** | 两轴 + 四象限 | bespoke / `quadrant` |
-| **Case Study** | 背景/挑战/方案/前后 | `split-two-col` + `big-stat` (`splitImage`+`kpiCards`) |
+| **Data / Trend** | 数据标题 + 指标 + 一句数据故事 | `chart-kpi` |
+| **Single impact** | 一个关键数字 + 上下文 | `big-stat` |
+| **Argument / Concept+visual** | 论点/定义 + 3–4 证据/组件 | `split-two-col` |
+| **Cards (并列要点)** | 3 个并列要点 | `cards-3` |
+| **Comparison** | 框架 + 2–3 选项 × 维度 + 推荐 | `comparison` |
+| **Process** | 目标 + 3–5 步骤 | `steps` / `steps-vertical` |
+| **Framework/Matrix** | 两轴 + 四象限 | `matrix-2x2` |
+| **Case Study** | 背景/挑战/方案/前后 | `split-two-col` + `big-stat` |
 
-Role pages: `cover` (`cool/cover`) · `toc` · `section` (`cool/section`) · `ending`.
+Role pages: `cover` · `toc` · `section` · `ending` (and their variants in `layouts/README.md`). Anything no layout fits → a bespoke slide (deck-design.md).
 
 ### 4.2 Pick the exact template — priority order (P1 → P2 → P3)
 
@@ -296,7 +295,7 @@ this **priority order** — P1 outranks P2 outranks P3; never trade layout-fit f
 - **P1 — Layout match (most important): image presence + position.** No image → a
   text-only template (`cards-3` / a text-column split). Image present → `split-two-col`
   with the visual on the side it reads best (mirror the `.tpl` for image-left). Data →
-  `chart-kpi` (native `data-chart`). Never force text into an image slot or an image
+  `chart-kpi` (chart choice — inline SVG vs native `data-chart` — per deck-design.md "Charts"). Never force text into an image slot or an image
   into a text slot; delete an unused image slot rather than leaving a placeholder.
 - **P2 — Density match: point count → variant.** 1–2 points / one hero number →
   spacious·centered (`big-stat`, hero cover); 3–4 points → balanced two-column
@@ -330,7 +329,7 @@ this **priority order** — P1 outranks P2 outranks P3; never trade layout-fit f
 - **Rich backgrounds** — never pure white/black; theme gradient + a decorative motif.
   **≥1–2 dark-accent slides** across the deck (Visual Rhythm).
 - **≥2 decorative/visual elements per content slide**; **charts > text for data**, one
-  insight per chart (native `data-chart`, editable), highlight the key datapoint, no junk.
+  insight per chart (SVG or native `data-chart` per deck-design.md "Charts"), highlight the key datapoint, no junk.
 - **Emotional opening & closing** — cover and ending are STATEMENTS (feeling, not
   facts): strong visual + few powerful words.
 - **Visual diversity** — enforced by P3 (§4.2); a deck of one repeated layout reads as
@@ -346,10 +345,12 @@ Use a two-stage loop; do not pay the Office cold-start cost on every visual edit
    `bin/html2pptx.cjs deck.html --preview-dir <dir> [--preview-pages <spec>]` and inspect every page on
    the first pass. Fix HTML/CSS, then preview only changed pages. Repeat until the HTML
    composition is clean.
-2. **Delivery loop (PPTX, once after HTML is clean):** generate the PPTX, run
-   `deck-qa --json` and `doc-validate --strict`, fixing objective findings before
-   visual review. Then perform one faithful `doc-convert → pdf-render all` pass to
-   catch PPTX/Office-only drift. If that final pass finds drift, fix and rerun only as
+2. **Delivery loop (PPTX, once after HTML is clean):** build the PPTX and fix the
+   `qa` findings the build prints. Then sign off with one `deck-qa deck.pptx --final`:
+   strict validation, the Office render and its drift check, and `previews` — the
+   only slides to look at again; every other slide was already judged in the HTML
+   preview (deck-design.md "Verify before delivering", step 3, and its
+   read-everything exceptions). If that pass finds drift, fix and rerun only as
    required; never use PPTX→PDF as the routine authoring preview.
 
 Assume there are defects and inspect text overflow/clipping, collisions, tofu/blank