slidemind 0.3.20 → 0.4.0

package/src/pptx/deck-assemble.mjs

@@ -0,0 +1,1278 @@
+// Targeted assembly: apply a handful of changed slides to an ACCEPTED BASE
+// package, leaving every part the change does not touch byte-identical.
+//
+// The whole-deck render throws the user's package away and builds a new one from
+// the design — which is right for a deck slidemind authored and wrong for a deck
+// it adopted: the notes, comments, animations, embeddings, sections and native
+// objects that were never in the projection do not come back. So a build against
+// a base renders ONLY the dirty slides and splices them in here.
+//
+// What this module is careful about, in the order it bites:
+//   • identity, never a name — a layout is reused only when its content (and its
+//     master's, and its theme's) is identical; two layouts called "Title" from
+//     different masters are two layouts;
+//   • an edited slide keeps the relationships the edit does not touch (its
+//     notes, its comments, foreign tag parts) and keeps its slide id + GUID;
+//   • a construct that cannot survive a body replacement (animation timing, an
+//     OLE object, a chart) BLOCKS that slide's edit by name instead of silently
+//     dropping it;
+//   • structure follows: the slide list, the section list, custom shows and the
+//     internal links that point at a slide that is going away;
+//   • only parts THIS operation imported may be garbage-collected, so ten cycles
+//     neither grow the package nor delete someone else's media.
+//
+// Regex-over-XML like the rest of src/pptx/ — the constructs touched here
+// (sldIdLst, sectionLst, custShowLst, Relationship, Override) are flat.
+
+import { createHash } from "node:crypto";
+
+import { unzip, zip, readText } from "./zip.mjs";
+import { relsFor, relsPathFor, resolvePartPath, slideOrderPaths, tagElements } from "./ooxml.mjs";
+import { TAG_GUID, readSlideTags } from "./tags.mjs";
+
+const enc = (s) => new TextEncoder().encode(s);
+const sha256 = (b) => createHash("sha256").update(Buffer.from(b)).digest("hex");
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const xmlEsc = (s) =>
+  String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+const REL_BASE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+const RELS_NS = "http://schemas.openxmlformats.org/package/2006/relationships";
+const SLIDE_PART_RE = /^ppt\/slides\/slide\d+\.xml$/;
+const MASTER_PART_RE = /^ppt\/slideMasters\/slideMaster\d+\.xml$/;
+
+// Parts whose life is tied to ONE slide, so an operation that replaced or
+// deleted that slide may collect them once nothing else points at them. The
+// design parts (layouts, masters, themes) are deliberately absent: PowerPoint
+// keeps unused layouts on purpose, and deleting one is how a deck loses a
+// layout someone was about to use again.
+const COLLECTIBLE_RE = /^ppt\/(media|embeddings|charts|drawings|diagrams|tags|notesSlides)\//;
+
+// Relationship types an EDITED slide keeps from the base: the edit replaced the
+// slide body, not the conversation around it. Everything the replaced body used
+// to reference (its own images, its own external links) comes from the render.
+const PRESERVED_REL_TYPES = [
+  "/notesSlide",
+  "/comments",
+  "/modernComments",
+  "/commentAuthors",
+];
+
+// Constructs that live INSIDE the slide part, so replacing the body destroys
+// them. Each is detected on the base slide and looked for on the replacement;
+// a base-only construct blocks that slide's edit by name.
+const FRAGILE = [
+  { id: "animation", label: "slide animation/timing", test: (xml) => /<p:timing\b/.test(xml) },
+  {
+    id: "oleObject",
+    label: "an embedded OLE object",
+    test: (xml) => /<p:oleObj\b/.test(xml) || /<mc:AlternateContent\b[\s\S]*?<p:oleObj\b/.test(xml),
+  },
+  {
+    id: "chart",
+    label: "a native chart",
+    test: (xml) => /graphicData\s+uri="[^"]*\/chart(?:Ex)?"/.test(xml),
+  },
+  {
+    id: "smartArt",
+    label: "a SmartArt diagram",
+    test: (xml) => /graphicData\s+uri="[^"]*\/diagram"/.test(xml),
+  },
+];
+
+// ---------------------------------------------------------------------------
+// package primitives
+// ---------------------------------------------------------------------------
+
+function contentTypeFor(files, part) {
+  const ct = readText(files, "[Content_Types].xml") ?? "";
+  const override = new RegExp(
+    `<Override\\b[^>]*\\bPartName="/${escapeRe(part)}"[^>]*\\bContentType="([^"]*)"`,
+  ).exec(ct);
+  if (override) return { kind: "override", value: override[1] };
+  const ext = part.includes(".") ? part.slice(part.lastIndexOf(".") + 1) : "";
+  const def = new RegExp(
+    `<Default\\b[^>]*\\bExtension="${escapeRe(ext)}"[^>]*\\bContentType="([^"]*)"`,
+    "i",
+  ).exec(ct);
+  return def ? { kind: "default", value: def[1], ext } : null;
+}
+
+function relativeTarget(fromPart, toPart) {
+  const from = fromPart.split("/").slice(0, -1);
+  const to = toPart.split("/");
+  let i = 0;
+  while (i < from.length && i < to.length - 1 && from[i] === to[i]) i++;
+  return [...Array(from.length - i).fill(".."), ...to.slice(i)].join("/");
+}
+
+function writeRels(rels) {
+  return (
+    '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\r\n' +
+    `<Relationships xmlns="${RELS_NS}">` +
+    rels
+      .map(
+        (r) =>
+          `<Relationship Id="${xmlEsc(r.id)}" Type="${xmlEsc(r.type)}" Target="${xmlEsc(r.target)}"` +
+          (r.targetMode ? ` TargetMode="${xmlEsc(r.targetMode)}"` : "") +
+          "/>",
+      )
+      .join("") +
+    "</Relationships>"
+  );
+}
+
+function nextFreeName(taken, part) {
+  const m = /^(.*?)(\d+)(\.[^.]+)$/.exec(part);
+  if (m) {
+    const [, stem, , ext] = m;
+    for (let n = 1; n < 100000; n++) {
+      const candidate = `${stem}${n}${ext}`;
+      if (!taken.has(candidate)) return candidate;
+    }
+  }
+  const dot = part.lastIndexOf(".");
+  const stem = dot === -1 ? part : part.slice(0, dot);
+  const ext = dot === -1 ? "" : part.slice(dot);
+  for (let n = 1; n < 100000; n++) {
+    const candidate = `${stem}-sm${n}${ext}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+  throw new Error(`deck-assemble: could not find a free part name for ${part}`);
+}
+
+// The sldIdLst entries of a package, in play order.
+function sldIdEntries(files) {
+  const pres = readText(files, "ppt/presentation.xml");
+  if (!pres) return [];
+  const list = /<(?:[\w.-]+:)?sldIdLst[\s\S]*?<\/(?:[\w.-]+:)?sldIdLst>/.exec(pres);
+  if (!list) return [];
+  const byRid = {};
+  for (const rel of relsFor(files, "ppt/presentation.xml")) {
+    if (rel.id) byRid[rel.id] = resolvePartPath("ppt", rel.target);
+  }
+  const out = [];
+  const re = /<(?:[\w.-]+:)?sldId\b([^>]*?)(?:\/>|>[\s\S]*?<\/(?:[\w.-]+:)?sldId>)/g;
+  let m;
+  while ((m = re.exec(list[0])) !== null) {
+    const rId = /\b[\w.-]+:id\s*=\s*"([^"]+)"/.exec(m[1])?.[1];
+    const id = /\bid\s*=\s*"([^"]+)"/.exec(m[1])?.[1];
+    const part = rId ? byRid[rId] : null;
+    if (part && SLIDE_PART_RE.test(part)) out.push({ id, rId, part });
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// layout / master identity — content, never the display name
+// ---------------------------------------------------------------------------
+
+// WHICH layouts a master lists is package bookkeeping — this module rewrites it
+// itself, and a slice of a deck carries a trimmed copy. Two masters that differ
+// only there are the same master, so the list is normalized out before hashing.
+// Everything that decides how a slide LOOKS (the master's own shapes, its
+// colour map, its theme) still counts.
+function normalizedMaster(xml) {
+  return xml
+    .replace(/<p:sldLayoutIdLst\b[\s\S]*?<\/p:sldLayoutIdLst>/g, "")
+    .replace(/<p:sldLayoutIdLst\b[^>]*\/>/g, "");
+}
+
+// A layout's identity is its own bytes PLUS its master's (normalized) and that
+// master's theme's. Two layouts named "Title" on different masters are different
+// layouts; the same layout re-serialized identically is the same one. A NAME is
+// never part of it.
+function layoutSignature(files, layoutPart) {
+  const bits = [files[layoutPart] ? sha256(files[layoutPart]) : "-"];
+  const dir = layoutPart.slice(0, layoutPart.lastIndexOf("/"));
+  for (const rel of relsFor(files, layoutPart)) {
+    if (rel.targetMode === "External" || !(rel.type ?? "").endsWith("/slideMaster")) continue;
+    const master = resolvePartPath(dir, rel.target);
+    bits.push(files[master] ? sha256(normalizedMaster(readText(files, master) ?? "")) : "-");
+    const mdir = master.slice(0, master.lastIndexOf("/"));
+    for (const mrel of relsFor(files, master)) {
+      if (mrel.targetMode === "External" || !(mrel.type ?? "").endsWith("/theme")) continue;
+      const theme = resolvePartPath(mdir, mrel.target);
+      bits.push(files[theme] ? sha256(files[theme]) : "-");
+    }
+  }
+  return sha256(bits.join("|"));
+}
+
+// A master's identity, on the same terms: what it looks like plus its theme,
+// minus the layout list this module maintains itself.
+function masterSignature(files, masterPart) {
+  const bits = [sha256(normalizedMaster(readText(files, masterPart) ?? ""))];
+  const dir = masterPart.slice(0, masterPart.lastIndexOf("/"));
+  for (const rel of relsFor(files, masterPart)) {
+    if (rel.targetMode === "External" || !(rel.type ?? "").endsWith("/theme")) continue;
+    const theme = resolvePartPath(dir, rel.target);
+    bits.push(files[theme] ? sha256(files[theme]) : "-");
+  }
+  return sha256(bits.join("|"));
+}
+
+function partIndex(files, match, signature) {
+  const index = new Map();
+  for (const part of Object.keys(files)) {
+    if (!match.test(part)) continue;
+    const sig = signature(files, part);
+    if (!index.has(sig)) index.set(sig, part);
+  }
+  return index;
+}
+
+function baseLayoutIndex(files) {
+  return partIndex(files, /^ppt\/slideLayouts\/slideLayout\d+\.xml$/, layoutSignature);
+}
+
+function baseMediaIndex(files) {
+  const index = new Map();
+  for (const part of Object.keys(files)) {
+    if (!/^ppt\/media\//.test(part)) continue;
+    const digest = sha256(files[part]);
+    if (!index.has(digest)) index.set(digest, part);
+  }
+  return index;
+}
+
+// ---------------------------------------------------------------------------
+// importing one slide's dependency closure
+// ---------------------------------------------------------------------------
+
+class Importer {
+  constructor(files) {
+    this.files = files;
+    this.taken = new Set(Object.keys(files));
+    this.layouts = baseLayoutIndex(files);
+    this.masters = partIndex(files, MASTER_PART_RE, masterSignature);
+    this.media = baseMediaIndex(files);
+    this.owned = new Set(); // parts THIS operation added — the only GC candidates
+    this.contentTypes = { overrides: [], defaults: new Map() };
+  }
+
+  claim(name) {
+    this.taken.add(name);
+    return name;
+  }
+
+  // Copy `part` (and everything it reaches) out of `src` into the base package,
+  // reusing an identical layout or an identical media part where one exists.
+  // Returns the part path it now lives at.
+  importPart(src, part, mapped = new Map()) {
+    if (mapped.has(part)) return mapped.get(part);
+    if (src[part] === undefined) return null;
+
+    // Design parts resolve by SIGNATURE, which deliberately looks past their own
+    // bytes (a layout is its master and theme too) — so they must not fall
+    // through to the byte-identity fast path below, or an unchanged layout on a
+    // changed master would silently reuse the wrong design.
+    const design = /^ppt\/(slideLayouts\/slideLayout|slideMasters\/slideMaster)\d+\.xml$/.test(part);
+    if (/^ppt\/slideLayouts\/slideLayout\d+\.xml$/.test(part)) {
+      const reuse = this.layouts.get(layoutSignature(src, part));
+      if (reuse) {
+        mapped.set(part, reuse);
+        return reuse;
+      }
+    }
+    if (MASTER_PART_RE.test(part)) {
+      const reuse = this.masters.get(masterSignature(src, part));
+      if (reuse) {
+        mapped.set(part, reuse);
+        return reuse;
+      }
+    }
+    if (/^ppt\/media\//.test(part)) {
+      const reuse = this.media.get(sha256(src[part]));
+      if (reuse) {
+        mapped.set(part, reuse);
+        return reuse;
+      }
+    }
+    // The same part, byte for byte, already at that path: reuse it. Without
+    // this a re-render of an unchanged tag/drawing/embedding part clones itself
+    // on every build, and the package doubles rather than grows.
+    if (!design && this.files[part] !== undefined && samePart(this.files, src, part)) {
+      mapped.set(part, part);
+      return part;
+    }
+
+    const target = this.taken.has(part) ? nextFreeName(this.taken, part) : part;
+    this.claim(target);
+    mapped.set(part, target);
+    this.files[target] = src[part];
+    this.owned.add(target);
+    if (/^ppt\/media\//.test(target)) this.media.set(sha256(src[part]), target);
+
+    const ct = contentTypeFor(src, part);
+    if (ct?.kind === "override") this.contentTypes.overrides.push([target, ct.value]);
+    else if (ct?.kind === "default") this.contentTypes.defaults.set(ct.ext.toLowerCase(), ct.value);
+
+    // Follow this part's own relationships, rewriting each target to where it
+    // landed. Slides are never traversed into — an internal slide link is a
+    // reference, not an instruction to import the whole presentation.
+    const srcRels = relsFor(src, part);
+    if (srcRels.length > 0 || src[relsPathFor(part)] !== undefined) {
+      const dir = part.includes("/") ? part.slice(0, part.lastIndexOf("/")) : "";
+      const rewritten = [];
+      for (const rel of srcRels) {
+        if (rel.targetMode === "External") {
+          rewritten.push(rel);
+          continue;
+        }
+        const absolute = resolvePartPath(dir, rel.target);
+        if (SLIDE_PART_RE.test(absolute)) continue; // dropped: mapped by the caller
+        const landed = this.importPart(src, absolute, mapped);
+        if (!landed) continue;
+        rewritten.push({ ...rel, target: relativeTarget(target, landed) });
+      }
+      const relsPath = relsPathFor(target);
+      this.files[relsPath] = enc(writeRels(rewritten));
+      this.owned.add(relsPath);
+      const relsCt = contentTypeFor(src, relsPath);
+      if (relsCt?.kind === "default") {
+        this.contentTypes.defaults.set(relsCt.ext.toLowerCase(), relsCt.value);
+      }
+    }
+
+    // A freshly imported layout must be reachable from its master's layout list,
+    // or PowerPoint repairs the file.
+    if (/^ppt\/slideLayouts\/slideLayout\d+\.xml$/.test(target)) {
+      this.layouts.set(layoutSignature(this.files, target), target);
+      this.linkLayoutToMaster(target);
+    } else if (MASTER_PART_RE.test(target)) {
+      this.masters.set(masterSignature(this.files, target), target);
+    }
+    return target;
+  }
+
+  linkLayoutToMaster(layoutPart) {
+    const dir = layoutPart.slice(0, layoutPart.lastIndexOf("/"));
+    for (const rel of relsFor(this.files, layoutPart)) {
+      if (rel.targetMode === "External" || !(rel.type ?? "").endsWith("/slideMaster")) continue;
+      const master = resolvePartPath(dir, rel.target);
+      if (this.files[master] === undefined) continue;
+      const masterRelsPath = relsPathFor(master);
+      const masterRels = relsFor(this.files, master);
+      const mdir = master.slice(0, master.lastIndexOf("/"));
+      if (
+        masterRels.some(
+          (r) =>
+            (r.type ?? "").endsWith("/slideLayout") &&
+            resolvePartPath(mdir, r.target) === layoutPart,
+        )
+      ) {
+        return;
+      }
+      const rId = freeRid(masterRels);
+      masterRels.push({
+        id: rId,
+        type: `${REL_BASE}/slideLayout`,
+        target: relativeTarget(master, layoutPart),
+      });
+      this.files[masterRelsPath] = enc(writeRels(masterRels));
+      const xml = readText(this.files, master) ?? "";
+      const nextId = nextLayoutId(xml);
+      const entry = `<p:sldLayoutId id="${nextId}" r:id="${rId}"/>`;
+      const withEntry = /<p:sldLayoutIdLst\b[^>]*\/>/.test(xml)
+        ? xml.replace(/<p:sldLayoutIdLst\b[^>]*\/>/, `<p:sldLayoutIdLst>${entry}</p:sldLayoutIdLst>`)
+        : /<p:sldLayoutIdLst\b/.test(xml)
+          ? xml.replace(/(<p:sldLayoutIdLst\b[^>]*>)/, `$1${entry}`)
+          : xml.replace(/(<\/p:cSld>)/, `$1<p:sldLayoutIdLst>${entry}</p:sldLayoutIdLst>`);
+      this.files[master] = enc(withEntry);
+      return;
+    }
+  }
+
+  applyContentTypes() {
+    let ct = readText(this.files, "[Content_Types].xml");
+    if (!ct) return;
+    for (const [ext, value] of this.contentTypes.defaults) {
+      if (new RegExp(`<Default\\b[^>]*\\bExtension="${escapeRe(ext)}"`, "i").test(ct)) continue;
+      ct = ct.replace(/(<Types\b[^>]*>)/, `$1<Default Extension="${xmlEsc(ext)}" ContentType="${xmlEsc(value)}"/>`);
+    }
+    for (const [part, value] of this.contentTypes.overrides) {
+      if (new RegExp(`<Override\\b[^>]*\\bPartName="/${escapeRe(part)}"`).test(ct)) continue;
+      ct = ct.replace(
+        /(<\/Types>)/,
+        `<Override PartName="/${xmlEsc(part)}" ContentType="${xmlEsc(value)}"/>$1`,
+      );
+    }
+    this.files["[Content_Types].xml"] = enc(ct);
+  }
+
+  dropContentType(part) {
+    const ct = readText(this.files, "[Content_Types].xml");
+    if (!ct) return;
+    this.files["[Content_Types].xml"] = enc(
+      ct.replace(
+        new RegExp(`<Override\\b(?=[^>]*\\bPartName="/${escapeRe(part)}")[^>]*?/>`, "g"),
+        "",
+      ),
+    );
+  }
+}
+
+// The same part path in two packages holding identical bytes AND identical
+// relationships — the one case where reusing rather than cloning is provably
+// lossless.
+function samePart(a, b, part) {
+  if (a[part] === undefined || b[part] === undefined) return false;
+  if (sha256(a[part]) !== sha256(b[part])) return false;
+  const rels = relsPathFor(part);
+  const ar = a[rels] === undefined ? null : sha256(a[rels]);
+  const br = b[rels] === undefined ? null : sha256(b[rels]);
+  return ar === br;
+}
+
+function freeRid(rels) {
+  let max = 0;
+  for (const r of rels) {
+    const n = /^rId(\d+)$/.exec(r.id ?? "")?.[1];
+    if (n) max = Math.max(max, Number(n));
+  }
+  return `rId${max + 1}`;
+}
+
+function nextLayoutId(masterXml) {
+  let max = 2147483648;
+  for (const m of masterXml.matchAll(/<p:sldLayoutId\b[^>]*\bid="(\d+)"/g)) {
+    max = Math.max(max, Number(m[1]));
+  }
+  return max + 1;
+}
+
+function nextSldId(entries) {
+  let max = 255;
+  for (const e of entries) {
+    const n = Number(e.id);
+    if (Number.isFinite(n)) max = Math.max(max, n);
+  }
+  return max + 1;
+}
+
+// Everything ONE slide reaches that belongs to it alone: its media, its
+// embeddings, its chart parts, its notes. Shared design parts and other slides
+// are never followed — this set exists to be garbage-collected, and a layout in
+// it would take the whole master down with it.
+function slideOwnedClosure(files, slidePart) {
+  const out = new Set();
+  const queue = [slidePart];
+  const seen = new Set([slidePart]);
+  while (queue.length) {
+    const part = queue.shift();
+    const dir = part.includes("/") ? part.slice(0, part.lastIndexOf("/")) : "";
+    for (const rel of relsFor(files, part)) {
+      if (rel.targetMode === "External") continue;
+      const target = resolvePartPath(dir, rel.target);
+      if (seen.has(target) || files[target] === undefined) continue;
+      if (SLIDE_PART_RE.test(target)) continue;
+      if (!COLLECTIBLE_RE.test(target)) continue;
+      seen.add(target);
+      out.add(target);
+      queue.push(target);
+    }
+  }
+  return out;
+}
+
+// A slide master reachable only through a layout is a repair prompt in
+// PowerPoint: the presentation's own master list is what makes it part of the
+// deck. Every master this operation imported is registered here.
+function linkMastersToPresentation(files, presRels, masters) {
+  if (masters.length === 0) return presRels;
+  let xml = readText(files, "ppt/presentation.xml") ?? "";
+  let nextId = 2147483648;
+  for (const m of xml.matchAll(/<p:sldMasterId\b[^>]*\bid="(\d+)"/g)) {
+    nextId = Math.max(nextId, Number(m[1]) + 1);
+  }
+  let rels = presRels;
+  let added = "";
+  for (const master of masters) {
+    const dir = "ppt";
+    if (
+      rels.some(
+        (r) =>
+          (r.type ?? "").endsWith("/slideMaster") &&
+          resolvePartPath(dir, r.target) === master,
+      )
+    ) {
+      continue;
+    }
+    const rId = freeRid(rels);
+    rels = [
+      ...rels,
+      {
+        id: rId,
+        type: `${REL_BASE}/slideMaster`,
+        target: relativeTarget("ppt/presentation.xml", master),
+      },
+    ];
+    added += `<p:sldMasterId id="${nextId++}" r:id="${rId}"/>`;
+  }
+  if (added) {
+    xml = /<p:sldMasterIdLst\b[^>]*\/>/.test(xml)
+      ? xml.replace(/<p:sldMasterIdLst\b[^>]*\/>/, () => `<p:sldMasterIdLst>${added}</p:sldMasterIdLst>`)
+      : /<\/p:sldMasterIdLst>/.test(xml)
+        ? xml.replace(/<\/p:sldMasterIdLst>/, (m) => added + m)
+        : xml.replace(/<p:sldIdLst\b/, (m) => `<p:sldMasterIdLst>${added}</p:sldMasterIdLst>${m}`);
+    files["ppt/presentation.xml"] = enc(xml);
+  }
+  return rels;
+}
+
+// Layout ids share ONE id space across the whole presentation (ST_SlideLayoutId,
+// unique with the master ids too). A master imported from another package —
+// the render's second design master, a folded library slide's master — brings
+// its own `sldLayoutIdLst` verbatim, so two masters end up numbering their
+// layouts identically, and PowerPoint answers with the repair prompt. Re-mint
+// every duplicate above everything already in use; the r:id links are what
+// bind a layout, so the id itself is free to move.
+// A master may list each layout part ONCE. The add-in's render lists the
+// design master's layouts twice (observed 2026-09-17: 13 duplicate rows, each
+// through its own r:id, on a fresh two-slide deck as much as on a 43-slide
+// pack deck), and PowerPoint answers with the repair prompt. Keep the first
+// row per part and drop the later rows with their relationships.
+export function dedupeLayoutLists(files) {
+  let dropped = 0;
+  for (const master of Object.keys(files).filter((p) => /^ppt\/slideMasters\/[^/]+\.xml$/.test(p))) {
+    const xml = readText(files, master) ?? "";
+    const dir = master.slice(0, master.lastIndexOf("/"));
+    const rels = relsFor(files, master);
+    const byId = new Map(rels.map((r) => [r.id, r]));
+    const seen = new Set();
+    const kept = new Set();
+    // Both spellings of an empty element. `validatePackage` matches the row
+    // without requiring `/>`, so a `<p:sldLayoutId …></p:sldLayoutId>` row used to
+    // be reported as an error this function could never fix.
+    const fixed = xml.replace(/<p:sldLayoutId\b[^>]*\br:id="([^"]+)"[^>]*?(?:\/>|><\/p:sldLayoutId>)/g, (row, rId) => {
+      const rel = byId.get(rId);
+      // A row must point, through a slideLayout relationship, at a layout part
+      // that exists and whose own relationships name THIS master. The render's
+      // second master (observed 2026-09-17) lists the first master's layouts —
+      // each twice — next to its own single layout; every such row goes.
+      if (!rel || !(rel.type ?? "").endsWith("/slideLayout")) {
+        dropped += 1;
+        return "";
+      }
+      const part = resolvePartPath(dir, rel.target);
+      if (files[part] === undefined || layoutOwner(files, part) !== master || seen.has(part)) {
+        dropped += 1;
+        return "";
+      }
+      seen.add(part);
+      kept.add(rId);
+      return row;
+    });
+    if (fixed === xml) continue;
+    files[master] = enc(fixed);
+    // Relationships no kept row uses any more go with the rows.
+    const remaining = rels.filter((r) => !(r.type ?? "").endsWith("/slideLayout") || kept.has(r.id));
+    if (remaining.length !== rels.length) files[relsPathFor(master)] = enc(writeRels(remaining));
+  }
+  return dropped;
+}
+
+// The master a layout part belongs to, by the layout's own relationships.
+function layoutOwner(files, layoutPart) {
+  const dir = layoutPart.slice(0, layoutPart.lastIndexOf("/"));
+  for (const rel of relsFor(files, layoutPart)) {
+    if (rel.targetMode === "External" || !(rel.type ?? "").endsWith("/slideMaster")) continue;
+    return resolvePartPath(dir, rel.target);
+  }
+  return null;
+}
+
+// A theme part belongs to ONE master. The render's second master points at the
+// first master's theme (observed 2026-09-17), and PowerPoint repairs that by
+// cloning the theme — so clone it here, before the file is anyone's problem.
+export function uniqueThemes(files) {
+  const owners = new Map();
+  let cloned = 0;
+  let next = 1;
+  for (const p of Object.keys(files)) {
+    const m = p.match(/^ppt\/theme\/theme(\d+)\.xml$/);
+    if (m) next = Math.max(next, Number(m[1]) + 1);
+  }
+  for (const master of Object.keys(files).filter((p) => /^ppt\/slideMasters\/[^/]+\.xml$/.test(p)).sort()) {
+    const dir = master.slice(0, master.lastIndexOf("/"));
+    const rels = relsFor(files, master);
+    let changed = false;
+    const rewritten = rels.map((rel) => {
+      if (rel.targetMode === "External" || !(rel.type ?? "").endsWith("/theme")) return rel;
+      const theme = resolvePartPath(dir, rel.target);
+      if (files[theme] === undefined) return rel;
+      if (!owners.has(theme)) {
+        owners.set(theme, master);
+        return rel;
+      }
+      const clone = `ppt/theme/theme${next++}.xml`;
+      files[clone] = files[theme];
+      // The theme's own relationships travel with it. A theme carrying a picture
+      // fill points at `../media/…` through `ppt/theme/_rels/themeN.xml.rels`, and a
+      // clone without that part leaves its `r:embed` ids resolving to nothing —
+      // exactly the repair prompt this function exists to prevent, and invisible to
+      // validatePackage (a part with no rels file yields no relationships to check).
+      // The clone sits in the same directory, so the relative targets still resolve.
+      const themeRels = relsPathFor(theme);
+      if (files[themeRels] !== undefined) files[relsPathFor(clone)] = files[themeRels];
+      files["[Content_Types].xml"] = enc(
+        (readText(files, "[Content_Types].xml") ?? "").replace(
+          "</Types>",
+          `<Override PartName="/${clone}" ContentType="application/vnd.openxmlformats-officedocument.theme+xml"/></Types>`,
+        ),
+      );
+      owners.set(clone, master);
+      cloned += 1;
+      changed = true;
+      return { ...rel, target: `../theme/${clone.slice("ppt/theme/".length)}` };
+    });
+    if (changed) files[relsPathFor(master)] = enc(writeRels(rewritten));
+  }
+  return cloned;
+}
+
+// One p:tags per customer-data list. Files written before the tag writers
+// learned to merge (every deck published up to 2026-09-17) carry two on the
+// presentation — ours next to another add-in's — and an accepted base keeps
+// that shape forever unless it is repaired here. Later parts' tags are merged
+// into the first part; their rows, relationships, parts and overrides go.
+export function mergeTagLists(files) {
+  let merged = 0;
+  const parts = Object.keys(files).filter((p) => /^ppt\/(presentation\.xml|(slides|slideLayouts|slideMasters)\/[^/]+\.xml)$/.test(p));
+  for (const part of parts) {
+    const xml = readText(files, part) ?? "";
+    if ((xml.match(/<p:tags\b/g) ?? []).length < 2) continue;
+    const dir = part.slice(0, part.lastIndexOf("/"));
+    const rels = relsFor(files, part);
+    const byId = new Map(rels.map((r) => [r.id, r]));
+    const dropRels = new Set();
+    const fixed = xml.replace(/<p:custDataLst\b[^>]*>([\s\S]*?)<\/p:custDataLst>/g, (list, body) => {
+      // Same widening as the layout rows: the validator counts `<p:tags` however it
+      // is closed, so a non-self-closing one left the list over the limit forever.
+      const rows = [...body.matchAll(/<p:tags\b[^>]*\br:id="([^"]+)"[^>]*?(?:\/>|><\/p:tags>)/g)];
+      if (rows.length < 2) return list;
+      const targets = rows.map((r) => byId.get(r[1])).map((rel) => (rel ? resolvePartPath(dir, rel.target) : null));
+      const keep = targets.findIndex((t) => t && files[t] !== undefined);
+      if (keep < 0) return list;
+      let keptXml = readText(files, targets[keep]) ?? "";
+      let next = body;
+      rows.forEach((row, i) => {
+        if (i === keep) return;
+        const target = targets[i];
+        const extra = target && files[target] !== undefined ? [...tagElements(readText(files, target))].map((m) => m[0]) : [];
+        if (extra.length) {
+          // An EMPTY kept list is written `<p:tagLst/>`: there is no closing tag to
+          // insert before, so appending silently did nothing while the other part —
+          // another add-in's tags — was deleted in the same breath. Expand the
+          // self-closing form instead, and if neither form is there leave this row
+          // alone rather than merge its tags into nothing.
+          const expanded = keptXml.replace(/<p:tagLst\b[^>]*\/>/, `<p:tagLst>${extra.join("")}</p:tagLst>`);
+          const appended = expanded !== keptXml ? expanded : keptXml.replace("</p:tagLst>", `${extra.join("")}</p:tagLst>`);
+          if (appended === keptXml) return;
+          keptXml = appended;
+        }
+        if (target && files[target] !== undefined) {
+          delete files[target];
+          files["[Content_Types].xml"] = enc((readText(files, "[Content_Types].xml") ?? "").replace(new RegExp(`<Override\\b[^>]*PartName="/${target.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}"[^>]*/>`), ""));
+        }
+        dropRels.add(row[1]);
+        next = next.replace(row[0], "");
+        merged += 1;
+      });
+      files[targets[keep]] = enc(keptXml);
+      return list.replace(body, next);
+    });
+    if (fixed === xml) continue;
+    files[part] = enc(fixed);
+    if (dropRels.size) files[relsPathFor(part)] = enc(writeRels(rels.filter((r) => !dropRels.has(r.id))));
+  }
+  return merged;
+}
+
+// Every fix a rendered or assembled package needs before it is a candidate.
+export function normalizeMasters(files) {
+  return {
+    droppedLayoutRows: dedupeLayoutLists(files),
+    remintedLayoutIds: uniqueLayoutIds(files),
+    clonedThemes: uniqueThemes(files),
+    mergedTagLists: mergeTagLists(files),
+  };
+}
+
+export function uniqueLayoutIds(files) {
+  const presXml = readText(files, "ppt/presentation.xml") ?? "";
+  const used = new Set([...presXml.matchAll(/<p:sldMasterId\b[^>]*\bid="(\d+)"/g)].map((m) => m[1]));
+  let next = 2147483648;
+  const masters = Object.keys(files).filter((p) => /^ppt\/slideMasters\/[^/]+\.xml$/.test(p)).sort();
+  for (const master of masters) {
+    for (const m of (readText(files, master) ?? "").matchAll(/<p:sldLayoutId\b[^>]*\bid="(\d+)"/g)) {
+      next = Math.max(next, Number(m[1]) + 1);
+    }
+  }
+  for (const id of used) next = Math.max(next, Number(id) + 1);
+  let reminted = 0;
+  for (const master of masters) {
+    const xml = readText(files, master) ?? "";
+    const fixed = xml.replace(/(<p:sldLayoutId\b[^>]*\bid=")(\d+)(")/g, (whole, open, id, close) => {
+      if (!used.has(id)) {
+        used.add(id);
+        return whole;
+      }
+      const fresh = String(next++);
+      used.add(fresh);
+      reminted += 1;
+      return `${open}${fresh}${close}`;
+    });
+    if (fixed !== xml) files[master] = enc(fixed);
+  }
+  return reminted;
+}
+
+// ---------------------------------------------------------------------------
+// structure: slide list, sections, custom shows, internal links
+// ---------------------------------------------------------------------------
+
+function rewriteSldIdLst(presXml, entries) {
+  const body = entries.map((e) => `<p:sldId id="${e.id}" r:id="${e.rId}"/>`).join("");
+  if (/<p:sldIdLst\b[^>]*\/>/.test(presXml)) {
+    return presXml.replace(/<p:sldIdLst\b[^>]*\/>/, `<p:sldIdLst>${body}</p:sldIdLst>`);
+  }
+  if (/<p:sldIdLst\b/.test(presXml)) {
+    return presXml.replace(/<p:sldIdLst\b[\s\S]*?<\/p:sldIdLst>/, `<p:sldIdLst>${body}</p:sldIdLst>`);
+  }
+  return presXml.replace(/(<p:sldMasterIdLst\b[\s\S]*?<\/p:sldMasterIdLst>)/, `$1<p:sldIdLst>${body}</p:sldIdLst>`);
+}
+
+// Sections carry their own copy of the slide ids. A deleted slide leaves its
+// section; an inserted slide joins the section of the slide it follows (or none
+// when the deck has no sections); a section left empty is removed.
+function rewriteSections(presXml, { removedIds, insertions, report }) {
+  const listMatch = /<p14:sectionLst\b[\s\S]*?<\/p14:sectionLst>/.exec(presXml);
+  if (!listMatch) return presXml;
+  const list = listMatch[0];
+  const open = /^<p14:sectionLst\b[^>]*>/.exec(list)?.[0] ?? "<p14:sectionLst>";
+  const sectionRe = /<p14:section\b[^>]*(?:\/>|>[\s\S]*?<\/p14:section>)/g;
+  const sections = list.match(sectionRe) ?? [];
+
+  const next = [];
+  for (const original of sections) {
+    let section = original;
+    for (const id of removedIds) {
+      section = section.replace(
+        new RegExp(`<p14:sldId\\b[^>]*\\bid="${escapeRe(String(id))}"[^>]*/>`, "g"),
+        "",
+      );
+    }
+    for (const { id, afterId } of insertions) {
+      if (afterId == null) continue;
+      const anchor = new RegExp(`<p14:sldId\\b[^>]*\\bid="${escapeRe(String(afterId))}"[^>]*/>`);
+      if (!anchor.test(section)) continue;
+      section = section.replace(anchor, (m) => `${m}<p14:sldId id="${id}"/>`);
+      report.sectionsUpdated++;
+    }
+    // A section is removed only when THIS operation emptied it. One that arrived
+    // empty is the user's own divider and stays exactly where it was.
+    if (/<p14:sldId\b/.test(original) && !/<p14:sldId\b/.test(section)) {
+      report.sectionsRemoved++;
+      continue;
+    }
+    next.push(section);
+  }
+
+  // Nothing left to section: drop the list rather than deliver an empty one. The
+  // now-empty <p:ext> wrapper is valid and stays, which beats guessing which of
+  // several extensions in presentation.xml was ours.
+  const rebuilt = next.length === 0 ? "" : `${open}${next.join("")}</p14:sectionLst>`;
+  return presXml.replace(list, () => rebuilt);
+}
+
+function rewriteCustomShows(presXml, removedRids, report) {
+  if (!/<p:custShowLst\b/.test(presXml)) return presXml;
+  return presXml.replace(/<p:custShowLst\b[\s\S]*?<\/p:custShowLst>/, (list) => {
+    let next = list;
+    for (const rId of removedRids) {
+      next = next.replace(
+        new RegExp(`<p:sld\\b[^>]*\\br:id="${escapeRe(rId)}"[^>]*/>`, "g"),
+        () => {
+          report.customShowsUpdated++;
+          return "";
+        },
+      );
+    }
+    // A custom show with no slides left is dropped, not delivered empty.
+    next = next.replace(
+      /<p:custShow\b[^>]*>[\s\S]*?<\/p:custShow>/g,
+      (show) => (/<p:sld\b/.test(show) ? show : ""),
+    );
+    return /<p:custShow\b/.test(next) ? next : "";
+  });
+}
+
+function removeRelationshipById(xml, id) {
+  return xml.replace(
+    new RegExp(
+      `<Relationship\\b(?=[^>]*\\bId="${escapeRe(id)}")[^>]*?(?:/>|>[\\s\\S]*?</Relationship>)`,
+      "g",
+    ),
+    "",
+  );
+}
+
+// ---------------------------------------------------------------------------
+// validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Structural checks before delivery: every internal relationship resolves,
+ * every part has a content type, the slide list is coherent and no two slides
+ * claim one identity. Returns `{ ok, errors }`.
+ */
+export function validatePackage(files) {
+  const errors = [];
+  const ct = readText(files, "[Content_Types].xml") ?? "";
+  const defaults = new Set(
+    [...ct.matchAll(/<Default\b[^>]*\bExtension="([^"]*)"/gi)].map((m) => m[1].toLowerCase()),
+  );
+  const overrides = new Set(
+    [...ct.matchAll(/<Override\b[^>]*\bPartName="\/([^"]*)"/g)].map((m) => m[1]),
+  );
+
+  for (const part of Object.keys(files)) {
+    if (part === "[Content_Types].xml") continue;
+    // A zip directory entry ("ppt/") is not an OPC part; the server's render
+    // emits them and fflate keeps them as empty entries. `[trash]/*` is Office's
+    // and SharePoint's scratch space, carried without a content type by both.
+    if (part.endsWith("/") || part.startsWith("[trash]/")) continue;
+    if (!part.endsWith(".rels")) {
+      const ext = part.includes(".") ? part.slice(part.lastIndexOf(".") + 1).toLowerCase() : "";
+      if (!overrides.has(part) && !defaults.has(ext)) {
+        errors.push(`no content type for part ${part}`);
+      }
+    }
+    const dir = part.includes("/") ? part.slice(0, part.lastIndexOf("/")) : "";
+    for (const rel of relsFor(files, part)) {
+      if (rel.targetMode === "External") continue;
+      const target = resolvePartPath(dir, rel.target);
+      if (files[target] === undefined) {
+        errors.push(`${part}: relationship ${rel.id} points at missing part ${target}`);
+      }
+    }
+  }
+
+  // One p:tags per customer-data list (CT_CustomerDataList): a second one is
+  // a PowerPoint repair prompt, and PowerPoint keeps whichever it likes.
+  for (const part of Object.keys(files)) {
+    if (!/^ppt\/(presentation\.xml|(slides|slideLayouts|slideMasters)\/[^/]+\.xml)$/.test(part)) continue;
+    for (const list of (readText(files, part) ?? "").matchAll(/<p:custDataLst\b[^>]*>([\s\S]*?)<\/p:custDataLst>/g)) {
+      const count = (list[1].match(/<p:tags\b/g) ?? []).length;
+      if (count > 1) errors.push(`${part}: a customer-data list carries ${count} p:tags elements (one is allowed)`);
+    }
+  }
+
+  // One id space for masters and layouts, one row per layout part in a
+  // master's list, every row backed by a layout relationship, one theme per
+  // master: each violation is a PowerPoint repair prompt.
+  const layoutIds = new Map();
+  const themeOwners = new Map();
+  for (const part of Object.keys(files)) {
+    if (!/^ppt\/slideMasters\/[^/]+\.xml$/.test(part)) continue;
+    const xml = readText(files, part) ?? "";
+    for (const m of xml.matchAll(/<p:sldLayoutId\b[^>]*\bid="(\d+)"/g)) {
+      if (layoutIds.has(m[1])) errors.push(`layout id ${m[1]} is used by both ${layoutIds.get(m[1])} and ${part}`);
+      else layoutIds.set(m[1], part);
+    }
+    const dir = part.slice(0, part.lastIndexOf("/"));
+    const byId = new Map(relsFor(files, part).map((r) => [r.id, r]));
+    const listed = new Set();
+    for (const m of xml.matchAll(/<p:sldLayoutId\b[^>]*\br:id="([^"]+)"/g)) {
+      const rel = byId.get(m[1]);
+      if (!rel || !(rel.type ?? "").endsWith("/slideLayout")) {
+        errors.push(`${part}: layout row ${m[1]} has no slideLayout relationship`);
+        continue;
+      }
+      const target = resolvePartPath(dir, rel.target);
+      if (listed.has(target)) errors.push(`${part} lists ${target} twice in its layout list`);
+      listed.add(target);
+      const owner = files[target] === undefined ? null : layoutOwner(files, target);
+      if (owner && owner !== part) errors.push(`${part} lists ${target}, which belongs to ${owner}`);
+    }
+    for (const rel of byId.values()) {
+      if (rel.targetMode === "External" || !(rel.type ?? "").endsWith("/theme")) continue;
+      const theme = resolvePartPath(dir, rel.target);
+      if (themeOwners.has(theme) && themeOwners.get(theme) !== part) errors.push(`${theme} is the theme of both ${themeOwners.get(theme)} and ${part}`);
+      themeOwners.set(theme, part);
+    }
+  }
+
+  const entries = sldIdEntries(files);
+  const order = slideOrderPaths(files);
+  if (entries.length !== order.length) {
+    errors.push(`slide list has ${entries.length} entries but ${order.length} resolve to slides`);
+  }
+  const ids = new Set();
+  for (const e of entries) {
+    if (ids.has(e.id)) errors.push(`duplicate slide id ${e.id} in the slide list`);
+    ids.add(e.id);
+  }
+  const guids = new Map();
+  for (const part of order) {
+    const guid = readSlideTags(files, part)[TAG_GUID];
+    if (!guid) continue;
+    if (guids.has(guid)) {
+      errors.push(`slides ${guids.get(guid)} and ${part} both claim GUID ${guid}`);
+    }
+    guids.set(guid, part);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+// ---------------------------------------------------------------------------
+// assemble
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the next deck from an accepted base plus the slides that changed.
+ *
+ * @param {object}   args
+ * @param {Buffer}   args.base      the accepted base .pptx
+ * @param {Buffer}  [args.rendered] a .pptx carrying ONLY the changed/new slides
+ * @param {Array}    args.plan      the FINAL deck, in play order. Each entry is
+ *                                  `{ guid, source: "base" }` (keep this base
+ *                                  slide) or `{ guid, source: "rendered",
+ *                                  index: <1-based play order in `rendered`> }`.
+ *                                  A base slide absent from the plan is deleted.
+ * @param {object}  [args.options]  `{ repairLinks }` — drop internal links whose
+ *                                  target slide is being deleted instead of
+ *                                  refusing. `{ allowFragileLoss }` — replace a
+ *                                  slide even when a construct cannot survive.
+ * @returns {{ bytes: Uint8Array|null, report: object }}
+ */
+export function assembleDeck({ base, rendered = null, plan, options = {} }) {
+  const { repairLinks = false, allowFragileLoss = false } = options;
+  const files = { ...unzip(base) };
+  // Office (Web and desktop) parks discarded parts under `[trash]/` with no
+  // content type. They are scratch space, not the document: every host drops
+  // them on its next save, and the OPC validator below rightly refuses them.
+  for (const part of Object.keys(files)) if (part.startsWith("[trash]/")) delete files[part];
+  const src = rendered ? unzip(rendered) : null;
+  const srcOrder = src ? slideOrderPaths(src) : [];
+
+  const report = {
+    kept: [],
+    replaced: [],
+    inserted: [],
+    deleted: [],
+    blocked: [],
+    reusedLayouts: 0,
+    importedParts: [],
+    collectedParts: [],
+    sectionsUpdated: 0,
+    sectionsRemoved: 0,
+    customShowsUpdated: 0,
+    warnings: [],
+    errors: [],
+  };
+
+  const baseEntries = sldIdEntries(files);
+  const byGuid = new Map();
+  for (const entry of baseEntries) {
+    const guid = readSlideTags(files, entry.part)[TAG_GUID];
+    if (guid && !byGuid.has(guid)) byGuid.set(guid, entry);
+  }
+  const byPart = new Map(baseEntries.map((e) => [e.part, e]));
+
+  // --- preflight: what would a replacement destroy? -----------------------
+  for (const item of plan) {
+    if (item.source !== "rendered") continue;
+    const existing = byGuid.get(item.guid) ?? (item.part ? byPart.get(item.part) : null);
+    if (!existing) continue;
+    const baseXml = readText(files, existing.part) ?? "";
+    const srcPart = srcOrder[(item.index ?? 0) - 1];
+    const newXml = srcPart ? (readText(src, srcPart) ?? "") : "";
+    const lost = FRAGILE.filter((f) => f.test(baseXml) && !f.test(newXml));
+    if (lost.length > 0 && !allowFragileLoss) {
+      report.blocked.push({
+        guid: item.guid,
+        part: existing.part,
+        reasons: lost.map(
+          (f) =>
+            `${f.label} on this slide cannot survive the edit — slidemind would have to re-author it, and it has no source for it`,
+        ),
+      });
+    }
+  }
+  if (report.blocked.length > 0) {
+    report.errors.push(
+      ...report.blocked.flatMap((b) => b.reasons.map((r) => `${b.part}: ${r}`)),
+    );
+    return { bytes: null, report };
+  }
+
+  const importer = new Importer(files);
+  const planned = new Set();
+  const finalEntries = [];
+  let presRels = relsFor(files, "ppt/presentation.xml");
+  const removedRids = [];
+  const insertions = [];
+  // What the slides this operation replaces or deletes used to own. Anything in
+  // here that nothing points at afterwards is this operation's own litter and
+  // may go; without it ten build cycles leave ten copies of one picture behind.
+  const displaced = new Set();
+
+  for (const item of plan) {
+    if (item.source === "base") {
+      const entry = byGuid.get(item.guid) ?? byPart.get(item.part);
+      if (!entry) {
+        report.errors.push(`plan names base slide ${item.guid ?? item.part}, which the base does not have`);
+        continue;
+      }
+      planned.add(entry.part);
+      finalEntries.push(entry);
+      report.kept.push(entry.part);
+      continue;
+    }
+
+    const srcPart = srcOrder[(item.index ?? 0) - 1];
+    if (!srcPart) {
+      report.errors.push(
+        `plan wants rendered slide ${item.index} for ${item.guid}, but the render has ${srcOrder.length} slide(s)`,
+      );
+      continue;
+    }
+    const existing = byGuid.get(item.guid) ?? (item.part ? byPart.get(item.part) : null);
+    if (existing) for (const p of slideOwnedClosure(files, existing.part)) displaced.add(p);
+    const mapped = new Map();
+
+    // The slide's own dependency closure, minus the slide part itself (that one
+    // is placed by hand so a replacement keeps the base slide's part path).
+    const srcRels = relsFor(src, srcPart);
+    const srcDir = srcPart.slice(0, srcPart.lastIndexOf("/"));
+    const importedRels = [];
+    for (const rel of srcRels) {
+      if (rel.targetMode === "External") {
+        importedRels.push({ ...rel });
+        continue;
+      }
+      const absolute = resolvePartPath(srcDir, rel.target);
+      if (SLIDE_PART_RE.test(absolute)) {
+        report.errors.push(`Cannot safely remap internal slide link from ${srcPart} to ${absolute}.`);
+        continue;
+      }
+      const landed = importer.importPart(src, absolute, mapped);
+      if (!landed) continue;
+      if (/^ppt\/slideLayouts\//.test(landed) && !importer.owned.has(landed)) {
+        report.reusedLayouts++;
+      }
+      importedRels.push({ ...rel, landed });
+    }
+
+    const targetPart = existing
+      ? existing.part
+      : importer.claim(nextFreeName(importer.taken, "ppt/slides/slide1.xml"));
+
+    // Relationship ids: the ones the base slide keeps come first and keep their
+    // ids; the imported ones are renumbered around them and the slide body is
+    // rewritten to match, so a preserved notes rel can never collide with an
+    // imported image rel.
+    const preserved = existing
+      ? relsFor(files, existing.part).filter((r) =>
+          PRESERVED_REL_TYPES.some((t) => (r.type ?? "").endsWith(t)),
+        )
+      : [];
+    if (existing) {
+      // A foreign tag part (another add-in's) is content, not slidemind's — it
+      // stays. slidemind's own tag part comes fresh with the render.
+      for (const rel of relsFor(files, existing.part)) {
+        if (!(rel.type ?? "").endsWith("/tags")) continue;
+        const part = resolvePartPath(existing.part.slice(0, existing.part.lastIndexOf("/")), rel.target);
+        const xml = readText(files, part) ?? "";
+        if (!/name="SLIDEMIND_/.test(xml)) preserved.push(rel);
+      }
+    }
+    const usedIds = new Set(preserved.map((r) => r.id));
+    const remap = new Map();
+    const finalRels = [...preserved];
+    // A preserved relationship and an imported one can name the SAME part (the
+    // render re-emitted a tag part the base already carries). Two relationships
+    // to one part is how a slide accumulates a second copy of everything on
+    // every cycle — so the import folds into the preserved id instead.
+    const preservedByTarget = new Map();
+    const targetDir = targetPart.slice(0, targetPart.lastIndexOf("/"));
+    for (const rel of preserved) {
+      if (rel.targetMode === "External") continue;
+      preservedByTarget.set(`${rel.type}|${resolvePartPath(targetDir, rel.target)}`, rel.id);
+    }
+    let n = 1;
+    for (const rel of importedRels) {
+      const key = rel.landed ? `${rel.type}|${rel.landed}` : null;
+      const already = key ? preservedByTarget.get(key) : null;
+      if (already) {
+        if (rel.id) remap.set(rel.id, already);
+        continue;
+      }
+      let id = `rId${n++}`;
+      while (usedIds.has(id)) id = `rId${n++}`;
+      usedIds.add(id);
+      if (rel.id) remap.set(rel.id, id);
+      finalRels.push({
+        id,
+        type: rel.type,
+        target: rel.landed ? relativeTarget(targetPart, rel.landed) : rel.target,
+        targetMode: rel.targetMode,
+      });
+    }
+
+    let slideXml = readText(src, srcPart) ?? "";
+    // Rewrite every r:id/r:embed/r:link in one pass off a placeholder map, so a
+    // renumber can never land on an id a later substitution then re-reads.
+    slideXml = slideXml.replace(
+      /\b(r:(?:id|embed|link|pict|dm|lo|qs|cs))="([^"]+)"/g,
+      (whole, attr, id) => (remap.has(id) ? `${attr}="${remap.get(id)}"` : whole),
+    );
+    files[targetPart] = enc(slideXml);
+    files[relsPathFor(targetPart)] = enc(writeRels(finalRels));
+    const ct = contentTypeFor(src, srcPart);
+    if (ct?.kind === "override") importer.contentTypes.overrides.push([targetPart, ct.value]);
+
+    if (existing) {
+      planned.add(existing.part);
+      finalEntries.push(existing);
+      report.replaced.push(existing.part);
+    } else {
+      importer.owned.add(targetPart);
+      importer.owned.add(relsPathFor(targetPart));
+      const rId = freeRid(presRels);
+      presRels = [
+        ...presRels,
+        { id: rId, type: `${REL_BASE}/slide`, target: relativeTarget("ppt/presentation.xml", targetPart) },
+      ];
+      const id = String(nextSldId([...baseEntries, ...finalEntries]));
+      const entry = { id, rId, part: targetPart };
+      finalEntries.push(entry);
+      insertions.push({ id, afterId: finalEntries[finalEntries.length - 2]?.id ?? null });
+      report.inserted.push(targetPart);
+    }
+    report.importedParts.push(...[...mapped.values()].filter((p) => importer.owned.has(p)));
+  }
+
+  // --- deletions -----------------------------------------------------------
+  const removedIds = [];
+  const deletedParts = new Set();
+  for (const entry of baseEntries) {
+    if (planned.has(entry.part)) continue;
+    deletedParts.add(entry.part);
+    removedIds.push(entry.id);
+    removedRids.push(entry.rId);
+    report.deleted.push(entry.part);
+    for (const p of slideOwnedClosure(files, entry.part)) displaced.add(p);
+  }
+
+  // An internal link from a SURVIVING slide to a slide that is going away is a
+  // dangling reference. Repair it explicitly or refuse — never deliver it.
+  if (deletedParts.size > 0) {
+    for (const entry of finalEntries) {
+      const dir = entry.part.slice(0, entry.part.lastIndexOf("/"));
+      const rels = relsFor(files, entry.part);
+      const broken = rels.filter(
+        (r) =>
+          r.targetMode !== "External" &&
+          (r.type ?? "").endsWith("/slide") &&
+          deletedParts.has(resolvePartPath(dir, r.target)),
+      );
+      if (broken.length === 0) continue;
+      if (!repairLinks) {
+        report.errors.push(
+          `${entry.part} links to ${broken.length} slide(s) being deleted ` +
+            `(${broken.map((r) => resolvePartPath(dir, r.target)).join(", ")}). ` +
+            `Re-point or remove the link, or pass repairLinks to drop it.`,
+        );
+        continue;
+      }
+      let xml = readText(files, relsPathFor(entry.part)) ?? "";
+      for (const rel of broken) {
+        xml = removeRelationshipById(xml, rel.id);
+        report.warnings.push(`${entry.part}: dropped the link to deleted slide ${resolvePartPath(dir, rel.target)}`);
+      }
+      files[relsPathFor(entry.part)] = enc(xml);
+    }
+  }
+  if (report.errors.length > 0) return { bytes: null, report };
+
+  for (const part of deletedParts) {
+    delete files[part];
+    delete files[relsPathFor(part)];
+    importer.dropContentType(part);
+    presRels = presRels.filter((r) => r.id !== byPart.get(part)?.rId);
+    // A notes slide belongs to exactly one slide; it goes with it.
+    for (const notes of Object.keys(files)) {
+      if (!/^ppt\/notesSlides\/notesSlide\d+\.xml$/.test(notes)) continue;
+      const ndir = notes.slice(0, notes.lastIndexOf("/"));
+      const backlinks = relsFor(files, notes).filter(
+        (r) => (r.type ?? "").endsWith("/slide") && resolvePartPath(ndir, r.target) === part,
+      );
+      if (backlinks.length === 0) continue;
+      delete files[notes];
+      delete files[relsPathFor(notes)];
+      importer.dropContentType(notes);
+    }
+  }
+
+  // --- presentation.xml ----------------------------------------------------
+  presRels = linkMastersToPresentation(
+    files,
+    presRels,
+    [...importer.owned].filter((p) => MASTER_PART_RE.test(p)),
+  );
+  files["ppt/_rels/presentation.xml.rels"] = enc(writeRels(presRels));
+  let presXml = readText(files, "ppt/presentation.xml") ?? "";
+  presXml = rewriteSldIdLst(presXml, finalEntries);
+  presXml = rewriteSections(presXml, { removedIds, insertions, report });
+  presXml = rewriteCustomShows(presXml, removedRids, report);
+  files["ppt/presentation.xml"] = enc(presXml);
+  importer.applyContentTypes();
+
+  // --- garbage collection: only what THIS operation imported ---------------
+  const referenced = new Set();
+  for (const part of Object.keys(files)) {
+    const dir = part.includes("/") ? part.slice(0, part.lastIndexOf("/")) : "";
+    for (const rel of relsFor(files, part)) {
+      if (rel.targetMode === "External") continue;
+      referenced.add(resolvePartPath(dir, rel.target));
+    }
+  }
+  for (const part of new Set([...importer.owned, ...displaced])) {
+    if (part.endsWith(".rels") || referenced.has(part)) continue;
+    // Only what this operation brought in, or what the slides it replaced owned
+    // — never a part that was simply sitting in the base unreferenced.
+    if (!importer.owned.has(part) && !COLLECTIBLE_RE.test(part)) continue;
+    delete files[part];
+    delete files[relsPathFor(part)];
+    importer.dropContentType(part);
+    report.collectedParts.push(part);
+  }
+
+  report.masters = normalizeMasters(files);
+  const validation = validatePackage(files);
+  report.errors.push(...validation.errors);
+  if (!validation.ok) return { bytes: null, report };
+  return { bytes: zip(files), report };
+}
+
+/**
+ * The plan `assembleDeck` takes, worked out from a deck's slide files and the
+ * dirty set. `slides` is the deck's slide file order; `guidFor` maps a file to
+ * its GUID; `dirty` is the set of slide files that must be rendered. Returns
+ * `{ plan, render }` where `render` is the ordered list of slide files the
+ * render request must carry (and therefore the index each plan entry points at).
+ */
+export function planFromDeck({ slides, guidFor, dirty, partFor = () => null }) {
+  const render = slides.filter((f) => dirty.has(f));
+  const indexOf = new Map(render.map((f, i) => [f, i + 1]));
+  const plan = slides.map((file) =>
+    dirty.has(file)
+      ? { guid: guidFor(file), part: partFor(file), source: "rendered", index: indexOf.get(file), file }
+      : { guid: guidFor(file), part: partFor(file), source: "base", file },
+  );
+  return { plan, render };
+}