slidemind 0.3.19 → 0.4.0

package/src/pptx/content-digest.mjs

@@ -0,0 +1,334 @@
+// What a person changed in a package — read so that a save nobody edited in
+// reads as no change at all.
+//
+// A three-way rebase has to answer "did the other side change this slide?" for
+// every slide of a file PowerPoint just saved. Comparing bytes cannot answer it:
+// one PowerPoint Online save of a one-slide deck rewrote 86 of its 98 parts
+// (decks/sp-probe, 2026-09-16) — every layout and master re-serialized, the
+// slide-number placeholder relocalized, every image and tag part renumbered,
+// every relationship id reshuffled, SharePoint metadata added. None of that is
+// an edit, and a byte comparison calls all of it one.
+//
+// So this module digests MEANING, never bytes or part names:
+//
+//   slide   the structural projection the manual-edit reconcile already relies
+//           on (`computeProjection`: geometry, text runs, fill, line, media
+//           content), plus what the projection does not carry — each shape's
+//           STYLE (shape type, scheme and gradient colours, line style, effects,
+//           text box anchoring, paragraph alignment / bullets / spacing / level,
+//           run font face and decoration), speaker notes, chart data (the
+//           residue, not the chart XML), table grids and cell styling, embedded
+//           payload bytes, comments, hyperlinks, the layout it uses, background,
+//           hidden flag, transition and animation.
+//   design  the deck's shared design: theme colours and fonts, every master's
+//           and layout's name and projection, the slide size.
+//
+// Everything is keyed by content or by name, never by part path, so a
+// renumbered `image7.png` is the same image it was as `image3.png`. And
+// everything is an attribute PowerPoint PRESERVES: what it recomputes on a save
+// (autofit scale, language and proofing flags, an empty paragraph's end-of-run
+// properties, field text) is left out on purpose.
+//
+// What it does NOT see, stated so nobody relies on it: 3D and the finer detail
+// of shadows and glows (their presence is seen, their parameters are not), a
+// list style defined inside one shape, and anything in a part no slide reaches.
+
+import { createHash } from "node:crypto";
+
+import { decodeXmlEntities, relsFor, resolvePartPath, slideOrderPaths } from "./ooxml.mjs";
+import { chartResidue } from "./package-evidence.mjs";
+import { computeProjection, topLevelShapes, withoutChartHashes } from "./tags.mjs";
+import { readText } from "./zip.mjs";
+
+const sha256 = (data) => createHash("sha256").update(data).digest("hex");
+const digestOf = (value) => sha256(JSON.stringify(value));
+const dirOf = (part) => part.slice(0, part.lastIndexOf("/"));
+const relType = (rel) => String(rel.type ?? "").slice(String(rel.type ?? "").lastIndexOf("/") + 1);
+
+// Runs as PowerPoint may re-serialize them: an empty run dropped, two adjacent
+// runs with identical formatting merged. Neither is a visible change.
+function normalizeRuns(runs) {
+  if (!runs) return null;
+  const out = [];
+  for (const run of runs) {
+    if (!run.t) continue;
+    const prev = out[out.length - 1];
+    if (prev && prev.b === run.b && prev.i === run.i && prev.sz === run.sz && prev.color === run.color) {
+      prev.t += run.t;
+    } else {
+      out.push({ ...run });
+    }
+  }
+  return out.length ? out : null;
+}
+
+// `prov` is slidemind's own bookkeeping (which JSX node drew the shape): no
+// person edits it, and a host is free to drop the tag that carries it.
+function projectionOf(files, part) {
+  const projection = withoutChartHashes(computeProjection(files, part));
+  return (projection?.shapes ?? []).map(({ prov: _bookkeeping, ...shape }) => ({
+    ...shape,
+    text: normalizeRuns(shape.text),
+  }));
+}
+
+// The text a part shows, paragraph by paragraph. Fields (`a:fld` — slide
+// numbers, dates) are left out on purpose: the host recomputes them on every
+// save and every reorder.
+function textOf(xml) {
+  const paragraphs = [];
+  for (const p of String(xml ?? "").matchAll(/<a:p>([\s\S]*?)<\/a:p>/g)) {
+    const text = [...p[1].matchAll(/<a:r>[\s\S]*?<a:t>([\s\S]*?)<\/a:t>[\s\S]*?<\/a:r>/g)]
+      .map((m) => decodeXmlEntities(m[1]))
+      .join("");
+    if (text) paragraphs.push(text);
+  }
+  return paragraphs;
+}
+
+// Every literal string a part carries — for parts whose structure is the host's
+// business (a SmartArt data model, a comment) but whose words are the author's.
+const stringsOf = (xml) =>
+  [...String(xml ?? "").matchAll(/<(?:a:t|p:text|cx:v|cx:pt\b[^>]*)>([^<]*)</g)]
+    .map((m) => decodeXmlEntities(m[1]).trim())
+    .filter(Boolean);
+
+function background(files, part, xml) {
+  const bg = /<p:bg>([\s\S]*?)<\/p:bg>/.exec(xml)?.[1];
+  if (!bg) return null;
+  const rels = new Map(relsFor(files, part).map((r) => [r.id, r]));
+  return {
+    colors: [...bg.matchAll(/\bval="([^"]+)"/g)].map((m) => m[1].toUpperCase()),
+    media: [...bg.matchAll(/\br:embed="([^"]+)"/g)].map((m) => {
+      const rel = rels.get(m[1]);
+      const bytes = rel ? files[resolvePartPath(dirOf(part), rel.target)] : undefined;
+      return bytes ? sha256(bytes) : null;
+    }),
+  };
+}
+
+// The effect names a transition uses. PowerPoint wraps a transition in
+// `mc:AlternateContent` with a fallback copy on save, so the names are a set.
+function transition(xml) {
+  const names = new Set();
+  for (const block of String(xml).matchAll(/<p:transition\b[^>]*?(?:\/>|>([\s\S]*?)<\/p:transition>)/g)) {
+    names.add("transition");
+    for (const m of String(block[1] ?? "").matchAll(/<(p14|p15|p):(\w+)\b/g)) names.add(m[2]);
+  }
+  return names.size ? [...names].sort() : null;
+}
+
+// Each animation as the preset it applies and the shape it applies to. Time
+// nodes NEST (the root holds the sequence holds every effect), so an effect is
+// read from its own start tag up to the next effect's — a lazy element match
+// would stop at the innermost closing tag and never see one.
+function animation(xml) {
+  const timing = /<p:timing\b[^>]*>([\s\S]*?)<\/p:timing>/.exec(xml)?.[1];
+  if (!timing) return null;
+  const starts = [...timing.matchAll(/<p:cTn\b([^>]*)>/g)].filter((m) => /\bpresetClass="/.test(m[1]));
+  const effects = starts.map((m, k) => {
+    const scope = timing.slice(m.index, starts[k + 1]?.index ?? timing.length);
+    return {
+      cls: /\bpresetClass="([^"]+)"/.exec(m[1])[1],
+      id: /\bpresetID="([^"]+)"/.exec(m[1])?.[1] ?? null,
+      sub: /\bpresetSubtype="([^"]+)"/.exec(m[1])?.[1] ?? null,
+      spid: /<p:spTgt\b[^>]*\bspid="([^"]+)"/.exec(scope)?.[1] ?? null,
+    };
+  });
+  return effects.length ? effects : null;
+}
+
+// ---------------------------------------------------------------------------
+// style — what the projection leaves out of a shape
+// ---------------------------------------------------------------------------
+
+const attrsOf = (tag, names) => {
+  const out = {};
+  for (const name of names) {
+    const value = new RegExp(`\\s${name}="([^"]*)"`).exec(tag ?? "")?.[1];
+    if (value !== undefined) out[name] = value;
+  }
+  return out;
+};
+const firstTag = (xml, name) => new RegExp(`<a:${name}\\b[^>]*>`).exec(xml ?? "")?.[0] ?? null;
+const block = (xml, name) => new RegExp(`<a:${name}\\b[^>]*?(?:\\/>|>[\\s\\S]*?<\\/a:${name}>)`).exec(xml ?? "")?.[0] ?? null;
+
+// Every colour a block names, with its modifiers, in order: a scheme colour
+// (accent1 → accent2) is as much an edit as an RGB one, and the projection
+// reads only a literal RGB fill. A system colour's `lastClr` is a cached
+// value the host refreshes, so only its name counts.
+const colorsIn = (xml) =>
+  [...String(xml ?? "").matchAll(/<a:(srgbClr|schemeClr|prstClr|sysClr|lumMod|lumOff|alpha|tint|shade|satMod)\b[^>]*\bval="([^"]*)"/g)].map(
+    (m) => `${m[1]}:${m[2]}`,
+  );
+
+function paragraphStyle(p) {
+  const pPr = block(p, "pPr") ?? "";
+  const bullet = [...pPr.matchAll(/<a:(bu\w+)\b([^>]*)/g)].map((m) => [m[1], attrsOf(m[2], ["char", "type", "typeface", "startAt"])]);
+  const spacing = ["lnSpc", "spcBef", "spcAft"].map((name) => {
+    const b = block(pPr, name);
+    return b ? `${name}:${/<a:(spcPct|spcPts)\b[^>]*\bval="([^"]*)"/.exec(b)?.slice(1).join("=") ?? ""}` : null;
+  });
+  const runs = [];
+  for (const r of p.matchAll(/<a:r>([\s\S]*?)<\/a:r>/g)) {
+    if (!/<a:t>[^<]/.test(r[1])) continue;
+    const rPr = block(r[1], "rPr") ?? "";
+    const style = JSON.stringify({
+      ...attrsOf(firstTag(rPr, "rPr"), ["u", "strike", "baseline", "cap", "spc"]),
+      fonts: [...rPr.matchAll(/<a:(latin|ea|cs|sym)\b[^>]*\btypeface="([^"]*)"/g)].map((m) => `${m[1]}:${m[2]}`),
+      colors: colorsIn(rPr),
+    });
+    if (runs[runs.length - 1] !== style) runs.push(style);
+  }
+  return {
+    ...attrsOf(firstTag(pPr, "pPr"), ["algn", "lvl", "marL", "indent", "rtl"]),
+    bullet,
+    spacing: spacing.filter(Boolean),
+    runs,
+  };
+}
+
+/** One shape's style, from the attributes a save keeps. A group is read whole. */
+function shapeStyle(unitXml) {
+  const xml = String(unitXml ?? "");
+  const tbl = block(xml, "tbl");
+  const fills = [...xml.matchAll(/<p:spPr\b[^>]*?(?:\/>|>([\s\S]*?)<\/p:spPr>)/g)].map((m) => {
+    const spPr = m[1] ?? "";
+    const ln = block(spPr, "ln");
+    return {
+      colors: colorsIn(ln ? spPr.replace(ln, "") : spPr),
+      gradient: [...(block(spPr, "gradFill") ?? "").matchAll(/<a:gs\b[^>]*\bpos="([^"]*)"/g)].map((g) => g[1]),
+      pattern: /<a:pattFill\b[^>]*\bprst="([^"]*)"/.exec(spPr)?.[1] ?? null,
+      line: ln
+        ? {
+            ...attrsOf(firstTag(ln, "ln"), ["w", "cap", "cmpd"]),
+            dash: /<a:prstDash\b[^>]*\bval="([^"]*)"/.exec(ln)?.[1] ?? null,
+            ends: [...ln.matchAll(/<a:(headEnd|tailEnd)\b[^>]*\btype="([^"]*)"/g)].map((e) => `${e[1]}:${e[2]}`),
+            colors: colorsIn(ln),
+          }
+        : null,
+      effects: [...(block(spPr, "effectLst") ?? "").matchAll(/<a:(\w+)\b/g)].map((e) => e[1]).filter((n) => n !== "effectLst"),
+    };
+  });
+  return {
+    shapes: [...xml.matchAll(/<a:prstGeom\b[^>]*\bprst="([^"]*)"/g)].map((m) => m[1]),
+    path: [...(block(xml, "custGeom") ?? "").matchAll(/<a:pt\b([^>]*)\/>/g)].map((m) => Object.values(attrsOf(m[1], ["x", "y"])).join(",")),
+    fills,
+    crop: [...xml.matchAll(/<a:srcRect\b([^>]*)\/>/g)].map((m) => attrsOf(m[1], ["l", "t", "r", "b"])),
+    body: [...xml.matchAll(/<a:bodyPr\b[^>]*>/g)].map((m) =>
+      attrsOf(m[0], ["anchor", "anchorCtr", "vert", "wrap", "lIns", "tIns", "rIns", "bIns", "numCol"]),
+    ),
+    paragraphs: [...xml.matchAll(/<a:p(?:\/>|>([\s\S]*?)<\/a:p>)/g)].map((m) => paragraphStyle(m[1] ?? "")),
+    table: tbl
+      ? {
+          ...attrsOf(firstTag(tbl, "tblPr"), ["firstRow", "firstCol", "lastRow", "lastCol", "bandRow", "bandCol"]),
+          styleId: /<a:tableStyleId>([^<]*)</.exec(tbl)?.[1] ?? null,
+          cells: [...tbl.matchAll(/<a:tcPr\b[^>]*?(?:\/>|>([\s\S]*?)<\/a:tcPr>)/g)].map((m) => colorsIn(m[1]).join(" ")),
+        }
+      : null,
+  };
+}
+
+function styleOf(xml) {
+  const spTree = /<p:spTree>([\s\S]*?)<\/p:spTree>/.exec(xml)?.[1] ?? "";
+  return topLevelShapes(spTree).map((unit) => shapeStyle(unit.xml));
+}
+
+/** The name a layout or master carries — its identity for anything that is not a path. */
+function cSldName(files, part) {
+  const xml = readText(files, part) ?? "";
+  return decodeXmlEntities(/<p:cSld\b[^>]*\bname="([^"]*)"/.exec(xml)?.[1] ?? "");
+}
+
+/**
+ * One slide's content digest: equal across any save that did not change what
+ * the slide shows, says or does.
+ */
+export function slideContentDigest(files, part) {
+  const xml = readText(files, part) ?? "";
+  const dir = dirOf(part);
+  const related = [];
+  let layout = null;
+  let notes = null;
+  for (const rel of relsFor(files, part)) {
+    const type = relType(rel);
+    if (rel.targetMode === "External") {
+      if (type === "hyperlink") related.push(`link:${rel.target}`);
+      continue;
+    }
+    const target = resolvePartPath(dir, rel.target);
+    if (files[target] === undefined) continue;
+    if (type === "slideLayout") layout = cSldName(files, target);
+    else if (type === "notesSlide") notes = textOf(readText(files, target));
+    else if (type === "chart") related.push(`chart:${digestOf(chartResidue(readText(files, target)))}`);
+    else if (type === "chartEx" || type === "diagramData" || type === "comments") {
+      related.push(`${type}:${digestOf(stringsOf(readText(files, target)))}`);
+    } else if (/^(tags|slide|vmlDrawing|diagramLayout|diagramColors|diagramQuickStyle|diagramDrawing)$/.test(type)) {
+      // Tags are slidemind's own bookkeeping (provenance rides the projection);
+      // a slide link points at a part path; a VML drawing and the diagram parts
+      // besides its data are the host's rendering cache. None of them is
+      // something a person edited.
+      continue;
+    } else if (!target.endsWith(".xml")) {
+      related.push(`bytes:${sha256(files[target])}`);
+    } else {
+      // An XML payload this module has no reader for (a modern comment, an
+      // ink part): its words, never its serialization.
+      related.push(`${type}:${digestOf(stringsOf(readText(files, target)))}`);
+    }
+  }
+  return digestOf({
+    shapes: projectionOf(files, part),
+    style: styleOf(xml),
+    layout,
+    notes,
+    related: related.sort(),
+    background: background(files, part, xml),
+    hidden: /<p:sld\b[^>]*\bshow="0"/.test(xml),
+    transition: transition(xml),
+    animation: animation(xml),
+  });
+}
+
+/** Every slide's content digest, keyed by slide part. */
+export function slideContentDigests(files) {
+  return new Map(slideOrderPaths(files).map((part) => [part, slideContentDigest(files, part)]));
+}
+
+/**
+ * The deck's shared design as one digest: theme colours and fonts, every
+ * master's and layout's name and content, and the slide size. Equal across a
+ * save that re-serialized all of them without changing one.
+ */
+export function designDigest(files) {
+  const themes = [];
+  const layouts = [];
+  for (const part of Object.keys(files).sort()) {
+    if (/^ppt\/theme\/theme\d+\.xml$/.test(part)) {
+      const xml = readText(files, part) ?? "";
+      const colors = /<a:clrScheme\b[\s\S]*?<\/a:clrScheme>/.exec(xml)?.[0] ?? "";
+      const fonts = /<a:fontScheme\b[\s\S]*?<\/a:fontScheme>/.exec(xml)?.[0] ?? "";
+      themes.push(
+        digestOf({
+          colors: [...colors.matchAll(/\b(?:val|lastClr)="([^"]+)"/g)].map((m) => m[1].toUpperCase()),
+          fonts: [...fonts.matchAll(/<a:latin\b[^>]*\btypeface="([^"]*)"/g)].map((m) => m[1]),
+        }),
+      );
+    } else if (/^ppt\/(slideMasters\/slideMaster|slideLayouts\/slideLayout)\d+\.xml$/.test(part)) {
+      layouts.push(
+        digestOf({
+          kind: part.includes("slideMasters") ? "master" : "layout",
+          name: cSldName(files, part),
+          shapes: projectionOf(files, part),
+          background: background(files, part, readText(files, part) ?? ""),
+        }),
+      );
+    }
+  }
+  const size = /<p:sldSz\b[^>]*\/>/.exec(readText(files, "ppt/presentation.xml") ?? "")?.[0] ?? "";
+  return digestOf({
+    themes: themes.sort(),
+    layouts: layouts.sort(),
+    size: [/\bcx="(\d+)"/.exec(size)?.[1] ?? null, /\bcy="(\d+)"/.exec(size)?.[1] ?? null],
+  });
+}