slidemind 0.3.17 → 0.3.19

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "slidemind",
-  "version": "0.3.17",
+  "version": "0.3.19",
   "description": "Connect Claude Code to the slidemind PowerPoint add-in — build and edit native, on-brand PowerPoint decks against the active corporate design, from the terminal.",
   "author": {
     "name": "statworx",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "slidemind",
-  "version": "0.3.17",
+  "version": "0.3.19",
   "description": "Connect Codex to the slidemind PowerPoint add-in — build and edit native, on-brand PowerPoint decks against the active corporate design. Requires the slidemind CLI (npm install -g slidemind); the skills explain the install when it is missing.",
   "author": {
     "name": "statworx",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slidemind",
-  "version": "0.3.17",
+  "version": "0.3.19",
   "description": "Connect Claude Code, Codex & opencode to the slidemind PowerPoint add-in — let your coding agent build and edit native, on-brand PowerPoint decks against your active corporate design, from the terminal.",
   "type": "module",
   "bin": {

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

@@ -37,10 +37,11 @@ import {
   writeDeckBundleRef,
 } from "./bundle.mjs";
 import { bundleHasCaptureEngine, captureDeckLocally } from "./capture.mjs";
+import { lintConvertedOrThrow } from "../lib/lint-converted.mjs";
 import { slideOrderWarning, sortSlideFilenames } from "../lib/slide-order.mjs";
 import {
   applyConversionGates,
-  conversionsMissingPreserveSource,
+  conversionIntegrityErrors,
   loadConversions,
   rehomeConversions,
 } from "../lib/conversions.mjs";
@@ -274,12 +275,25 @@ export async function renderDeckToBase64(
   // 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, deckDir)) {
-    process.stderr.write(
-      `note: ${file} has preserved native objects or a sourced chart but no ` +
-        `conversions/*.slide.pptx to read them from — re-run 'slidemind adopt' for that deck\n`,
+  // A record that points at a package file that is gone, or still names the
+  // 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);
+  if (integrity.length > 0) {
+    throw new Error(
+      `conversion records are out of sync with the deck:\n  ${integrity.join("\n  ")}`,
     );
   }
+  // The export gate for the converted dialect. `view-draft` prints these as
+  // warnings so a half-authored deck still previews; here — the last step
+  // before a .pptx exists — a surviving master prompt, copy in a field frame
+  // or text spilling a fixed box stops the deck from shipping.
+  if (hasConversions) {
+    lintConvertedOrThrow({
+      slideFiles: Object.keys(conversions).map((f) => path.join(deckDir, "slides", f)),
+    });
+  }
 
   const bundleDir = resolveBundleDirForDeck(deckDir);
   // Local capture only applies to authored JSX slides. A native-only deck (just
@@ -544,19 +558,16 @@ export async function viewDraft(
   }
   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).
+  // and a stale sidecar here would mislabel renamed converted slides.
   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.
+  // layout, which no materialized bundle carries — buildCaptureInput feeds the
+  // engine a stand-in host per source canvas so they preview here like any
+  // other slide. 34 converted slides were once authored blind because this
+  // refused them.
   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]);
+  const convertedNote = "converted slide — geometry authoritative on the server render";
+  const hasJsx = all.some((f) => f.endsWith(".jsx"));
 
   // 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
@@ -593,19 +604,14 @@ export async function viewDraft(
     bundleDir = resolveBundleDirForDeck(deckDir);
   }
 
-  // Nothing left to capture — a native-only deck (just reused .pptx), a fully
-  // converted one, or both.
+  // Nothing left to capture — a native-only deck (just reused .pptx).
   if (!hasJsx) {
     return {
-      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",
-            },
-      ),
+      slides: all.map((fileName) => ({
+        fileName,
+        status: "native",
+        note: "reused native slide — not authored JSX, no draft preview rendered",
+      })),
       warnings,
     };
   }
