slidemind 0.3.20 → 0.4.0

package/src/pptx/fill/engine.mjs

@@ -36,6 +36,7 @@ import {
   insertPictureAtGeom, findShape, esc, imageSize, cellText, blocks,
   shapeFillXml, shapeRunRPr, setShapeFillXml,
 } from "./xml.mjs";
+import { deckPptxPath } from "../../lib/deck-paths.mjs";
 
 const enc = (s) => new TextEncoder().encode(s);
 const RESERVED_PROPS = new Set(["repeat", "tables", "patches", "highlight"]);
@@ -128,9 +129,7 @@ export async function buildFillTemplateDeck({ deckDir, skill, outPath, onLog })
     throw new Error(`integrity check failed:\n  - ${integrity.join("\n  - ")}`);
   }
 
-  const finalOut = outPath
-    ? path.resolve(outPath)
-    : path.join(deckDir, `${path.basename(deckDir)}.pptx`);
+  const finalOut = outPath ? path.resolve(outPath) : deckPptxPath(deckDir);
   fs.writeFileSync(finalOut, zip(files));
   return { outPath: finalOut, slideCount: output.length, warnings };
 }

package/src/pptx/fill/freeform.mjs

@@ -19,6 +19,7 @@ import { unzip, readText } from "../zip.mjs";
 import { slideOrderPaths } from "../ooxml.mjs";
 import { foldPickedSlides } from "../slide-swap.mjs";
 import { layoutNumber } from "./parse-slides.mjs";
+import { deckBundleRefPath } from "../../bridge/bundle.mjs";
 
 const SIDE_CAR = ".freeform-renders.json";
 
