ppt-template-reuse 0.4.0-rc.2

package/src/core/ooxml-editor.mjs

@@ -0,0 +1,753 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import {
+  attr,
+  attrQName,
+  elements,
+  loadPptx,
+  localName,
+  parseXml,
+  relationshipPart,
+  relationships,
+  serializeXml,
+  shapeRecords,
+  slideRecords,
+  textOf,
+  xmlFrom,
+} from "./pptx-package.mjs";
+import { fingerprint, sha256File } from "./io.mjs";
+
+const REL_NS =
+  "http://schemas.openxmlformats.org/package/2006/relationships";
+const P_NS =
+  "http://schemas.openxmlformats.org/presentationml/2006/main";
+const A_NS =
+  "http://schemas.openxmlformats.org/drawingml/2006/main";
+const R_NS =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+const CT_NS =
+  "http://schemas.openxmlformats.org/package/2006/content-types";
+const FIXED_DATE = new Date("2000-01-01T00:00:00.000Z");
+
+function xmlEscape(value) {
+  return String(value ?? "")
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+function relationshipDocument(document) {
+  return (
+    document ||
+    parseXml(
+      `<Relationships xmlns="${REL_NS}"></Relationships>`,
+    )
+  );
+}
+
+function contentTypesDocument(xml) {
+  return parseXml(xml);
+}
+
+function ensureOverride(contentTypes, partName, contentType) {
+  const normalized = partName.startsWith("/") ? partName : `/${partName}`;
+  const existing = elements(contentTypes, "Override").find(
+    (node) => attr(node, "PartName") === normalized,
+  );
+  if (existing) {
+    existing.setAttribute("ContentType", contentType);
+    return;
+  }
+  const node = contentTypes.createElementNS(CT_NS, "Override");
+  node.setAttribute("PartName", normalized);
+  node.setAttribute("ContentType", contentType);
+  contentTypes.documentElement.appendChild(node);
+}
+
+function ensureDefault(contentTypes, extension, contentType) {
+  const existing = elements(contentTypes, "Default").find(
+    (node) => attr(node, "Extension") === extension,
+  );
+  if (existing) return;
+  const node = contentTypes.createElementNS(CT_NS, "Default");
+  node.setAttribute("Extension", extension);
+  node.setAttribute("ContentType", contentType);
+  contentTypes.documentElement.appendChild(node);
+}
+
+function removeOverrides(contentTypes, predicate) {
+  for (const node of elements(contentTypes, "Override")) {
+    if (predicate(String(attr(node, "PartName") || ""))) {
+      node.parentNode.removeChild(node);
+    }
+  }
+}
+
+function pruneOrphanedSlideParts(zip, contentTypes, outputSlideCount) {
+  const removed = [];
+  const shouldRemove = (name) => {
+    const slide = name.match(
+      /^ppt\/slides\/(?:_rels\/)?slide(\d+)\.xml(?:\.rels)?$/,
+    );
+    if (slide) return Number(slide[1]) > outputSlideCount;
+    const notes = name.match(
+      /^ppt\/notesSlides\/(?:_rels\/)?notesSlide(\d+)\.xml(?:\.rels)?$/,
+    );
+    return notes ? Number(notes[1]) > outputSlideCount : false;
+  };
+  for (const name of Object.keys(zip.files)) {
+    if (!shouldRemove(name)) continue;
+    zip.remove(name);
+    removed.push(name);
+  }
+  removeOverrides(contentTypes, (partName) => {
+    const normalized = partName.replace(/^\//, "");
+    return shouldRemove(normalized);
+  });
+  return removed.sort();
+}
+
+function relationshipById(document, relationshipId) {
+  return elements(document, "Relationship").find(
+    (node) => attr(node, "Id") === relationshipId,
+  );
+}
+
+function removeRelationshipsByType(document, suffix) {
+  for (const node of elements(document, "Relationship")) {
+    if (String(attr(node, "Type") || "").endsWith(suffix)) {
+      node.parentNode.removeChild(node);
+    }
+  }
+}
+
+function appendRelationship(document, { id, type, target }) {
+  const node = document.createElementNS(REL_NS, "Relationship");
+  node.setAttribute("Id", id);
+  node.setAttribute("Type", type);
+  node.setAttribute("Target", target);
+  document.documentElement.appendChild(node);
+  return node;
+}
+
+function findShapeNode(slideDocument, target) {
+  const shapes = shapeRecords(slideDocument);
+  const match =
+    shapes.find(
+      (shape) =>
+        target.sourceShapeId !== undefined &&
+        String(shape.id) === String(target.sourceShapeId),
+    ) ||
+    shapes.find(
+      (shape) =>
+        target.sourceElementName &&
+        shape.name === target.sourceElementName,
+    );
+  if (!match) {
+    throw new Error(
+      `Cannot resolve ${target.slotId} by shape id/name on source slide`,
+    );
+  }
+  return match;
+}
+
+function rewriteText(shape, value) {
+  let textNodes = elements(shape.node, "t");
+  if (!textNodes.length) {
+    const textBody = elements(shape.node, "txBody")[0];
+    if (!textBody) {
+      throw new Error(`Shape ${shape.id} is not an editable text shape`);
+    }
+    let paragraph = elements(textBody, "p")[0];
+    if (!paragraph) {
+      paragraph = shape.node.ownerDocument.createElementNS(A_NS, "a:p");
+      textBody.appendChild(paragraph);
+    }
+    const run = shape.node.ownerDocument.createElementNS(A_NS, "a:r");
+    const textNode = shape.node.ownerDocument.createElementNS(A_NS, "a:t");
+    const endProperties = elements(paragraph, "endParaRPr")[0];
+    run.appendChild(textNode);
+    if (endProperties) paragraph.insertBefore(run, endProperties);
+    else paragraph.appendChild(run);
+    textNodes = [textNode];
+  }
+  textNodes[0].textContent = String(value ?? "");
+  textNodes[0].setAttribute("xml:space", "preserve");
+  for (const node of textNodes.slice(1)) node.textContent = "";
+}
+
+function replaceTable(shape, value) {
+  const rows = value?.values;
+  if (!Array.isArray(rows)) {
+    throw new Error(`Table target ${shape.id} requires value.values`);
+  }
+  const cells = elements(shape.node, "tc");
+  const flat = rows.flat();
+  if (flat.length !== cells.length) {
+    throw new Error(
+      `Table target ${shape.id} has ${cells.length} cells but received ${flat.length}`,
+    );
+  }
+  cells.forEach((cell, index) => {
+    const textNodes = elements(cell, "t");
+    if (!textNodes.length) throw new Error(`Table cell ${index + 1} has no text run`);
+    textNodes[0].textContent = String(flat[index] ?? "");
+    for (const node of textNodes.slice(1)) node.textContent = "";
+  });
+}
+
+function chartSeriesNodes(chartDocument) {
+  return elements(chartDocument, "ser").filter((node) =>
+    ["barChart", "lineChart", "pieChart", "areaChart", "scatterChart"].includes(
+      localName(node.parentNode),
+    ),
+  );
+}
+
+function replaceCache(cacheParent, values, type) {
+  const cache =
+    elements(cacheParent, type === "number" ? "numCache" : "strCache")[0];
+  if (!cache) return false;
+  for (const point of elements(cache, "pt")) point.parentNode.removeChild(point);
+  const pointCount = elements(cache, "ptCount")[0];
+  if (pointCount) pointCount.setAttribute("val", String(values.length));
+  values.forEach((value, index) => {
+    const point = cache.ownerDocument.createElementNS(
+      "http://schemas.openxmlformats.org/drawingml/2006/chart",
+      "c:pt",
+    );
+    point.setAttribute("idx", String(index));
+    const valueNode = cache.ownerDocument.createElementNS(
+      "http://schemas.openxmlformats.org/drawingml/2006/chart",
+      "c:v",
+    );
+    valueNode.appendChild(
+      cache.ownerDocument.createTextNode(String(value ?? "")),
+    );
+    point.appendChild(valueNode);
+    cache.appendChild(point);
+  });
+  return true;
+}
+
+function updateChartXml(chartXml, payload) {
+  const document = parseXml(chartXml);
+  const seriesNodes = chartSeriesNodes(document);
+  if (!Array.isArray(payload?.series) || payload.series.length !== seriesNodes.length) {
+    throw new Error(
+      `Chart series mismatch: expected ${seriesNodes.length}, received ${payload?.series?.length || 0}`,
+    );
+  }
+  seriesNodes.forEach((series, index) => {
+    const next = payload.series[index];
+    const titleParent = elements(series, "tx")[0];
+    if (titleParent) {
+      replaceCache(titleParent, [String(next.name || "")], "string");
+      const directValue = elements(titleParent, "v")[0];
+      if (directValue) directValue.textContent = String(next.name || "");
+    }
+    const categories = payload.categories || next.categories || [];
+    const categoryParent = elements(series, "cat")[0];
+    if (categoryParent) replaceCache(categoryParent, categories, "string");
+    const valueParent = elements(series, "val")[0];
+    if (valueParent) replaceCache(valueParent, next.values || [], "number");
+  });
+  return serializeXml(document);
+}
+
+function contentTypeForImage(extension) {
+  return (
+    {
+      png: "image/png",
+      jpg: "image/jpeg",
+      jpeg: "image/jpeg",
+      gif: "image/gif",
+      svg: "image/svg+xml",
+      webp: "image/webp",
+    }[extension] || "application/octet-stream"
+  );
+}
+
+async function replaceImage({
+  zip,
+  slideDocument,
+  slideRels,
+  shape,
+  target,
+  outputSlide,
+  targetIndex,
+  contentTypes,
+}) {
+  const sourcePath =
+    typeof target.value === "string" ? target.value : target.value?.path;
+  if (!sourcePath) throw new Error(`Image target ${target.slotId} has no path`);
+  const resolved = path.resolve(sourcePath);
+  const bytes = await fs.readFile(resolved);
+  const extension = path.extname(resolved).slice(1).toLowerCase() || "png";
+  const blip = elements(shape.node, "blip")[0];
+  let relationshipId =
+    attrQName(blip, "r:embed") || attr(blip, "embed") || shape.relationshipId;
+  let relationship = relationshipId
+    ? relationshipById(slideRels, relationshipId)
+    : undefined;
+  if (!relationship) {
+    relationshipId = `rIdV04Image${targetIndex}`;
+    while (relationshipById(slideRels, relationshipId)) {
+      relationshipId = `${relationshipId}x`;
+    }
+    relationship = appendRelationship(slideRels, {
+      id: relationshipId,
+      type: `${R_NS}/image`,
+      target: "",
+    });
+    const shapeProperties = elements(shape.node, "spPr")[0];
+    if (!shapeProperties) {
+      throw new Error(`Image target ${target.slotId} has no shape properties`);
+    }
+    for (const child of Array.from(shapeProperties.childNodes || [])) {
+      if (
+        child.nodeType === 1 &&
+        ["noFill", "solidFill", "gradFill", "pattFill", "blipFill"].includes(
+          localName(child),
+        )
+      ) {
+        shapeProperties.removeChild(child);
+      }
+    }
+    const blipFill = slideDocument.createElementNS(A_NS, "a:blipFill");
+    const nextBlip = slideDocument.createElementNS(A_NS, "a:blip");
+    nextBlip.setAttributeNS(R_NS, "r:embed", relationshipId);
+    const stretch = slideDocument.createElementNS(A_NS, "a:stretch");
+    stretch.appendChild(slideDocument.createElementNS(A_NS, "a:fillRect"));
+    blipFill.appendChild(nextBlip);
+    blipFill.appendChild(stretch);
+    shapeProperties.appendChild(blipFill);
+    for (const textNode of elements(shape.node, "t")) textNode.textContent = "";
+  }
+  const mediaPart = `ppt/media/v04-slide-${outputSlide}-${targetIndex}.${extension}`;
+  zip.file(mediaPart, bytes, { date: FIXED_DATE });
+  relationship.setAttribute(
+    "Target",
+    `../media/${path.posix.basename(mediaPart)}`,
+  );
+  ensureDefault(contentTypes, extension, contentTypeForImage(extension));
+  return { sourcePath: resolved, mediaPart };
+}
+
+async function updateChart({
+  zip,
+  sourceSlidePart,
+  slideRels,
+  shape,
+  target,
+  outputSlide,
+  targetIndex,
+  sourceEntries,
+  contentTypes,
+}) {
+  const chartNode = elements(shape.node, "chart")[0];
+  const relationshipId =
+    attrQName(chartNode, "r:id") || attr(chartNode, "id") || shape.relationshipId;
+  const relationship = relationshipById(slideRels, relationshipId);
+  if (!relationship) throw new Error(`Chart relationship ${relationshipId} is missing`);
+  const sourceChartPart = path.posix.normalize(
+    path.posix.join(
+      path.posix.dirname(sourceSlidePart),
+      attr(relationship, "Target"),
+    ),
+  );
+  const sourceChartXml = sourceEntries.get(sourceChartPart)?.text;
+  if (!sourceChartXml) throw new Error(`Chart part is missing: ${sourceChartPart}`);
+  const chartPart = `ppt/charts/chart-v04-${outputSlide}-${targetIndex}.xml`;
+  zip.file(chartPart, updateChartXml(sourceChartXml, target.value), {
+    date: FIXED_DATE,
+  });
+  relationship.setAttribute(
+    "Target",
+    `../charts/${path.posix.basename(chartPart)}`,
+  );
+  ensureOverride(
+    contentTypes,
+    chartPart,
+    "application/vnd.openxmlformats-officedocument.drawingml.chart+xml",
+  );
+  return { sourceChartPart, chartPart, workbookSynced: false };
+}
+
+function generatedNotesSlideXml(originalText, generatedText) {
+  const combined = [originalText, generatedText ? `[生成讲稿]\n${generatedText}` : ""]
+    .filter(Boolean)
+    .join("\n\n");
+  return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<p:notes xmlns:a="${A_NS}" xmlns:r="${R_NS}" xmlns:p="${P_NS}">
+  <p:cSld><p:spTree>
+    <p:nvGrpSpPr><p:cNvPr id="1" name=""/><p:cNvGrpSpPr/><p:nvPr/></p:nvGrpSpPr>
+    <p:grpSpPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="0" cy="0"/><a:chOff x="0" y="0"/><a:chExt cx="0" cy="0"/></a:xfrm></p:grpSpPr>
+    <p:sp>
+      <p:nvSpPr><p:cNvPr id="2" name="Notes Text Placeholder 1"/><p:cNvSpPr txBox="1"/><p:nvPr><p:ph type="body" idx="1"/></p:nvPr></p:nvSpPr>
+      <p:spPr/>
+      <p:txBody><a:bodyPr/><a:lstStyle/><a:p><a:r><a:rPr lang="zh-CN"/><a:t xml:space="preserve">${xmlEscape(combined)}</a:t></a:r><a:endParaRPr lang="zh-CN"/></a:p></p:txBody>
+    </p:sp>
+  </p:spTree></p:cSld>
+  <p:clrMapOvr><a:masterClrMapping/></p:clrMapOvr>
+</p:notes>`;
+}
+
+function notesMasterXml() {
+  return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<p:notesMaster xmlns:a="${A_NS}" xmlns:r="${R_NS}" xmlns:p="${P_NS}">
+  <p:cSld><p:spTree>
+    <p:nvGrpSpPr><p:cNvPr id="1" name=""/><p:cNvGrpSpPr/><p:nvPr/></p:nvGrpSpPr>
+    <p:grpSpPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="0" cy="0"/><a:chOff x="0" y="0"/><a:chExt cx="0" cy="0"/></a:xfrm></p:grpSpPr>
+  </p:spTree></p:cSld>
+  <p:clrMap accent1="accent1" accent2="accent2" accent3="accent3" accent4="accent4" accent5="accent5" accent6="accent6" bg1="lt1" bg2="lt2" folHlink="folHlink" hlink="hlink" tx1="dk1" tx2="dk2"/>
+  <p:hf hdr="0" ftr="0" dt="0" sldNum="0"/>
+  <p:txStyles><p:titleStyle/><p:bodyStyle/><p:otherStyle/></p:txStyles>
+</p:notesMaster>`;
+}
+
+async function ensureNotesMaster({
+  zip,
+  contentTypes,
+  presentation,
+  presentationRels,
+}) {
+  const existing = Object.keys(zip.files)
+    .filter((name) => /^ppt\/notesMasters\/notesMaster\d+\.xml$/.test(name))
+    .sort()[0];
+  if (existing) return existing;
+  const partName = "ppt/notesMasters/notesMaster1.xml";
+  zip.file(partName, notesMasterXml(), { date: FIXED_DATE });
+  zip.file(
+    relationshipPart(partName),
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="${REL_NS}"></Relationships>`,
+    { date: FIXED_DATE },
+  );
+  ensureOverride(
+    contentTypes,
+    partName,
+    "application/vnd.openxmlformats-officedocument.presentationml.notesMaster+xml",
+  );
+  const relId = "rIdNotesMasterV04";
+  appendRelationship(presentationRels, {
+    id: relId,
+    type: `${R_NS}/notesMaster`,
+    target: "notesMasters/notesMaster1.xml",
+  });
+  let list = elements(presentation, "notesMasterIdLst")[0];
+  if (!list) {
+    list = presentation.createElementNS(P_NS, "p:notesMasterIdLst");
+    presentation.documentElement.appendChild(list);
+  }
+  const idNode = presentation.createElementNS(P_NS, "p:notesMasterId");
+  idNode.setAttributeNS(R_NS, "r:id", relId);
+  list.appendChild(idNode);
+  return partName;
+}
+
+async function originalNotesText(zip, sourceSlidePart, sourceRels) {
+  const record = elements(sourceRels, "Relationship").find((node) =>
+    String(attr(node, "Type") || "").endsWith("/notesSlide"),
+  );
+  if (!record) return "";
+  const notesPart = path.posix.normalize(
+    path.posix.join(path.posix.dirname(sourceSlidePart), attr(record, "Target")),
+  );
+  const entry = zip.file(notesPart);
+  if (!entry) return "";
+  return textOf(parseXml(await entry.async("string")));
+}
+
+async function attachNotes({
+  zip,
+  slidePart,
+  slideRels,
+  notesMasterPart,
+  outputSlide,
+  originalText,
+  generatedText,
+  contentTypes,
+}) {
+  removeRelationshipsByType(slideRels, "/notesSlide");
+  const notesPart = `ppt/notesSlides/notesSlide${outputSlide}.xml`;
+  zip.file(notesPart, generatedNotesSlideXml(originalText, generatedText), {
+    date: FIXED_DATE,
+  });
+  zip.file(
+    relationshipPart(notesPart),
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="${REL_NS}"><Relationship Id="rId1" Type="${R_NS}/notesMaster" Target="../notesMasters/${path.posix.basename(notesMasterPart)}"/><Relationship Id="rId2" Type="${R_NS}/slide" Target="../slides/${path.posix.basename(slidePart)}"/></Relationships>`,
+    { date: FIXED_DATE },
+  );
+  appendRelationship(slideRels, {
+    id: "rIdNotesV04",
+    type: `${R_NS}/notesSlide`,
+    target: `../notesSlides/${path.posix.basename(notesPart)}`,
+  });
+  ensureOverride(
+    contentTypes,
+    notesPart,
+    "application/vnd.openxmlformats-officedocument.presentationml.notesSlide+xml",
+  );
+}
+
+async function sourceEntryMap(zip, slides) {
+  const map = new Map();
+  for (const slide of slides) {
+    const slideXml = await xmlFrom(zip, slide.partName);
+    const relPart = relationshipPart(slide.partName);
+    const relXml = zip.file(relPart)
+      ? await zip.file(relPart).async("string")
+      : `<Relationships xmlns="${REL_NS}"></Relationships>`;
+    map.set(slide.partName, { text: slideXml });
+    map.set(relPart, { text: relXml });
+    const rels = parseXml(relXml);
+    for (const node of elements(rels, "Relationship")) {
+      if (attr(node, "TargetMode") === "External") continue;
+      const targetPart = path.posix.normalize(
+        path.posix.join(path.posix.dirname(slide.partName), attr(node, "Target")),
+      );
+      const entry = zip.file(targetPart);
+      if (entry && !map.has(targetPart)) {
+        const binary = !/\.(xml|rels)$/i.test(targetPart);
+        map.set(targetPart, {
+          ...(binary
+            ? { bytes: await entry.async("nodebuffer") }
+            : { text: await entry.async("string") }),
+        });
+      }
+    }
+  }
+  return map;
+}
+
+export async function editPptxNative({
+  templatePath,
+  frameMap,
+  outputPath,
+  progress,
+  progressSnapshotPath,
+}) {
+  if (frameMap.fidelityMode === "hybrid-locked") {
+    throw new Error(
+      "hybrid-locked authoring requires reviewed overlay slots; automatic flattened-page authoring is blocked",
+    );
+  }
+  const zip = await loadPptx(templatePath);
+  const order = await slideRecords(zip);
+  const sourceByNumber = new Map(
+    order.slides.map((slide) => [slide.slideNumber, slide]),
+  );
+  const sourceEntries = await sourceEntryMap(zip, order.slides);
+  const contentTypes = contentTypesDocument(
+    await xmlFrom(zip, "[Content_Types].xml"),
+  );
+  const presentation = order.presentation;
+  const presentationRels = relationshipDocument(
+    order.presentationRels.document,
+  );
+  const notesMasterPart = await ensureNotesMaster({
+    zip,
+    contentTypes,
+    presentation,
+    presentationRels,
+  });
+  ensureOverride(
+    contentTypes,
+    "ppt/presentation.xml",
+    "application/vnd.openxmlformats-officedocument.presentationml.presentation.main+xml",
+  );
+
+  const slideList = elements(presentation, "sldIdLst")[0];
+  if (!slideList) throw new Error("PPTX presentation has no slide list");
+  for (const child of Array.from(slideList.childNodes || [])) {
+    if (child.nodeType === 1 && localName(child) === "sldId") {
+      slideList.removeChild(child);
+    }
+  }
+  removeRelationshipsByType(presentationRels, "/slide");
+
+  const editLog = [];
+  for (const [index, slideMap] of frameMap.outputSlides.entries()) {
+    const outputSlide = index + 1;
+    const source = sourceByNumber.get(Number(slideMap.sourceSlide));
+    if (!source) throw new Error(`Missing source slide ${slideMap.sourceSlide}`);
+    const sourceSlideXml = sourceEntries.get(source.partName)?.text;
+    const sourceRelPart = relationshipPart(source.partName);
+    const sourceRelXml = sourceEntries.get(sourceRelPart)?.text;
+    const slideDocument = parseXml(sourceSlideXml);
+    const slideRels = relationshipDocument(parseXml(sourceRelXml));
+    const originalNotes = await originalNotesText(
+      zip,
+      source.partName,
+      slideRels,
+    );
+    removeRelationshipsByType(slideRels, "/notesSlide");
+
+    for (const [targetIndex, target] of (slideMap.editTargets || []).entries()) {
+      const shape = findShapeNode(slideDocument, target);
+      let evidence = {};
+      if (target.action === "rewrite" && target.type === "text") {
+        rewriteText(shape, target.value);
+      } else if (
+        ["replace", "update-data"].includes(target.action) &&
+        target.type === "table"
+      ) {
+        replaceTable(shape, target.value);
+      } else if (target.action === "replace" && target.type === "image") {
+        evidence = await replaceImage({
+          zip,
+          slideDocument,
+          slideRels,
+          shape,
+          target,
+          outputSlide,
+          targetIndex: targetIndex + 1,
+          contentTypes,
+        });
+      } else if (
+        ["replace", "update-data"].includes(target.action) &&
+        target.type === "chart"
+      ) {
+        const error = new Error(
+          `Chart target ${target.slotId} is blocked until both the visible chart cache and embedded workbook can be synchronized`,
+        );
+        error.code = "CHART_WORKBOOK_SYNC_REQUIRED";
+        throw error;
+      } else {
+        throw new Error(
+          `Unsupported native edit ${target.action}/${target.type} for ${target.slotId}`,
+        );
+      }
+      editLog.push({
+        outputSlide,
+        sourceSlide: slideMap.sourceSlide,
+        slotId: target.slotId,
+        action: target.action,
+        type: target.type,
+        valueFingerprint: fingerprint(target.value),
+        ...evidence,
+      });
+    }
+
+    const slidePart = `ppt/slides/slide${outputSlide}.xml`;
+    await attachNotes({
+      zip,
+      slidePart,
+      slideRels,
+      notesMasterPart,
+      outputSlide,
+      originalText: originalNotes,
+      generatedText: slideMap.speakerNotes,
+      contentTypes,
+    });
+    zip.file(slidePart, serializeXml(slideDocument), { date: FIXED_DATE });
+    zip.file(relationshipPart(slidePart), serializeXml(slideRels), {
+      date: FIXED_DATE,
+    });
+    ensureOverride(
+      contentTypes,
+      slidePart,
+      "application/vnd.openxmlformats-officedocument.presentationml.slide+xml",
+    );
+    const relId = `rIdV04Slide${outputSlide}`;
+    appendRelationship(presentationRels, {
+      id: relId,
+      type: `${R_NS}/slide`,
+      target: `slides/slide${outputSlide}.xml`,
+    });
+    const slideIdNode = presentation.createElementNS(P_NS, "p:sldId");
+    slideIdNode.setAttribute("id", String(255 + outputSlide));
+    slideIdNode.setAttributeNS(R_NS, "r:id", relId);
+    slideList.appendChild(slideIdNode);
+    if (progressSnapshotPath) {
+      zip.file("ppt/presentation.xml", serializeXml(presentation), {
+        date: FIXED_DATE,
+      });
+      zip.file(
+        "ppt/_rels/presentation.xml.rels",
+        serializeXml(presentationRels),
+        { date: FIXED_DATE },
+      );
+      zip.file("[Content_Types].xml", serializeXml(contentTypes), {
+        date: FIXED_DATE,
+      });
+      const snapshotBytes = await zip.generateAsync({
+        type: "nodebuffer",
+        compression: "DEFLATE",
+        compressionOptions: { level: 6 },
+        platform: "UNIX",
+      });
+      await fs.mkdir(path.dirname(progressSnapshotPath), { recursive: true });
+      await fs.writeFile(progressSnapshotPath, snapshotBytes);
+    }
+    await progress?.({
+      event: "slide-authored",
+      outputSlide,
+      sourceSlide: Number(slideMap.sourceSlide),
+      slideCount: frameMap.outputSlides.length,
+      snapshotPptx: progressSnapshotPath
+        ? path.resolve(progressSnapshotPath)
+        : undefined,
+    });
+  }
+
+  zip.file("ppt/presentation.xml", serializeXml(presentation), {
+    date: FIXED_DATE,
+  });
+  zip.file(
+    "ppt/_rels/presentation.xml.rels",
+    serializeXml(presentationRels),
+    { date: FIXED_DATE },
+  );
+  const removedOrphanedParts = pruneOrphanedSlideParts(
+    zip,
+    contentTypes,
+    frameMap.outputSlides.length,
+  );
+  zip.file("[Content_Types].xml", serializeXml(contentTypes), {
+    date: FIXED_DATE,
+  });
+  for (const entry of Object.values(zip.files)) entry.date = FIXED_DATE;
+  const bytes = await zip.generateAsync({
+    type: "nodebuffer",
+    compression: "DEFLATE",
+    compressionOptions: { level: 9 },
+    platform: "UNIX",
+  });
+  await fs.mkdir(path.dirname(outputPath), { recursive: true });
+  await fs.writeFile(outputPath, bytes);
+  return {
+    schemaVersion: 1,
+    output: path.resolve(outputPath),
+    sha256: await sha256File(outputPath),
+    slideCount: frameMap.outputSlides.length,
+    editLog,
+    removedOrphanedParts,
+  };
+}
+
+export async function inspectPptxPackage(pptxPath) {
+  const zip = await loadPptx(pptxPath);
+  const order = await slideRecords(zip);
+  const notes = Object.keys(zip.files).filter((name) =>
+    /^ppt\/notesSlides\/notesSlide\d+\.xml$/.test(name),
+  );
+  return {
+    path: path.resolve(pptxPath),
+    sha256: await sha256File(pptxPath),
+    slideCount: order.slides.length,
+    notesSlideCount: notes.length,
+    macroParts: Object.keys(zip.files).filter((name) => /vbaProject/i.test(name)),
+    externalRelationships: (
+      await Promise.all(
+        order.slides.map(async (slide) => relationships(zip, slide.partName)),
+      )
+    )
+      .flatMap((record) => record.records)
+      .filter((record) => record.targetMode === "External")
+      .map((record) => record.target),
+  };
+}