slidemind 0.2.4 → 0.3.1

package/src/pptx/tags.mjs

@@ -0,0 +1,676 @@
+// Deck-embedded source: tag format for slidemind-authored slides (CLI mirror).
+//
+// A rendered slide carries its own authoring source as PowerPoint tags
+// (ppt/tags/*.xml referenced from p:custDataLst) so any user, machine, or
+// chat can recover the slides/<name>.jsx that produced it. Format spec:
+// intern-slidemind docs/deck-embedded-source-spec.md §2. The reference
+// implementation is the add-in's src/ui/src/agents/services/slide-source-tags.ts
+// — the two must stay format-identical (spec §9); change them in lockstep.
+
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { readText } from "./zip.mjs";
+import {
+  decodeXmlEntities,
+  firstSlidePath,
+  relsFor,
+  relsPathFor,
+  resolvePartPath,
+} from "./ooxml.mjs";
+
+export const CHUNK_BYTES = 12288;
+export const EMBED_BUDGET = 196608;
+export const SLIDEMIND_TAG_PREFIX = "SLIDEMIND_";
+
+export const TAG_GUID = "SLIDEMIND_GUID";
+export const TAG_SRC_META = "SLIDEMIND_SRC_META";
+export const TAG_SRC_CHUNK = "SLIDEMIND_SRC_";
+export const TAG_BASELINE_CHUNK = "SLIDEMIND_BASELINE_";
+export const TAG_ASSET_CHUNK = "SLIDEMIND_ASSET_";
+export const TAG_PROV = "SLIDEMIND_PROV";
+
+const TAGS_REL_TYPE =
+  "http://schemas.openxmlformats.org/officeDocument/2006/relationships/tags";
+const TAGS_CONTENT_TYPE =
+  "application/vnd.openxmlformats-officedocument.presentationml.tags+xml";
+const TAG_XML_NS =
+  'xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main"';
+
+export function mintSlideGuid() {
+  return `sm-${randomUUID()}`;
+}
+
+function sha256Hex(data) {
+  return createHash("sha256")
+    .update(typeof data === "string" ? Buffer.from(data, "utf8") : data)
+    .digest("hex");
+}
+
+function b64(bytes) {
+  return Buffer.from(bytes).toString("base64");
+}
+
+function chunk(s) {
+  const out = [];
+  for (let i = 0; i < s.length; i += CHUNK_BYTES) {
+    out.push(s.slice(i, i + CHUNK_BYTES));
+  }
+  return out.length ? out : [""];
+}
+
+function xmlEsc(s) {
+  return String(s)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+// ---------------------------------------------------------------------------
+// Encode / decode (spec §2.1/§2.2/§2.4)
+// ---------------------------------------------------------------------------
+
+// input: { name, jsx, guid, bundle:{presFP,etag}, renderer, assets:[{name,bytes}],
+//          baseline?, pushedAt, metaExtra? }
+// `metaExtra` merges extra properties into SRC_META (e.g. kind:"template-fill");
+// decoders ignore unknown properties.
+export function encodeSourceTags(input) {
+  const tags = { [TAG_GUID]: input.guid };
+
+  const jsxBytes = Buffer.from(input.jsx, "utf8");
+  const srcChunks = chunk(b64(jsxBytes));
+  srcChunks.forEach((c, i) => {
+    tags[`${TAG_SRC_CHUNK}${i}`] = c;
+  });
+
+  let baselineFields = {};
+  if (input.baseline) {
+    const json = JSON.stringify(input.baseline);
+    const chunks = chunk(b64(Buffer.from(json, "utf8")));
+    chunks.forEach((c, i) => {
+      tags[`${TAG_BASELINE_CHUNK}${i}`] = c;
+    });
+    baselineFields = {
+      baselineSha256: sha256Hex(json),
+      baselineChunks: chunks.length,
+    };
+  }
+
+  // Embed smallest-first within the budget; the rest stay remote.
+  const assets = input.assets ?? [];
+  const bySize = [...assets].sort((a, b) => a.bytes.length - b.bytes.length);
+  let budget = EMBED_BUDGET;
+  const embedded = new Set();
+  for (const asset of bySize) {
+    if (asset.bytes.length <= budget) {
+      budget -= asset.bytes.length;
+      embedded.add(asset.name);
+    }
+  }
+  let embedIdx = 0;
+  const assetMetas = [];
+  for (const asset of assets) {
+    const sha = sha256Hex(asset.bytes);
+    if (embedded.has(asset.name)) {
+      const chunks = chunk(b64(asset.bytes));
+      const idx = embedIdx++;
+      chunks.forEach((c, i) => {
+        tags[`${TAG_ASSET_CHUNK}${idx}_${i}`] = c;
+      });
+      assetMetas.push({
+        name: asset.name,
+        sha256: sha,
+        size: asset.bytes.length,
+        mode: "embedded",
+        idx,
+        chunks: chunks.length,
+      });
+    } else {
+      assetMetas.push({
+        name: asset.name,
+        sha256: sha,
+        size: asset.bytes.length,
+        mode: "remote",
+      });
+    }
+  }
+
+  tags[TAG_SRC_META] = JSON.stringify({
+    v: 1,
+    name: input.name,
+    srcSha256: sha256Hex(jsxBytes),
+    srcChunks: srcChunks.length,
+    ...baselineFields,
+    bundle: input.bundle,
+    renderer: input.renderer,
+    assets: assetMetas,
+    pushedAt: input.pushedAt,
+    ...(input.metaExtra ?? {}),
+  });
+  return tags;
+}
+
+// Deck-relative asset references in a slide source: "assets/logo.png",
+// "assets/images/photo.png". Mirrors ASSET_REF_RE in the add-in's
+// build-pptx/translate-deck.ts — an extension is required so prose mentions
+// don't match. Returns `[{ name: "assets/<rel>", bytes }]` for the ones that
+// exist on disk, which is exactly what encodeSourceTags embeds (within the
+// budget) and lists in SRC_META. Without this a locally-baked slide records
+// no assets at all, so `adopt` rebuilds jsx that points at missing images.
+const ASSET_REF_RE = /assets\/([A-Za-z0-9_\-.@/]+\.[A-Za-z0-9]+)/g;
+
+export function referencedAssets(jsx, assetsDir) {
+  const out = [];
+  const seen = new Set();
+  for (const m of String(jsx).matchAll(ASSET_REF_RE)) {
+    const name = m[1];
+    if (seen.has(name) || name.includes("..")) continue;
+    seen.add(name);
+    const file = path.join(assetsDir, name);
+    try {
+      if (!fs.statSync(file).isFile()) continue;
+      out.push({ name: `assets/${name}`, bytes: fs.readFileSync(file) });
+    } catch {
+      /* referenced but not on disk — nothing to embed */
+    }
+  }
+  return out;
+}
+
+function joinChunks(tags, prefix, count) {
+  let joined = "";
+  for (let i = 0; i < count; i++) {
+    const part = tags[`${prefix}${i}`];
+    if (part === undefined) return null;
+    joined += part;
+  }
+  return joined;
+}
+
+// Returns { guid, meta, jsx, baseline, assets } or null. Hash-verified —
+// a corrupt payload is never half-trusted (the slide then counts as foreign).
+export function decodeSourceTags(tags) {
+  const guid = tags?.[TAG_GUID];
+  const metaRaw = tags?.[TAG_SRC_META];
+  if (!guid || !metaRaw) return null;
+
+  let meta;
+  try {
+    meta = JSON.parse(metaRaw);
+  } catch {
+    return null;
+  }
+  if (meta?.v !== 1 || !meta.name || !meta.srcSha256 || !meta.srcChunks) {
+    return null;
+  }
+
+  const srcB64 = joinChunks(tags, TAG_SRC_CHUNK, meta.srcChunks);
+  if (srcB64 === null) return null;
+  const jsxBytes = Buffer.from(srcB64, "base64");
+  if (sha256Hex(jsxBytes) !== meta.srcSha256) return null;
+
+  let baseline = null;
+  if (meta.baselineSha256 && meta.baselineChunks) {
+    const raw = joinChunks(tags, TAG_BASELINE_CHUNK, meta.baselineChunks);
+    if (raw !== null) {
+      const json = Buffer.from(raw, "base64").toString("utf8");
+      if (sha256Hex(json) === meta.baselineSha256) {
+        try {
+          baseline = JSON.parse(json);
+        } catch {
+          baseline = null;
+        }
+      }
+    }
+  }
+
+  const assets = [];
+  for (const asset of meta.assets ?? []) {
+    if (asset.mode !== "embedded" || asset.idx === undefined || !asset.chunks) {
+      continue;
+    }
+    const raw = joinChunks(tags, `${TAG_ASSET_CHUNK}${asset.idx}_`, asset.chunks);
+    if (raw === null) continue;
+    const bytes = Buffer.from(raw, "base64");
+    if (sha256Hex(bytes) !== asset.sha256) continue;
+    assets.push({ name: asset.name, sha256: asset.sha256, bytes });
+  }
+
+  return { guid, meta, jsx: jsxBytes.toString("utf8"), baseline, assets };
+}
+
+// ---------------------------------------------------------------------------
+// Package-side reads
+// ---------------------------------------------------------------------------
+
+// Read every tag reachable from a slide part's custDataLst refs (slide-level
+// AND shape-level — keys never collide: shapes carry only SLIDEMIND_PROV).
+export function readSlideTags(files, slidePath) {
+  const xml = readText(files, slidePath);
+  if (!xml) return {};
+  const tagRels = {};
+  const dir = slidePath.slice(0, slidePath.lastIndexOf("/"));
+  for (const rel of relsFor(files, slidePath)) {
+    if (rel.id && rel.type === TAGS_REL_TYPE) {
+      tagRels[rel.id] = resolvePartPath(dir, rel.target);
+    }
+  }
+  const out = {};
+  for (const cust of xml.matchAll(/<p:custDataLst\b[\s\S]*?<\/p:custDataLst>/g)) {
+    for (const ref of cust[0].matchAll(/<p:tags\b[^>]*\br:id="([^"]+)"/g)) {
+      const partPath = tagRels[ref[1]];
+      const tagXml = partPath ? readText(files, partPath) : null;
+      if (!tagXml) continue;
+      for (const t of tagXml.matchAll(/<p:tag\b([^>]*)\/>/g)) {
+        const name = t[1].match(/\bname="([^"]*)"/)?.[1];
+        const val = t[1].match(/\bval="([^"]*)"/)?.[1];
+        if (name) out[decodeXmlEntities(name)] = decodeXmlEntities(val ?? "");
+      }
+    }
+  }
+  return out;
+}
+
+// True when a slide part carries any tag key OUTSIDE the SLIDEMIND_ namespace
+// (another add-in marked it — think-cell tags every shape it owns).
+export function slideHasForeignTags(files, slidePath) {
+  for (const key of Object.keys(readSlideTags(files, slidePath))) {
+    if (!key.startsWith(SLIDEMIND_TAG_PREFIX)) return true;
+  }
+  return false;
+}
+
+
+// True when the slide references an embedded WORKBOOK (.xls*) — the
+// think-cell "slide workbook" pattern. Deliberately NOT any embeddings/*.bin:
+// generic hidden OLE junk (developer-machine leftovers) also lives under
+// ppt/embeddings/ and is exactly what the hidden-OLE strip must keep removing.
+export function slideReferencesEmbeddedWorkbook(files, slidePath) {
+  const dir = slidePath.slice(0, slidePath.lastIndexOf("/"));
+  for (const rel of relsFor(files, slidePath)) {
+    if (rel.targetMode === "External" || !rel.target) continue;
+    const target = resolvePartPath(dir, rel.target);
+    if (target.startsWith("ppt/embeddings/") && /\.xls[xmb]?$/i.test(target)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Bake (spec §5.4) — ADDITIVE ONLY (coexistence rule C1)
+// ---------------------------------------------------------------------------
+
+function tagPartXml(tags) {
+  return (
+    `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\r\n<p:tagLst ${TAG_XML_NS}>` +
+    Object.entries(tags)
+      .map(([name, val]) => `<p:tag name="${xmlEsc(name)}" val="${xmlEsc(val)}"/>`)
+      .join("") +
+    `</p:tagLst>`
+  );
+}
+
+function nextTagIndex(files) {
+  let max = 0;
+  for (const name of Object.keys(files)) {
+    const m = name.match(/^ppt\/tags\/tag(\d+)\.xml$/);
+    if (m) max = Math.max(max, Number(m[1]));
+  }
+  return max + 1;
+}
+
+function nextRid(relsXml) {
+  let max = 0;
+  for (const m of relsXml.matchAll(/\bId="rId(\d+)"/g)) {
+    max = Math.max(max, Number(m[1]));
+  }
+  return max + 1;
+}
+
+const enc = (s) => new TextEncoder().encode(s);
+
+// Bake slide-level SLIDEMIND tags into the entry map IN PLACE.
+// entries = [{ partName, tags }] with `tags` from encodeSourceTags. Existing
+// tag parts, rels, and custDataLst content are never modified or renumbered.
+export function bakeSlideSourceTags(files, entries) {
+  if (!entries?.length) return false;
+  let contentTypes = readText(files, "[Content_Types].xml") ?? "";
+  let tagIndex = nextTagIndex(files);
+  let changed = false;
+
+  for (const entry of entries) {
+    const slideXml = readText(files, entry.partName);
+    if (!slideXml || !slideXml.includes("</p:cSld>")) continue;
+
+    const partName = `ppt/tags/tag${tagIndex}.xml`;
+    files[partName] = enc(tagPartXml(entry.tags));
+    if (!contentTypes.includes(`PartName="/${partName}"`)) {
+      contentTypes = contentTypes.replace(
+        "</Types>",
+        `<Override PartName="/${partName}" ContentType="${TAGS_CONTENT_TYPE}"/></Types>`,
+      );
+    }
+
+    const relsPath = relsPathFor(entry.partName);
+    const relsXml =
+      readText(files, relsPath) ??
+      `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\r\n<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"></Relationships>`;
+    const rId = `rId${nextRid(relsXml)}`;
+    files[relsPath] = enc(
+      relsXml.replace(
+        "</Relationships>",
+        `<Relationship Id="${rId}" Type="${TAGS_REL_TYPE}" Target="../tags/tag${tagIndex}.xml"/></Relationships>`,
+      ),
+    );
+
+    // Slide-level custDataLst sits in p:cSld directly after p:spTree
+    // (ECMA-376 CT_CommonSlideData order, maxOccurs 1). Append to an existing
+    // list, else insert a fresh one. The existing element is matched
+    // attribute- and self-closing-tolerantly: a second <p:custDataLst> in one
+    // p:cSld is exactly the malformed placement rule C5 forbids (PowerPoint
+    // repairs the file on open).
+    const existingCust = slideXml.match(
+      /<\/p:spTree>\s*<p:custDataLst\b[^>]*?(\/?)>/,
+    );
+    let nextXml;
+    if (existingCust && existingCust[1] === "/") {
+      // Empty <p:custDataLst/> — expand it into a list holding our ref.
+      nextXml = slideXml.replace(
+        existingCust[0],
+        `${existingCust[0].replace(/\/>$/, ">")}<p:tags r:id="${rId}"/></p:custDataLst>`,
+      );
+    } else if (existingCust) {
+      nextXml = slideXml.replace(
+        existingCust[0],
+        `${existingCust[0]}<p:tags r:id="${rId}"/>`,
+      );
+    } else {
+      nextXml = slideXml.replace(
+        "</p:spTree>",
+        `</p:spTree><p:custDataLst><p:tags r:id="${rId}"/></p:custDataLst>`,
+      );
+    }
+    files[entry.partName] = enc(nextXml);
+    tagIndex += 1;
+    changed = true;
+  }
+
+  // Never write back an EMPTY content-type map: a package without one is
+  // already broken, and clobbering it would turn a missing part into a
+  // truncated one.
+  if (changed && contentTypes) {
+    files["[Content_Types].xml"] = enc(contentTypes);
+  }
+  return changed;
+}
+
+
+// ---------------------------------------------------------------------------
+// Structural projection (spec §2.5) — MIRROR of computeProjection in the
+// add-in's src/ui/src/agents/services/slide-source-tags.ts
+// ---------------------------------------------------------------------------
+//
+// Deterministic function over a single-slide OOXML package: the drift baseline
+// P(slide). The two implementations are cross-checked by the shared fixtures in
+// test/fixtures/slide-source-tags/ (spec §9) — same original.pptx in both
+// repos, same committed expected-projection.json, one CI job on each side.
+// Every regex, every default and every rounding rule below is copied from the
+// TypeScript, deliberately verbatim; change them in lockstep or the parity test
+// goes red.
+//
+// The CLI reads an already-unzipped `files` map, so this is synchronous where
+// the TS is async over JSZip. That is the only intended difference.
+
+// The five shape elements, plus the two non-shape children that also count as a
+// top-level unit: mc:AlternateContent and p:contentPart. PowerPoint serializes
+// an embedded OLE object as a single p:spTree child holding a FULL copy of the
+// frame in each markup-compatibility branch (mc:Choice graphicFrame +
+// mc:Fallback picture). Counting the branch shapes instead of the wrapper made
+// one object read as two top-level shapes, and the add-in's foreign lift then
+// appended BOTH branches — the object shipped twice, unwrapped. One block is one
+// unit, at the wrapper's own position, in every raw-XML scanner on both sides of
+// the mirror.
+//
+// LOCKSTEP: the add-in exports this same pattern as the factory
+// `topLevelShapeRe()` in src/ui/src/agents/services/slide-source-tags.ts, where
+// three scanners share it. Here it stays a plain const: this file is its ONLY
+// consumer, so there is nothing to centralize — but the pattern itself must
+// still change on both sides at once, or expected-projection.json goes red.
+const TOP_SHAPE_RE =
+  /<(\/?)(?:p:(sp|grpSp|pic|graphicFrame|cxnSp|contentPart)|mc:(AlternateContent))(?=[\s/>])[^>]*?(\/?)>/g;
+
+// Both non-shape units project as the carrier the wrapped object uses — a
+// graphic frame. Canonical, so the two implementations of this projection cannot
+// disagree about a unit's kind.
+const UNIT_BLOCK_KIND = "graphicFrame";
+
+// Split the spTree inner XML into top-level shape subtrees (depth-aware).
+function topLevelShapes(spTreeInner) {
+  const shapes = [];
+  let depth = 0;
+  let start = -1;
+  let startKind = null;
+  // Tracked separately from `depth`: an MC block is a CONTAINER, not a shape.
+  let mcDepth = 0;
+  let mcStart = -1;
+  TOP_SHAPE_RE.lastIndex = 0;
+  for (const m of spTreeInner.matchAll(TOP_SHAPE_RE)) {
+    const closing = m[1] === "/";
+    const selfClosing = m[4] === "/";
+    if (m[3]) {
+      // Only a TOP-LEVEL wrapper is a unit: one nested inside a shape is that
+      // shape's own business, and a self-closing one carries no shape at all.
+      if (depth > 0 || selfClosing) continue;
+      if (!closing) {
+        if (mcDepth === 0) mcStart = m.index;
+        mcDepth++;
+      } else if (mcDepth > 0) {
+        mcDepth--;
+        if (mcDepth === 0 && mcStart >= 0) {
+          shapes.push({
+            kind: UNIT_BLOCK_KIND,
+            xml: spTreeInner.slice(mcStart, m.index + m[0].length),
+          });
+          mcStart = -1;
+        }
+      }
+      continue;
+    }
+    // Every shape inside a top-level MC block belongs to a branch of the ONE
+    // unit that block already is, so it never opens a unit of its own.
+    if (mcDepth > 0) continue;
+    // p:contentPart is a bare r:id reference, not a shape carrier: it projects
+    // as the same canonical unit kind an MC block does.
+    const kind = m[2] === "contentPart" ? UNIT_BLOCK_KIND : m[2];
+    if (!closing && !selfClosing) {
+      if (depth === 0) {
+        start = m.index;
+        startKind = kind;
+      }
+      depth++;
+    } else if (closing) {
+      depth--;
+      if (depth === 0 && start >= 0 && startKind) {
+        shapes.push({
+          kind: startKind,
+          xml: spTreeInner.slice(start, m.index + m[0].length),
+        });
+        start = -1;
+        startKind = null;
+      }
+    } else if (selfClosing && depth === 0) {
+      shapes.push({ kind, xml: m[0] });
+    }
+  }
+  return shapes;
+}
+
+const roundEmu = (n) => Math.round(n / 100) * 100;
+
+function parseXfrm(xml) {
+  const xfrm = xml.match(
+    /<(?:a|p):xfrm\b([^>]*)>[\s\S]*?<a:off\b([^>]*)\/>\s*<a:ext\b([^>]*)\/>/,
+  );
+  if (!xfrm) return { x: 0, y: 0, w: 0, h: 0, rot: 0 };
+  const rot60k = Number(xfrm[1].match(/\brot="(-?\d+)"/)?.[1] ?? 0);
+  const x = Number(xfrm[2].match(/\bx="(-?\d+)"/)?.[1] ?? 0);
+  const y = Number(xfrm[2].match(/\by="(-?\d+)"/)?.[1] ?? 0);
+  const w = Number(xfrm[3].match(/\bcx="(\d+)"/)?.[1] ?? 0);
+  const h = Number(xfrm[3].match(/\bcy="(\d+)"/)?.[1] ?? 0);
+  return {
+    x: roundEmu(x),
+    y: roundEmu(y),
+    w: roundEmu(w),
+    h: roundEmu(h),
+    rot: Math.round(rot60k / 60000),
+  };
+}
+
+// The five predefined entities plus DECIMAL character references, in the TS's
+// order (ampersand last, so a decoded `&` is never re-read as an entity head).
+// NOT decodeXmlEntities: that one also decodes hex refs, which the TS reader
+// does not — a projection must not decode more than its twin does.
+function xmlUnescape(s) {
+  return s
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&#(\d+);/g, (_, n) => String.fromCodePoint(Number(n)))
+    .replace(/&amp;/g, "&");
+}
+
+// Two text carriers, one walk. `p:txBody` covers sp/pic/cxnSp/grpSp children;
+// a table graphicFrame has NO `p:txBody` at all — its text lives in
+// `a:tbl/a:tr/a:tc/a:txBody`, which is why table cell edits used to be invisible
+// to drift detection. Matching the whole `a:tbl` subtree leaves the run walk
+// untouched: XML document order inside `a:tbl` (rows in order, cells in order
+// within a row) IS row-major reading order, and the frame keeps its position in
+// the shape sequence because this runs per top-level shape. Merge-continuation
+// cells (`hMerge`/`vMerge`) carry no runs, so they add nothing — cell index is
+// NOT recoverable from the run index, exactly as for a multi-paragraph frame.
+function parseTextRuns(xml) {
+  const runs = [];
+  const carriers =
+    /<p:txBody>[\s\S]*?<\/p:txBody>|<a:tbl\b[^>]*>[\s\S]*?<\/a:tbl>/g;
+  for (const body of xml.matchAll(carriers)) {
+    for (const r of body[0].matchAll(/<a:r>([\s\S]*?)<\/a:r>/g)) {
+      const run = r[1];
+      const t = run.match(/<a:t>([\s\S]*?)<\/a:t>/)?.[1] ?? "";
+      const rPr = run.match(/<a:rPr\b([^>]*)(?:\/>|>([\s\S]*?)<\/a:rPr>)/);
+      const attrs = rPr?.[1] ?? "";
+      const inner = rPr?.[2] ?? "";
+      runs.push({
+        t: xmlUnescape(t),
+        b: /\bb="1"/.test(attrs),
+        i: /\bi="1"/.test(attrs),
+        sz: attrs.match(/\bsz="(\d+)"/)
+          ? Number(attrs.match(/\bsz="(\d+)"/)?.[1])
+          : null,
+        color:
+          inner.match(/<a:srgbClr val="([0-9A-Fa-f]{6})"/)?.[1]?.toUpperCase() ??
+          null,
+      });
+    }
+  }
+  return runs.length ? runs : null;
+}
+
+function firstSolidFill(section) {
+  if (!section) return null;
+  return (
+    section
+      .match(/<a:solidFill>\s*<a:srgbClr val="([0-9A-Fa-f]{6})"/)?.[1]
+      ?.toUpperCase() ?? null
+  );
+}
+
+function parseFillAndLine(xml) {
+  const spPr = xml.match(/<p:spPr\b[^>]*>([\s\S]*?)<\/p:spPr>/)?.[1] ?? null;
+  if (!spPr) return { fill: null, line: null };
+  const lnMatch = spPr.match(/<a:ln\b[\s\S]*?<\/a:ln>/);
+  const ln = lnMatch ? lnMatch[0] : null;
+  const spPrNoLn = ln ? spPr.replace(ln, "") : spPr;
+  return { fill: firstSolidFill(spPrNoLn), line: firstSolidFill(ln) };
+}
+
+// rId -> { type, target } for one part, mirroring the TS parseRels map.
+function relsById(files, partPath) {
+  const map = new Map();
+  for (const rel of relsFor(files, partPath)) {
+    if (rel.id) map.set(rel.id, { type: rel.type ?? "", target: rel.target ?? "" });
+  }
+  return map;
+}
+
+function parseMediaSha(files, slidePath, shapeXml) {
+  const rId = shapeXml.match(/<a:blip\b[^>]*\br:embed="([^"]+)"/)?.[1];
+  if (!rId) return null;
+  const rel = relsById(files, slidePath).get(rId);
+  if (!rel) return null;
+  const dir = slidePath.slice(0, slidePath.lastIndexOf("/"));
+  const bytes = files[resolvePartPath(dir, rel.target)];
+  if (!bytes) return null;
+  return sha256Hex(bytes);
+}
+
+function parseProv(files, slidePath, shapeXml) {
+  const nv = shapeXml.match(/<p:nvPr>[\s\S]*?<\/p:nvPr>/)?.[0];
+  if (!nv) return null;
+  const cust = nv.match(/<p:custDataLst\b[\s\S]*?<\/p:custDataLst>/)?.[0];
+  if (!cust) return null;
+  const rels = relsById(files, slidePath);
+  const dir = slidePath.slice(0, slidePath.lastIndexOf("/"));
+  const tags = {};
+  for (const m of cust.matchAll(/<p:tags\b[^>]*\br:id="([^"]+)"/g)) {
+    const rel = rels.get(m[1]);
+    if (!rel?.type.endsWith("/tags")) continue;
+    const tagXml = readText(files, resolvePartPath(dir, rel.target));
+    if (!tagXml) continue;
+    for (const t of tagXml.matchAll(/<p:tag\b([^>]*)\/>/g)) {
+      const name = t[1].match(/\bname="([^"]+)"/)?.[1];
+      const val = t[1].match(/\bval="([^"]*)"/)?.[1];
+      if (name) tags[xmlUnescape(name)] = xmlUnescape(val ?? "");
+    }
+  }
+  const raw = tags[TAG_PROV];
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed?.f === "string" && typeof parsed?.p === "string") {
+      return parsed;
+    }
+  } catch {
+    /* not a provenance ref */
+  }
+  return null;
+}
+
+// Structural projection of a slide in an unzipped package (the FIRST slide when
+// `slidePathOverride` is omitted — the single-slide case). Deterministic;
+// excludes every id/name/theme-resolved churn source. Groups are one entry each
+// (molecule = reconcile unit); their child text runs are collected in document
+// order.
+export function computeProjection(files, slidePathOverride) {
+  const slidePath = slidePathOverride ?? firstSlidePath(files);
+  if (!slidePath) return { v: 1, shapes: [] };
+  const xml = readText(files, slidePath) ?? "";
+  const spTree = xml.match(/<p:spTree>([\s\S]*?)<\/p:spTree>/)?.[1] ?? "";
+  const shapes = [];
+  for (const raw of topLevelShapes(spTree)) {
+    const paint = parseFillAndLine(raw.xml);
+    shapes.push({
+      prov: parseProv(files, slidePath, raw.xml),
+      kind: raw.kind,
+      geom: parseXfrm(raw.xml),
+      text: parseTextRuns(raw.xml),
+      fill: paint.fill,
+      line: paint.line,
+      mediaSha256: parseMediaSha(files, slidePath, raw.xml),
+    });
+  }
+  return { v: 1, shapes };
+}