slidemind 0.2.4 → 0.3.1

package/src/lib/adopt.mjs

@@ -0,0 +1,407 @@
+// `slidemind adopt <file.pptx>` — reconstruct a local deck workspace from a
+// presentation's deck-embedded source tags (intern-slidemind
+// docs/deck-embedded-source-spec.md §6.2) and, where the add-in offers it,
+// from a deterministic conversion of the slides that carry no source at all.
+//
+// Three outcomes per slide, in order:
+//   1. decodable SLIDEMIND source  → slides/NN-<name>.jsx, byte-identical to
+//      what was authored, plus its embedded assets;
+//   2. deterministically CONVERTED → slides/NN-<name>.jsx in the converted
+//      dialect + assets + a conversions/<stem>.json identity/evidence record
+//      (openspec `pptx-to-jsx-deterministic-reverse`, D9 — the parse runs
+//      server-side, this repo ships no parser);
+//   3. everything else             → native NN-reused-<id>.pptx (opaque,
+//      re-render-safe) exactly like engine reuse.
+//
+// The deck binds to the bundle recorded in the tags, and slide GUIDs persist in
+// .slide-guids.json so a later `push`/`build-pptx` keeps every slide's identity.
+//
+// v1 is FILE decks only: converting a LIVE presentation needs a slide export
+// and a tag read over the relay, and neither event exists — that flow belongs
+// to the add-in (design D9).
+
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import { unzip } from "../pptx/zip.mjs";
+import { slideOrderPaths } from "../pptx/ooxml.mjs";
+import { decodeSourceTags, mintSlideGuid, readSlideTags } from "../pptx/tags.mjs";
+import { foldPickedSlides } from "../pptx/slide-swap.mjs";
+import { readDeckBundleRef, writeDeckBundleRef } from "../bridge/bundle.mjs";
+import { loadSlideGuids, saveSlideGuids, slideGuidEntry } from "./slide-guids.mjs";
+import { writeConversionRecord } from "./conversions.mjs";
+
+export const LIVE_DECK_UNSUPPORTED =
+  "conversion of live presentations requires the add-in path in v1 — " +
+  "`slidemind adopt` takes a .pptx FILE. Save the open deck to disk and adopt " +
+  "that file, or make the change in PowerPoint with the slidemind pane open.";
+
+function pad2(n) {
+  return String(n).padStart(2, "0");
+}
+
+// Slide names and asset names arrive from an UNTRUSTED file's tags (anyone can
+// mail a crafted .pptx) and both end up in filesystem paths, so neither may
+// carry a directory component or escape the deck dir (spec §10).
+function safeName(raw) {
+  return path
+    .basename(String(raw ?? "").replace(/\\/g, "/"))
+    // Control chars and the reserved filename set — NOT a broad range (a
+    // `[ -<]` style range would swallow digits and eat the NN- prefix).
+    .replace(/[\u0000-\u001f<>:"|?*/]/g, "-")
+    .replace(/^\.+/, "")
+    .trim();
+}
+
+function stemFor(metaName, index, taken) {
+  // meta.name usually already carries its NN- prefix ("03-market-overview");
+  // only prefix by play order when it doesn't.
+  const name = safeName(metaName) || `slide-${pad2(index + 1)}`;
+  const stem = /^\d/.test(name) ? name : `${pad2(index + 1)}-${name}`;
+  let candidate = stem;
+  let n = 2;
+  while (taken.has(candidate)) candidate = `${stem}-${n++}`;
+  taken.add(candidate);
+  return candidate;
+}
+
+// Deck-embedded asset name → deck-local path ("assets/…" stays deck-relative).
+// Returns null for anything that would land outside the deck's assets dir.
+function assetPathFor(deckDir, assetName) {
+  const root = path.resolve(deckDir, "assets");
+  const rel = String(assetName ?? "")
+    .replace(/\\/g, "/")
+    .replace(/^assets\//, "");
+  const target = path.resolve(root, rel);
+  return target.startsWith(root + path.sep) ? target : null;
+}
+
+const sha256Hex = (bytes) => createHash("sha256").update(bytes).digest("hex");
+
+// Write one adopted asset, resolving name collisions by CONTENT: two adopts
+// into the same deck may both ship an assets/images/photo.png. Identical bytes
+// reuse the existing file; different bytes land under the first free -N suffix
+// (and the caller rewrites the slide's references), so an adopted slide never
+// silently renders another deck's picture. Returns the deck-relative name
+// actually used, or null when the name escapes the assets dir.
+function placeAsset(deckDir, name, bytes, sha256) {
+  for (let n = 1; ; n++) {
+    const suffixed = name.replace(/(\.[^./]+)$/, `-${n}$1`);
+    const candidate = n === 1 ? name : suffixed !== name ? suffixed : `${name}-${n}`;
+    const target = assetPathFor(deckDir, candidate);
+    if (!target) return null;
+    if (!fs.existsSync(target)) {
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, bytes);
+      return candidate;
+    }
+    if (sha256Hex(fs.readFileSync(target)) === sha256) return candidate;
+  }
+}
+
+// Read a source deck once: bytes, parts, and the decoded embedded source per
+// slide (null = untagged). Shared by the sync adopt core and the async
+// conversion step so a file is never tag-decoded on two different snapshots —
+// `cmdAdopt` reads once and threads the result into both.
+export function readSourceDeck(pptxPath) {
+  const buffer = fs.readFileSync(pptxPath);
+  const files = unzip(buffer);
+  const order = slideOrderPaths(files);
+  if (order.length === 0) throw new Error(`${pptxPath}: no slides found`);
+  const decodedByIndex = order.map((part) =>
+    decodeSourceTags(readSlideTags(files, part)),
+  );
+  return { buffer, files, order, decodedByIndex };
+}
+
+// Route result -> per-slide-number map, flattened into the per-slide shape the
+// rest of this file reads.
+//
+// The server names the slide it converted (`index`, 1-based play order in the
+// uploaded package); an entry without one is DROPPED rather than joined by
+// array position — a positional join would attach one slide's source to another
+// slide's identity (design R11).
+//
+// The wire keeps identity and evidence in TOP-LEVEL maps keyed by the slide's
+// jsx path (`sourceBaselines` / `conversionEvidence`), because that is the key
+// the render route joins them on. `preserved[]` rides inside the baseline. This
+// is the single place that key shape is unfolded; get it wrong and a converted
+// slide silently loses its preserved natives (`conv.preserved` empty => no
+// `conversions/<stem>.slide.pptx` is folded, and the render has nothing to
+// splice back).
+function convertedByNumber(converted) {
+  const baselines = converted?.sourceBaselines ?? {};
+  const evidence = converted?.conversionEvidence ?? {};
+  const map = new Map();
+  for (const slide of converted?.slides ?? []) {
+    const n = Number(slide?.index);
+    if (!Number.isInteger(n) || n < 1 || typeof slide.jsx !== "string") continue;
+    if (map.has(n)) continue;
+    const baseline = baselines[slide.path] ?? null;
+    map.set(n, {
+      jsx: slide.jsx,
+      // "slides/converted-slide1.jsx" -> "converted-slide1"; stemFor() adds the
+      // NN- play-order prefix.
+      name: slide.name || path.basename(String(slide.path ?? ""), ".jsx") || null,
+      guid: slide.guid ?? null,
+      state: slide.state ?? "needsReview",
+      part: slide.sourcePart ?? slide.part ?? null,
+      sourceBaseline: baseline,
+      conversionEvidence: evidence[slide.path] ?? null,
+      preserved: Array.isArray(baseline?.preserved) ? baseline.preserved : [],
+      warnings: Array.isArray(slide.warnings) ? slide.warnings : [],
+    });
+  }
+  return map;
+}
+
+export function adoptDeckFromPptx({ pptxPath, deckDir, converted = null, source = null }) {
+  const { buffer, order, decodedByIndex } = source ?? readSourceDeck(pptxPath);
+  const convertedSlides = convertedByNumber(converted);
+
+  const slidesDir = path.join(deckDir, "slides");
+  fs.mkdirSync(slidesDir, { recursive: true });
+
+  const taken = new Set(
+    fs.existsSync(slidesDir)
+      ? fs.readdirSync(slidesDir).map((f) => f.replace(/\.(jsx|pptx)$/, ""))
+      : [],
+  );
+  const guids = {};
+  const adopted = [];
+  const convertedFiles = [];
+  const native = [];
+  let bundle = null;
+
+  // Fold in ONE pass: foldPickedSlides unzips and prunes the whole source
+  // package per call, so folding slide by slide redid that work for the entire
+  // deck on every native slide. Two kinds of pick share the pass — a slide that
+  // stays native, and a CONVERTED slide whose preserved natives (chart / OLE /
+  // SmartArt) need their verbatim source package kept for the render-time
+  // splice (design D4/D6).
+  const picks = [];
+  decodedByIndex.forEach((decoded, index) => {
+    if (decoded) return;
+    const conv = convertedSlides.get(index + 1);
+    if (!conv || conv.preserved?.length > 0) picks.push(index + 1);
+  });
+  const foldByPick = new Map(
+    (picks.length
+      ? foldPickedSlides(buffer, picks, { sourceName: "adopted" })
+      : []
+    ).map((fold) => [fold.selection, fold]),
+  );
+
+  // Spec §6.3: two slides with the same GUID resolve by NEWEST META.pushedAt
+  // (an ND-mode edit leaves the untouched original as a frozen archive while
+  // its duplicate evolves — identity must follow the evolution). Ties (a
+  // manual duplicate carries byte-identical tags) keep the first slide in
+  // deck order. Every non-owner gets a fresh GUID so the deck never pushes
+  // two slides claiming to be the same slide. Mirrors hydrate-from-deck.ts.
+  const ownerIndexByGuid = new Map();
+  decodedByIndex.forEach((decoded, index) => {
+    if (!decoded) return;
+    const pushedAt = decoded.meta.pushedAt ?? "";
+    const current = ownerIndexByGuid.get(decoded.guid);
+    if (!current || pushedAt > current.pushedAt) {
+      ownerIndexByGuid.set(decoded.guid, { index, pushedAt });
+    }
+  });
+  // Seeded from the deck's persisted sidecar: adopting into an EXISTING deck
+  // dedupes against the slides already there, or a re-adopt writes a second
+  // slide file claiming the first one's identity.
+  const seenGuids = new Set(Object.values(loadSlideGuids(deckDir)));
+
+  // Conversion-route assets (materialized media, preserved-object preview
+  // crops) land BEFORE the slide loop so a collision-renamed asset can be
+  // rewritten in the converted jsx. Names arrive from an UNTRUSTED package,
+  // so they pass the same escape guard as tag-embedded assets.
+  const convAssetRenames = new Map();
+  for (const [name, b64] of Object.entries(converted?.assets ?? {})) {
+    const bytes = Buffer.from(String(b64), "base64");
+    const placed = placeAsset(deckDir, name, bytes, sha256Hex(bytes));
+    if (placed && placed !== name) convAssetRenames.set(name, placed);
+  }
+
+  decodedByIndex.forEach((decoded, index) => {
+    if (decoded) {
+      const stem = stemFor(decoded.meta.name, index, taken);
+      let jsx = decoded.jsx;
+      for (const asset of decoded.assets) {
+        const placed = placeAsset(deckDir, asset.name, asset.bytes, asset.sha256);
+        if (placed && placed !== asset.name) jsx = jsx.split(asset.name).join(placed);
+      }
+      fs.writeFileSync(path.join(slidesDir, `${stem}.jsx`), jsx, "utf8");
+      const owns = ownerIndexByGuid.get(decoded.guid)?.index === index;
+      const guid =
+        owns && !seenGuids.has(decoded.guid) ? decoded.guid : mintSlideGuid();
+      seenGuids.add(guid);
+      guids[`slides/${stem}.jsx`] = slideGuidEntry(guid, jsx);
+      bundle ??= decoded.meta.bundle ?? null;
+      adopted.push(`${stem}.jsx`);
+      return;
+    }
+    const fold = foldByPick.get(index + 1);
+    const conv = convertedSlides.get(index + 1);
+    if (conv) {
+      // Deterministically converted: editable jsx in the converted dialect,
+      // plus the identity/evidence record push threads back to the server.
+      const stem = stemFor(conv.name ?? `${pad2(index + 1)}-converted`, index, taken);
+      let jsx = conv.jsx;
+      for (const [from, to] of convAssetRenames) jsx = jsx.split(from).join(to);
+      fs.writeFileSync(path.join(slidesDir, `${stem}.jsx`), jsx, "utf8");
+      const guid = conv.guid && !seenGuids.has(conv.guid) ? conv.guid : mintSlideGuid();
+      seenGuids.add(guid);
+      guids[`slides/${stem}.jsx`] = slideGuidEntry(guid, jsx);
+      writeConversionRecord(
+        deckDir,
+        `${stem}.jsx`,
+        {
+          guid,
+          state: conv.state ?? "needsReview",
+          sourceBaseline: conv.sourceBaseline ?? null,
+          conversionEvidence: conv.conversionEvidence ?? null,
+          preserved: Array.isArray(conv.preserved) ? conv.preserved : [],
+          warnings: Array.isArray(conv.warnings) ? conv.warnings : [],
+          source: {
+            file: path.basename(pptxPath),
+            index: index + 1,
+            part: conv.part ?? order[index],
+          },
+          convertedAt: new Date().toISOString(),
+        },
+        fold?.bytes ?? null,
+      );
+      convertedFiles.push(`${stem}.jsx`);
+      return;
+    }
+    // No decodable source and no conversion → keep the slide verbatim as a
+    // native one-slide .pptx, spliced back by filename order on every future
+    // render.
+    if (!fold) return;
+    const stem = stemFor(`${pad2(index + 1)}-reused-adopted`, index, taken);
+    fs.writeFileSync(path.join(slidesDir, `${stem}.pptx`), fold.bytes);
+    native.push(`${stem}.pptx`);
+  });
+
+  if (Object.keys(guids).length > 0) saveSlideGuids(deckDir, guids);
+  // A wholly foreign deck names no bundle in any tag, but conversion ran
+  // against a design — bind to that one so the next push renders pane-free
+  // (the etag self-heals on the first render).
+  if (!bundle && convertedFiles.length > 0 && converted?.brandId) {
+    bundle = { presFP: converted.brandId, etag: "" };
+  }
+  // Bind the deck to the bundle the tags name — but NEVER clobber an
+  // existing binding: adopting into an existing deck must not repoint every
+  // other slide's design at the incoming file's CD.
+  if (
+    bundle?.presFP &&
+    bundle.presFP !== "unknown" &&
+    !readDeckBundleRef(deckDir)?.presFP
+  ) {
+    writeDeckBundleRef(deckDir, { presFP: bundle.presFP, etag: bundle.etag });
+  }
+  const planPath = path.join(deckDir, "plan.md");
+  if (!fs.existsSync(planPath)) {
+    fs.writeFileSync(
+      planPath,
+      `---\nskill: create-slides\n---\n\n# ${path.basename(deckDir)}\n\nAdopted from ${path.basename(pptxPath)}.\n`,
+      "utf8",
+    );
+  }
+
+  return {
+    deckDir,
+    adopted,
+    converted: convertedFiles,
+    native,
+    bundle,
+    // Why a slide the server was asked to convert stayed native (addinOwned,
+    // nativeOnlyEnvelope, a parse failure) — the agent has to be able to say so.
+    skipped: Array.isArray(converted?.skipped) ? converted.skipped : [],
+    warnings: Array.isArray(converted?.warnings) ? converted.warnings : [],
+  };
+}
+
+/**
+ * Deterministically convert a FILE deck's untagged slides through the add-in's
+ * `POST /api/cli/brands/:brandId/convert-pptx` route. Returns the route result
+ * (`{ slides, assets, skipped, warnings }` + the `brandId` it ran against) to
+ * hand to {@link adoptDeckFromPptx}, or null when conversion is not available
+ * here — no design to convert against, no backend serving the route, or the
+ * route refused. A null result is not an error: every untagged slide then folds
+ * in as native .pptx exactly as before.
+ *
+ * `note` receives one human line per degradation; the caller prints it.
+ */
+export async function convertUntaggedSlides({
+  pptxPath,
+  deckDir,
+  brandId = null,
+  note = () => {},
+  source = null,
+}) {
+  const { buffer, decodedByIndex } = source ?? readSourceDeck(pptxPath);
+  const slides = [];
+  decodedByIndex.forEach((decoded, i) => {
+    if (!decoded) slides.push(i + 1);
+  });
+  if (slides.length === 0) return null;
+
+  const client = await import("../bridge/client.mjs");
+  const brand =
+    brandId ??
+    readDeckBundleRef(deckDir)?.presFP ??
+    decodedByIndex.find((d) => d?.meta?.bundle?.presFP)?.meta.bundle.presFP ??
+    null;
+  let resolved = brand && brand !== "unknown" ? brand : null;
+  let backendURL = null;
+  if (!resolved) {
+    // No design anywhere: adopt one only when the answer is unambiguous.
+    let brands = [];
+    try {
+      brands = await client.listBrands();
+    } catch {
+      brands = [];
+    }
+    if (brands.length !== 1) {
+      note(
+        brands.length === 0
+          ? "no corporate design available to convert against — untagged slides stay native"
+          : "several corporate designs available — pass `--brand <presFP>` to convert the untagged slides",
+      );
+      return null;
+    }
+    resolved = brands[0].presFP;
+    backendURL = brands[0].backendURL ?? null;
+    // Routing the upload straight at that backend skips the fan-out's
+    // capability probe — do it here, so a whole .pptx is never shipped to a
+    // backend that will just 404 the route.
+    if (backendURL && !(await client.backendSupportsConvertPptx(backendURL))) {
+      note("this add-in does not convert foreign slides — untagged slides stay native");
+      return null;
+    }
+  }
+
+  try {
+    const result = await client.convertPptxForBrand(resolved, {
+      bytes: buffer,
+      fileName: path.basename(pptxPath),
+      slides,
+      backendURL,
+    });
+    if (result?.ok === false) {
+      note("the add-in declined to convert this file — untagged slides stay native");
+      return null;
+    }
+    return { ...result, brandId: resolved };
+  } catch (err) {
+    note(
+      err?.code === "convert_route_unavailable"
+        ? "this add-in does not convert foreign slides — untagged slides stay native"
+        : `slide conversion unavailable (${err?.message ?? err}) — untagged slides stay native`,
+    );
+    return null;
+  }
+}

package/src/lib/conversions.mjs

@@ -0,0 +1,263 @@
+// Deck-dir conversion metadata — the durable half of `slidemind adopt`'s
+// reverse conversion (intern-slidemind openspec change
+// `pptx-to-jsx-deterministic-reverse`, design D6/D9).
+//
+// A slide the add-in's `POST /api/cli/brands/:brandId/convert-pptx` route
+// converted lands as ordinary deck source (`slides/NN-name.jsx` + `assets/…`),
+// but its IDENTITY and its FIDELITY PROOF are not derivable from that jsx:
+//
+//   • sourceBaseline      — what the source slide WAS (projection, canvas,
+//                           fingerprint, envelope class). The drift baseline.
+//   • conversionEvidence  — what the UNEDITED generated jsx rendered to.
+//   • preserved[]         — the opaque natives (chart/OLE/SmartArt) that must
+//                           be spliced back verbatim on every render.
+//
+// So each converted slide keeps a compact `conversions/<stem>.json` next to the
+// deck, and — ONLY when it carries preserved objects — the verbatim one-slide
+// source package `conversions/<stem>.slide.pptx` that the server re-parses to
+// splice those natives back in. Bulky, re-derivable packages stay out of the
+// record for every other slide (D6).
+//
+// `slidemind push` / `build-pptx` reads both back and threads them onto the
+// render request; nothing here talks to the network.
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** Deck-relative home of every conversion artifact. */
+export const CONVERSIONS_DIR = "conversions";
+
+/** Record format version — bumped when the on-disk shape changes. */
+export const CONVERSION_RECORD_VERSION = 1;
+
+function conversionsDir(deckDir) {
+  return path.join(deckDir, CONVERSIONS_DIR);
+}
+
+// Records are keyed by the slide's FILE NAME ("03-market.jsx"), the same key
+// the render body's `slides` map uses, so the server joins the two without a
+// second convention. basename() keeps a crafted record name inside the dir.
+function stemOf(slideFileName) {
+  return path.basename(String(slideFileName)).replace(/\.jsx$/i, "");
+}
+
+/**
+ * Write one converted slide's record (+ its source package when the slide
+ * carries preserved natives). `sourcePackage` is a Uint8Array/Buffer or null.
+ */
+export function writeConversionRecord(
+  deckDir,
+  slideFileName,
+  record,
+  sourcePackage = null,
+) {
+  const stem = stemOf(slideFileName);
+  const dir = conversionsDir(deckDir);
+  fs.mkdirSync(dir, { recursive: true });
+  const packageName =
+    sourcePackage && record.preserved?.length ? `${stem}.slide.pptx` : null;
+  if (packageName) {
+    fs.writeFileSync(path.join(dir, packageName), Buffer.from(sourcePackage));
+  }
+  const full = {
+    v: CONVERSION_RECORD_VERSION,
+    slide: `slides/${stem}.jsx`,
+    dialect: "converted",
+    ...record,
+    source: { ...(record.source ?? {}), package: packageName },
+  };
+  fs.writeFileSync(
+    path.join(dir, `${stem}.json`),
+    `${JSON.stringify(full, null, 2)}\n`,
+    "utf8",
+  );
+  return full;
+}
+
+/**
+ * Every conversion record of a deck, keyed by slide file name, in the shape the
+ * render request carries: identity + evidence + the base64 preserve source.
+ *
+ * A record whose `slides/<stem>.jsx` no longer exists is skipped — the slide was
+ * deleted or renamed, and shipping its baseline would bind conversion identity
+ * to a slide that is no longer in the deck. Unreadable/corrupt records are
+ * skipped too: a converted slide then renders as ordinary jsx (its preserved
+ * natives are lost, which the caller warns about) rather than failing the push.
+ *
+ * `includeSource: false` skips reading the preserve packages — for callers that
+ * only need to know WHICH slides are converted (they can be megabytes).
+ */
+export function loadConversions(deckDir, { includeSource = true } = {}) {
+  const dir = conversionsDir(deckDir);
+  if (!fs.existsSync(dir)) return {};
+  const out = {};
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith(".json")) continue;
+    const stem = name.replace(/\.json$/, "");
+    if (!fs.existsSync(path.join(deckDir, "slides", `${stem}.jsx`))) continue;
+    let record;
+    try {
+      record = JSON.parse(fs.readFileSync(path.join(dir, name), "utf8"));
+    } catch {
+      continue;
+    }
+    const entry = {
+      guid: record.guid ?? null,
+      state: record.state ?? "needsReview",
+      dialect: record.dialect ?? "converted",
+      sourceBaseline: record.sourceBaseline ?? null,
+      conversionEvidence: record.conversionEvidence ?? null,
+      preserved: Array.isArray(record.preserved) ? record.preserved : [],
+    };
+    // The preserve splice runs server-side against the ORIGINAL bytes: shape
+    // indices are re-derived from this package on every push, never persisted
+    // (design D4 — one replace reorders the slide's shape list).
+    const packageName = record.source?.package
+      ? path.basename(record.source.package)
+      : null;
+    if (packageName && includeSource) {
+      const packagePath = path.join(dir, packageName);
+      if (fs.existsSync(packagePath)) {
+        entry.preserveSource = fs.readFileSync(packagePath).toString("base64");
+      }
+    }
+    out[`${stem}.jsx`] = entry;
+  }
+  return out;
+}
+
+/**
+ * Follow the deck's reconciled GUIDs: move every conversion record whose slide
+ * file was renamed (a reorder renames every slide — the NN- prefix IS the play
+ * order) to the file now carrying its GUID, and delete records whose GUID left
+ * the deck. Without this a renamed converted slide silently loses its record —
+ * the next render drops its preserved natives and `push --replace` sails past
+ * the first-replace gate — while the dead record's multi-MB preserve package
+ * sits on disk forever.
+ *
+ * `guidsByPath` MUST be fresh (the return of reconcileSlideGuids in the same
+ * flow); a stale map would read a mid-rename deck as a deletion. A record that
+ * cannot be parsed is left untouched — it may be a hand-edit gone wrong, and
+ * deleting it would take the preserve package with it.
+ *
+ * Returns one human-readable note per record moved or removed.
+ */
+export function rehomeConversions(deckDir, guidsByPath) {
+  const dir = conversionsDir(deckDir);
+  if (!fs.existsSync(dir)) return [];
+  const stemByGuid = new Map();
+  for (const [p, guid] of Object.entries(guidsByPath ?? {})) {
+    stemByGuid.set(guid, stemOf(p));
+  }
+  const notes = [];
+  for (const name of fs.readdirSync(dir)) {
+    if (!name.endsWith(".json")) continue;
+    const stem = name.replace(/\.json$/, "");
+    if (fs.existsSync(path.join(deckDir, "slides", `${stem}.jsx`))) continue;
+    let record;
+    try {
+      record = JSON.parse(fs.readFileSync(path.join(dir, name), "utf8"));
+    } catch {
+      continue;
+    }
+    const nextStem = record?.guid ? stemByGuid.get(record.guid) : undefined;
+    if (nextStem && !fs.existsSync(path.join(dir, `${nextStem}.json`))) {
+      record.slide = `slides/${nextStem}.jsx`;
+      if (record.source?.package) {
+        const oldPackage = path.join(dir, path.basename(record.source.package));
+        record.source.package = `${nextStem}.slide.pptx`;
+        if (fs.existsSync(oldPackage)) {
+          fs.renameSync(oldPackage, path.join(dir, record.source.package));
+        }
+      }
+      fs.writeFileSync(
+        path.join(dir, `${nextStem}.json`),
+        `${JSON.stringify(record, null, 2)}\n`,
+        "utf8",
+      );
+      fs.rmSync(path.join(dir, name), { force: true });
+      notes.push(
+        `${stem}.jsx was renamed to ${nextStem}.jsx — moved its conversion record along`,
+      );
+    } else if (record?.guid && !nextStem) {
+      fs.rmSync(path.join(dir, name), { force: true });
+      if (record.source?.package) {
+        fs.rmSync(path.join(dir, path.basename(record.source.package)), { force: true });
+      }
+      notes.push(`${stem}.jsx left the deck — removed its conversion record`);
+    }
+  }
+  return notes;
+}
+
+/**
+ * Apply the render response's first-replace gate outcome to the deck records.
+ *
+ * A FILE deck has no live slide, so the server cannot block: `gateConversions`
+ * renders anyway and reports every slide that is not cleared for a silent
+ * replace. That makes THIS the only place the outcome can become visible or
+ * durable — drop `conversionGates` here and an unreviewed conversion overwrites
+ * the user's original slides with no prompt and no warning line.
+ *
+ * Each record is stamped with the outcome (`firstReplace: {route, reasons, at}`)
+ * so a later run — and the user reading the deck dir — can see why a slide is
+ * still unconfirmed. The stamp deliberately does NOT touch `state`: `state` is
+ * what the server gates ON, and rewriting it here would either forge a review
+ * that never happened or re-gate a slide the server already cleared.
+ *
+ * Returns one `{ file, route, reasons, note }` per GATED slide — `note` is the
+ * user-facing line, in the caller's `warnings` vocabulary.
+ */
+export function applyConversionGates(deckDir, conversions, gates) {
+  const byFile = new Map(
+    (Array.isArray(gates) ? gates : [])
+      .filter((g) => g && typeof g.file === "string")
+      .map((g) => [path.basename(g.file), g]),
+  );
+  const gated = [];
+  for (const file of Object.keys(conversions).sort()) {
+    const gate = byFile.get(file) ?? null;
+    if (gate) {
+      const reasons =
+        Array.isArray(gate.reasons) && gate.reasons.length > 0
+          ? gate.reasons
+          : [String(gate.route ?? "gated")];
+      gated.push({
+        file,
+        route: String(gate.route ?? "gated"),
+        reasons,
+        note:
+          `${file}: this converted slide was NOT confirmed for replacement ` +
+          `(${gate.route}: ${reasons.join(", ")}) — it is in the rendered deck, but pushing ` +
+          `it over the original is unreviewed. Compare it with the source slide, then set ` +
+          `"state": "verified" in ${CONVERSIONS_DIR}/${stemOf(file)}.json once it is right.`,
+      });
+    }
+    stampFirstReplace(deckDir, file, gate);
+  }
+  return gated;
+}
+
+// Durable half of the gate outcome. Best-effort: a deck dir the user made
+// read-only must not lose them a finished render.
+function stampFirstReplace(deckDir, slideFileName, gate) {
+  const file = path.join(conversionsDir(deckDir), `${stemOf(slideFileName)}.json`);
+  try {
+    const record = JSON.parse(fs.readFileSync(file, "utf8"));
+    record.firstReplace = {
+      route: gate ? String(gate.route ?? "gated") : "autoSilent",
+      reasons: gate && Array.isArray(gate.reasons) ? gate.reasons : [],
+      at: new Date().toISOString(),
+    };
+    fs.writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+  } catch {
+    /* unreadable/unwritable record — the warning line still reached the user */
+  }
+}
+
+/** Conversion records whose preserved natives have no source package to splice. */
+export function conversionsMissingPreserveSource(conversions) {
+  return Object.entries(conversions)
+    .filter(([, c]) => c.preserved?.length > 0 && !c.preserveSource)
+    .map(([file]) => file);
+}