slidemind 0.3.20 → 0.4.1

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

@@ -16,7 +16,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 
 import {
   exportSlides,
@@ -37,11 +37,29 @@ import {
   writeDeckBundleRef,
 } from "./bundle.mjs";
 import { bundleHasCaptureEngine, captureDeckLocally } from "./capture.mjs";
+import { buildImageIntentEnvelope } from "./image-intent-envelope.mjs";
+import { writePackagePreview } from "./package-preview.mjs";
+import {
+  assertImageIntentSatisfied,
+  draftImageIntentLines,
+  formatIssue,
+  imageIntentVerdict,
+  slideNumberOf,
+  slideNumbersOf,
+} from "../builders/image-intent-check.mjs";
+import { IMAGE_INTENT_META_KEY, imageIntentTagMetaForSlides } from "../lib/image-intent-tags.mjs";
+import {
+  PRESERVATION_META_KEY,
+  preservationDocForBake,
+  preservationTagMeta,
+} from "../lib/preservation-tags.mjs";
 import { lintConvertedOrThrow } from "../lib/lint-converted.mjs";
 import { slideOrderWarning, sortSlideFilenames } from "../lib/slide-order.mjs";
 import {
   applyConversionGates,
+  CONVERSIONS_DIR,
   conversionIntegrityErrors,
+  conversionProvenance,
   loadConversions,
   rehomeConversions,
 } from "../lib/conversions.mjs";
@@ -63,7 +81,9 @@ import {
   SLIDEMIND_TAG_PREFIX,
   TAG_GUID,
   TAG_PROV,
+  augmentSourceMeta,
   bakeSlideSourceTags,
+  computeProjection,
   encodeSourceTags,
   mintSlideGuid,
   readSlideTags,
@@ -71,19 +91,72 @@ import {
 } from "../pptx/tags.mjs";
 import { unzip, zip } from "../pptx/zip.mjs";
 import { slideOrderPaths } from "../pptx/ooxml.mjs";
+import { assembleDeck, normalizeMasters, planFromDeck, validatePackage } from "../pptx/deck-assemble.mjs";
+import {
+  acceptedBasePath,
+  acquireOwner,
+  computeDirty,
+  materializedInputs,
+  inputDigest,
+  readAcceptedBase,
+  readRevision,
+  saveCandidate,
+  slideFileOrder,
+} from "../lib/revision.mjs";
+import {
+  bundleOwnedFiles,
+  deckPptxPath,
+  deckRoot,
+  deckSlug,
+  previewPath,
+} from "../lib/deck-paths.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) {
+// `metaExtra` per slide file: the slide's `SRC_META.imageIntent`, or undefined
+// so a slide with no image use adds nothing at all to its tags. Resolved for
+// the whole bake in one pass — the lookup re-hashes every slide file to map
+// overrides onto slide numbers, and doing that per slide is quadratic.
+function intentMetaByFile(deckDir, fileNames) {
+  const bySlide = imageIntentTagMetaForSlides(deckDir, slideNumbersOf(fileNames));
+  const out = new Map();
+  if (!bySlide.size) return out;
+  for (const fileName of fileNames) {
+    const intent = bySlide.get(slideNumberOf(fileName));
+    if (intent) out.set(fileName, { [IMAGE_INTENT_META_KEY]: intent });
+  }
+  return out;
+}
+
+// Merge the optional SRC_META extras of one slide, dropping the ones it has
+// none of. `undefined` when there are none at all, so a slide that carries
+// neither an image obligation nor a preservation record bakes exactly the tags
+// it baked before either contract existed.
+function slideMetaExtra(...parts) {
+  const out = {};
+  for (const part of parts) {
+    for (const [key, value] of Object.entries(part ?? {})) {
+      if (value != null) out[key] = value;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+// Exported for the round-trip tests: bake → adopt → edit → bake is the contract
+// the deck-embedded records live or die by (task 5.7 / E19), and imitating the
+// bake in a test would prove only that the imitation works.
+export function ensureDeckSourceTags(deckDir, base64, only = null) {
   const slidesDir = path.join(deckDir, "slides");
   if (!fs.existsSync(slidesDir)) return null;
+  const wanted = only ? new Set(only) : null;
   const deckFiles = sortSlideFilenames(
     fs
       .readdirSync(slidesDir)
-      .filter((f) => f.endsWith(".jsx") || f.endsWith(".pptx")),
+      .filter((f) => f.endsWith(".jsx") || f.endsWith(".pptx"))
+      .filter((f) => !wanted || wanted.has(f)),
   );
   if (deckFiles.length === 0) return null;
 
@@ -101,13 +174,36 @@ function ensureDeckSourceTags(deckDir, base64) {
   }
 
   const bundleRef = readDeckBundleRef(deckDir);
+  const intentMeta = intentMetaByFile(deckDir, deckFiles);
   const guids = loadSlideGuids(deckDir);
+  // The deck's preservation records, read once for the whole bake and looked up
+  // per slide by its GUID below (src/lib/preservation-tags.mjs).
+  const preservationDoc = preservationDocForBake(deckDir);
   const minted = {};
   const entries = [];
+  // What the bake adds beyond the source itself, per slide: the approved image
+  // obligations and the slide's preservation record.
+  const extrasFor = (fileName, guid) =>
+    slideMetaExtra(intentMeta.get(fileName), {
+      [PRESERVATION_META_KEY]: preservationTagMeta(deckDir, guid, {
+        preservation: preservationDoc,
+      }),
+    });
+  let augmented = false;
   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
+    const serverGuid = readSlideTags(files, order[i])[TAG_GUID];
+    if (serverGuid) {
+      // The server baked this slide's source. It could not have written the
+      // extras — `imageIntent` needs the deck's registry, which only this side
+      // holds — so they are added to ITS meta rather than baked a second time
+      // under the same key (two writers, one key, two answers).
+      if (augmentSourceMeta(files, order[i], extrasFor(fileName, serverGuid))) {
+        augmented = true;
+      }
+      continue;
+    }
     let jsx;
     try {
       jsx = fs.readFileSync(path.join(slidesDir, fileName), "utf8");
@@ -132,12 +228,31 @@ function ensureDeckSourceTags(deckDir, base64) {
         // 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")),
+        // The DRIFT BASELINE: the slide's structural projection as it stands in
+        // the package being baked. Without it the payload can later be proved
+        // intact but never proved CURRENT, so `adopt` has to convert the slide
+        // instead of restoring its jsx, and `detectManualEdits` has nothing to
+        // compare an Office edit against. The bake only appends a custDataLst
+        // after </p:spTree>, which the projection does not read, so computing it
+        // here and baking it are the same picture.
+        baseline: computeProjection(files, order[i]),
         pushedAt: new Date().toISOString(),
+        // The slide's approved image obligations, so a .pptx that travels can
+        // be adopted back with its picture identities intact instead of as a
+        // slide that merely HAS a picture (design decision 8). Absent — and the
+        // tags unchanged — for every slide with no image use.
+        //
+        // Next to them, what the slide must still CONTAIN: its preservation
+        // record, so a deck adopted into a fresh workspace comes back owing what
+        // it owed — including the requirements it intentionally superseded, so
+        // a deletion is not silently owed again (task 5.7 / E19–E20).
+        metaExtra: extrasFor(fileName, guid),
       }),
     });
   }
-  if (entries.length === 0 || !bakeSlideSourceTags(files, entries)) return null;
-  saveSlideGuids(deckDir, minted);
+  const baked = entries.length > 0 && bakeSlideSourceTags(files, entries);
+  if (!baked && !augmented) return null;
+  if (baked) saveSlideGuids(deckDir, minted);
   return Buffer.from(zip(files)).toString("base64");
 }
 
@@ -167,7 +282,7 @@ function collectSourceTagsBySlide(base64) {
   }
 }
 
-function gatherSlides(deckDir) {
+function gatherSlides(deckDir, only = null) {
   const slidesDir = path.join(deckDir, "slides");
   if (!fs.existsSync(slidesDir) || !fs.statSync(slidesDir).isDirectory()) {
     throw new Error(`Expected 'slides/' folder in ${deckDir}`);
@@ -176,12 +291,22 @@ function gatherSlides(deckDir) {
   // namespace (filename order, numeric-aware). The server splices the native
   // .pptx in by the SAME sorted-filename key, so the two kinds interleave by
   // their numeric prefix regardless of extension.
-  const all = sortSlideFilenames(
+  //
+  // `only` narrows the request to the slides that actually changed — the
+  // targeted-assembly path, where the rest of the deck comes from the accepted
+  // base instead of being re-rendered. The SUBSET keeps its relative order, so
+  // the returned package's slide N is the Nth entry of `only`.
+  let all = sortSlideFilenames(
     fs.readdirSync(slidesDir).filter((f) => f.endsWith(".jsx") || f.endsWith(".pptx")),
   );
   if (all.length === 0) {
     throw new Error(`No .jsx or .pptx slides under ${slidesDir}`);
   }
+  if (only) {
+    const wanted = new Set(only);
+    all = all.filter((f) => wanted.has(f));
+    if (all.length === 0) throw new Error(`none of the requested slides exist under ${slidesDir}`);
+  }
   const slides = {};
   const nativeSlides = {};
   for (const f of all) {
@@ -194,20 +319,27 @@ function gatherSlides(deckDir) {
   return { slides, nativeSlides, orderWarning: slideOrderWarning(all) };
 }
 
-// Collect deck-local assets (icons the agent downloaded, deck photos) as
+// Collect DECK-OWNED assets (icons the agent downloaded, deck photos) as
 // base64, keyed by their `assets/<rel>` path so the server-side renderer mounts
 // them where the slide JSX references them (`<img src="./assets/<rel>">`).
+//
+// Copies of the design bundle a pre-workspace deck still carries are never
+// uploaded: the server resolves brand assets from the design itself ("brand asset
+// wins"), and a deck carrying them would ship megabytes on every render. A copy is
+// one the bundle owns AND whose bytes match it — a user's own `master-data.png`
+// merely shares a name and is uploaded like any other deck media.
 function gatherDeckAssets(deckDir) {
   const assetsDir = path.join(deckDir, "assets");
   const out = {};
   if (!fs.existsSync(assetsDir)) return out;
+  const bundleOwned = bundleOwnedFiles(deckDir, resolveBundleDirForDeck(deckDir));
   const walk = (dir, prefix) => {
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
       const abs = path.join(dir, entry.name);
       const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
       if (entry.isDirectory()) {
         walk(abs, rel);
-      } else {
+      } else if (!bundleOwned.has(`assets/${rel}`)) {
         out[`assets/${rel}`] = fs.readFileSync(abs).toString("base64");
       }
     }
@@ -232,15 +364,30 @@ export async function renderDeckToBase64(
     backendURL = null,
     reconcile = null,
     onProgress = null,
+    only = null,
   },
 ) {
   if (!presId && !brandId) {
     throw new Error("renderDeckToBase64: presId or brandId is required");
   }
-  const deckName = path.basename(deckDir);
-  const { slides, nativeSlides, orderWarning } = gatherSlides(deckDir);
+  const deckName = deckSlug(deckDir);
+  const { slides, nativeSlides, orderWarning } = gatherSlides(deckDir, only);
   const hasJsx = Object.keys(slides).length > 0;
   const deckAssets = gatherDeckAssets(deckDir);
+  // The deck's approved image obligations for exactly the slides this request
+  // carries. Built BEFORE anything is rendered, because the builder resolves
+  // every registered source on the way: a deleted or overwritten original
+  // raises `image_asset_missing` / `image_asset_changed` here, with no .pptx
+  // written and nothing silently substituted (A14). `null` for every deck that
+  // has no image uses — which is every deck that predates the contract — so the
+  // request body is byte-for-byte what it always was.
+  const imageIntent = buildImageIntentEnvelope(deckDir, {
+    slides: slideNumbersOf([...Object.keys(slides), ...Object.keys(nativeSlides)]),
+    // Render/translate resolve the descriptors against the byte map the request
+    // already ships (`deckAssets`, keyed `assets/local/<id>.<ext>` — the asset's
+    // own workspacePath), instead of inlining every screenshot a second time.
+    inline: false,
+  });
   // Bind the deck to a materialized bundle if it isn't already. Without a
   // `.bundle-ref.json` the etag below is null (server-side skew detection
   // silently no-ops), the local HTML/editor preview can't resolve the deck's
@@ -279,7 +426,29 @@ export async function renderDeckToBase64(
   // file it was renamed away from, used to be a note AFTER the render — by
   // which time the slide had already come back on a fallback layout. It is a
   // hard stop: the render request would carry a lie about the source.
-  const integrity = conversionIntegrityErrors(deckDir, conversions);
+  //
+  // A record that exists but will not PARSE is the same lie with nobody left
+  // to tell it: `loadConversions` skips it, so the slide is simply absent from
+  // `conversions` — which reads as "not converted". It would then render as
+  // ordinary jsx with its preserved natives (SmartArt, OLE, an unmodeled
+  // chart) silently gone, and `conversionIntegrityErrors` /
+  // `conversionsMissingPreserveSource` cannot warn, because both iterate that
+  // same map. So ask per slide, where absence and unreadable are different
+  // answers, and stop on unreadable exactly as on a missing package: at
+  // delivery, unknown provenance is refused, never rendered past.
+  const integrity = [
+    ...Object.keys(slides)
+      .filter((f) => conversionProvenance(deckDir, f) === undefined)
+      .sort()
+      .map(
+        (f) =>
+          `${f}: its ${CONVERSIONS_DIR}/${f.replace(/\.jsx$/, "")}.json exists but could not be read, ` +
+            `so whether this slide is converted is unknown — it would render as ordinary jsx and lose ` +
+            `any preserved native objects. Repair or delete that record, or re-run 'slidemind adopt' ` +
+            `for this deck.`,
+      ),
+    ...conversionIntegrityErrors(deckDir, conversions),
+  ];
   if (integrity.length > 0) {
     throw new Error(
       `conversion records are out of sync with the deck:\n  ${integrity.join("\n  ")}`,
@@ -328,6 +497,7 @@ export async function renderDeckToBase64(
       sourceGuids,
       conversions: hasConversions ? conversions : null,
       reconcile,
+      imageIntent,
       onProgress,
     });
   const attemptRender = async (etag) => {
@@ -346,7 +516,7 @@ export async function renderDeckToBase64(
       }
       const n = Array.isArray(captured?.slides) ? captured.slides.length : 0;
       onProgress?.({ done: n, total: n, stage: "assembling" });
-      return translateDeck({ ...target, captured, nativeSlides, etag });
+      return translateDeck({ ...target, captured, nativeSlides, etag, imageIntent });
     }
     return serverRender(target, etag);
   };
@@ -399,6 +569,13 @@ export async function renderDeckToBase64(
   if (!result?.base64) {
     throw new Error("render returned no pptx bytes");
   }
+  // The image-obligation gate, on the ONE path every deliverable .pptx passes
+  // through and before a single byte is written or inserted. Two refusals, one
+  // rule: a verdict that failed, and a verdict that never came. The export gate
+  // next door may degrade to a note when the backend cannot answer; this one may
+  // not — "the picture check was skipped" and "the picture is on the slide" are
+  // not the same sentence, and only the second one is a built deck.
+  assertImageIntentSatisfied(imageIntent, result);
   // 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) {
@@ -413,14 +590,17 @@ export async function renderDeckToBase64(
   // 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) {
+  // Make sure EVERY jsx slide carries source tags. 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 would be pure waste — EXCEPT for a deck carrying image
+  // obligations, whose provenance the server cannot write (the transport
+  // descriptor it holds carries no `provenance`, only this side's registry
+  // does). There the pass runs to top its meta up in place.
+  if (useLocalCapture || !result.sourceGuids || imageIntent) {
     try {
-      const baked = ensureDeckSourceTags(deckDir, result.base64);
+      const baked = ensureDeckSourceTags(deckDir, result.base64, only);
       if (baked) result = { ...result, base64: baked };
     } catch {
       /* best-effort — an unbaked deck still opens fine, it just isn't adoptable */
@@ -487,9 +667,12 @@ function mapCapturedSlide(fileName, cap, warnings) {
 
   if (cap.previewDataUrl) {
     // The serialised boxes ride along so view-draft can run the measured
-    // checks (fill band, content grid) the add-in's see_draft runs.
-    const { root = null, stage = null, boxes = null } = cap.render ?? {};
-    return { fileName, status: "ok", dataUri: cap.previewDataUrl, render: { root, stage, boxes } };
+    // checks (fill band, content grid) the add-in's see_draft runs; the
+    // chrome text feeds its chrome rule. That rule quotes the text into a
+    // one-line verdict, so a title set on two lines reads as one.
+    const { root = null, stage = null, boxes = null, chromeText = null } = cap.render ?? {};
+    const chrome = chromeText?.map((f) => ({ ...f, text: String(f.text ?? "").replace(/\s+/g, " ") })) ?? null;
+    return { fileName, status: "ok", dataUri: cap.previewDataUrl, render: { root, stage, boxes, chromeText: chrome } };
   }
   // A degraded render is a non-editable raster; push/build-pptx will REJECT it.
   // Attach it anyway (so the agent isn't blind) but flag the named cause.
@@ -647,12 +830,17 @@ export async function viewDraft(
       };
     }
     const slide = mapCapturedSlide(fileName, byFile.get(fileName), warnings);
-    if (conversions[fileName] && !slide.note) slide.note = convertedNote;
+    if (conversions[fileName]) {
+      // The measured draft checks are authored-slide only (the add-in's
+      // translate-deck exempts the converted dialect the same way).
+      slide.converted = true;
+      if (!slide.note) slide.note = convertedNote;
+    }
     return slide;
   });
 
   // --translate: run the captured slides through the server's translate gate
-  // (slot-fit, diagram-geometry, connector-endpoints — the checks the local
+  // (slot-fit, diagram-geometry, text escape — the checks the local
   // capture cannot make) and hand its verdict back per slide. The returned
   // .pptx is discarded: this is validation, not delivery, so no review gate
   // stands in front of it and a per-slide builder can prove its ONE slide
@@ -671,7 +859,22 @@ export async function viewDraft(
   let translateErrors = null;
   let translateWarnings = [];
   let translateRan = false;
+  let gateResult = null;
+  let draftIntent = null;
   if (translate && gateDeck.slides.length) {
+    // The deck's image obligations, so the gate validates against what was
+    // approved and not against whatever the JSX happens to say. A draft never
+    // dies of one: a source that cannot be resolved comes back as a repair line
+    // below (that is what the draft is FOR), where the final build refuses on
+    // the same fact.
+    try {
+      draftIntent = buildImageIntentEnvelope(deckDir, {
+        slides: slideNumbersOf(gateDeck.slides.map((s) => s.fileName)),
+        inline: false,
+      });
+    } catch {
+      draftIntent = null;
+    }
     const skip = (why) => {
       if (translate !== "auto") throw new Error(why);
       warnings.push(`export gate skipped: ${why}`);
@@ -693,10 +896,12 @@ export async function viewDraft(
           const res = await translateDeck({
             brandId: ref.presFP,
             backendURL: mat.backendURL,
-            deckName: path.basename(deckDir),
+            deckName: deckSlug(deckDir),
             captured: gateDeck,
             etag: mat.etag,
+            imageIntent: draftIntent,
           });
+          gateResult = res;
           translateErrors = new Map();
           translateWarnings = Array.isArray(res?.warnings) ? res.warnings : [];
           translateRan = true;
@@ -719,6 +924,26 @@ export async function viewDraft(
   }
   if (translateErrors?.has("")) warnings.push(...translateErrors.get(""));
 
+  // Image obligations, draft flavour: the local half always (is the source
+  // still there, did the captured render actually place it), plus the server's
+  // own verdict when the export gate ran and carried the expectations. Reported
+  // per slide so the agent can repair from the preview it is looking at — the
+  // refusal lives in the build path, not here.
+  const intentLines = draftImageIntentLines(deckDir, slides);
+  if (draftIntent && translateRan && gateResult) {
+    const verdict = imageIntentVerdict(draftIntent, gateResult);
+    for (const issue of verdict.issues) {
+      const key = issue.file ?? "";
+      if (!intentLines.has(key)) intentLines.set(key, []);
+      intentLines.get(key).push(formatIssue(issue));
+    }
+  }
+  for (const slide of slides) {
+    const lines = intentLines.get(slide.fileName);
+    if (lines?.length) slide.imageIntentIssues = lines;
+  }
+  if (intentLines.has("")) warnings.push(...intentLines.get(""));
+
   return { slides, warnings, translateWarnings, translateRan };
 }
 
@@ -743,7 +968,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, reconcile = null) {
+async function tryDetachedRender(deckDir, deckRef, onProgress, reconcile = null, only = null) {
   const brandId = deckRef.presFP;
   let backendURL;
   try {
@@ -760,6 +985,7 @@ async function tryDetachedRender(deckDir, deckRef, onProgress, reconcile = null)
     backendURL,
     reconcile,
     onProgress,
+    only,
   });
   return { result, backendURL };
 }
@@ -770,6 +996,7 @@ async function renderWithRetarget(
   onProgress,
   registry = [],
   reconcile = null,
+  only = null,
 ) {
   const run = (target) =>
     renderDeckToBase64(deckDir, {
@@ -777,6 +1004,7 @@ async function renderWithRetarget(
       backendURL: target.backendURL ?? null,
       reconcile,
       onProgress,
+      only,
     });
   try {
     return { entry, result: await run(entry) };
@@ -903,16 +1131,20 @@ export async function buildAndPush({
   // `--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`).
+  // half stops here and asks. The confirmation is the USER's, as in the add-in,
+  // where the same gated route opens the preview review: the agent asks and
+  // passes --accept-conversions only on their go-ahead. 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` +
+        `--replace would overwrite the originals with a conversion nobody reviewed.\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.`,
+        `\nThis is the user's call, not a retry: name these slides to the user and re-run with ` +
+        `--accept-conversions only after they agree, or push without --replace to insert them ` +
+        `and leave the originals in place.`,
     );
     err.code = "conversions_not_confirmed";
     err.gatedConversions = gatedConversions;
@@ -928,15 +1160,15 @@ 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) => {
-    let fallbackFile = path.join(deckDir, `${path.basename(deckDir)}.pptx`);
+    let fallbackFile = deckPptxPath(deckDir);
     // 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`,
+        deckRoot(deckDir),
+        `${deckSlug(deckDir)}-${stamp}.pptx`,
       );
     }
     fs.writeFileSync(fallbackFile, Buffer.from(base64, "base64"));
@@ -1064,9 +1296,9 @@ export async function buildAndPush({
   };
 }
 
-// After a successful build-pptx: per-slide PNGs of what was just shipped, into
-// `<deck>/.build-preview/NN-name.png`. The .pptx itself is opaque here, so
-// without this the agent hands over a deck it has never seen. Best-effort — a
+// Browser source previews after build-pptx. These are NOT a render of the
+// emitted package; writePackagePreview separately inspects those exact bytes.
+// Best-effort — a
 // missing engine or a Chrome that won't launch returns a note, never a failure:
 // the .pptx is already written.
 export async function writeBuildPreview(deckDir, onProgress = null) {
@@ -1077,7 +1309,7 @@ export async function writeBuildPreview(deckDir, onProgress = null) {
       files: [],
       note:
         "visual check skipped — the deck's bundle carries no capture engine " +
-        `(run 'slidemind download-bundle ${path.basename(deckDir)}')`,
+        `(run 'slidemind download-bundle ${deckSlug(deckDir)}')`,
     };
   }
   let captured;
@@ -1090,7 +1322,7 @@ export async function writeBuildPreview(deckDir, onProgress = null) {
       note: `visual check skipped — local capture failed (${err instanceof Error ? err.message : String(err)})`,
     };
   }
-  const dir = path.join(deckDir, ".build-preview");
+  const dir = previewPath(deckDir, "build");
   fs.mkdirSync(dir, { recursive: true });
   const files = [];
   for (const slide of captured?.slides ?? []) {
@@ -1103,7 +1335,161 @@ export async function writeBuildPreview(deckDir, onProgress = null) {
     fs.writeFileSync(file, Buffer.from(b64, "base64"));
     files.push(file);
   }
-  return { dir, files, note: null };
+  return { kind: "browser", status: "source-only", dir, files, note: "Browser source preview; not a render of the exported PPTX." };
+}
+
+
+// ---------------------------------------------------------------------------
+// targeted assembly — a deck that HAS an accepted base
+// ---------------------------------------------------------------------------
+
+// GUID per slide FILE. An adopted deck's authority is its revision record (it
+// carries the native slides too, which the jsx-only GUID sidecar cannot); the
+// sidecar fills in for slides authored since.
+function guidsByFile(deckDir, revision) {
+  const byFile = new Map();
+  for (const [key, guid] of Object.entries(reconcileSlideGuids(deckDir))) {
+    byFile.set(key.replace(/^slides\//, ""), guid);
+  }
+  for (const slide of revision?.base?.slides ?? []) {
+    if (slide.file && slide.guid && !byFile.has(slide.file)) byFile.set(slide.file, slide.guid);
+  }
+  return byFile;
+}
+
+/**
+ * Build the next deck by applying only what changed to the accepted base.
+ *
+ * Returns null when this deck has no base (nothing to be targeted about — the
+ * caller renders the whole deck as before). Otherwise `{ base64, report,
+ * candidate, rendered }`, where `rendered` is the slide files that actually
+ * went to the renderer.
+ *
+ * Three properties this exists for, none of which whole-deck rendering has:
+ *   • two changed slides in a forty-slide deck cost two slide renders;
+ *   • an order-only change costs NONE — nothing is re-rendered at all;
+ *   • every part the change does not touch keeps its exact bytes, which is the
+ *     only way notes, comments, animations, embeddings and native objects
+ *     survive a deck slidemind did not author.
+ */
+function renderSetOf(dirty, files, refreshDesign) {
+  const changed = new Set([...dirty.dirtySlides, ...dirty.added]);
+  if (refreshDesign) for (const f of files) changed.add(f);
+  return changed;
+}
+
+/**
+ * The slide files `build-pptx` will render: every slide of a deck without an
+ * accepted base, otherwise exactly `buildAgainstBase`'s render set. The
+ * delivery draft gate asks each of them for a current draft check.
+ */
+export function deliveredSlideFiles(deckDir, { refreshDesign = false } = {}) {
+  const revision = readRevision(deckDir);
+  const files = slideFileOrder(deckDir);
+  if (!revision?.base || !fs.existsSync(acceptedBasePath(deckDir))) return files;
+  return [...renderSetOf(computeDirty(deckDir, revision), files, refreshDesign)];
+}
+
+async function buildAgainstBase(deckDir, { render, onProgress, refreshDesign = false }) {
+  const revision = readRevision(deckDir);
+  const base = readAcceptedBase(deckDir);
+  if (!revision?.base || !base) return null;
+
+  const dirty = computeDirty(deckDir, revision);
+  const files = slideFileOrder(deckDir);
+  const byFile = guidsByFile(deckDir, revision);
+  // The render set is what the user changed — never more. A design that moved
+  // under the deck is announced, and re-rendered only on --refresh-design.
+  const changed = renderSetOf(dirty, files, refreshDesign);
+  const designStale = dirty.sharedChanged && !refreshDesign ? files.filter((f) => !changed.has(f)) : [];
+  process.stderr.write(
+    `  rendering ${changed.size} of ${files.length} slide(s)` +
+      (changed.size ? `: ${[...changed].sort().join(", ")}` : " — nothing changed since the accepted base") +
+      "\n",
+  );
+  if (designStale.length) {
+    process.stderr.write(
+      `  note: the corporate design moved since the accepted base — ${designStale.length} untouched slide(s) ` +
+        `keep the design they were last rendered with; \`slidemind build-pptx --refresh-design\` re-renders them\n`,
+    );
+  }
+  const { plan, render: toRender } = planFromDeck({
+    slides: files,
+    guidFor: (f) => byFile.get(f) ?? null,
+    partFor: (f) => revision.base.slides.find((s) => s.file === f)?.part ?? null,
+    dirty: changed,
+  });
+
+  let rendered = null;
+  if (toRender.length > 0) {
+    const result = await render(toRender);
+    rendered = Buffer.from(result.base64, "base64");
+  } else if (onProgress) {
+    onProgress({ stage: "assembling", done: 0, total: 0 });
+  }
+
+  const { bytes, report } = assembleDeck({ base, rendered, plan });
+  if (!bytes) {
+    const err = new Error(
+      `the deck could not be assembled onto the file it was adopted from:\n  ` +
+        report.errors.join("\n  ") +
+        (report.blocked.length
+          ? `\nThese slides carry something a re-render cannot reproduce. Either leave them ` +
+            `alone, or delete the slide and add a new one in its place.`
+          : ""),
+    );
+    err.code = "assembly_blocked";
+    err.report = report;
+    throw err;
+  }
+  return {
+    base64: Buffer.from(bytes).toString("base64"),
+    report,
+    rendered: toRender,
+    plan,
+    designStale,
+    renderedAll: changed.size === files.length,
+  };
+}
+
+function renderInputs(deckDir) {
+  const inputs = materializedInputs(deckDir);
+  for (const file of Object.keys(inputs.inputs)) {
+    if (!file.startsWith("conversions/") || !file.endsWith(".json")) continue;
+    // An unreadable record is NOT fatal here: the conversion gate below owns
+    // that case and says something actionable about it. Throwing a raw
+    // SyntaxError from the etag inputs would pre-empt it with a stack trace.
+    let record;
+    try {
+      record = JSON.parse(fs.readFileSync(path.join(deckDir, file), "utf8"));
+    } catch {
+      continue;
+    }
+    // This is a render RESULT, stamped by this very request, not an input.
+    delete record.firstReplace;
+    inputs.inputs[file] = JSON.stringify(record);
+  }
+  return inputs;
+}
+
+function renderInputDigest(deckDir) {
+  return inputDigest(renderInputs(deckDir));
+}
+
+// Which inputs moved between two snapshots — printed when a render restarts,
+// because "inputs changed" without a name is a full re-render nobody can act on.
+function renderInputChanges(before, after) {
+  const hash = (v) => createHash("sha256").update(typeof v === "string" ? v : Buffer.from(v)).digest("hex");
+  const changed = [];
+  for (const key of new Set([...Object.keys(before.inputs), ...Object.keys(after.inputs)])) {
+    const a = before.inputs[key], b = after.inputs[key];
+    if (a === undefined) changed.push(`${key} (added)`);
+    else if (b === undefined) changed.push(`${key} (removed)`);
+    else if (hash(a) !== hash(b)) changed.push(key);
+  }
+  if (JSON.stringify(before.order) !== JSON.stringify(after.order)) changed.push("slide order");
+  if (before.shared?.design !== after.shared?.design) changed.push(`design bundle (${before.shared?.design} -> ${after.shared?.design})`);
+  return changed;
 }
 
 // Render a deck to a .pptx file (the `slidemind build-pptx` path). For a BOUND
@@ -1116,11 +1502,12 @@ export async function buildPptxFile({
   presentationId = null,
   outPath = null,
   force = false,
+  refreshDesign = 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`);
+  const out = outPath || deckPptxPath(deckDir);
 
   // 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
@@ -1133,41 +1520,129 @@ export async function buildPptxFile({
   // the registry path — reading the design off an open presentation is the one
   // thing a render legitimately needs a window for.
   const brandId = presentationId ? null : await resolveWindowlessBrand(deckDir);
-  if (brandId) {
-    const detached = await tryDetachedRender(deckDir, { presFP: brandId }, onProgress, reconcile);
-    if (detached) {
-      fs.writeFileSync(out, Buffer.from(detached.result.base64, "base64"));
-      return {
-        outPath: out,
-        presId: null,
-        windowless: true,
-        slideCount: detached.result.slideCount ?? null,
-        warnings: detached.result.warnings ?? [],
-        skippedSlides: detached.result.skippedSlides ?? [],
-        preview: await writeBuildPreview(deckDir, onProgress),
-      };
+
+  // One render closure, whichever route answers — so the targeted path below
+  // does not have to know which of the two it is riding on.
+  let presId = null;
+  let renderedWindowless = false;
+  let lastResult = null;
+  let previewTarget = null;
+  const renderSubset = async (only) => {
+    if (brandId) {
+      const detached = await tryDetachedRender(
+        deckDir,
+        { presFP: brandId },
+        onProgress,
+        reconcile,
+        only,
+      );
+      if (detached) {
+        renderedWindowless = true;
+        lastResult = detached.result;
+        previewTarget = { brandId, backendURL: detached.backendURL };
+        return detached.result;
+      }
     }
+    const registry = await requireRenderHost();
+    const entry = pickPresentationEntry(registry, presentationId, {
+      preferBrandId: deckRef?.presFP ?? null,
+    });
+    const { entry: renderEntry, result } = await renderWithRetarget(
+      deckDir,
+      entry,
+      onProgress,
+      [],
+      reconcile,
+      only,
+    );
+    presId = renderEntry.presId;
+    previewTarget = { brandId: renderEntry.brandId ?? deckRef?.presFP, backendURL: renderEntry.backendURL };
+    lastResult = result;
+    return result;
+  };
+
+  // A deck with an accepted base assembles onto it: only the changed slides
+  // render, and everything the change does not touch keeps its exact bytes.
+  // That whole stretch — read the base, work out the dirty set, render, assemble,
+  // capture the candidate — runs under the deck's ownership, so an `adopt` or a
+  // `rebase` cannot move the base out from under it halfway through. Under an
+  // open edit session (SLIDEMIND_OWNER) it re-enters that session. Fresh decks
+  // take the same lock and persist an unaccepted candidate for first publish.
+  const held = acquireOwner(deckDir, { command: "build-pptx" });
+  let targeted;
+  let candidate = null;
+  let base64;
+  let result;
+  let preview;
+  let packagePreview;
+  try {
+    // A bundle refresh or source edit during rendering invalidates those bytes.
+    // Restart once from current inputs; persistent churn refuses certification.
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const startingInputs = renderInputs(deckDir);
+      targeted = await buildAgainstBase(deckDir, { render: renderSubset, onProgress, refreshDesign });
+      result = targeted ?? (await renderSubset(null));
+      const changed = renderInputChanges(startingInputs, renderInputs(deckDir));
+      if (!changed.length) break;
+      if (attempt === 1) throw new Error(`Deck inputs changed during rendering (${changed.join(", ")}); no candidate was certified. Build again from stable inputs.`);
+      process.stderr.write(`  inputs changed during the render (${changed.slice(0, 5).join(", ")}${changed.length > 5 ? `, +${changed.length - 5} more` : ""}); rendering again from the current inputs…\n`);
+    }
+    base64 = targeted ? targeted.base64 : result.base64;
+    // The build proposes; it does not decide. The bytes are kept as an immutable
+    // candidate with the evidence they were built from, the accepted base does
+    // not move and localDirty does not clear — so edit → build → build keeps the
+    // first edit and nothing is accepted that a human did not accept.
+    {
+      // The render's own package is normalized the way an assembled one is:
+      // its design master lists layouts twice, which PowerPoint repairs.
+      const files = unzip(Buffer.from(base64, "base64"));
+      const fixed = normalizeMasters(files);
+      if (Object.values(fixed).some(Boolean)) base64 = Buffer.from(zip(files)).toString("base64");
+      const packageValidation = validatePackage(files);
+      if (!packageValidation.ok) throw new Error(`Rendered package is invalid: ${packageValidation.errors.join('; ')}`);
+      candidate = saveCandidate(deckDir, {
+        bytes: Buffer.from(base64, "base64"),
+        validation: {
+          ok: true,
+          errors: [],
+          checks: ["opc-relationships", "content-types", "slide-identity"],
+        },
+        renderedAll: targeted ? targeted.renderedAll : true,
+      });
+    }
+    // The delivered file and its package render are one unit, so they stay
+    // under the lock: a second build that wrote its bytes between them left a
+    // file no render had verified (x97).
+    fs.writeFileSync(out, Buffer.from(base64, "base64"));
+    preview = await writeBuildPreview(deckDir, onProgress);
+    packagePreview = await writePackagePreview({deckDir, bytes: Buffer.from(base64, "base64"), target: previewTarget, onProgress});
+  } finally {
+    held?.release();
   }
 
-  const registry = await requireRenderHost();
-  const entry = pickPresentationEntry(registry, presentationId, {
-    preferBrandId: deckRef?.presFP ?? null,
-  });
-  const { entry: renderEntry, result } = await renderWithRetarget(
-    deckDir,
-    entry,
-    onProgress,
-    [],
-    reconcile,
-  );
-  const presId = renderEntry.presId;
-  fs.writeFileSync(out, Buffer.from(result.base64, "base64"));
   return {
     outPath: out,
     presId,
-    slideCount: result.slideCount ?? null,
-    warnings: result.warnings ?? [],
-    skippedSlides: result.skippedSlides ?? [],
-    preview: await writeBuildPreview(deckDir, onProgress),
+    windowless: renderedWindowless && !presId ? true : undefined,
+    slideCount: lastResult?.slideCount ?? null,
+    warnings: [
+      ...(lastResult?.warnings ?? []),
+      ...(targeted?.report.warnings ?? []),
+    ],
+    skippedSlides: lastResult?.skippedSlides ?? [],
+    targeted: targeted
+      ? {
+          rendered: targeted.rendered,
+          designStale: targeted.designStale,
+          kept: targeted.report.kept.length,
+          replaced: targeted.report.replaced.length,
+          inserted: targeted.report.inserted.length,
+          deleted: targeted.report.deleted.length,
+          reusedLayouts: targeted.report.reusedLayouts,
+        }
+      : null,
+    candidate: candidate ? { candidateId: candidate.candidateId, outputSha256: candidate.outputSha256 } : null,
+    preview,
+    packagePreview,
   };
 }