slidemind 0.2.4 → 0.3.0

package/src/bridge/build-and-push.mjs

@@ -19,6 +19,7 @@ import path from "node:path";
 import { randomUUID } from "node:crypto";
 
 import {
+  exportSlides,
   insertSlides,
   pickPresentationEntry,
   renderPptx,
@@ -36,7 +37,133 @@ import {
 } from "./bundle.mjs";
 import { bundleHasCaptureEngine, captureDeckLocally } from "./capture.mjs";
 import { slideOrderWarning, sortSlideFilenames } from "../lib/slide-order.mjs";
+import {
+  applyConversionGates,
+  conversionsMissingPreserveSource,
+  loadConversions,
+  rehomeConversions,
+} from "../lib/conversions.mjs";
+import { detectManualEdits } from "../lib/overwrite-guard.mjs";
+import {
+  applyReconcileResponse,
+  collectLiveReconcileInputs,
+  collectReconcileInputs,
+  reconcileErrorPayload,
+} from "../lib/reconcile.mjs";
 import { normalizePptxAppPropertiesBase64 } from "../pptx/app-props.mjs";
+import {
+  loadSlideGuids,
+  reconcileSlideGuids,
+  saveSlideGuids,
+  slideGuidEntry,
+} from "../lib/slide-guids.mjs";
+import {
+  SLIDEMIND_TAG_PREFIX,
+  TAG_GUID,
+  TAG_PROV,
+  bakeSlideSourceTags,
+  encodeSourceTags,
+  mintSlideGuid,
+  readSlideTags,
+  referencedAssets,
+} from "../pptx/tags.mjs";
+import { unzip, zip } from "../pptx/zip.mjs";
+import { slideOrderPaths } from "../pptx/ooxml.mjs";
+
+// Deck-embedded source, translate-path bake (spec §5.4): the server never
+// sees the jsx on the local-capture path, so tag any UNTAGGED jsx slide in
+// the returned deck locally. Deck slide order == sorted deck filename order
+// (jsx + native .pptx share one namespace), which maps 1:1 onto the
+// package's slide order. Returns new base64 or null when nothing changed.
+function ensureDeckSourceTags(deckDir, base64) {
+  const slidesDir = path.join(deckDir, "slides");
+  if (!fs.existsSync(slidesDir)) return null;
+  const deckFiles = sortSlideFilenames(
+    fs
+      .readdirSync(slidesDir)
+      .filter((f) => f.endsWith(".jsx") || f.endsWith(".pptx")),
+  );
+  if (deckFiles.length === 0) return null;
+
+  const files = unzip(Buffer.from(base64, "base64"));
+  const order = slideOrderPaths(files);
+  if (order.length !== deckFiles.length) {
+    // A skipped/spliced-away slide broke the 1:1 filename↔slide mapping —
+    // never guess; the deck ships without locally-baked tags and the user
+    // should know it isn't `adopt`-able.
+    process.stderr.write(
+      `note: rendered deck has ${order.length} slide(s) but the deck folder has ` +
+        `${deckFiles.length} — skipping the local source-tag bake (file won't be adoptable)\n`,
+    );
+    return null;
+  }
+
+  const bundleRef = readDeckBundleRef(deckDir);
+  const guids = loadSlideGuids(deckDir);
+  const minted = {};
+  const entries = [];
+  for (let i = 0; i < deckFiles.length; i++) {
+    const fileName = deckFiles[i];
+    if (!fileName.endsWith(".jsx")) continue; // natives carry their own tags
+    if (readSlideTags(files, order[i])[TAG_GUID]) continue; // server already baked
+    let jsx;
+    try {
+      jsx = fs.readFileSync(path.join(slidesDir, fileName), "utf8");
+    } catch {
+      continue;
+    }
+    const key = `slides/${fileName}`;
+    const guid = guids[key] ?? mintSlideGuid();
+    minted[key] = slideGuidEntry(guid, jsx);
+    entries.push({
+      partName: order[i],
+      tags: encodeSourceTags({
+        name: fileName.replace(/\.jsx$/, ""),
+        jsx,
+        guid,
+        bundle: {
+          presFP: bundleRef?.presFP ?? "unknown",
+          etag: bundleRef?.etag ?? "",
+        },
+        renderer: "slidemind-cli-translate",
+        // The jsx's deck-local assets ride along (smallest-first within the
+        // budget, spec §2.2) — without them `adopt` rebuilds a deck whose
+        // slides point at images that were never handed over.
+        assets: referencedAssets(jsx, path.join(deckDir, "assets")),
+        pushedAt: new Date().toISOString(),
+      }),
+    });
+  }
+  if (entries.length === 0 || !bakeSlideSourceTags(files, entries)) return null;
+  saveSlideGuids(deckDir, minted);
+  return Buffer.from(zip(files)).toString("base64");
+}
+
+// Per-slide SLIDEMIND tag maps of a deck in slide order, for the relay's
+// post-insert tag write (the pane upserts them onto the landed slides —
+// insertSlidesFromBase64 merges rather than byte-copies). Slides without an
+// embedded source yield null placeholders to keep the array aligned.
+function collectSourceTagsBySlide(base64) {
+  try {
+    const files = unzip(Buffer.from(base64, "base64"));
+    const maps = slideOrderPaths(files).map((part) => {
+      const tags = readSlideTags(files, part);
+      // SLIDE-level keys only. readSlideTags also walks every SHAPE's
+      // custDataLst, and those carry SLIDEMIND_PROV — stamping that onto the
+      // landed slide would file one arbitrary shape's provenance as the
+      // slide's own.
+      const own = Object.fromEntries(
+        Object.entries(tags).filter(
+          ([k]) => k.startsWith(SLIDEMIND_TAG_PREFIX) && k !== TAG_PROV,
+        ),
+      );
+      return own[TAG_GUID] ? own : null;
+    });
+    return maps.some(Boolean) ? maps : null;
+  } catch {
+    return null;
+  }
+}
 
 function gatherSlides(deckDir) {
   const slidesDir = path.join(deckDir, "slides");
@@ -97,7 +224,13 @@ function gatherDeckAssets(deckDir) {
 // ref rewritten, and the render retried once against the current design.
 export async function renderDeckToBase64(
   deckDir,
-  { presId = null, brandId = null, backendURL = null, onProgress = null },
+  {
+    presId = null,
+    brandId = null,
+    backendURL = null,
+    reconcile = null,
+    onProgress = null,
+  },
 ) {
   if (!presId && !brandId) {
     throw new Error("renderDeckToBase64: presId or brandId is required");
@@ -126,17 +259,62 @@ export async function renderDeckToBase64(
     }
   }
 
+  // Deck-embedded source identity FIRST: reconcile the GUID sidecar with the
+  // slide files on disk (a reorder renames every file — the content hash moves
+  // each GUID to its renamed file and prunes dead entries), then let the
+  // conversion records follow their GUIDs to the renamed files.
+  const sourceGuids = reconcileSlideGuids(deckDir);
+  for (const note of rehomeConversions(deckDir, sourceGuids)) {
+    process.stderr.write(`note: ${note}\n`);
+  }
+
+  // Reverse-converted slides (`slidemind adopt`): conversion identity, fidelity
+  // evidence and — where the slide kept opaque natives — the source package the
+  // server splices them back from. Keyed by slide file name, like `slides`.
+  const conversions = loadConversions(deckDir);
+  const hasConversions = Object.keys(conversions).length > 0;
+  for (const file of conversionsMissingPreserveSource(conversions)) {
+    process.stderr.write(
+      `note: ${file} has preserved native objects but no conversions/*.slide.pptx ` +
+        `to splice them from — re-run 'slidemind adopt' for that deck\n`,
+    );
+  }
+
   const bundleDir = resolveBundleDirForDeck(deckDir);
   // Local capture only applies to authored JSX slides. A native-only deck (just
   // reused .pptx) has nothing to capture, so it goes straight to the server
   // render, which splices the native slides in.
-  let useLocalCapture = hasJsx && bundleHasCaptureEngine(bundleDir);
+  //
+  // Converted slides also go server-side: they invoke the synthetic
+  // `ConvertedHost` layout, which is minted per source canvas at conversion
+  // time and lives in NO materialized bundle — the local capture engine reads
+  // its layout registry from the bundle dir, so it would reject every converted
+  // slide as an unregistered layout.
+  // Pending manual edits go server-side too: the reconcile round trip rides the
+  // render request, and the translate route never sees the jsx it would fold.
+  let useLocalCapture =
+    hasJsx && !hasConversions && !reconcile && bundleHasCaptureEngine(bundleDir);
 
   // One attempt at the chosen etag. Local capture that can't run (no Chrome,
   // corrupt engine) falls back to the server render for this and later attempts;
   // translate/render FAILURES (etag-stale, per-slide errors) propagate. Native
   // .pptx slides ride alongside on either path so the server splices them by
   // play-order filename.
+  // Deck-embedded source: the reconciled slide GUIDs keep identities stable
+  // across re-renders (server bake on the render path, local bake on the
+  // translate path — the server never sees jsx sources there).
+  const serverRender = (target, etag) =>
+    renderPptx({
+      ...target,
+      slides,
+      deckAssets,
+      nativeSlides,
+      etag,
+      sourceGuids,
+      conversions: hasConversions ? conversions : null,
+      reconcile,
+      onProgress,
+    });
   const attemptRender = async (etag) => {
     const target = { presId, brandId, deckName, backendURL };
     if (useLocalCapture) {
@@ -149,18 +327,35 @@ export async function renderDeckToBase64(
             "falling back to the server render\n",
         );
         useLocalCapture = false;
-        return renderPptx({ ...target, slides, deckAssets, nativeSlides, etag, onProgress });
+        return serverRender(target, etag);
       }
       const n = Array.isArray(captured?.slides) ? captured.slides.length : 0;
       onProgress?.({ done: n, total: n, stage: "assembling" });
       return translateDeck({ ...target, captured, nativeSlides, etag });
     }
-    return renderPptx({ ...target, slides, deckAssets, nativeSlides, etag, onProgress });
+    return serverRender(target, etag);
+  };
+
+  // A render where EVERY jsx slide blocked comes back as a REFUSAL (409, or a
+  // failed job carrying that same payload) — there is no deck to return, so the
+  // echo rides the error. It is the same outcome as a partial block, so it runs
+  // through the same handler: folds saved, hashes acknowledged, build refused
+  // with the reports. Never a transport error, never the fail-closed branch.
+  const renderOnce = async (etag) => {
+    try {
+      return await attemptRender(etag);
+    } catch (err) {
+      const refusal = reconcileErrorPayload(err);
+      if (refusal) {
+        applyReconcileResponse({ deckDir, sent: reconcile, result: refusal });
+      }
+      throw err;
+    }
   };
 
   let result;
   try {
-    result = await attemptRender(ref?.etag ?? null);
+    result = await renderOnce(ref?.etag ?? null);
   } catch (err) {
     if (err?.code !== "bundle_etag_stale") throw err;
     // The active corporate design moved on since the deck was authored. The
@@ -182,12 +377,40 @@ export async function renderDeckToBase64(
     writeDeckBundleRef(deckDir, { presFP: mat.presFP, etag: mat.etag });
     // The bundle dir is keyed by presFP, so a refreshed capture engine landed
     // in place — re-evaluate in case it appeared (or vanished) on this sync.
-    useLocalCapture = bundleHasCaptureEngine(bundleDir);
-    result = await attemptRender(mat.etag);
+    useLocalCapture =
+      !hasConversions && !reconcile && bundleHasCaptureEngine(bundleDir);
+    result = await renderOnce(mat.etag);
   }
   if (!result?.base64) {
     throw new Error("render returned no pptx bytes");
   }
+  // Persist GUIDs the server minted for new slides (render path), with the
+  // jsx hash alongside so a later rename can still be reconciled to them.
+  if (result.sourceGuids) {
+    const entries = {};
+    for (const [key, guid] of Object.entries(result.sourceGuids)) {
+      const jsx = slides[key.replace(/^slides\//, "")];
+      entries[key] = typeof jsx === "string" ? slideGuidEntry(guid, jsx) : guid;
+    }
+    saveSlideGuids(deckDir, entries);
+  }
+  // Manual-edit reconcile: fold what the server folded, acknowledge the hashes,
+  // and refuse the build when an edit needs human judgment. Deliberately BEFORE
+  // the bake/normalize below — on a refusal those bytes are thrown away anyway.
+  applyReconcileResponse({ deckDir, sent: reconcile, result });
+  // Make sure EVERY jsx slide carries source tags. Only needed when the server
+  // never saw the jsx: the translate path (local capture), or a backend too old
+  // to bake tags — either way it reports no sourceGuids. When the server DID
+  // bake (sourceGuids present), unzipping the whole deck here just to find
+  // TAG_GUID on every slide is pure waste.
+  if (useLocalCapture || !result.sourceGuids) {
+    try {
+      const baked = ensureDeckSourceTags(deckDir, result.base64);
+      if (baked) result = { ...result, base64: baked };
+    } catch {
+      /* best-effort — an unbaked deck still opens fine, it just isn't adoptable */
+    }
+  }
   const normalized = normalizePptxAppPropertiesBase64(result.base64);
   if (normalized.changed) {
     result = {
@@ -198,10 +421,36 @@ export async function renderDeckToBase64(
   } else if (normalized.slideCount !== null && result.slideCount == null) {
     result = { ...result, slideCount: normalized.slideCount };
   }
+  // First-replace gate (design D9). A backend that evaluated the request's
+  // `conversions` ALWAYS reports `conversionGates` (empty when everything is
+  // cleared for a silent replace). A response WITHOUT the field means the
+  // backend ignored the conversions body entirely — it predates the feature,
+  // so its render also dropped the preserved natives. Fail CLOSED there: gate
+  // every converted slide rather than stamping a clearance ("autoSilent") for
+  // a check that never ran.
+  const gates = Array.isArray(result.conversionGates)
+    ? result.conversionGates
+    : Object.keys(conversions).map((file) => ({
+        file,
+        route: "backendUnaware",
+        reasons: [
+          "this add-in did not evaluate converted slides (no conversion support) — the render dropped their preserved natives",
+        ],
+      }));
+  const gatedConversions = hasConversions
+    ? applyConversionGates(deckDir, conversions, gates)
+    : [];
+  if (gatedConversions.length > 0) {
+    result.warnings = [
+      ...(result.warnings ?? []),
+      ...gatedConversions.map((g) => g.note),
+    ];
+  }
+  result.gatedConversions = gatedConversions;
   if (orderWarning) {
     result.warnings = [orderWarning, ...(result.warnings ?? [])];
   }
-  return result; // { ok, base64, slideCount, warnings, skippedSlides }
+  return result; // { ok, base64, slideCount, warnings, skippedSlides, gatedConversions }
 }
 
 // Map ONE captured slide to a draft-view entry. The capture engine produces a
@@ -282,11 +531,26 @@ export async function viewDraft(
   if (all.length === 0) {
     throw new Error(`No .jsx or .pptx slides under ${slidesDir}`);
   }
-  const hasJsx = all.some((f) => f.endsWith(".jsx"));
+  const warnings = [];
+  // Same identity reconcile as the render path — a reorder renames every file,
+  // and a stale sidecar here would mislabel renamed converted slides (Chrome
+  // would then choke on their unregistered ConvertedHost layout).
+  warnings.push(...rehomeConversions(deckDir, reconcileSlideGuids(deckDir)));
+  // Converted slides (`slidemind adopt`) invoke the synthetic ConvertedHost
+  // layout, which no materialized bundle carries — the local capture engine
+  // builds its layout registry from the bundle dir, so it cannot render them.
+  // They are named here instead of surfacing as a cryptic unregistered-layout
+  // error, and a deck of nothing but converted slides never launches Chrome.
+  const conversions = loadConversions(deckDir, { includeSource: false });
+  const convertedNote =
+    "converted slide — renders server-side only (its ConvertedHost layout is not in the " +
+    "bundle); use `slidemind build-pptx <deck>` to look at it";
+  const hasJsx = all.some((f) => f.endsWith(".jsx") && !conversions[f]);
 
   // Resolve the materialized bundle. Local capture needs the bundle's capture
   // engine; once it's cached this whole call is offline. Only reach for a host
-  // (to fetch the bundle) when there are JSX slides and no usable cached engine.
+  // (to fetch the bundle) when there are capturable JSX slides and no usable
+  // cached engine.
   let ref = readDeckBundleRef(deckDir);
   let bundleDir = resolveBundleDirForDeck(deckDir);
   if (hasJsx && (!bundleDir || !bundleHasCaptureEngine(bundleDir))) {
@@ -302,16 +566,19 @@ export async function viewDraft(
     bundleDir = resolveBundleDirForDeck(deckDir);
   }
 
-  const warnings = [];
-
-  // A native-only deck (just reused .pptx) has no authored JSX to draft-preview.
+  // Nothing left to capture — a native-only deck (just reused .pptx), a fully
+  // converted one, or both.
   if (!hasJsx) {
     return {
-      slides: all.map((fileName) => ({
-        fileName,
-        status: "native",
-        note: "reused native slide — not authored JSX, no draft preview rendered",
-      })),
+      slides: all.map((fileName) =>
+        conversions[fileName]
+          ? { fileName, status: "converted", note: convertedNote }
+          : {
+              fileName,
+              status: "native",
+              note: "reused native slide — not authored JSX, no draft preview rendered",
+            },
+      ),
       warnings,
     };
   }
@@ -332,20 +599,25 @@ export async function viewDraft(
     throw new Error(
       `local draft capture failed (${err instanceof Error ? err.message : String(err)}). ` +
         "It runs a local headless Chrome; if Chrome can't launch here, use " +
-        "`slidemind build <deck>` for an HTML preview instead.",
+        "`slidemind build <deck>` for an HTML preview instead." +
+        (Object.keys(conversions).length > 0 ? ` ${convertedNote}.` : ""),
     );
   }
 
   const byFile = new Map((captured?.slides ?? []).map((s) => [s.fileName, s]));
-  const slides = all.map((fileName) =>
-    fileName.endsWith(".pptx")
-      ? {
-          fileName,
-          status: "native",
-          note: "reused native slide — not authored JSX, no draft preview rendered",
-        }
-      : mapCapturedSlide(fileName, byFile.get(fileName), warnings),
-  );
+  const slides = all.map((fileName) => {
+    if (fileName.endsWith(".pptx")) {
+      return {
+        fileName,
+        status: "native",
+        note: "reused native slide — not authored JSX, no draft preview rendered",
+      };
+    }
+    if (conversions[fileName]) {
+      return { fileName, status: "converted", note: convertedNote };
+    }
+    return mapCapturedSlide(fileName, byFile.get(fileName), warnings);
+  });
 
   return { slides, warnings };
 }
@@ -369,7 +641,7 @@ function isBrandRouteMiss(err) {
 // involved. Returns null when the brand route can't serve this deck (caller
 // falls back to the pane flow); render failures (lint, stale-after-retry)
 // propagate, they are real.
-async function tryDetachedRender(deckDir, deckRef, onProgress) {
+async function tryDetachedRender(deckDir, deckRef, onProgress, reconcile = null) {
   const brandId = deckRef.presFP;
   let backendURL;
   try {
@@ -384,16 +656,24 @@ async function tryDetachedRender(deckDir, deckRef, onProgress) {
   const result = await renderDeckToBase64(deckDir, {
     brandId,
     backendURL,
+    reconcile,
     onProgress,
   });
   return { result, backendURL };
 }
 
-async function renderWithRetarget(deckDir, entry, onProgress, registry = []) {
+async function renderWithRetarget(
+  deckDir,
+  entry,
+  onProgress,
+  registry = [],
+  reconcile = null,
+) {
   const run = (target) =>
     renderDeckToBase64(deckDir, {
       presId: target.presId,
       backendURL: target.backendURL ?? null,
+      reconcile,
       onProgress,
     });
   try {
@@ -427,6 +707,8 @@ export async function buildAndPush({
   insertAt = null,
   replace = false,
   slideIds = null,
+  acceptConversions = false,
+  force = false,
   onProgress = null,
 }) {
   if (!deckDir) throw new Error("buildAndPush: deckDir is required");
@@ -444,17 +726,58 @@ export async function buildAndPush({
   }
 
   const deckRef = readDeckBundleRef(deckDir);
+  // Every window we saw next to the target. The retarget wait treats these as
+  // definitely-not-the-target, so a second deck on the same corporate design
+  // can never inherit this push (waitForPaneReady's `otherPresIds`).
+  let seenRegistry = [];
+
+  // Manual-edit reconcile against the LIVE deck (plan Phase C2). `--replace`
+  // deletes what is on screen and re-pushes the deck, so the thing that must be
+  // inspected first is the presentation itself — not the deck's .pptx sibling
+  // (that file keeps its own guard, in saveFallback below). An INSERT push adds
+  // slides and destroys nothing, so it never reconciles.
+  //
+  // Needs a live window, because only the pane can export its slides. When no
+  // window is registered at all, nothing can be replaced either: the render
+  // still runs and its bytes land through saveFallback, where the output-file
+  // guard is the protection.
+  let reconcile = null;
+  if (replace && !force) {
+    let registry = null;
+    try {
+      registry = await requireHost();
+    } catch {
+      registry = null;
+    }
+    if (registry) {
+      seenRegistry = registry;
+      // May throw the "which window?" question — the same one the push itself
+      // would raise a moment later, just earlier and before any render work.
+      const target = pickPresentationEntry(registry, presentationId, {
+        preferBrandId: deckRef?.presFP ?? null,
+      });
+      reconcile = await collectLiveReconcileInputs({
+        deckDir,
+        // A subset push (`--slides`) reconciles only its own guids; this CLI
+        // rejects --replace with --slides upstream, so today this is always the
+        // whole deck — which is exactly when `deck.unmatched` bites.
+        guids: Array.isArray(slideIds) && slideIds.length > 0 ? slideIds : null,
+        exportSlides: (guids) =>
+          exportSlides({
+            presId: target.presId,
+            guids,
+            backendURL: target.backendURL ?? null,
+          }),
+      });
+    }
+  }
 
   // --- Render half. Pane-free for a bound deck (the window may be closed or
   // backgrounded during the render); the pane matters only for the insert. ---
   let result = null;
   let renderEntry = null;
-  // Every window we saw next to the target. The retarget wait treats these as
-  // definitely-not-the-target, so a second deck on the same corporate design
-  // can never inherit this push (waitForPaneReady's `otherPresIds`).
-  let seenRegistry = [];
   if (!presentationId && deckRef?.presFP) {
-    const detached = await tryDetachedRender(deckDir, deckRef, onProgress);
+    const detached = await tryDetachedRender(deckDir, deckRef, onProgress, reconcile);
     if (detached) result = detached.result;
   }
   if (!result) {
@@ -463,11 +786,36 @@ export async function buildAndPush({
     const entry = pickPresentationEntry(registry, presentationId, {
       preferBrandId: deckRef?.presFP ?? null,
     });
-    const rendered = await renderWithRetarget(deckDir, entry, onProgress, registry);
+    const rendered = await renderWithRetarget(
+      deckDir,
+      entry,
+      onProgress,
+      registry,
+      reconcile,
+    );
     renderEntry = rendered.entry;
     result = rendered.result;
   }
 
+  // `--replace` wipes the presentation and re-pushes the built deck: for a
+  // converted deck that IS the first replacement of the user's original slides.
+  // A slide the server gated has not been confirmed for that, so the destructive
+  // half stops here and asks. Insert mode leaves the originals alone, so it only
+  // warns (the gate lines are already on `result.warnings`).
+  const gatedConversions = result.gatedConversions ?? [];
+  if (replace && gatedConversions.length > 0 && !acceptConversions) {
+    const err = new Error(
+      `${gatedConversions.length} converted slide(s) are not confirmed for replacement — ` +
+        `--replace would overwrite the originals with an unreviewed conversion.\n` +
+        gatedConversions.map((g) => `  ${g.note}`).join("\n") +
+        `\nRe-run with --accept-conversions to replace anyway, or push without --replace ` +
+        `to insert them and leave the originals in place.`,
+    );
+    err.code = "conversions_not_confirmed";
+    err.gatedConversions = gatedConversions;
+    throw err;
+  }
+
   const base64 = result.base64;
   const bytes = Buffer.byteLength(base64, "base64");
   const mode = replace ? "replace" : "insert";
@@ -477,7 +825,17 @@ export async function buildAndPush({
   // find one — save the .pptx next to the deck and tell the caller (bin prints
   // the recovery instructions).
   const saveFallback = (presIdForResult) => {
-    const fallbackFile = path.join(deckDir, `${path.basename(deckDir)}.pptx`);
+    let fallbackFile = path.join(deckDir, `${path.basename(deckDir)}.pptx`);
+    // This save is the ONLY copy of a render nobody could take delivery of, so
+    // it must land somewhere — it can never be the thing that destroys manual
+    // edits, and it can never refuse either. Edited sibling ⇒ write next to it.
+    if (detectManualEdits(fallbackFile).length > 0) {
+      const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+      fallbackFile = path.join(
+        deckDir,
+        `${path.basename(deckDir)}-${stamp}.pptx`,
+      );
+    }
     fs.writeFileSync(fallbackFile, Buffer.from(base64, "base64"));
     return {
       presId: presIdForResult,
@@ -516,12 +874,24 @@ export async function buildAndPush({
   // The SAME operationId on every attempt: the pane keeps an LRU of applied
   // operationIds and drops duplicates, so a retry after an ambiguous failure
   // can never double-insert.
+  // Deck-embedded source: per-slide tag maps for the pane's post-insert tag
+  // write (insertSlidesFromBase64 merges rather than byte-copies, so the
+  // baked tags may not survive the insert). Aligned with FULL-deck slide
+  // order only — a --slides subset insert reorders the landed set, so subset
+  // pushes rely on the baked-in tags alone.
+  // ponytail: subset alignment needs the id→index map of the rendered deck;
+  // add it if spike shows baked tags don't survive UseDestinationTheme.
+  const sourceTagsBySlide =
+    Array.isArray(slideIds) && slideIds.length > 0
+      ? null
+      : collectSourceTagsBySlide(base64);
   const doPush = (targetPresId, targetBackendURL) =>
     replace
       ? replaceSlides({
           presId: targetPresId,
           base64,
           operationId,
+          sourceTagsBySlide,
           backendURL: targetBackendURL,
         })
       : insertSlides({
@@ -530,6 +900,7 @@ export async function buildAndPush({
           insertAt,
           sourceSlideIds: slideIds,
           operationId,
+          sourceTagsBySlide,
           backendURL: targetBackendURL,
         });
 
@@ -599,16 +970,23 @@ export async function buildPptxFile({
   deckDir,
   presentationId = null,
   outPath = null,
+  force = false,
   onProgress = null,
 }) {
   if (!deckDir) throw new Error("buildPptxFile: deckDir is required");
   const deckRef = readDeckBundleRef(deckDir);
   const out = outPath || path.join(deckDir, `${path.basename(deckDir)}.pptx`);
 
+  // Before ANY render work: what did the user change by hand in the file this
+  // build is about to replace? An edit we cannot address refuses here and now
+  // (nothing renders); everything else rides the render request and comes back
+  // folded or reported.
+  const reconcile = collectReconcileInputs({ deckDir, outFile: out, force });
+
   // Pane-free path. `--to <presId>` names a window explicitly and therefore
   // keeps the registry path.
   if (!presentationId && deckRef?.presFP) {
-    const detached = await tryDetachedRender(deckDir, deckRef, onProgress);
+    const detached = await tryDetachedRender(deckDir, deckRef, onProgress, reconcile);
     if (detached) {
       fs.writeFileSync(out, Buffer.from(detached.result.base64, "base64"));
       return {
@@ -630,6 +1008,8 @@ export async function buildPptxFile({
     deckDir,
     entry,
     onProgress,
+    [],
+    reconcile,
   );
   const presId = renderEntry.presId;
   fs.writeFileSync(out, Buffer.from(result.base64, "base64"));

package/src/bridge/capture.mjs

@@ -27,8 +27,19 @@ const LAUNCH_ARGS = [
   "--no-default-browser-check",
 ];
 
-/** True when the materialized bundle carries a capture engine to run locally. */
+/**
+ * True when the materialized bundle carries a capture engine to run locally.
+ *
+ * `SLIDEMIND_FORCE_SERVER_RENDER=1` forces the server-render fallback even
+ * when the bundle has one. Escape hatch for the case where the two paths
+ * disagree: capture runs client-side and its output crosses a JSON wire to
+ * `/translate`, so an engine bug can lose data that the in-process server
+ * render keeps (this is how the base64 background-image fix was isolated —
+ * same deck, same asset, images only on the server path). It costs the
+ * pane-free speed win, so it is a diagnostic, not a default.
+ */
 export function bundleHasCaptureEngine(bundleDir) {
+  if (process.env.SLIDEMIND_FORCE_SERVER_RENDER === "1") return false;
   if (!bundleDir) return false;
   return fs.existsSync(path.join(bundleDir, "capture-engine.mjs"));
 }