slidemind 0.1.9 → 0.2.0

package/src/pptx/fill/engine.mjs

@@ -0,0 +1,1273 @@
+// The fill-template deck builder — the host-free `build-pptx` path for
+// proposal-style packs (mode: "fill-template" in the pack's skill.json).
+//
+// Assembly direction: the template .pptx is cloned WHOLE (masters, layouts,
+// media, tags, embeddings), then only declared shapes inside the clone are
+// patched. Slides are duplicated/dropped/reordered by the deck's file order;
+// native one-slide .pptx files in slides/ (engine-search folds) are inserted
+// carrying their own layout+master. Nothing is ever rendered from HTML.
+//
+// The pack owns every template-specific fact: fields.json (semantic name →
+// shape id, {shape,paragraph} targets, {image:{anchor,z}} picture wells),
+// repeats.json (member shapes + strategy + timeline), and skill.json `policy`
+// (immutable tables, hygiene deletions, freeform placeholders).
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { unzip, zip, readText } from "../zip.mjs";
+import { slideOrderPaths, relsPathFor, resolvePartPath } from "../ooxml.mjs";
+import { parseSlideFile, layoutNumber } from "./parse-slides.mjs";
+import {
+  setShapeText, setParagraphText, setShapeFill, deleteShapes, cloneShape,
+  getGeom, setGeom, fillTable, mergedCellViolations, insertPicture,
+  insertPictureAtGeom, findShape, esc, imageSize, cellText, blocks,
+  shapeFillXml, shapeRunRPr, setShapeFillXml,
+} from "./xml.mjs";
+
+const enc = (s) => new TextEncoder().encode(s);
+const RESERVED_PROPS = new Set(["repeat", "tables", "patches", "highlight"]);
+const IMAGE_PATH_RE = /\.(png|jpe?g)$/i;
+
+export async function buildFillTemplateDeck({ deckDir, skill, outPath, onLog }) {
+  const log = makeLog(onLog);
+  const pack = loadPack(skill);
+  const locale = skill.locale || "en";
+  const fieldsByNo = pack.fields[locale] ?? {};
+  const repeatsByNo = pack.repeats[locale] ?? {};
+
+  if (!skill.templatePath || !fs.existsSync(skill.templatePath)) {
+    throw new Error(
+      `template "${skill.templateKey}" not found in pack ${skill.skillDir} — check plan.md frontmatter and skill.json templates`,
+    );
+  }
+
+  // ---- deck reading ---------------------------------------------------------
+  const slidesDir = path.join(deckDir, "slides");
+  const entries = fs.readdirSync(slidesDir)
+    .filter((f) => f.endsWith(".jsx") || f.endsWith(".pptx"))
+    .sort((a, b) => a.localeCompare(b, "en", { numeric: true }));
+  if (entries.length === 0) throw new Error(`no .jsx or .pptx slides in ${slidesDir}`);
+
+  const problems = [];
+  const warnings = [];
+  const sequence = []; // { kind: "master", no, props, file } | { kind: "insert", file, buf }
+
+  // In-deck freeform pairing: NN-name.jsx (create-slides source) renders to a
+  // sibling NN-name.pptx artifact — when both exist, the .pptx carries the
+  // slide and the .jsx is source only.
+  const renderedStems = new Set(
+    entries.filter((f) => f.endsWith(".pptx")).map((f) => f.replace(/\.pptx$/, "")),
+  );
+
+  for (const file of entries) {
+    if (file.endsWith(".pptx")) {
+      sequence.push({ kind: "insert", file, buf: fs.readFileSync(path.join(slidesDir, file)) });
+      continue;
+    }
+    if (renderedStems.has(file.replace(/\.jsx$/, ""))) continue;
+    const src = fs.readFileSync(path.join(slidesDir, file), "utf8");
+    let parsed;
+    try {
+      parsed = parseSlideFile(src, file);
+    } catch (err) {
+      problems.push(err.message);
+      continue;
+    }
+    const layout = layoutNumber(parsed.component, locale);
+    if (!layout) {
+      problems.push(`${file}: <${parsed.component}> is a freeform (create-slides) slide with no ` +
+        `rendered artifact next to it — 'slidemind build-pptx' renders slides/${file.replace(/\.jsx$/, "")}.pptx ` +
+        `automatically when a paired add-in backend is reachable`);
+      continue;
+    }
+    if (layout.warn) warnings.push(`${file}: ${layout.warn}`);
+    const no = String(layout.no);
+
+    if ((pack.policy.freeform ?? []).includes(no)) {
+      if (Object.keys(parsed.props).length > 0) {
+        problems.push(`${file}: slide ${no} is a freeform placeholder — it takes no props. ` +
+          `Keep it bare to keep the master placeholder, or delete the file to drop the slide.`);
+        continue;
+      }
+      warnings.push(`${file}: keeping the master's slide-${no} placeholder (freeform replacement pending)`);
+    }
+
+    validateProps(parsed.props, fieldsByNo[no] ?? {}, repeatsByNo[no] ?? {}, pack.policy, no, file, problems);
+    sequence.push({ kind: "master", no: Number(no), props: parsed.props, file });
+  }
+
+  checkIdentities(sequence, warnings, problems);
+  if (problems.length) {
+    const err = new Error(`deck has ${problems.length} authoring error(s):\n  - ${problems.join("\n  - ")}`);
+    err.problems = problems;
+    throw err;
+  }
+
+  // ---- clone the template & patch ------------------------------------------
+  const files = unzip(fs.readFileSync(skill.templatePath));
+  const order = slideOrderPaths(files);
+  const partOfNo = (no) => order[no - 1];
+
+  const seen = new Map();     // master no → instance count
+  const pristine = new Map(); // master no → untouched template slide XML
+  const output = [];          // { part, isNew }
+  let insertCounter = 0;
+
+  for (const item of sequence) {
+    if (item.kind === "insert") {
+      insertCounter++;
+      const part = insertForeignSlide(files, item.buf, insertCounter, item.file, log, warnings);
+      output.push({ part, isNew: true });
+      continue;
+    }
+    const basePart = partOfNo(item.no);
+    if (!basePart) throw new Error(`${item.file}: template has no slide ${item.no}`);
+    const n = (seen.get(item.no) ?? 0) + 1;
+    seen.set(item.no, n);
+    if (n === 1) pristine.set(item.no, files[basePart]);
+
+    let part = basePart;
+    if (n > 1) {
+      // Copies start from the UNTOUCHED template slide, not from the patched
+      // first instance — otherwise fields the copy doesn't set would leak the
+      // first instance's content.
+      part = cloneSlidePart(files, basePart, pristine.get(item.no), log);
+    }
+    log.slide(`${item.file} → template slide ${item.no}${n > 1 ? ` (copy ${n})` : ""}`);
+    let xml = readText(files, part);
+    const fieldMap = fieldsByNo[String(item.no)] ?? {};
+    xml = applyProps(xml, item, fieldMap, repeatsByNo[String(item.no)] ?? {},
+      pack.policy, files, part, deckDir, log, warnings);
+    xml = applyDeckChrome(xml, fieldMap, skill.planMeta ?? {}, item.props, log);
+    xml = applyHygiene(xml, pack.policy, item.no, log);
+    files[part] = enc(xml);
+    output.push({ part, isNew: n > 1 });
+  }
+
+  // Hygiene also applies to untouched (clone-only) slides that made it in.
+  // Drop every template slide the deck never referenced.
+  const referenced = new Set(output.map((o) => o.part));
+  for (let no = 1; no <= order.length; no++) {
+    if (![...seen.keys()].includes(no)) {
+      dropSlide(files, order[no - 1], log);
+    }
+  }
+
+  rebuildPresentation(files, output, log);
+  rebuildAppProps(files, output, log);
+  // AFTER the rebuild: cloned slides are only registered in
+  // presentation.xml.rels by rebuildPresentation, so pruning any earlier would
+  // sweep them up as orphans.
+  pruneOrphanParts(files, log);
+
+  const integrity = checkIntegrity(files);
+  for (const issue of integrity) warnings.push(`integrity: ${issue}`);
+  if (integrity.length) {
+    throw new Error(`integrity check failed:\n  - ${integrity.join("\n  - ")}`);
+  }
+
+  const finalOut = outPath
+    ? path.resolve(outPath)
+    : path.join(deckDir, `${path.basename(deckDir)}.pptx`);
+  fs.writeFileSync(finalOut, zip(files));
+  return { outPath: finalOut, slideCount: output.length, warnings };
+}
+
+// ---------------------------------------------------------------------------
+// Pack
+// ---------------------------------------------------------------------------
+
+function loadPack(skill) {
+  const read = (name, fallback) => {
+    const p = path.join(skill.skillDir, name);
+    if (!fs.existsSync(p)) return fallback;
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  };
+  const fields = read("fields.json", null);
+  if (!fields) throw new Error(`pack ${skill.skillDir} has no fields.json`);
+  return {
+    fields,
+    repeats: read("repeats.json", {}),
+    policy: skill.manifest.policy ?? {},
+  };
+}
+
+function validateProps(props, fieldMap, repeatMap, policy, no, file, problems) {
+  for (const [key, value] of Object.entries(props)) {
+    if (key === "repeat") {
+      for (const group of Object.keys(value ?? {})) {
+        if (!repeatMap[group]) {
+          problems.push(`${file}: repeat group "${group}" is not declared for slide ${no} in repeats.json`);
+        }
+      }
+      continue;
+    }
+    if (key === "tables") {
+      const immutable = (policy.immutableTables ?? {})[no] ?? [];
+      for (const frameId of Object.keys(value ?? {})) {
+        if (immutable.includes(frameId)) {
+          problems.push(`${file}: table "${frameId}" on slide ${no} is immutable (baked into the template) — never pass it`);
+        }
+      }
+      continue;
+    }
+    if (key === "patches") {
+      // Silent near-misses here destroy content (a `paragraph` key that gets
+      // ignored replaces the WHOLE shape) — validate the full patch shape.
+      for (const patch of Array.isArray(value) ? value : []) {
+        const keys = Object.keys(patch ?? {});
+        const unknown = keys.filter((k) => !["shape", "text", "fill", "paragraph"].includes(k));
+        if (unknown.length) {
+          problems.push(`${file}: patch has unknown key(s) ${unknown.join(", ")} — patches support {shape, text}, {shape, paragraph, text}, {shape, fill}`);
+        }
+        if (patch?.shape == null) {
+          problems.push(`${file}: every patch needs a "shape" id`);
+        }
+        if (patch?.paragraph != null && patch?.text == null) {
+          problems.push(`${file}: a paragraph-targeted patch needs "text"`);
+        }
+      }
+      continue;
+    }
+    if (RESERVED_PROPS.has(key)) continue;
+    if (!(key in fieldMap)) {
+      const near = nearest(key, Object.keys(fieldMap));
+      problems.push(`${file}: unknown prop "${key}" for slide ${no}${near ? ` — did you mean "${near}"?` : ""}`);
+    }
+  }
+}
+
+function nearest(key, candidates) {
+  let best = null;
+  let bestDist = 3;
+  for (const c of candidates) {
+    const d = editDistance(key.toLowerCase(), c.toLowerCase());
+    if (d < bestDist) { bestDist = d; best = c; }
+  }
+  return best;
+}
+
+function editDistance(a, b) {
+  const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 0; j <= b.length; j++) dp[0][j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      dp[i][j] = Math.min(
+        dp[i - 1][j] + 1,
+        dp[i][j - 1] + 1,
+        dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+  }
+  return dp[a.length][b.length];
+}
+
+// ---------------------------------------------------------------------------
+// Cross-slide identities (the catalog's consistency table, as code)
+// ---------------------------------------------------------------------------
+
+const asLines = (v) => (Array.isArray(v) ? v : String(v ?? "").split("\n")).map((s) => s.trim()).filter(Boolean);
+
+function checkIdentities(sequence, warnings, problems) {
+  const slide = (no) => sequence.filter((s) => s.kind === "master" && s.no === no);
+  const approach = slide(10)[0];
+  const details = slide(11);
+  const gantt = slide(13)[0];
+  const calc = slide(16)[0];
+
+  const wpItems = approach?.props?.repeat?.workPackages ?? null;
+  const ganttItems = gantt?.props?.repeat?.workPackages ?? null;
+
+  if (wpItems && details.length && wpItems.length !== details.length) {
+    problems.push(`WP count mismatch: slide 10 declares ${wpItems.length} work packages but there are ${details.length} WP-detail files (slide 11)`);
+  }
+  // Every WP detail must carry FULL bullet lists — a section left empty (or a
+  // one-liner) is a defect in a client proposal, not a style choice.
+  details.forEach((d, i) => {
+    for (const section of ["services", "assumptions", "deliverables"]) {
+      const lines = asLines(d.props?.[section]);
+      if (lines.length === 0) {
+        problems.push(`${d.file}: WP detail ${i + 1} has no "${section}" — every WP detail needs all three bullet lists filled`);
+      } else if (lines.length < 3) {
+        warnings.push(`${d.file}: "${section}" has only ${lines.length} bullet(s) — WP details expect full lists (3–5)`);
+      }
+    }
+  });
+  if (wpItems && ganttItems && wpItems.length !== ganttItems.length) {
+    problems.push(`WP count mismatch: slide 10 has ${wpItems.length} work packages, the project plan (13) has ${ganttItems.length} rows`);
+  }
+  if (ganttItems && details.length === ganttItems.length) {
+    ganttItems.forEach((item, i) => {
+      const canonical = asLines(details[i]?.props?.deliverables);
+      const row = asLines(item.deliverable);
+      if (canonical.length && row.length && canonical.join("\n") !== row.join("\n")) {
+        problems.push(`deliverables drift: gantt row ${i + 1} must repeat WP-${i + 1}'s deliverables verbatim (slide 11 owns them)`);
+      }
+    });
+  }
+  if (wpItems && ganttItems) {
+    ganttItems.forEach((item, i) => {
+      if (item.title && wpItems[i]?.title && item.title !== wpItems[i].title) {
+        problems.push(`WP name drift: slide 10 card ${i + 1} is "${wpItems[i].title}" but gantt row ${i + 1} is "${item.title}"`);
+      }
+    });
+  }
+  for (const [frameId, rows] of Object.entries(calc?.props?.tables ?? {})) {
+    if (!Array.isArray(rows) || !wpItems) continue;
+    const labels = rows.slice(1, -1).map((r) => String(r[0] ?? ""));
+    labels.forEach((label, i) => {
+      if (wpItems[i]?.title && label && label !== wpItems[i].title) {
+        problems.push(`WP name drift: calculation table ${frameId} row ${i + 1} is "${label}" but slide 10 card ${i + 1} is "${wpItems[i].title}"`);
+      }
+    });
+  }
+  // Price echo: the contracted total should appear in the management summary.
+  const costRows = calc?.props?.tables?.["15"];
+  if (Array.isArray(costRows)) {
+    const grand = String(costRows[costRows.length - 1]?.slice(-1)[0] ?? "");
+    const digits = grand.replace(/[^\d.,]/g, "");
+    const summary = slide(7)[0];
+    if (digits && summary?.props?.approach && !String(summary.props.approach).includes(digits)) {
+      warnings.push(`slide 7's approach paragraph does not mention the contracted total ${grand} from table 15`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Per-slide ops
+// ---------------------------------------------------------------------------
+
+function applyProps(xml, item, fieldMap, repeatMap, policy, files, part, deckDir, log, warnings) {
+  const { props } = item;
+
+  for (const [key, value] of Object.entries(props)) {
+    if (RESERVED_PROPS.has(key)) continue;
+    const target = fieldMap[key];
+    if (target == null) continue; // validated earlier
+    if (typeof target === "object" && target.image) {
+      xml = applyImage(xml, files, part, deckDir, String(value), target.image, log);
+    } else if (typeof target === "object" && target.shape != null) {
+      xml = setParagraphText(xml, target.shape, target.paragraph, String(value), log);
+    } else {
+      xml = setShapeText(xml, target, value, log);
+    }
+  }
+
+  for (const [group, items] of Object.entries(props.repeat ?? {})) {
+    xml = applyRepeat(xml, repeatMap[group], items, group, log, warnings, {
+      highlight: props.highlight,
+      files, part, deckDir,
+    });
+  }
+
+  for (const [frameId, rows] of Object.entries(props.tables ?? {})) {
+    xml = fillTable(xml, frameId, rows, log);
+  }
+
+  for (const patch of props.patches ?? []) {
+    if (patch.paragraph != null && patch.text != null) {
+      xml = setParagraphText(xml, patch.shape, patch.paragraph, String(patch.text), log);
+    } else if (patch.text != null) {
+      xml = setShapeText(xml, patch.shape, patch.text, log);
+    }
+    if (patch.fill != null) xml = setShapeFill(xml, patch.shape, patch.fill, log);
+  }
+
+  return xml;
+}
+
+function applyHygiene(xml, policy, no, log) {
+  const ids = (policy.deleteShapes ?? {})[String(no)] ?? [];
+  if (ids.length) xml = deleteShapes(xml, ids, log);
+  // Some template slides ship internal authoring highlights inside text that
+  // stays (general conditions) — the pack lists them for a wholesale strip.
+  if ((policy.stripHighlights ?? []).includes(String(no)) && /<a:highlight>/.test(xml)) {
+    xml = xml.replace(/<a:highlight>[\s\S]*?<\/a:highlight>/g, "");
+    log.ok("stripped template highlights");
+  }
+  return xml;
+}
+
+// Deck-wide chrome from plan.md frontmatter: `footer:` / `date:` apply to every
+// master-backed slide that declares the field and wasn't explicitly authored.
+// Shapes driven by live PowerPoint fields (<a:fld> — auto date, slide number)
+// are never overwritten with static text.
+function applyDeckChrome(xml, fieldMap, planMeta, props, log) {
+  for (const key of ["footer", "date"]) {
+    if (!planMeta[key] || props[key] != null || fieldMap[key] == null) continue;
+    const target = fieldMap[key];
+    if (typeof target === "object") continue;
+    const hit = findShape(xml, target, ["sp"]);
+    if (!hit || /<a:fld /.test(hit.block)) continue;
+    xml = setShapeText(xml, target, planMeta[key], log);
+  }
+  return xml;
+}
+
+// ---- repeats ---------------------------------------------------------------
+
+function applyRepeat(xml, group, items, name, log, warnings, ctx = {}) {
+  if (!group) return xml;
+  const n = items.length;
+  if (n < (group.min ?? 1) || n > (group.max ?? 99)) {
+    throw new Error(`repeat "${name}": ${n} items is outside the template's supported range ${group.min}..${group.max}`);
+  }
+  const base = group.baseCount ?? group.members[0].shapes.length;
+
+  if (group.strategy === "ganttRow" && n > base) {
+    throw new Error(`repeat "${name}": the template carries ${base} rows and row cloning is not supported yet — cap at ${base}`);
+  }
+
+  // Extend member shape lists by cloning the last member when n > base.
+  const members = group.members.map((m) => ({ ...m, shapes: [...m.shapes] }));
+  if (n > base) {
+    for (const m of members) {
+      for (let k = base; k < n; k++) {
+        const res = cloneShape(xml, m.shapes[base - 1], log);
+        xml = res.xml;
+        m.shapes.push(String(res.newId));
+      }
+    }
+  }
+
+  // Even horizontal respacing across the ORIGINAL span (first..last member).
+  // Above the template's base count the slot pitch shrinks, so member widths
+  // scale down with it — otherwise neighbouring cards overlap.
+  if (group.strategy === "evenSpacedHorizontal" && n !== 1) {
+    const widthScale = n > base ? (base - 1) / (n - 1) : 1;
+    for (const m of members) {
+      const first = getGeom(xml, m.shapes[0]);
+      const last = getGeom(xml, m.shapes[base - 1]);
+      if (!first || !last) continue;
+      for (let i = 0; i < n; i++) {
+        const g = getGeom(xml, m.shapes[i]);
+        if (!g) continue;
+        const x = first.x + (i * (last.x - first.x)) / (n - 1);
+        xml = setGeom(xml, m.shapes[i], { ...g, x, cx: g.cx * widthScale }, log);
+      }
+    }
+  }
+
+  // Bars carry their formatting in a styled sibling when the template pill is
+  // empty — the pack can name that sibling explicitly (textDonor), else pick
+  // the first member shape that has its own run properties.
+  const donorFor = (m) => {
+    if (group.textDonor) return group.textDonor;
+    for (const id of m.shapes) {
+      const hit = findShape(xml, id, ["sp"]);
+      if (hit && /<a:rPr[\s>]/.test(hit.block)) return id;
+    }
+    return null;
+  };
+
+  // Highlight state-swap (the approach chevron "where we are" marker): the
+  // template's first member is the active style, the second the inactive one —
+  // both probed from the slide itself, never hardcoded.
+  const hl = Number(ctx.highlight) || 0;
+  const titleRole = members.find((m) => m.role === "title");
+  const hlStyles = hl && titleRole && titleRole.shapes.length >= 2
+    ? {
+        activeFill: shapeFillXml(xml, titleRole.shapes[0]),
+        inactiveFill: shapeFillXml(xml, titleRole.shapes[1]),
+        activeRPr: shapeRunRPr(xml, titleRole.shapes[0]),
+        inactiveRPr: shapeRunRPr(xml, titleRole.shapes[1]),
+      }
+    : null;
+
+  const pendingImages = [];
+  for (const m of members) {
+    const donorId = donorFor(m);
+    for (let i = 0; i < n; i++) {
+      const item = items[i] ?? {};
+      const value = item[m.role];
+      if (value == null) continue;
+      if (typeof value === "string" && IMAGE_PATH_RE.test(value.trim())) {
+        // An image path in a repeat role (e.g. illustration icons) replaces
+        // the placeholder box with a contain-fit picture — after respacing.
+        pendingImages.push({ shapeId: m.shapes[i], file: value.trim() });
+        continue;
+      }
+      const opts = { donorId };
+      if (hlStyles && m === titleRole) {
+        opts.rPrOverride = i === hl - 1 ? hlStyles.activeRPr : hlStyles.inactiveRPr;
+      }
+      xml = m.paragraph != null
+        ? setParagraphText(xml, m.shapes[i], m.paragraph, String(value), log)
+        : setShapeText(xml, m.shapes[i], value, log, opts);
+    }
+  }
+  // Surplus members disappear entirely (shape, not just text) — deduped, since
+  // paragraph-targeted members legitimately share one shape (name/level).
+  if (n < base) {
+    const surplus = new Set();
+    for (const m of members) {
+      for (const id of m.shapes.slice(n, base)) surplus.add(id);
+    }
+    xml = deleteShapes(xml, [...surplus], log);
+  }
+
+  if (hlStyles) {
+    for (let i = 0; i < n; i++) {
+      const fill = i === hl - 1 ? hlStyles.activeFill : hlStyles.inactiveFill;
+      xml = setShapeFillXml(xml, titleRole.shapes[i], fill, log);
+    }
+    log.ok(`highlighted work package ${hl}`);
+  }
+
+  for (const img of pendingImages) {
+    xml = replaceShapeWithImage(xml, img.shapeId, img.file, ctx, log);
+  }
+
+  // Gantt bars: span from startMonth/endMonth via the template's timeline.
+  if (group.strategy === "ganttRow" && group.timeline) {
+    const { leftX, monthWidth, months } = group.timeline;
+    const bars = members.find((m) => m.role === "bar");
+    items.forEach((item, i) => {
+      if (!bars || item.startMonth == null || item.endMonth == null) return;
+      const s = Math.max(1, Math.min(months, item.startMonth));
+      const e = Math.max(s, Math.min(months, item.endMonth));
+      const g = getGeom(xml, bars.shapes[i]);
+      if (!g) return;
+      xml = setGeom(xml, bars.shapes[i], {
+        ...g,
+        x: leftX + (s - 1) * monthWidth,
+        cx: (e - s + 1) * monthWidth,
+      }, log);
+      log.ok(`bar ${i + 1} spans ${s}..${e}`);
+      // A repositioned bar makes the row's fixed annotations (dashed "planned"
+      // extensions) stale — drop them with the move. Track lines stay.
+      const stale = group.annotations?.[i] ?? [];
+      if (stale.length) xml = deleteShapes(xml, stale, log);
+    });
+  }
+
+  // Trimmed rows lose their furniture too (track lines AND annotations) — the
+  // member shapes alone leave orphan rules behind otherwise.
+  if (n < base) {
+    for (let i = n; i < base; i++) {
+      const gone = [...(group.furniture?.[i] ?? []), ...(group.annotations?.[i] ?? [])];
+      if (gone.length) xml = deleteShapes(xml, gone, log);
+    }
+  }
+
+  return xml;
+}
+
+// ---- images ------------------------------------------------------------------
+
+// Register an image file as a media part + slide relationship. Returns null
+// (with a log line) when the file is missing.
+function addImageMedia(files, part, deckDir, file, log) {
+  const imgPath = path.isAbsolute(file) ? file : path.join(deckDir, file);
+  if (!fs.existsSync(imgPath)) {
+    log.miss(`image ${file} not found (resolved ${imgPath})`);
+    return null;
+  }
+  const buf = fs.readFileSync(imgPath);
+  const ext = path.extname(imgPath).slice(1).toLowerCase().replace("jpg", "jpeg");
+  const mediaName = `ppt/media/fillImage${Object.keys(files).filter((p) => p.startsWith("ppt/media/fillImage")).length + 1}.${ext}`;
+  files[mediaName] = new Uint8Array(buf);
+  ensureDefaultContentType(files, ext, ext === "png" ? "image/png" : "image/jpeg");
+
+  const relsPath = relsPathFor(part);
+  let rels = readText(files, relsPath) ??
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"></Relationships>`;
+  const relId = nextRelId(rels);
+  rels = rels.replace(
+    "</Relationships>",
+    `<Relationship Id="${relId}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" Target="../media/${path.posix.basename(mediaName)}"/></Relationships>`,
+  );
+  files[relsPath] = enc(rels);
+  return { relId, dims: imageSize(buf) };
+}
+
+function applyImage(xml, files, part, deckDir, file, spec, log) {
+  const media = addImageMedia(files, part, deckDir, file, log);
+  if (!media) return xml;
+  const z = spec.z ?? "below";
+  if (z === "above") {
+    // The picture covers its anchor (e.g. the client-logo well) — blank the
+    // anchor's placeholder text so it cannot bleed through transparency.
+    xml = setShapeText(xml, spec.anchor, "", log);
+  }
+  return insertPicture(xml, spec.anchor, media.relId, media.dims, { z }, log);
+}
+
+// Replace a placeholder box (e.g. the approach "Illustration" wells) with a
+// contain-fit image at the box's geometry — the box itself is removed.
+function replaceShapeWithImage(xml, shapeId, file, ctx, log) {
+  const geom = getGeom(xml, shapeId);
+  if (!geom) return log.miss(`image target ${shapeId} has no geometry`), xml;
+  const media = addImageMedia(ctx.files, ctx.part, ctx.deckDir, file, log);
+  if (!media) return xml;
+  xml = deleteShapes(xml, [shapeId], log);
+  return insertPictureAtGeom(xml, geom, media.relId, media.dims, log);
+}
+
+// ---------------------------------------------------------------------------
+// Slide duplication (self-contained, the way PowerPoint's writer does it)
+// ---------------------------------------------------------------------------
+
+let clonePartCounter = 0;
+
+// think-cell's payload on a slide: the custData tag pointer and the invisible
+// TCLayout OLE frames. Both carry an object identity that must appear once per
+// presentation — a second copy makes PowerPoint strip it and report "couldn't
+// read some content". Prefix-tolerant: engine slices arrive with generic ns
+// prefixes rather than p:.
+export function stripThinkCell(xml) {
+  return xml
+    .replace(/<(?:[\w.-]+:)?custDataLst>[\s\S]*?<\/(?:[\w.-]+:)?custDataLst>/g, "")
+    .replace(/<((?:[\w.-]+:)?)graphicFrame>[\s\S]*?<\/\1graphicFrame>/g, (frame) =>
+      /progId="TCLayout/.test(frame) ? "" : frame,
+    );
+}
+
+// PowerPoint requires every <p:sp> to carry a <p:txBody>, even when the shape
+// holds no text. The schema marks it optional and LibreOffice renders happily
+// without it, but PowerPoint answers a text-free shape with "couldn't read some
+// content" and repairs the file by inserting an empty body — so we insert it
+// first. The add-in's translator omits it for pure-geometry boxes, which is the
+// real origin; normalizing here also fixes artifacts already cached on disk and
+// any slide folded in from a foreign deck.
+// NB the `(?:\s[^>]*)?` — <p:sp> takes an optional useBgFill attribute, which
+// PowerPoint writes whenever a user picks "background fill". Matching the bare
+// literal <p:sp> would silently exempt exactly those shapes from the guard.
+const SP_OPEN = String.raw`<((?:[\w.-]+:)?)sp((?:\s[^>]*)?)>`;
+
+export function ensureShapeTextBodies(xml) {
+  const a = xml.match(/xmlns:([\w.-]+)="http:\/\/schemas\.openxmlformats\.org\/drawingml\/2006\/main"/)?.[1] ?? "a";
+  return xml.replace(
+    new RegExp(`${SP_OPEN}([\\s\\S]*?)</\\1sp>`, "g"),
+    (whole, pfx, attrs, body) => {
+      if (new RegExp(`<${pfx}txBody[\\s>]`).test(body)) return whole;
+      return (
+        `<${pfx}sp${attrs}>${body}` +
+        `<${pfx}txBody><${a}:bodyPr/><${a}:lstStyle/><${a}:p/></${pfx}txBody>` +
+        `</${pfx}sp>`
+      );
+    },
+  );
+}
+
+// Shapes live in layouts and masters too, not just slides — an inserted deck
+// brings its own of each.
+export function shapesWithoutTextBody(xml) {
+  return [...xml.matchAll(new RegExp(`${SP_OPEN}(?:(?!</\\1sp>)[\\s\\S])*</\\1sp>`, "g"))]
+    .filter((m) => !new RegExp(`<${m[1]}txBody[\\s>]`).test(m[0])).length;
+}
+
+function cloneSlidePart(files, basePart, srcBytes, log) {
+  const maxNo = Math.max(
+    ...Object.keys(files)
+      .map((p) => (p.match(/^ppt\/slides\/slide(\d+)\.xml$/) || [])[1])
+      .filter(Boolean)
+      .map(Number),
+  );
+  const newPart = `ppt/slides/slide${maxNo + 1}.xml`;
+
+  // Strip think-cell from the COPY. Its custData + TCLayout OLE frames carry an
+  // object identity that PowerPoint refuses to see on two slides at once: given
+  // a duplicate it removes the copy's tag and OLE parts on open and reports
+  // "couldn't read some content". The first instance keeps its payload exactly
+  // as the template ships it; the frames are invisible layout metadata, so the
+  // copies lose nothing on screen. Same treatment the insert path applies.
+  const xml = stripThinkCell(new TextDecoder().decode(srcBytes ?? files[basePart]));
+  files[newPart] = enc(xml);
+
+  // Rels: drop the notes pointer; duplicate the per-slide unique parts that
+  // SURVIVED the strip (a non-think-cell embedded object, a real tag list) so
+  // clones stay self-contained, and drop the relationships the strip orphaned.
+  const liveIds = new Set(
+    [...xml.matchAll(/\br:(?:id|embed|link)="([^"]+)"/g)].map((m) => m[1]),
+  );
+  let rels = readText(files, relsPathFor(basePart)) ?? "";
+  rels = rels.replace(/<Relationship [^>]*Type="[^"]*\/notesSlide"[^>]*\/>/g, "");
+  rels = rels.replace(/<Relationship [^>]*\/>/g, (rel) => {
+    const type = (rel.match(/Type="([^"]+)"/) || [])[1] ?? "";
+    if (!/\/(tags|oleObject)$/.test(type)) return rel;
+    const id = (rel.match(/Id="([^"]+)"/) || [])[1];
+    return id && !liveIds.has(id) ? "" : rel;
+  });
+  for (const m of [...rels.matchAll(/<Relationship [^>]*\/>/g)]) {
+    const rel = m[0];
+    const type = (rel.match(/Type="([^"]+)"/) || [])[1] ?? "";
+    if (!/\/(tags|oleObject)$/.test(type)) continue;
+    const target = (rel.match(/Target="([^"]+)"/) || [])[1];
+    const srcPart = resolvePartPath("ppt/slides", target);
+    if (!files[srcPart]) continue;
+    clonePartCounter++;
+    const extM = srcPart.match(/\.([a-z0-9]+)$/i);
+    const dupPart = srcPart.replace(/(\.[a-z0-9]+)$/i, `Fill${clonePartCounter}$1`);
+    files[dupPart] = files[srcPart];
+    rels = rels.replace(rel, rel.replace(`Target="${target}"`, `Target="${target.replace(/(\.[a-z0-9]+)$/i, `Fill${clonePartCounter}$1`)}"`));
+    duplicateOverride(files, srcPart, dupPart);
+    void extM;
+  }
+  files[relsPathFor(newPart)] = enc(rels);
+  duplicateOverride(files, basePart, newPart);
+  log.ok(`cloned slide part → ${newPart}`);
+  return newPart;
+}
+
+function duplicateOverride(files, srcPart, dupPart) {
+  const ct = readText(files, "[Content_Types].xml");
+  const m = ct.match(new RegExp(`<Override PartName="/${srcPart.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}"[^>]*/>`));
+  if (m) {
+    files["[Content_Types].xml"] = enc(
+      ct.replace("</Types>", m[0].replace(`/${srcPart}`, `/${dupPart}`) + "</Types>"),
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Foreign one-slide inserts (engine-search folds, later freeform renders)
+// ---------------------------------------------------------------------------
+
+// `sldMasterId` and `sldLayoutId` share ONE id space. PowerPoint allocates both
+// from it and treats any collision anywhere in that space as repairable
+// corruption — see the same rule already written down at app-props.mjs:9-17 for
+// the add-in splice path. So an inserted master registered at "one past the
+// highest sldMasterId" lands squarely on the host master's FIRST layout id
+// (host master 2147483757, its layouts 2147483758…2147483771), and the deck
+// repairs on open even though every id is unique within its own kind.
+//
+// Collect every id of both kinds, from presentation.xml and every master.
+export function usedMasterLayoutIds(files, presXml) {
+  const used = new Set();
+  const pres = presXml ?? readText(files, "ppt/presentation.xml") ?? "";
+  for (const m of pres.matchAll(/<p:sldMasterId\b[^>]*\bid="(\d+)"/g)) used.add(Number(m[1]));
+  for (const part of Object.keys(files)) {
+    if (!/^ppt\/slideMasters\/[^/]+\.xml$/.test(part)) continue;
+    for (const m of (readText(files, part) ?? "").matchAll(/<p:sldLayoutId\b[^>]*\bid="(\d+)"/g)) {
+      used.add(Number(m[1]));
+    }
+  }
+  return used;
+}
+
+// Both kinds live in the >= 2^31 space (ISO-29500-4: ST_SlideMasterId and
+// ST_SlideLayoutId are minInclusive 2147483648, and unsignedInt caps at 2^32-1).
+//
+// Allocate ABOVE everything in use rather than filling the template's gaps.
+// Both are valid per the schema, but every PowerPoint-authored deck we have
+// numbers layouts above their master, and this is the behaviour verified to
+// open cleanly — filling gaps would put a layout id below its master's, which
+// nothing in the corpus does. Headroom is ~2.1 billion, so the climb is
+// theoretical; the guard is here so it fails loudly rather than emitting an
+// out-of-range id if it ever is not.
+export function nextMasterLayoutId(used) {
+  const next = Math.max(2147483647, ...used) + 1;
+  if (next > 4294967295) {
+    throw new Error("no free slide master/layout id remains in the 2^31..2^32-1 space");
+  }
+  return next;
+}
+
+// Renumber a just-inserted master's layout ids off anything the package already
+// uses — masters included, not just other layouts. `used` is passed in so a
+// caller mid-way through registering a master can include the id it just
+// allocated, which presentation.xml does not carry yet.
+export function reidLayoutIds(files, masterPart, extraClaimed = new Set()) {
+  const xml = readText(files, masterPart);
+  if (!xml || !/<p:sldLayoutId\b/.test(xml)) return;
+
+  // Ids claimed by anything OTHER than this master: every sldMasterId, the
+  // caller's freshly allocated ids (presentation.xml is not written back until
+  // the registration loop ends), and every other master's layout ids. One of
+  // ours appearing in here is a collision, whichever kind it collides with.
+  const elsewhere = new Set(extraClaimed);
+  const pres = readText(files, "ppt/presentation.xml") ?? "";
+  for (const m of pres.matchAll(/<p:sldMasterId\b[^>]*\bid="(\d+)"/g)) elsewhere.add(Number(m[1]));
+  for (const part of Object.keys(files)) {
+    if (!/^ppt\/slideMasters\/[^/]+\.xml$/.test(part) || part === masterPart) continue;
+    for (const m of (readText(files, part) ?? "").matchAll(/<p:sldLayoutId\b[^>]*\bid="(\d+)"/g)) {
+      elsewhere.add(Number(m[1]));
+    }
+  }
+
+  // Re-derive the free id per assignment: nextMasterLayoutId hands out the
+  // LOWEST free one, so a running counter would re-issue ids sitting in the
+  // template's gaps.
+  const out = xml.replace(
+    /(<p:sldLayoutId\b[^>]*\bid=")(\d+)(")/g,
+    (whole, pre, id, post) => {
+      if (!elsewhere.has(Number(id))) return whole;
+      const assigned = nextMasterLayoutId(elsewhere);
+      elsewhere.add(assigned);
+      return `${pre}${assigned}${post}`;
+    },
+  );
+  if (out !== xml) files[masterPart] = enc(out);
+}
+
+// Parts scoped to the PRESENTATION, not to a slide: OPC allows exactly one of
+// each per package, and each is reached from ppt/presentation.xml rather than
+// from a slide. An insert carries its source deck's copies, so copying them in
+// yields N+1 parts sharing one singleton content type, referenced by nothing —
+// PowerPoint answers that with "couldn't read some content ... removed it" and
+// strips them on open. The host's own copy already governs the whole package,
+// so the incoming ones are simply dropped.
+const PRESENTATION_SCOPED = new Set([
+  "ppt/presProps.xml",
+  "ppt/viewProps.xml",
+  "ppt/tableStyles.xml",
+  "ppt/commentAuthors.xml",
+]);
+const PRESENTATION_SCOPED_DIRS = [
+  "ppt/changesInfos/",
+  "ppt/notesMasters/", // notesSlides are dropped, so a notes master would orphan
+  "ppt/handoutMasters/",
+];
+export function isPresentationScoped(part) {
+  return (
+    PRESENTATION_SCOPED.has(part) ||
+    PRESENTATION_SCOPED_DIRS.some((d) => part.startsWith(d))
+  );
+}
+
+// The ONLY unbounded surface in a fill-template build. Master-backed slides are
+// clones of a known-good template patched through declared shape ids; an insert
+// is whatever OOXML some other renderer produced for arbitrary authored
+// content, so a renderer regression arrives here rather than being caught by
+// the pack's own validation. Check the incoming package on its own terms BEFORE
+// splicing, so the error names the artifact to re-render instead of surfacing
+// later as a corrupt 30-slide deck — or worse, as a repair prompt in front of a
+// client. Everything here is a property the artifact must already satisfy as a
+// standalone .pptx; the splice cannot repair a broken input.
+export function checkIncomingInsert(inc, file) {
+  const problems = [];
+  const slides = slideOrderPaths(inc);
+  if (slides.length !== 1) {
+    problems.push(`expected a one-slide .pptx fold, found ${slides.length} slides`);
+    return problems; // everything below assumes the single-slide shape
+  }
+
+  const names = new Set(Object.keys(inc));
+  for (const p of names) {
+    if (!p.endsWith(".rels")) continue;
+    const dir = p.replace(/_rels\/[^/]+$/, "").replace(/\/$/, "");
+    for (const m of (readText(inc, p) ?? "").matchAll(/<Relationship [^>]*Target="([^"]+)"[^>]*\/>/g)) {
+      if (/TargetMode="External"/.test(m[0]) || /^(https?|mailto):/i.test(m[1])) continue;
+      const resolved = resolvePartPath(dir, m[1]);
+      if (!names.has(resolved)) problems.push(`dangling relationship ${m[1]} in ${p}`);
+    }
+  }
+
+  const ct = readText(inc, "[Content_Types].xml") ?? "";
+  if (!ct) problems.push("no [Content_Types].xml");
+  for (const m of ct.matchAll(/<Override PartName="\/([^"]+)"/g)) {
+    if (!names.has(m[1])) problems.push(`content-type override for missing part ${m[1]}`);
+  }
+
+  // A slide must reach exactly one layout, and that layout exactly one master —
+  // the chain the splice re-parents into the host.
+  const relsOf = (part) => {
+    const d = part.includes("/") ? part.slice(0, part.lastIndexOf("/")) : "";
+    const b = part.slice(part.lastIndexOf("/") + 1);
+    return readText(inc, d ? `${d}/_rels/${b}.rels` : `_rels/${b}.rels`) ?? "";
+  };
+  const countType = (part, type) =>
+    [...relsOf(part).matchAll(/Type="[^"]*\/([^"/]+)"/g)].filter((m) => m[1] === type).length;
+  if (countType(slides[0], "slideLayout") !== 1) {
+    problems.push(`the slide must reference exactly one slideLayout`);
+  }
+  for (const p of [...names].filter((x) => /^ppt\/slideLayouts\/[^/]+\.xml$/.test(x))) {
+    if (countType(p, "slideMaster") !== 1) problems.push(`${p} must reference exactly one slideMaster`);
+  }
+  return problems.map((p) => `${file}: ${p}`);
+}
+
+function insertForeignSlide(files, buf, i, file, log, warnings) {
+  const inc = unzip(buf);
+  const incoming = checkIncomingInsert(inc, file);
+  if (incoming.length) {
+    throw new Error(
+      `the rendered artifact for this freeform slide is malformed — delete ` +
+        `slides/${path.posix.basename(file)} and rebuild to re-render it:\n  - ${incoming.join("\n  - ")}`,
+    );
+  }
+  const incOrder = slideOrderPaths(inc);
+
+  // Rename every ppt/ part with an insert-scoped basename, folders preserved
+  // (mislocated parts are a known PowerPoint-repair class).
+  const rename = new Map();
+  for (const p of Object.keys(inc)) {
+    if (!p.startsWith("ppt/")) continue;
+    if (p === "ppt/presentation.xml" || p.startsWith("ppt/_rels/")) continue;
+    if (p.includes("/_rels/")) continue; // carried along with their owner part
+    if (p.startsWith("ppt/notesSlides/")) continue; // dropped
+    if (isPresentationScoped(p)) continue; // the host already has the one copy
+    const dir = path.posix.dirname(p);
+    const base = path.posix.basename(p);
+    rename.set(p, p === incOrder[0] ? `ppt/slides/slideIns${i}.xml` : `${dir}/ins${i}_${base}`);
+  }
+
+  const renameTargetBase = (fromDir, target) => {
+    const resolved = resolvePartPath(fromDir, target);
+    const to = rename.get(resolved);
+    if (!to) return null;
+    // Folders are preserved, so only the basename changes.
+    return target.replace(path.posix.basename(resolved), path.posix.basename(to));
+  };
+
+  for (const [from, to] of rename) {
+    let bytes = inc[from];
+    // Carry the part's rels along, rewriting targets to renamed basenames and
+    // dropping notes pointers.
+    const fromRels = relsPathFor(from);
+    if (inc[fromRels]) {
+      let rels = readText(inc, fromRels)
+        .replace(/<Relationship [^>]*Type="[^"]*\/notesSlide"[^>]*\/>/g, "");
+      // A relationship pointing at a part we deliberately did NOT copy (a
+      // presentation-scoped singleton, a notes slide) would dangle in the host
+      // and is itself a repair trigger — drop the whole relationship.
+      rels = rels.replace(/<Relationship\b[^>]*?\/>/g, (rel) => {
+        const target = rel.match(/\bTarget="([^"]+)"/)?.[1];
+        if (!target || /^(https?|mailto):/i.test(target)) return rel;
+        if (/\bTargetMode="External"/.test(rel)) return rel;
+        const resolved = resolvePartPath(path.posix.dirname(from), target);
+        if (inc[resolved] !== undefined && !rename.has(resolved)) return "";
+        return rel;
+      });
+      rels = rels.replace(/Target="([^"]+)"/g, (whole, target) => {
+        if (/^https?:/.test(target)) return whole;
+        const next = renameTargetBase(path.posix.dirname(from), target);
+        return next ? `Target="${next}"` : whole;
+      });
+      files[relsPathFor(to)] = enc(rels);
+    }
+    if (from === incOrder[0]) {
+      // Normalize the incoming slide: think-cell custData and invisible
+      // TCLayout OLE frames are the known cross-package repair class, and a
+      // text-free <p:sp> is the known foreign-renderer one.
+      bytes = enc(ensureShapeTextBodies(stripThinkCell(readText(inc, from))));
+    } else if (/^ppt\/(slideLayouts|slideMasters)\//.test(from)) {
+      // The insert brings its own layout and master, and those carry shapes
+      // under the same rule.
+      bytes = enc(ensureShapeTextBodies(readText(inc, from)));
+    }
+    files[to] = bytes;
+  }
+
+  // Content types: merge Defaults, clone Overrides for renamed parts.
+  const hostCtPath = "[Content_Types].xml";
+  let hostCt = readText(files, hostCtPath);
+  const incCt = readText(inc, hostCtPath) ?? "";
+  for (const d of incCt.matchAll(/<Default Extension="([^"]+)" ContentType="([^"]+)"\/>/g)) {
+    if (!new RegExp(`<Default Extension="${d[1]}"`).test(hostCt)) {
+      hostCt = hostCt.replace(/<Default /, `<Default Extension="${d[1]}" ContentType="${d[2]}"/><Default `);
+    }
+  }
+  for (const [from, to] of rename) {
+    const m = incCt.match(new RegExp(`<Override PartName="/${from.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}"[^>]*/>`));
+    if (m) hostCt = hostCt.replace("</Types>", m[0].replace(`/${from}`, `/${to}`) + "</Types>");
+  }
+  files[hostCtPath] = enc(hostCt);
+
+  // Register the incoming master(s) with the host presentation.
+  const presPath = "ppt/presentation.xml";
+  const presRelsPath = "ppt/_rels/presentation.xml.rels";
+  let pres = readText(files, presPath);
+  let presRels = readText(files, presRelsPath);
+  for (const [from, to] of rename) {
+    if (!/^ppt\/slideMasters\/[^/]+\.xml$/.test(from)) continue;
+    const relId = nextRelId(presRels);
+    presRels = presRels.replace(
+      "</Relationships>",
+      `<Relationship Id="${relId}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideMaster" Target="${to.replace("ppt/", "")}"/></Relationships>`,
+    );
+    // Allocate out of the SHARED master/layout id space — scanning only
+    // sldMasterId lands on the host master's first layout id.
+    const used = usedMasterLayoutIds(files, pres);
+    const masterId = nextMasterLayoutId(used);
+    used.add(masterId);
+    pres = pres.replace(
+      "</p:sldMasterIdLst>",
+      `<p:sldMasterId id="${masterId}" r:id="${relId}"/></p:sldMasterIdLst>`,
+    );
+    // `used` carries the id just allocated; presentation.xml is not written
+    // back until the loop ends, so reidLayoutIds cannot re-derive it.
+    reidLayoutIds(files, to, new Set([masterId]));
+    log.ok(`registered inserted master ${path.posix.basename(to)}`);
+  }
+  files[presPath] = enc(pres);
+  files[presRelsPath] = enc(presRels);
+
+  warnings.push(`${file}: inserted as a native slide with its own layout/master (think-cell payload stripped)`);
+  log.slide(`${file} → inserted native slide`);
+  return `ppt/slides/slideIns${i}.xml`;
+}
+
+// ---------------------------------------------------------------------------
+// Presentation & app parts
+// ---------------------------------------------------------------------------
+
+// Delete every ppt/ part no relationship points at, and its content-type
+// override with it. Dropping a template slide orphans the parts only that slide
+// referenced — its think-cell tags above all — and orphans are NOT tolerated:
+// PowerPoint reports "couldn't read some content" and strips them on open. Runs
+// to a fixed point, since removing a part can orphan the parts it referenced.
+// Shared parts are safe: they stay referenced by whichever slide survived.
+export function pruneOrphanParts(files, log = { ok() {} }) {
+  let removed = 0;
+  for (;;) {
+    const targeted = new Set();
+    for (const p of Object.keys(files).filter((x) => x.endsWith(".rels"))) {
+      const dir = p.replace(/_rels\/[^/]+$/, "").replace(/\/$/, "");
+      for (const m of (readText(files, p) ?? "").matchAll(/<Relationship [^>]*Target="([^"]+)"[^>]*\/>/g)) {
+        if (/TargetMode="External"/.test(m[0]) || /^(https?|mailto):/i.test(m[1])) continue;
+        targeted.add(resolvePartPath(dir, m[1]));
+      }
+    }
+    const orphans = Object.keys(files).filter(
+      (p) => p.startsWith("ppt/") && !p.endsWith(".rels") && !targeted.has(p),
+    );
+    if (orphans.length === 0) break;
+    for (const p of orphans) {
+      delete files[p];
+      delete files[relsPathFor(p)];
+      removeOverride(files, p);
+      removed++;
+    }
+  }
+  if (removed) log.ok(`pruned ${removed} orphaned part(s)`);
+  return removed;
+}
+
+function dropSlide(files, part, log) {
+  const rels = readText(files, relsPathFor(part)) ?? "";
+  // Also remove this slide's notes part; anything else the slide alone
+  // referenced is swept up by pruneOrphanParts once every drop has happened.
+  const notes = rels.match(/<Relationship [^>]*Type="[^"]*\/notesSlide"[^>]*Target="([^"]+)"[^>]*\/>/);
+  if (notes) {
+    const notesPart = resolvePartPath("ppt/slides", notes[1]);
+    delete files[notesPart];
+    delete files[relsPathFor(notesPart)];
+    removeOverride(files, notesPart);
+  }
+  delete files[part];
+  delete files[relsPathFor(part)];
+  removeOverride(files, part);
+  log.ok(`dropped template slide ${path.posix.basename(part)}`);
+}
+
+function removeOverride(files, part) {
+  const ct = readText(files, "[Content_Types].xml");
+  files["[Content_Types].xml"] = enc(
+    ct.replace(new RegExp(`<Override PartName="/${part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}"[^>]*/>`), ""),
+  );
+}
+
+function rebuildPresentation(files, output, log) {
+  const presPath = "ppt/presentation.xml";
+  const presRelsPath = "ppt/_rels/presentation.xml.rels";
+  let pres = readText(files, presPath);
+  let presRels = readText(files, presRelsPath);
+
+  // Existing slide rels by target part.
+  const relByPart = new Map();
+  for (const m of presRels.matchAll(/<Relationship Id="([^"]+)"[^>]*Type="[^"]*\/slide"[^>]*Target="([^"]+)"[^>]*\/>/g)) {
+    relByPart.set(resolvePartPath("ppt", m[2]), m[1]);
+  }
+  // Drop slide rels pointing at parts that no longer exist.
+  presRels = presRels.replace(/<Relationship [^>]*Type="[^"]*\/slide"[^>]*\/>/g, (rel) => {
+    const target = (rel.match(/Target="([^"]+)"/) || [])[1];
+    return files[resolvePartPath("ppt", target)] ? rel : "";
+  });
+
+  const oldIds = [...pres.matchAll(/<p:sldId id="(\d+)"/g)].map((m) => Number(m[1]));
+  let nextSldId = Math.max(255, ...oldIds) + 1;
+
+  const entries = [];
+  for (const o of output) {
+    let relId = relByPart.get(o.part);
+    if (!relId) {
+      relId = nextRelId(presRels);
+      presRels = presRels.replace(
+        "</Relationships>",
+        `<Relationship Id="${relId}" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide" Target="${o.part.replace("ppt/", "")}"/></Relationships>`,
+      );
+    }
+    entries.push(`<p:sldId id="${nextSldId++}" r:id="${relId}"/>`);
+  }
+  // Fresh ids for the WHOLE list keeps the id space dense and far from the
+  // 2^31 ceiling some authoring tools have already crowded.
+  pres = pres.replace(/<p:sldIdLst>[\s\S]*?<\/p:sldIdLst>/, `<p:sldIdLst>${entries.join("")}</p:sldIdLst>`);
+  files[presPath] = enc(pres);
+  files[presRelsPath] = enc(presRels);
+  log.ok(`slide list rebuilt (${output.length} slides)`);
+}
+
+function rebuildAppProps(files, output, log) {
+  const appPath = "docProps/app.xml";
+  let app = readText(files, appPath);
+  if (!app) return;
+
+  const titles = output.map((o) => {
+    const xml = readText(files, o.part) ?? "";
+    for (const hit of blocks(xml, "sp")) {
+      if (/<p:ph type="(title|ctrTitle)"/.test(hit.block)) {
+        const text = [...hit.block.matchAll(/<a:t>([^<]*)<\/a:t>/g)].map((m) => m[1]).join("");
+        return text || "PowerPoint Presentation";
+      }
+    }
+    return "PowerPoint Presentation";
+  });
+
+  app = app.replace(/<Slides>\d+<\/Slides>/, `<Slides>${output.length}</Slides>`);
+
+  // TitlesOfParts = [non-slide entries…, slide titles…]; HeadingPairs' LAST
+  // pair is the slide-title bucket in these templates.
+  const tp = app.match(/<TitlesOfParts><vt:vector size="(\d+)"[^>]*>([\s\S]*?)<\/vt:vector><\/TitlesOfParts>/);
+  const hpCounts = [...app.matchAll(/<vt:i4>(\d+)<\/vt:i4>/g)];
+  if (tp && hpCounts.length) {
+    const oldSlideCount = Number(hpCounts[hpCounts.length - 1][1]);
+    const lpstrs = [...tp[2].matchAll(/<vt:lpstr>[\s\S]*?<\/vt:lpstr>/g)].map((m) => m[0]);
+    const lead = lpstrs.slice(0, lpstrs.length - oldSlideCount);
+    const next = [...lead, ...titles.map((t) => `<vt:lpstr>${esc(t)}</vt:lpstr>`)];
+    app = app.replace(tp[0],
+      `<TitlesOfParts><vt:vector size="${next.length}" baseType="lpstr">${next.join("")}</vt:vector></TitlesOfParts>`);
+    const last = hpCounts[hpCounts.length - 1];
+    app = app.slice(0, last.index) + `<vt:i4>${titles.length}</vt:i4>` + app.slice(last.index + last[0].length);
+  }
+  files[appPath] = enc(app);
+  log.ok(`app.xml reconciled (${output.length} slides)`);
+}
+
+// ---------------------------------------------------------------------------
+// Integrity
+// ---------------------------------------------------------------------------
+
+export function checkIntegrity(files) {
+  const issues = [];
+  const ct = readText(files, "[Content_Types].xml");
+  for (const m of ct.matchAll(/<Override PartName="\/([^"]+)"/g)) {
+    if (!files[m[1]]) issues.push(`content-type override for missing part ${m[1]}`);
+  }
+  for (const p of Object.keys(files).filter((p) => p.endsWith(".rels"))) {
+    const dir = p.replace(/_rels\/[^/]+$/, "").replace(/\/$/, "");
+    for (const m of readText(files, p).matchAll(/<Relationship [^>]*Target="([^"]+)"[^>]*\/>/g)) {
+      if (/TargetMode="External"/.test(m[0]) || /^https?:/.test(m[1])) continue;
+      const resolved = resolvePartPath(dir, m[1]);
+      if (!files[resolved]) issues.push(`dangling relationship in ${p}: ${m[1]}`);
+    }
+  }
+  const pres = readText(files, "ppt/presentation.xml");
+  const sldCount = [...pres.matchAll(/<p:sldId /g)].length;
+  const partCount = Object.keys(files).filter((p) => /^ppt\/slides\/[^/]+\.xml$/.test(p)).length;
+  if (sldCount !== partCount) issues.push(`sldIdLst has ${sldCount} entries but ${partCount} slide parts exist`);
+  for (const p of Object.keys(files).filter((p) => /^ppt\/slides\/[^/]+\.xml$/.test(p))) {
+    const n = mergedCellViolations(readText(files, p));
+    if (n) issues.push(`${p}: ${n} merged-away table cell(s) carry text`);
+  }
+
+  // Orphans. In OPC every part is reachable from the package root through
+  // relationships; a part that nothing targets is content PowerPoint cannot
+  // place, and it repairs the file by removing it. (.rels sidecars and the
+  // content-type map are not relationship targets and are exempt.)
+  const targeted = new Set();
+  for (const p of Object.keys(files).filter((x) => x.endsWith(".rels"))) {
+    const dir = p.replace(/_rels\/[^/]+$/, "").replace(/\/$/, "");
+    for (const m of readText(files, p).matchAll(/<Relationship [^>]*Target="([^"]+)"[^>]*\/>/g)) {
+      if (/TargetMode="External"/.test(m[0]) || /^(https?|mailto):/i.test(m[1])) continue;
+      targeted.add(resolvePartPath(dir, m[1]));
+    }
+  }
+  for (const p of Object.keys(files)) {
+    if (p.endsWith(".rels") || p === "[Content_Types].xml") continue;
+    if (!targeted.has(p)) issues.push(`orphan part referenced by no relationship: ${p}`);
+  }
+
+  // Presentation-scoped singletons. Exactly one part per package may carry each
+  // of these content types; an insert that brings its own is invalid even when
+  // the extra copy is harmlessly ignored.
+  const byType = new Map();
+  for (const m of ct.matchAll(/<Override PartName="\/([^"]+)" ContentType="([^"]+)"/g)) {
+    if (!/\b(presProps|viewProps|tableStyles|commentAuthors)\+xml$/.test(m[2])) continue;
+    if (!byType.has(m[2])) byType.set(m[2], []);
+    byType.get(m[2]).push(m[1]);
+  }
+  for (const [type, parts] of byType) {
+    if (parts.length > 1) {
+      issues.push(
+        `${parts.length} parts declare the singleton content type ${type.split(".").pop()}: ${parts.join(", ")}`,
+      );
+    }
+  }
+
+  // A <p:sp> with no <p:txBody>. Both shipped masters have zero of these; a
+  // foreign renderer that omits it makes PowerPoint repair the file on open.
+  for (const p of Object.keys(files).filter((x) =>
+    /^ppt\/(slides|slideLayouts|slideMasters)\/[^/]+\.xml$/.test(x),
+  )) {
+    const n = shapesWithoutTextBody(readText(files, p) ?? "");
+    if (n) issues.push(`${p}: ${n} shape(s) have no <p:txBody> — PowerPoint repairs those`);
+  }
+
+  // Hard id ranges from ISO-IEC-29500-4 pml.xsd: ST_SlideId is [256,2^31),
+  // ST_SlideMasterId and ST_SlideLayoutId are >= 2^31. The allocators satisfy
+  // these by construction today; asserting them here keeps a future allocator
+  // from drifting out of range silently.
+  for (const [re, label, lo, hi] of [
+    [/<p:sldId\b[^>]*\bid="(\d+)"/g, "sldId", 256, 2147483647],
+    [/<p:sldMasterId\b[^>]*\bid="(\d+)"/g, "sldMasterId", 2147483648, 4294967295],
+  ]) {
+    for (const m of pres.matchAll(re)) {
+      const v = Number(m[1]);
+      if (v < lo || v > hi) issues.push(`${label} ${v} outside the legal range ${lo}..${hi}`);
+    }
+  }
+  for (const p of Object.keys(files).filter((x) => /^ppt\/slideMasters\/[^/]+\.xml$/.test(x))) {
+    for (const m of (readText(files, p) ?? "").matchAll(/<p:sldLayoutId\b[^>]*\bid="(\d+)"/g)) {
+      const v = Number(m[1]);
+      if (v < 2147483648 || v > 4294967295) {
+        issues.push(`${p}: sldLayoutId ${v} outside the legal range 2147483648..4294967295`);
+      }
+    }
+  }
+
+  // sldMasterId and sldLayoutId share ONE id space across the whole
+  // presentation. Uniqueness within each kind is NOT enough — a master id equal
+  // to some layout id repairs on open (app-props.mjs:9-17).
+  const idOwner = new Map();
+  const claim = (id, where) => {
+    if (idOwner.has(id)) {
+      issues.push(`id ${id} used twice in the shared master/layout id space: ${idOwner.get(id)} and ${where}`);
+    } else {
+      idOwner.set(id, where);
+    }
+  };
+  for (const m of pres.matchAll(/<p:sldMasterId\b[^>]*\bid="(\d+)"/g)) {
+    claim(m[1], "presentation.xml sldMasterId");
+  }
+  for (const p of Object.keys(files).filter((x) => /^ppt\/slideMasters\/[^/]+\.xml$/.test(x))) {
+    for (const m of readText(files, p).matchAll(/<p:sldLayoutId\b[^>]*\bid="(\d+)"/g)) {
+      claim(m[1], `${p} sldLayoutId`);
+    }
+  }
+  return issues;
+}
+
+// ---------------------------------------------------------------------------
+
+function nextRelId(rels) {
+  let max = 0;
+  for (const m of rels.matchAll(/Id="rId(\d+)"/g)) max = Math.max(max, Number(m[1]));
+  return `rId${max + 1}`;
+}
+
+function ensureDefaultContentType(files, ext, type) {
+  const ct = readText(files, "[Content_Types].xml");
+  if (new RegExp(`<Default Extension="${ext}"`).test(ct)) return;
+  files["[Content_Types].xml"] = enc(ct.replace(/<Default /, `<Default Extension="${ext}" ContentType="${type}"/><Default `));
+}
+
+function makeLog(onLog = () => {}) {
+  return {
+    slide: (msg) => onLog(`${msg}`),
+    ok: (msg) => onLog(`    ✓ ${msg}`),
+    miss: (msg) => onLog(`    !! ${msg}`),
+  };
+}