@@ -107,7 +108,7 @@ export async function ensureFreeformRenders({
   // of the freshness key — a CD update re-renders the freeform slides.
   let etag = "";
   try {
-    const ref = JSON.parse(fs.readFileSync(path.join(deckDir, ".bundle-ref.json"), "utf8"));
+    const ref = JSON.parse(fs.readFileSync(deckBundleRefPath(deckDir), "utf8"));
     etag = ref?.etag ?? "";
   } catch {
     etag = "";
@@ -133,9 +134,11 @@ export async function ensureFreeformRenders({
         if (fs.existsSync(assetsDir)) {
           fs.cpSync(assetsDir, path.join(tmp, "assets"), { recursive: true });
         }
-        const refPath = path.join(deckDir, ".bundle-ref.json");
+        const refPath = deckBundleRefPath(deckDir);
         if (fs.existsSync(refPath)) {
-          fs.copyFileSync(refPath, path.join(tmp, ".bundle-ref.json"));
+          const tmpRef = deckBundleRefPath(tmp);
+          fs.mkdirSync(path.dirname(tmpRef), { recursive: true });
+          fs.copyFileSync(refPath, tmpRef);
         }
         const outPath = path.join(tmp, "render.pptx");
         try {

package/src/pptx/ooxml.mjs

@@ -145,6 +145,26 @@ function normalizeSegments(parts) {
   return out.join("/");
 }
 
+// One `<p:tag .../>` element: the whole element, its attributes in group 1.
+// Quote-aware on purpose: PowerPoint writes `>` UNESCAPED inside an attribute
+// value (valid XML), and a `[^>]*` match stops there — the value is cut off
+// and the tag silently lost. Observed on a Mac PowerPoint save (2026-10-09):
+// every SLIDEMIND_PROV whose selector read `svg > <line>` came back unreadable.
+// Both quote styles XML allows, and both spellings of an empty element
+// (`<p:tag …/>`, `<p:tag …></p:tag>`), are read.
+export const TAG_ELEMENT = String.raw`<p:tag\b((?:[^>"']|"[^"]*"|'[^']*')*?)(?:\/>|><\/p:tag>)`;
+
+/** One attribute of a `<p:tag>`'s attribute string, in either quote style — undecoded. */
+export function tagAttr(attrs, name) {
+  const m = new RegExp(`\\b${name}=(?:"([^"]*)"|'([^']*)')`).exec(String(attrs ?? ""));
+  return m ? (m[1] ?? m[2]) : undefined;
+}
+
+/** Every `<p:tag/>` element of a tag list, attributes in group 1. */
+export function tagElements(tagXml) {
+  return String(tagXml ?? "").matchAll(new RegExp(TAG_ELEMENT, "g"));
+}
+
 // Decode the five predefined XML entities plus numeric character references
 // (`&#233;`, `&#xE9;`). Ampersand is resolved LAST so a decoded `&` from a
 // numeric ref can't be re-read as the head of another entity.

package/src/pptx/package-evidence.mjs

@@ -0,0 +1,383 @@
+// What a delivered package proves about one slide's objects.
+//
+// `src/lib/preservation-verdict.mjs` compares NORMALIZED projections keyed by
+// element identity — deliberately, so that one pure module can serve both
+// clients without importing either one's package machinery. It does not read
+// packages. Nothing did, which is why the final delivery gate could never reach
+// `passed`: a connector's endpoints and a native object's dependency closure
+// only resolve against the delivered bytes, and no one produced that evidence.
+//
+// This module is that producer, on the CLI side. It takes an unzipped package
+// and returns exactly what `comparePackageEvidence` and `preservationVerdict`
+// consume:
+//
+//   shapes           { [elementId]: projection shape (+ native / chart) }
+//   resolvedTargets  what this PACKAGE resolves — read the warning below
+//   tables           per-element grid evidence (see the note below)
+//   connectors       per-element { start, end } as each connector claims them
+//   natives          per-element { kind, progId, parts, digests }
+//
+// ---------------------------------------------------------------------------
+// WARNING — `resolvedTargets` speaks ONE namespace, and a requirement's
+// `target` may be written in any of three
+// ---------------------------------------------------------------------------
+//
+// A preservation requirement's `relationships[].target`
+// (`src/lib/slide-preservation.mjs`) is minted in the namespace its `role`
+// belongs to, and they are not interchangeable:
+//
+//   role            target is                          resolved by
+//   start / end     an ELEMENT id on this slide         this module
+//   package-part    a WORKSPACE path                    the caller
+//                   (`conversions/<stem>.slide.pptx`)
+//   native-slot     an INDEX into the conversion        the caller
+//                   record's `preserved[]`
+//
+// `resolvedTargets` contains element ids and the package's own part paths. It
+// does NOT contain workspace paths or slot indices, and it never will — this
+// module reads one .pptx and knows nothing about a deck's conversion records.
+//
+// **The consequence, stated so nobody has to rediscover it: resolving a
+// non-element target against this set produces a FALSE DELETION.** The
+// obligation looks unmet, the slide looks broken, and the gate refuses a
+// delivery that lost nothing. That is strictly worse than the `unknown` it
+// replaced, and it reached `PRESERVATION FAILED` on a clean deck once already.
+//
+// A caller holding requirements of mixed roles must resolve each one in its own
+// namespace and union the results — which is what `packageEvidenceFor` in the
+// delivery gate does. There is deliberately no `targetsByRole` here: one
+// consumer exists and it has solved this, and a second mechanism for one job
+// would only be a second thing to keep in step. Add it when a second consumer
+// makes the shape obvious.
+//
+// Four rules it exists to keep:
+//
+//   * **One normalizer.** The units, their order and the MC-block rule come
+//     from `computeProjection`'s own `topLevelShapes`. A second split would
+//     drift, and a drifted split relabels every element on the slide.
+//   * **No ZIP byte streams, and no part PATHS either.** Package timestamps,
+//     relationship ids, part ordering and part NAMES all legitimately change —
+//     delivery renames an imported embedding whenever the name is taken. What
+//     is compared is the normalized projection, the RESOLVED targets of
+//     relationships, and, for an opaque payload, the digest of its bytes. A
+//     path-keyed comparison reports a relocated object as a deleted one.
+//   * **Identity, never count.** A native object is bound to the parts it
+//     depends on and a connector to the shape ids at its ends. Swapping either
+//     for something else leaves the counts identical, which is exactly how E11
+//     and E17 get through a check that only counts.
+//   * **A moved object is still that object.** E17's clause: an allowed
+//     position change must not lose the native or its closure. Geometry lives
+//     in its own scope, so moving a frame changes `geom` and nothing else —
+//     the closure digests are computed from the parts, not from the placement.
+
+import { createHash } from "node:crypto";
+
+import { relsFor, resolvePartPath, slideOrderPaths } from "./ooxml.mjs";
+import { computeProjection, topLevelShapes } from "./tags.mjs";
+import { readText } from "./zip.mjs";
+
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+
+/** Relationship types whose target is a document of its own, not a payload. */
+const NON_PAYLOAD_REL = /\/(slideLayout|slideMaster|notesSlide|theme|tags)$/;
+
+// ---------------------------------------------------------------------------
+// Identity
+// ---------------------------------------------------------------------------
+
+/**
+ * The `p:cNvPr/@id` of one top-level unit, as a string.
+ *
+ * The FIRST id in the unit's own XML: for an `mc:AlternateContent` block that
+ * is the `mc:Choice` branch's frame, which is the object itself — the
+ * `mc:Fallback` picture beside it carries a different id and is a preview of
+ * the same thing, never a second element. This is the same spelling the
+ * converted dialect uses (`data-sm-source-id={60}`) and the same one a
+ * preservation requirement for an imported slide carries, so a record, a source
+ * file and a package all name an element one way.
+ */
+export function unitElementId(unitXml) {
+  const m = /<p:cNvPr\b[^>]*\bid="(\d+)"/.exec(String(unitXml ?? ""));
+  return m ? m[1] : null;
+}
+
+// ---------------------------------------------------------------------------
+// Dependency closure
+// ---------------------------------------------------------------------------
+
+/** Every `r:id` / `r:embed` / `r:link` a unit's XML names. */
+function relIdsIn(unitXml) {
+  const ids = new Set();
+  for (const m of String(unitXml ?? "").matchAll(/\br:(?:id|embed|link|pict|dm|lo|qs|cs)="([^"]+)"/g)) ids.add(m[1]);
+  return ids;
+}
+
+/**
+ * The parts reachable from `starts`, with each one's digest.
+ *
+ * Breadth-first over the package's own relationships, so a chart's embedded
+ * workbook and an OLE object's sidecars are in the closure even though the
+ * slide never names them directly. External targets are skipped: they are a
+ * URL, not bytes this package can lose. Layouts, masters, themes, notes and
+ * tag parts are skipped too — they are documents the whole deck shares, not
+ * this object's payload, and pulling them in would make every element's
+ * closure the entire deck.
+ *
+ * @returns {Record<string, string>} part path → sha256 of its bytes
+ */
+export function dependencyDigests(files, starts) {
+  const digests = {};
+  const queue = [...starts];
+  const seen = new Set(starts);
+  while (queue.length) {
+    const part = queue.shift();
+    const bytes = files[part];
+    if (bytes === undefined) continue; // a missing part is reported by its absence
+    digests[part] = sha256(bytes);
+    const dir = part.slice(0, part.lastIndexOf("/"));
+    for (const rel of relsFor(files, part)) {
+      if (rel.targetMode === "External") continue;
+      if (NON_PAYLOAD_REL.test(rel.type ?? "")) continue;
+      const target = resolvePartPath(dir, rel.target);
+      if (!target || seen.has(target)) continue;
+      seen.add(target);
+      queue.push(target);
+    }
+  }
+  return digests;
+}
+
+/**
+ * Turn a path -> digest map into the map `comparePackageEvidence` compares:
+ * keyed by CONTENT, valued by how many parts carry those bytes.
+ *
+ * Not by path, and that is the whole point. Delivery renames parts — an
+ * imported OLE embedding comes back as `oleObject2.bin` when its neighbour
+ * already holds `oleObject1.bin` — so a path-keyed map reports a relocated
+ * object as a DELETED one. A false deletion is the worst direction for a
+ * preservation gate to be wrong in: it refuses a delivery that lost nothing.
+ * Bytes are what a native object's dependency actually is; where the package
+ * files them is the package's business.
+ *
+ * The value is the COUNT rather than the digest again, so that dropping one of
+ * two parts that happen to share bytes still moves the map. The readable
+ * path->digest mapping stays in `natives[elementId].digests`, because a human
+ * reading a failure needs the path and a comparison must not.
+ */
+function contentKeyedParts(digests) {
+  const parts = {};
+  for (const sha of Object.values(digests)) {
+    const key = `sha256:${sha}`;
+    parts[key] = String((Number(parts[key] ?? 0)) + 1);
+  }
+  return parts;
+}
+
+// ---------------------------------------------------------------------------
+// Native objects
+// ---------------------------------------------------------------------------
+
+/** Does this unit carry an opaque object the package must keep whole? */
+export function nativeKindOf(unitXml) {
+  const xml = String(unitXml ?? "");
+  if (/<p:oleObj\b/.test(xml)) return "ole";
+  if (/<p:contentPart\b/.test(xml)) return "contentPart";
+  if (/graphicData[^>]*uri="[^"]*\/(diagram|smartArt)"/.test(xml)) return "diagram";
+  if (/<mc:AlternateContent\b/.test(xml)) return "alternateContent";
+  return null;
+}
+
+/** The `progId` an OLE object declares — its identity beyond its bytes. */
+const progIdOf = (unitXml) => /\bprogId="([^"]*)"/.exec(String(unitXml ?? ""))?.[1] ?? null;
+
+// ---------------------------------------------------------------------------
+// Charts — data residue, not a re-serialization digest
+// ---------------------------------------------------------------------------
+
+/**
+ * A chart's DATA as the package carries it: every series' name, its category
+ * cache and its value cache, with the formula each came from.
+ *
+ * Deliberately not a digest of the chart part. PowerPoint re-serializes a chart
+ * on every save and materializes its own defaults into it, so an XML hash
+ * reports drift on a deck nobody touched (the note in `src/pptx/tags.mjs` says
+ * the same thing about why this repo has no ChartSpec hash). The cached values
+ * and the refs they came from are what a build must not silently lose, and they
+ * survive that round trip.
+ *
+ * This is NOT the add-in's `ProjectionShape.chart`, which is a hash over its
+ * canonical ChartSpec. Both answer "did this chart's data change"; they are not
+ * interchangeable, which is why a verdict is always computed from ONE
+ * composer's own before and after.
+ */
+export function chartResidue(chartXml) {
+  const xml = String(chartXml ?? "");
+  const series = [];
+  for (const ser of xml.matchAll(/<c:ser\b[\s\S]*?<\/c:ser>/g)) {
+    const block = ser[0];
+    const cache = (section) => {
+      const found = block.match(new RegExp(`<c:${section}\\b[\\s\\S]*?</c:${section}>`));
+      if (!found) return null;
+      return {
+        f: /<c:f>([\s\S]*?)<\/c:f>/.exec(found[0])?.[1] ?? null,
+        pts: [...found[0].matchAll(/<c:pt\b[^>]*idx="(\d+)"[^>]*>\s*<c:v>([\s\S]*?)<\/c:v>/g)].map((m) => [
+          Number(m[1]),
+          m[2],
+        ]),
+      };
+    };
+    series.push({ idx: Number(/<c:idx\b[^>]*val="(\d+)"/.exec(block)?.[1] ?? 0), tx: cache("tx"), cat: cache("cat"), val: cache("val") });
+  }
+  series.sort((a, b) => a.idx - b.idx);
+  return series.length ? series : null;
+}
+
+// ---------------------------------------------------------------------------
+// Tables
+// ---------------------------------------------------------------------------
+
+/**
+ * A table's GRID: how many rows and columns, and which cells are merge
+ * continuations. Cell TEXT is already in the projection's `text` scope
+ * (`parseTextRuns` walks `a:tbl`), so this is the part that text alone cannot
+ * prove — a merged cell whose neighbour was absorbed keeps every word.
+ *
+ * Sibling evidence, not a property scope: `PROPERTY_SCOPES` is a shared
+ * contract (`src/lib/edit-operations.mjs`) and a table grid is not one of the
+ * seven things a requirement can protect. A round-trip test asserts it
+ * directly; a row that genuinely disappears also loses its text, which the
+ * verdict does see.
+ */
+export function tableGrid(unitXml) {
+  const tbl = String(unitXml ?? "").match(/<a:tbl\b[\s\S]*?<\/a:tbl>/)?.[0];
+  if (!tbl) return null;
+  const declared = (tbl.match(/<a:gridCol\b/g) ?? []).length;
+  const rows = [...tbl.matchAll(/<a:tr\b[\s\S]*?<\/a:tr>/g)].map((r) =>
+    [...r[0].matchAll(/<a:tc\b([^>]*)>/g)].map((c) => {
+      const attrs = c[1];
+      const span = /\bgridSpan="(\d+)"/.exec(attrs)?.[1];
+      const row = /\browSpan="(\d+)"/.exec(attrs)?.[1];
+      if (/\bhMerge="1"/.test(attrs)) return "h";
+      if (/\bvMerge="1"/.test(attrs)) return "v";
+      if (span || row) return `${span ?? 1}x${row ?? 1}`;
+      return ".";
+    }),
+  );
+  // A table without an `a:tblGrid` still has a column count — its widest row.
+  return { cols: declared || Math.max(0, ...rows.map((r) => r.length)), rows };
+}
+
+// ---------------------------------------------------------------------------
+// The composer
+// ---------------------------------------------------------------------------
+
+/**
+ * Compose one slide's package evidence.
+ *
+ * @param {Record<string, Uint8Array>} files an unzipped package
+ * @param {{slidePart?: string|null}} [opts]
+ * @returns {{
+ *   slidePart: string|null,
+ *   shapes: Record<string, object>,
+ *   resolvedTargets: string[],
+ *   tables: Record<string, {cols: number, rows: string[][]}>,
+ *   natives: Record<string, {kind: string, progId: string|null, parts: string[]}>,
+ *   unidentified: number,
+ * }}
+ */
+export function composeSlideEvidence(files, { slidePart = null } = {}) {
+  const part = slidePart ?? slideOrderPaths(files)[0] ?? null;
+  const empty = { slidePart: part, shapes: {}, resolvedTargets: [], tables: {}, natives: {}, connectors: {}, unidentified: 0 };
+  if (!part) return empty;
+  const xml = readText(files, part) ?? "";
+  const spTree = xml.match(/<p:spTree>([\s\S]*?)<\/p:spTree>/)?.[1] ?? "";
+  const units = topLevelShapes(spTree);
+  const { shapes: projected } = computeProjection(files, part);
+  if (units.length !== projected.length) return empty; // two readers disagreeing is not evidence
+
+  const dir = part.slice(0, part.lastIndexOf("/"));
+  const relsById = new Map();
+  const targets = new Set();
+  for (const rel of relsFor(files, part)) {
+    if (rel.targetMode === "External") continue;
+    const resolved = resolvePartPath(dir, rel.target);
+    if (rel.id) relsById.set(rel.id, { type: rel.type ?? "", target: resolved });
+    if (resolved && files[resolved] !== undefined) targets.add(resolved);
+  }
+
+  const out = { ...empty, shapes: {}, tables: {}, natives: {}, connectors: {} };
+  units.forEach((unit, i) => {
+    const elementId = unitElementId(unit.xml);
+    if (!elementId) {
+      out.unidentified += 1;
+      return;
+    }
+    // An id that appears twice is not an identity. Report the collision by
+    // dropping both rather than letting one silently answer for the other.
+    if (out.shapes[elementId]) {
+      // Both claimants lose their identity, so both are counted: one of them
+      // silently answering for the other is the failure mode this avoids.
+      delete out.shapes[elementId];
+      out.unidentified += 2;
+      return;
+    }
+    const shape = { ...projected[i] };
+
+    // A connector's ENDS, exactly as it claims them. These are the only element
+    // ids that become resolvable targets: a target is something something
+    // points AT, and adding every id on the slide would make "the end is still
+    // there" true however the connector was repointed — the same
+    // count-is-not-identity hole E11 walks through. `connectors` below carries
+    // the per-element pairing for a precise check.
+    const ends = [...unit.xml.matchAll(/<a:(stCxn|endCxn)\b[^>]*\bid="(\d+)"/g)].map((m) => [
+      m[1] === "stCxn" ? "start" : "end",
+      m[2],
+    ]);
+    if (ends.length) {
+      out.connectors[elementId] = Object.fromEntries(ends);
+      for (const [, id] of ends) targets.add(id);
+    }
+
+    // The parts this unit depends on, transitively.
+    const starts = [];
+    for (const id of relIdsIn(unit.xml)) {
+      const rel = relsById.get(id);
+      if (!rel?.target || NON_PAYLOAD_REL.test(rel.type)) continue;
+      starts.push(rel.target);
+    }
+    const digests = starts.length ? dependencyDigests(files, starts) : {};
+
+    const nativeKind = nativeKindOf(unit.xml);
+    if (nativeKind) {
+      // A native object's obligation IS its closure plus what it claims to be.
+      // `progId` rides in the map so a payload swapped for another application's
+      // object fails even when the byte count is identical.
+      const parts = contentKeyedParts(digests);
+      const progId = progIdOf(unit.xml);
+      if (progId) parts[`progId:${progId}`] = progId;
+      shape.native = { parts };
+      out.natives[elementId] = { kind: nativeKind, progId, parts: Object.keys(digests), digests };
+    } else if (Object.keys(digests).length) {
+      // An ordinary unit's payload (a picture's media, a chart's part) is still
+      // recorded, so a dropped dependency is visible even where the element
+      // itself survived.
+      shape.native = { parts: contentKeyedParts(digests) };
+    }
+
+    // A chart frame's data residue, hashed so the comparison stays a string
+    // equality like every other scope.
+    const chartRel = [...relIdsIn(unit.xml)].map((id) => relsById.get(id)).find((r) => r?.type.endsWith("/chart"));
+    if (chartRel?.target) {
+      const residue = chartResidue(readText(files, chartRel.target));
+      if (residue) shape.chart = sha256(JSON.stringify(residue));
+    }
+
+    const grid = tableGrid(unit.xml);
+    if (grid) out.tables[elementId] = grid;
+
+    out.shapes[elementId] = shape;
+  });
+
+  out.resolvedTargets = [...targets].sort();
+  return out;
+}