@@ -621,16 +627,13 @@ export async function viewDraft(
 
   let captured;
   try {
-    // Converted slides never reach the local engine — it would lint each one
-    // as an unregistered layout and the noise would ride the translate gate.
-    const capturable = all.filter((f) => f.endsWith(".jsx") && !conversions[f]);
+    const capturable = all.filter((f) => f.endsWith(".jsx"));
     captured = await captureDeckLocally({ deckDir, bundleDir, onProgress, only: capturable });
   } catch (err) {
     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, " +
-        "`slidemind review <deck>` still builds and serves the HTML preview without it." +
-        (Object.keys(conversions).length > 0 ? ` ${convertedNote}.` : ""),
+        "`slidemind review <deck>` still builds and serves the HTML preview without it.",
     );
   }
 
@@ -643,10 +646,9 @@ export async function viewDraft(
         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);
+    const slide = mapCapturedSlide(fileName, byFile.get(fileName), warnings);
+    if (conversions[fileName] && !slide.note) slide.note = convertedNote;
+    return slide;
   });
 
   // --translate: run the captured slides through the server's translate gate
@@ -658,10 +660,18 @@ export async function viewDraft(
   // `translate: "auto"` (the default) runs the gate when it can and reports
   // why not otherwise — an unbound deck or a dead backend must not turn a
   // host-free draft check into a failure; `true` (--translate) insists.
+  // Converted slides are captured for the PICTURE only. Their export gate is
+  // the server render with their conversion record, and the stand-in host they
+  // preview on names no brand layout — sending them through /translate would
+  // judge them against a layout contract the CLI invented.
+  const gateDeck = {
+    ...captured,
+    slides: (captured?.slides ?? []).filter((s) => !conversions[s.fileName]),
+  };
   let translateErrors = null;
   let translateWarnings = [];
   let translateRan = false;
-  if (translate && captured?.slides?.length) {
+  if (translate && gateDeck.slides.length) {
     const skip = (why) => {
       if (translate !== "auto") throw new Error(why);
       warnings.push(`export gate skipped: ${why}`);
@@ -684,7 +694,7 @@ export async function viewDraft(
             brandId: ref.presFP,
             backendURL: mat.backendURL,
             deckName: path.basename(deckDir),
-            captured,
+            captured: gateDeck,
             etag: mat.etag,
           });
           translateErrors = new Map();
@@ -1054,6 +1064,48 @@ 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
+// 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) {
+  const bundleDir = resolveBundleDirForDeck(deckDir);
+  if (!bundleHasCaptureEngine(bundleDir)) {
+    return {
+      dir: null,
+      files: [],
+      note:
+        "visual check skipped — the deck's bundle carries no capture engine " +
+        `(run 'slidemind download-bundle ${path.basename(deckDir)}')`,
+    };
+  }
+  let captured;
+  try {
+    captured = await captureDeckLocally({ deckDir, bundleDir, onProgress });
+  } catch (err) {
+    return {
+      dir: null,
+      files: [],
+      note: `visual check skipped — local capture failed (${err instanceof Error ? err.message : String(err)})`,
+    };
+  }
+  const dir = path.join(deckDir, ".build-preview");
+  fs.mkdirSync(dir, { recursive: true });
+  const files = [];
+  for (const slide of captured?.slides ?? []) {
+    const b64 =
+      /^data:image\/png;base64,(.+)$/.exec(slide.previewDataUrl ?? "")?.[1] ??
+      slide.render?.fallbackPngBase64 ??
+      null;
+    if (!b64) continue;
+    const file = path.join(dir, `${path.basename(slide.fileName, ".jsx")}.png`);
+    fs.writeFileSync(file, Buffer.from(b64, "base64"));
+    files.push(file);
+  }
+  return { dir, files, note: null };
+}
+
 // Render a deck to a .pptx file (the `slidemind build-pptx` path). For a BOUND
 // deck against a backend serving brand routes this is fully pane-free — no
 // PowerPoint window needed at all (backgrounded or closed). Otherwise it needs
@@ -1092,6 +1144,7 @@ export async function buildPptxFile({
         slideCount: detached.result.slideCount ?? null,
         warnings: detached.result.warnings ?? [],
         skippedSlides: detached.result.skippedSlides ?? [],
+        preview: await writeBuildPreview(deckDir, onProgress),
       };
     }
   }
@@ -1115,5 +1168,6 @@ export async function buildPptxFile({
     slideCount: result.slideCount ?? null,
     warnings: result.warnings ?? [],
     skippedSlides: result.skippedSlides ?? [],
+    preview: await writeBuildPreview(deckDir, onProgress),
   };
 }

package/src/bridge/capture.mjs

@@ -14,6 +14,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
+import { convertedHostLayouts, loadConversions } from "../lib/conversions.mjs";
+
 // Same launch profile as the add-in's chrome-launcher.ts, so the client browser
 // behaves identically to the server's during capture.
 const LAUNCH_ARGS = [
@@ -88,6 +90,15 @@ export function buildCaptureInput(deckDir, bundleDir) {
 
   const slides = readJsxDir(path.join(deckDir, "slides"));
   const layouts = readJsxDir(path.join(bundleDir, "layouts"));
+  // Converted slides (`slidemind adopt`) invoke a ConvertedHost layout the
+  // server mints per source canvas — no bundle carries it, so without a
+  // stand-in the engine rejects every one of them as an unregistered layout
+  // and the agent authors them blind. The stub is the deck's own host box;
+  // geometry stays authoritative on the server render.
+  Object.assign(
+    layouts,
+    convertedHostLayouts(deckDir, loadConversions(deckDir, { includeSource: false })),
+  );
 
   const layoutsCssPath = path.join(bundleDir, "layouts", "layouts.css");
   const layoutsCss = fs.existsSync(layoutsCssPath)

package/src/builders/build.mjs

@@ -37,8 +37,9 @@ import { resolveBundleDirForDeck } from "../bridge/bundle.mjs";
 import { loadChartPreview, loadConnectorPreview } from "../bridge/capture.mjs";
 import { FAVICON_LINK } from "./gate-server.mjs";
 import { lintSlidesOrThrow } from "./lint.mjs";
+import { lintConvertedOrThrow } from "../lib/lint-converted.mjs";
 import { resolveSkillForDeck } from "./resolve-skill.mjs";
-import { loadConversions } from "../lib/conversions.mjs";
+import { convertedHostLayouts, loadConversions } from "../lib/conversions.mjs";
 import { slideOrderWarning, sortSlideFilenames } from "../lib/slide-order.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -88,26 +89,13 @@ function inlineLayout(file) {
   );
 }
 
-// Preview stand-ins for the ConvertedHost layouts converted slides invoke. The
-// host's name carries its canvas (`ConvertedHost<cx>x<cy>`, EMU), so the stub
-// sizes itself the way the minted host does (EMU / 9525, 3 decimals) instead of
-// assuming 16:9 — a 4:3 source previews at 960x720, not stretched to 1280.
-// Real geometry still comes from the server render.
-const HOST_NAME_RE = /<(ConvertedHost(\d+)x(\d+))/;
-const emuToCssPx = (emu) => `${Math.round((Number(emu) / 9525) * 1000) / 1000}px`;
-
-function convertedHostStubs(slideFiles, conversions) {
-  const hosts = new Map();
-  for (const file of slideFiles) {
-    if (!conversions[path.basename(file)]) continue;
-    const m = HOST_NAME_RE.exec(fs.readFileSync(file, "utf8"));
-    if (m) hosts.set(m[1], { w: emuToCssPx(m[2]), h: emuToCssPx(m[3]) });
-  }
-  return [...hosts].map(
-    ([name, { w, h }]) =>
-      `<script type="text/jsx-template" data-kind="layout" data-name="${name}" data-binding="${name}">\n` +
-      `function ${name}({ background, children }) { return <div style={{ position: "relative", width: "${w}", height: "${h}", overflow: "hidden", background: background || "#FFFFFF" }}>{children}</div>; }\n` +
-      `</script>`,
+// Preview stand-ins for the ConvertedHost layouts converted slides invoke —
+// same sources the local capture path feeds its engine (src/lib/conversions.mjs),
+// wrapped as inline jsx-templates for this page.
+function convertedHostStubs(deckDir, conversions) {
+  return Object.entries(convertedHostLayouts(deckDir, conversions)).map(
+    ([name, source]) =>
+      `<script type="text/jsx-template" data-kind="layout" data-name="${name.replace(/\.jsx$/, "")}" data-binding="${name.replace(/\.jsx$/, "")}">\n${source}</script>`,
   );
 }
 
@@ -381,12 +369,24 @@ export async function buildDeck(deckDir, opts = {}) {
   // Converted slides (`slidemind adopt`) invoke a synthetic ConvertedHost
   // layout the server mints per source canvas; no bundle carries it, so the
   // local engine would fail every one of them as an unregistered layout. They
-  // are linted server-side on render — skip them here, lint the authored rest.
+  // get the dialect's OWN lint instead (master prompts that survived, empty
+  // placeholders, text in a field frame, text spilling a fixed box) — without
+  // it the adopted half of a deck was checked by nothing at all.
   const conversions = loadConversions(deckDir, { includeSource: false });
+  const convertedFiles = slideFiles.filter((f) => conversions[path.basename(f)]);
   const authoredFiles = slideFiles.filter((f) => !conversions[path.basename(f)]);
   if (authoredFiles.length > 0) {
     await lintSlidesOrThrow({ deckDir, slideFiles: authoredFiles, layoutSources });
   }
+  if (convertedFiles.length > 0) {
+    lintConvertedOrThrow({
+      slideFiles: convertedFiles,
+      strict: Boolean(opts.strict),
+      // view-draft looks at half-authored slides, so it passes false; the
+      // review gate and the render path enforce.
+      enforce: opts.enforceConverted !== false,
+    });
+  }
 
   // The <Chart> stand-in runtime rides in the same bundle cache (see
   // loadChartPreview) — resolved after lint, which already proved the bundle
@@ -398,7 +398,7 @@ export async function buildDeck(deckDir, opts = {}) {
 
   const layoutsBlock = layoutFiles
     .map(inlineLayout)
-    .concat(convertedHostStubs(slideFiles, conversions))
+    .concat(convertedHostStubs(deckDir, conversions))
     .join("\n");
   const slidesBlock = slideFiles
     .map((file, i) => inlineSlide(file, i))

package/src/cli/deck.mjs

@@ -29,9 +29,24 @@ export async function cmdImagen(rest) {
   let outName = null;
   let size = null;
   let quality = null;
+  let into = null;
+  let behind = null;
+  let rect = null;
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
-    if (a === "--deck") {
+    if (a === "--into") {
+      into = rest[++i];
+      if (!into) fail("--into expects a slide file (e.g. slides/07-approach.jsx)");
+    } else if (a === "--behind") {
+      behind = rest[++i];
+      if (!/^\d+$/.test(behind ?? "")) fail("--behind expects a data-sm-source-id number");
+    } else if (a === "--rect") {
+      const parts = String(rest[++i] ?? "").split(",").map((n) => n.trim());
+      if (parts.length !== 4 || parts.some((n) => !/^-?[\d.]+$/.test(n))) {
+        fail("--rect expects <left,top,width,height> in px");
+      }
+      rect = { left: parts[0], top: parts[1], width: parts[2], height: parts[3] };
+    } else if (a === "--deck") {
       deck = rest[++i];
       if (!deck) fail("--deck expects a deck");
     } else if (a === "--out" || a === "-o") {
@@ -58,9 +73,12 @@ export async function cmdImagen(rest) {
   if (!prompt || !prompt.trim() || !deck) {
     fail(
       'usage: slidemind imagen "<prompt>" --deck <deck> [--out <name.png>] ' +
-        "[--size auto|1024x1024|1536x1024|1024x1536] [--quality low|medium|high|auto]",
+        "[--size auto|1024x1024|1536x1024|1024x1536] [--quality low|medium|high|auto] " +
+        "[--into slides/NN-name.jsx --behind <source-id>|--rect <l,t,w,h>]",
     );
   }
+  if ((behind || rect) && !into) fail("--behind/--rect need --into <slide file>");
+  if (into && !behind && !rect) fail("--into needs --behind <source-id> or --rect <l,t,w,h>");
   const deckDir = resolveDeckArg(deck);
   const bundleMod = await import(
     pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href
@@ -106,9 +124,37 @@ export async function cmdImagen(rest) {
   }
   const outPath = path.join(assetsDir, file);
   fs.writeFileSync(outPath, Buffer.from(m[2], "base64"));
+  process.stdout.write(`Wrote ${path.relative(process.cwd(), outPath)}\n`);
+  if (!into) {
+    process.stdout.write(
+      `  Reference it from slide props as "assets/${file}" (e.g. summaryImage, illustration),\n` +
+        `  or re-run with --into <slide> --behind <source-id> to place it for you.\n`,
+    );
+    return;
+  }
+  // Place it: a picture the agent wires up by hand is the step that put the
+  // last one on the wrong element.
+  const slidePath = path.isAbsolute(into)
+    ? into
+    : path.join(deckDir, into.startsWith("slides/") ? into : path.join("slides", into));
+  if (!fs.existsSync(slidePath)) fail(`--into: no such slide file: ${slidePath}`);
+  const { insertImageDiv } = await import(
+    pathToFileURL(path.join(SRC_DIR, "lib", "jsx-insert.mjs")).href
+  );
+  let next;
+  try {
+    next = insertImageDiv(fs.readFileSync(slidePath, "utf8"), {
+      url: `./assets/${file}`,
+      behind,
+      rect,
+    });
+  } catch (err) {
+    fail(`${err.message}\n  The image is on disk at assets/${file} — place it by hand.`);
+  }
+  fs.writeFileSync(slidePath, next);
   process.stdout.write(
-    `Wrote ${path.relative(process.cwd(), outPath)}\n` +
-      `  Reference it from slide props as "assets/${file}" (e.g. summaryImage, illustration).\n`,
+    `  Placed it in ${path.relative(process.cwd(), slidePath)} ` +
+      `${behind ? `behind data-sm-source-id={${behind}}` : "at the given rect"} — re-read the file before patching it.\n`,
   );
 }
 
@@ -301,13 +347,21 @@ export async function cmdBuildPptx(rest) {
     .catch((err) => fail(withUnboundHint(deckDir, err)));
   if (asJson) {
     process.stdout.write(
-      `${JSON.stringify({ outPath: result.outPath, slideCount: result.slideCount ?? null, presId: result.presId ?? null, windowless: Boolean(result.windowless), warnings: result.warnings ?? [], skippedSlides: result.skippedSlides ?? [] }, null, 2)}\n`,
+      `${JSON.stringify({ outPath: result.outPath, slideCount: result.slideCount ?? null, presId: result.presId ?? null, windowless: Boolean(result.windowless), warnings: result.warnings ?? [], skippedSlides: result.skippedSlides ?? [], preview: result.preview ?? null }, null, 2)}\n`,
     );
   } else {
     process.stdout.write(
       `Wrote ${result.outPath} (${result.slideCount ?? "?"} slides) via the slidemind add-in` +
         `${result.windowless ? " (no PowerPoint window needed)" : ""}\n`,
     );
+    // LOOK at what shipped — the .pptx is opaque from here.
+    if (result.preview?.dir) {
+      process.stdout.write(
+        `  ${result.preview.files.length} slide png(s) in ${path.relative(process.cwd(), result.preview.dir)}/ — read them before handing the deck over\n`,
+      );
+    } else if (result.preview?.note) {
+      process.stdout.write(`  ${result.preview.note}\n`);
+    }
   }
   for (const w of result.warnings ?? []) {
     process.stderr.write(`  warning: ${w}\n`);
@@ -331,10 +385,15 @@ export async function cmdViewDraft(rest) {
   let fix = false;
   let lintOnly = false;
   let asJson = false;
+  // Converted slides only: promote the dialect lint's warnings (an empty
+  // title/body placeholder) to errors.
+  let strict = false;
   for (let i = 0; i < passthrough.length; i++) {
     const a = passthrough[i];
     if (a === "--fix") {
       fix = true;
+    } else if (a === "--strict") {
+      strict = true;
     } else if (a === "--lint-only") {
       lintOnly = true;
     } else if (a === "--json") {
@@ -399,7 +458,9 @@ export async function cmdViewDraft(rest) {
       );
     }
   }
-  await buildDeck(deckDir);
+  // Advisory here: the converted rules print as warnings while slides are
+  // still being edited, and block at `review` / `build-pptx`. --strict gates now.
+  await buildDeck(deckDir, { strict, enforceConverted: strict });
   if (lintOnly) {
     if (asJson) process.stdout.write(`${JSON.stringify({ deck: path.basename(deckDir), lint: "clean" })}\n`);
     else process.stdout.write("Lint clean (no render — drop --lint-only for the draft previews).\n");

package/src/cli/help.mjs

@@ -63,6 +63,7 @@ export function printHelp(cmd = null) {
       `                                     --out <path>    output path (default <deck>/<deck>.pptx)\n` +
       `                                     --force         discard manual PowerPoint edits instead of reconciling them\n` +
       `                                     --json          machine-readable result\n` +
+      `                                     (writes per-slide PNGs of the built deck to <deck>/.build-preview/)\n` +
       `  slidemind inspect-template-deck <deck>  Inspect a template deck as JSON for pack-owned validation\n` +
       `                                     --pack <dir>   explicit template-pack directory (required)\n` +
       `                                     --allow-unrendered-freeform  include JSX inserts without .pptx artifacts\n` +
@@ -76,6 +77,7 @@ export function printHelp(cmd = null) {
       `                                     --only <file|N>[,…]  render just these slides (a per-slide builder's own check)\n` +
       `                                     --fix           apply the deterministic lint autofixes first\n` +
       `                                     --lint-only     lint + HTML build, no render (fast fix loop)\n` +
+      `                                     --strict        converted slides: gate here like review does (they only warn by default)\n` +
       `                                     --no-translate  skip the export gate (purely local check)\n` +
       `                                     --translate     insist on the export gate (fail instead of skipping when the backend is unreachable)\n` +
       `                                     --json          machine-readable result (slides, defects, reviewCanOpen)\n` +
@@ -144,6 +146,9 @@ export function printHelp(cmd = null) {
       `                                     --out <name>    file name under assets/ (default imagen-N.png)\n` +
       `                                     --size <s>      auto|1024x1024|1536x1024|1024x1536 (default auto)\n` +
       `                                     --quality <q>   low|medium|high|auto\n` +
+      `                                     --into <slide>  place it in this slide file instead of only writing the asset\n` +
+      `                                     --behind <id>   ... as a background div right before data-sm-source-id={id} (takes its rect)\n` +
+      `                                     --rect <l,t,w,h>  ... at this rect in px instead\n` +
       `  slidemind download-bundle [deck] Materialize or refresh a corporate design's bundle locally\n` +
       `                                     (pane-free for a bound deck, --brand or --all — no PowerPoint needed)\n` +
       `                                     --to <presId>   target a specific window (forces the pane route)\n` +

package/src/lib/adopt.mjs

@@ -30,7 +30,14 @@ 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 { hasSourcedChart, writeConversionRecord } from "./conversions.mjs";
+import { writeConversionRecord } from "./conversions.mjs";
+
+// Converted JSX needs a fresh baseline against the imported PPTX. Source tags
+// alone cannot recover the original conversion evidence or preserved natives.
+export function needsConversion(decoded) {
+  return !decoded || /<ConvertedHost\d+x\d+\b/.test(decoded.jsx) ||
+    /^\s*\/\/\s*SLIDEMIND_DIALECT:\s*converted\b/m.test(decoded.jsx);
+}
 
 export const LIVE_DECK_UNSUPPORTED =
   "conversion of live presentations requires the add-in path in v1 — " +
@@ -174,21 +181,13 @@ export function adoptDeckFromPptx({ pptxPath, deckDir, converted = null, source
   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. Three kinds of pick share the pass — a slide
-  // that stays native, a CONVERTED slide whose preserved natives (OLE /
-  // SmartArt / unsupported chart kinds) need their verbatim source package kept
-  // for the render-time splice (design D4/D6), and a converted slide carrying
-  // the deck's own chart as `<Chart data-sm-source-id>`, which the render
-  // patches against that same package (native-charts 5.4a).
+  // Fold every converted slide in one pass. The package supplies preserved
+  // natives AND the original envelope (layouts, passive third-party tags,
+  // relationships). Tagged converted JSX alone cannot restore either safely.
   const picks = [];
   decodedByIndex.forEach((decoded, index) => {
-    if (decoded) return;
-    const conv = convertedSlides.get(index + 1);
-    if (!conv || conv.preserved?.length > 0 || hasSourcedChart(conv.jsx)) {
-      picks.push(index + 1);
-    }
+    if (!needsConversion(decoded)) return;
+    picks.push(index + 1);
   });
   const foldByPick = new Map(
     (picks.length
@@ -229,7 +228,7 @@ export function adoptDeckFromPptx({ pptxPath, deckDir, converted = null, source
   }
 
   decodedByIndex.forEach((decoded, index) => {
-    if (decoded) {
+    if (decoded && !needsConversion(decoded)) {
       const stem = stemFor(decoded.meta.name, index, taken);
       let jsx = decoded.jsx;
       for (const asset of decoded.assets) {
@@ -251,11 +250,14 @@ export function adoptDeckFromPptx({ pptxPath, deckDir, converted = null, source
     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);
+      const stem = stemFor(decoded?.meta.name ?? 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();
+      const candidateGuid = decoded?.guid ?? conv.guid;
+      const owns = !decoded || ownerIndexByGuid.get(decoded.guid)?.index === index;
+      const guid = owns && candidateGuid && !seenGuids.has(candidateGuid)
+        ? candidateGuid : mintSlideGuid();
       seenGuids.add(guid);
       guids[`slides/${stem}.jsx`] = slideGuidEntry(guid, jsx);
       writeConversionRecord(
@@ -277,6 +279,7 @@ export function adoptDeckFromPptx({ pptxPath, deckDir, converted = null, source
         },
         fold?.bytes ?? null,
       );
+      bundle ??= decoded?.meta.bundle ?? null;
       convertedFiles.push(`${stem}.jsx`);
       return;
     }
@@ -329,7 +332,10 @@ export function adoptDeckFromPptx({ pptxPath, deckDir, converted = null, source
 }
 
 /**
- * Deterministically convert a FILE deck's untagged slides through the add-in's
+ * Convert foreign slides and re-convert embedded converted slides against the
+ * CURRENT imported PPTX. This recovers a fresh baseline/evidence pair without
+ * pretending the original conversion was reviewed. Ordinary authored JSX is
+ * restored verbatim. Requests go 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
@@ -349,7 +355,7 @@ export async function convertUntaggedSlides({
   const { buffer, decodedByIndex } = source ?? readSourceDeck(pptxPath);
   const slides = [];
   decodedByIndex.forEach((decoded, i) => {
-    if (!decoded) slides.push(i + 1);
+    if (needsConversion(decoded)) slides.push(i + 1);
   });
   if (slides.length === 0) return null;
 
@@ -372,7 +378,7 @@ export async function convertUntaggedSlides({
     if (brands.length !== 1) {
       note(
         brands.length === 0
-          ? "no corporate design available to convert against — untagged slides stay native"
+          ? "no corporate design available to convert against — slides requiring conversion stay native"
           : "several corporate designs available — pass `--brand <presFP>` to convert the untagged slides",
       );
       return null;
@@ -383,7 +389,7 @@ export async function convertUntaggedSlides({
     // 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");
+      note("this add-in does not convert foreign slides — slides requiring conversion stay native");
       return null;
     }
   }
@@ -396,15 +402,15 @@ export async function convertUntaggedSlides({
       backendURL,
     });
     if (result?.ok === false) {
-      note("the add-in declined to convert this file — untagged slides stay native");
+      note("the add-in declined to convert this file — slides requiring conversion 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`,
+        ? "this add-in does not convert foreign slides — slides requiring conversion stay native"
+        : `slide conversion unavailable (${err?.message ?? err}) — slides requiring conversion stay native`,
     );
     return null;
   }