slidemind 0.3.18 → 0.3.19

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "slidemind",
-  "version": "0.3.18",
+  "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.18",
+  "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.18",
+  "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` +
-      `export default 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/conversions.mjs

@@ -281,3 +281,111 @@ export function conversionsMissingPreserveSource(conversions, deckDir = null) {
     .filter(([file, c]) => needsPackage(file, c) && !c.preserveSource)
     .map(([file]) => file);
 }
+
+/**
+ * Preview stand-ins for the ConvertedHost layouts a deck's converted slides
+ * invoke: `{ "<HostName>.jsx": "<source>" }`, the shape both preview paths want
+ * (the HTML build inlines them as jsx-templates, the local capture engine takes
+ * them as bundle layouts). The host's name carries its canvas
+ * (`ConvertedHost<cx>x<cy>`, EMU), so the stub sizes itself the way the minted
+ * host does instead of assuming 16:9 — a 4:3 source previews at 960x720.
+ * Real geometry still comes from the server render.
+ *
+ * The `// PLACEHOLDERS:` line is not decoration: the capture engine builds its
+ * layout registry from exactly that contract and refuses any component without
+ * one ("unsupported layout contract: … (available: …)"). Two fields carry
+ * weight —
+ *   • `nativeLayoutName` must be a non-empty string or the entry is dropped
+ *     from the registry entirely. It names the HOST ITSELF here: a converted
+ *     slide never rides a brand layout (it renders server-side from its
+ *     conversion record, and viewDraft keeps it out of the translate gate), so
+ *     naming a real one would be a lie the CLI cannot check;
+ *   • `content` must be non-null or the engine treats the slide as a
+ *     purpose-built layout with no freeform region and captures NO image —
+ *     which is exactly the "no freeform slides to capture" dead end. Its
+ *     selector defaults to `.slide-content__area`, so the stub carries that
+ *     class, and its areas (in points, EMU/12700) are the whole canvas,
+ *     because on a converted slide every shape is content.
+ */
+const HOST_NAME_RE = /<(ConvertedHost(\d+)x(\d+))/;
+const emuToCssPx = (emu) => `${Math.round((Number(emu) / 9525) * 1000) / 1000}px`;
+const emuToPt = (emu) => Math.round((Number(emu) / 12700) * 1000) / 1000;
+
+export function convertedHostLayouts(deckDir, conversions) {
+  const out = {};
+  for (const file of Object.keys(conversions).sort()) {
+    let src;
+    try {
+      src = fs.readFileSync(path.join(deckDir, "slides", file), "utf8");
+    } catch {
+      continue;
+    }
+    const m = HOST_NAME_RE.exec(src);
+    if (!m || out[`${m[1]}.jsx`]) continue;
+    const contract = {
+      nativeLayoutName: m[1],
+      chrome: [],
+      content: {
+        type: "obj",
+        idx: null,
+        areas: [{ left: 0, top: 0, right: emuToPt(m[2]), bottom: emuToPt(m[3]) }],
+      },
+    };
+    out[`${m[1]}.jsx`] =
+      `// Preview stand-in for a converted slide's host — the server mints the real one.\n` +
+      `// PLACEHOLDERS: ${JSON.stringify(contract)}\n\n` +
+      `export default function ${m[1]}({ background, children }) { return <div className="slide-content__area" style={{ position: "relative", width: "${emuToCssPx(m[2])}", height: "${emuToCssPx(m[3])}", overflow: "hidden", background: background || "#FFFFFF" }}>{children}</div>; }\n`;
+  }
+  return out;
+}
+
+/**
+ * Every way a deck's conversion records can lie about their source, as
+ * user-facing lines. Two hand-renamed slides shipped on the WRONG master
+ * layout because their record pointed at a package file that no longer
+ * existed: loadConversions simply sent no package, the server fell back to a
+ * default layout, and the mismatch only surfaced as a post-build warning.
+ *
+ * Read from disk (not from the loaded entries) so the wire body stays exactly
+ * what the render route expects — these are checks, not payload.
+ *
+ * Covers: a `source.package` that is set but missing; a `record.slide` that no
+ * longer names its own file (a hand rename); and preserved natives / a sourced
+ * chart with no package at all.
+ */
+export function conversionIntegrityErrors(deckDir, conversions) {
+  const dir = conversionsDir(deckDir);
+  const errors = [];
+  for (const file of Object.keys(conversions).sort()) {
+    const stem = stemOf(file);
+    let record;
+    try {
+      record = JSON.parse(fs.readFileSync(path.join(dir, `${stem}.json`), "utf8"));
+    } catch {
+      continue; // unreadable record — loadConversions already skipped it
+    }
+    const packageName = record.source?.package
+      ? path.basename(record.source.package)
+      : null;
+    if (packageName && !fs.existsSync(path.join(dir, packageName))) {
+      errors.push(
+        `${file}: its conversion record points at ${CONVERSIONS_DIR}/${packageName}, which does not ` +
+          `exist — the slide would render on a fallback layout. Re-run 'slidemind adopt' for this deck.`,
+      );
+    }
+    if (record.slide && record.slide !== `slides/${stem}.jsx`) {
+      errors.push(
+        `${file}: its conversion record still claims "slide": "${record.slide}" — the file was renamed ` +
+          `by hand. Rename it back, or re-run 'slidemind adopt' (a plan-driven reorder belongs to ` +
+          `'proposal-plan renumber', which moves the jsx, the brief, the record and the GUID together).`,
+      );
+    }
+  }
+  for (const file of conversionsMissingPreserveSource(conversions, deckDir)) {
+    errors.push(
+      `${file}: it has preserved native objects or a sourced chart but no ${CONVERSIONS_DIR}/*.slide.pptx ` +
+        `to read them from — re-run 'slidemind adopt' for this deck.`,
+    );
+  }
+  return errors;
+}

package/src/lib/jsx-insert.mjs

@@ -0,0 +1,115 @@
+// Put a generated picture INTO a slide, not just next to it.
+//
+// `slidemind imagen` wrote assets/imagen-N.png and left the agent to wire it
+// up by hand — which is where it went wrong: the image was dropped onto the
+// wrong element, or on top of the text that was supposed to sit over it. The
+// picture belongs in one specific place: a plain absolute div, at a known
+// rect, immediately BEFORE the element it should paint behind.
+
+// Find the open tag that carries `data-sm-source-id={<id>}` — the converted
+// dialect's stable handle on a source shape. Returns { start, tag } or null.
+function findSourceIdTag(source, id) {
+  const marker = new RegExp(`\\sdata-sm-source-id=\\{${Number(id)}\\}`);
+  const hit = marker.exec(source);
+  if (!hit) return null;
+  const start = source.lastIndexOf("<", hit.index);
+  if (start < 0) return null;
+  let depth = 0;
+  let quote = null;
+  let i = start;
+  for (; i < source.length; i++) {
+    const c = source[i];
+    if (quote) {
+      if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'") quote = c;
+    else if (c === "{") depth++;
+    else if (c === "}") depth--;
+    else if (c === ">" && depth === 0) break;
+  }
+  return { start, tag: source.slice(start, i + 1) };
+}
+
+const styleProp = (tag, prop) =>
+  new RegExp(`\\b${prop}:\\s*"([^"]*)"`).exec(tag)?.[1] ?? null;
+
+function imageDiv({ url, left, top, width, height }) {
+  return (
+    `<div style={{ position: "absolute", left: "${left}", top: "${top}", ` +
+    `width: "${width}", height: "${height}", backgroundImage: "url(${url})", ` +
+    `backgroundSize: "cover", backgroundPosition: "center" }} />`
+  );
+}
+
+/**
+ * Insert a background-image div into a slide's JSX.
+ *
+ * `behind`: the data-sm-source-id of the element to paint under — the div
+ * takes that element's own rect and is inserted immediately before it, so an
+ * overlay keeps sitting on top. `rect` ({left, top, width, height} in px)
+ * overrides that geometry, and on its own appends the div at the end of the
+ * article.
+ *
+ * Throws rather than guessing: a picture in the wrong element is exactly the
+ * defect this replaces. Never writes inside a preserved native object — that
+ * subtree is spliced back verbatim from the source package on every render, so
+ * anything added there is silently dropped.
+ */
+export function insertImageDiv(source, { url, behind = null, rect = null }) {
+  if (!url) throw new Error("insertImageDiv: url is required");
+  if (behind == null && !rect) {
+    throw new Error("insertImageDiv: pass behind (a data-sm-source-id) or rect");
+  }
+  const px = (v) => (/px$/.test(String(v)) ? String(v) : `${Number(v)}px`);
+
+  if (behind != null) {
+    const target = findSourceIdTag(source, behind);
+    if (!target) {
+      throw new Error(`no element with data-sm-source-id={${behind}} in this slide`);
+    }
+    if (/data-sm-native-object|sm-native-object-/.test(target.tag)) {
+      throw new Error(
+        `data-sm-source-id={${behind}} is a preserved native object — it is spliced back ` +
+          `from the source package on every render, so anything inserted there is lost. ` +
+          `Pick a different source id, or place the picture with --rect.`,
+      );
+    }
+    const geom = rect ?? {
+      left: styleProp(target.tag, "left"),
+      top: styleProp(target.tag, "top"),
+      width: styleProp(target.tag, "width"),
+      height: styleProp(target.tag, "height"),
+    };
+    if (!geom.left || !geom.top || !geom.width || !geom.height) {
+      throw new Error(
+        `the element with data-sm-source-id={${behind}} has no absolute rect to copy — pass --rect`,
+      );
+    }
+    const lineStart = source.lastIndexOf("\n", target.start) + 1;
+    const indent = source.slice(lineStart, target.start);
+    const div = imageDiv({
+      url,
+      left: px(geom.left),
+      top: px(geom.top),
+      width: px(geom.width),
+      height: px(geom.height),
+    });
+    return source.slice(0, lineStart) + `${indent}${div}\n` + source.slice(lineStart);
+  }
+
+  const close = source.lastIndexOf("</article>");
+  if (close < 0) {
+    throw new Error("no </article> in this slide — pass --behind <source-id> instead");
+  }
+  const lineStart = source.lastIndexOf("\n", close) + 1;
+  const indent = `${source.slice(lineStart, close)}\t`;
+  const div = imageDiv({
+    url,
+    left: px(rect.left),
+    top: px(rect.top),
+    width: px(rect.width),
+    height: px(rect.height),
+  });
+  return source.slice(0, lineStart) + `${indent}${div}\n` + source.slice(lineStart);
+}

package/src/lib/lint-converted.mjs

@@ -0,0 +1,433 @@
+// Lint for the CONVERTED dialect (`slidemind adopt`) — the slides the bundle's
+// lint engine cannot see.
+//
+// A converted slide invokes a server-minted ConvertedHost layout, so the
+// add-in's capability-table lint rejects it as an unregistered layout and
+// src/builders/build.mjs skips it. That left the authored half of an adopted
+// deck completely unchecked, and a real proposal shipped with the master's
+// prompt text still in it ("[Action title …]", "xxx", "adjust footer"), a
+// sentence written into the slide-number field frame, and 12pt bold body copy
+// spilling out of fixed `noAutofit` boxes.
+//
+// These four rules are the ones that would have caught that, and they are
+// structural — they read the dialect's own attributes (data-sm-text-frame,
+// data-sm-para, data-sm-rpr, data-sm-field), not the brand.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { estimateLines } from "./text-fit.mjs";
+
+const PT_TO_PX = 96 / 72;
+
+// Master prompts that must never survive into a delivered slide. Bracketed
+// text ("[Commercial summary …]", "[First Name]") is caught by shape; these
+// are the bare ones that are not.
+const PROMPT_LITERALS = new Set([
+  "xxx",
+  "adjust footer",
+  "illustration",
+  "3 wp template",
+]);
+const BRACKETED = /^\s*\[.+\]\s*$/s;
+const isPromptText = (text) => {
+  const trimmed = String(text ?? "").trim();
+  return Boolean(trimmed) && (BRACKETED.test(trimmed) || PROMPT_LITERALS.has(trimmed.toLowerCase()));
+};
+
+// A field frame holds a slide number or a date — a handful of characters. Any
+// more is an agent that mistook it for a text box.
+const FIELD_TEXT_MAX = 40;
+
+// Placeholder types worth reporting empty. An unfilled title or body is a
+// slide that lost its message; every other type (sldNum, ftr, dt, pic, …) is
+// chrome the master owns.
+const CONTENT_PLACEHOLDERS = new Set(["title", "ctrTitle", "body", "subTitle"]);
+
+// Older conversions carry no data-sm-ph, so the frame's GEOMETRY has to stand
+// in for it: the action-title band across the top of the content width, or the
+// thin kicker line above it. Without this the rule fired on every empty text
+// box on a library reference slide — 25 of them on one deck, none actionable.
+const CANVAS_DEFAULT_W = 1280;
+function looksLikeTitleFrame(node, canvasWidth) {
+  const top = px(styleProp(node, "top"));
+  const width = px(styleProp(node, "width"));
+  const height = px(styleProp(node, "height"));
+  if (top > 60 || width < canvasWidth * 0.4) return false;
+  return height >= 60 || (height >= 10 && height <= 30);
+}
+
+// ---------------------------------------------------------------------------
+// A very small JSX reader. The converted dialect is machine-generated and
+// well-formed (every element self-closes or has a matching close tag), so a
+// tag scanner that understands quoted attribute values and `{…}` expressions
+// is enough — no parser dependency.
+// ponytail: a `<` inside slide text (`{"a <b"}`) would read as a tag; add a
+// real parser if that ever shows up.
+
+function* scanTags(src) {
+  for (let i = 0; i < src.length; i++) {
+    if (src[i] !== "<") continue;
+    const head = /^<(\/?)([A-Za-z][\w.:-]*)/.exec(src.slice(i, i + 64));
+    if (!head) continue;
+    let j = i + head[0].length;
+    let depth = 0;
+    let quote = null;
+    for (; j < src.length; j++) {
+      const c = src[j];
+      if (quote) {
+        if (c === quote) quote = null;
+        continue;
+      }
+      if (c === '"' || c === "'") quote = c;
+      else if (c === "{") depth++;
+      else if (c === "}") depth--;
+      else if (c === ">" && depth === 0) break;
+    }
+    const raw = src.slice(i, j + 1);
+    yield {
+      close: head[1] === "/",
+      name: head[2],
+      raw,
+      selfClose: raw.endsWith("/>"),
+      start: i,
+      end: j + 1,
+    };
+    i = j;
+  }
+}
+
+// Element tree. Each node keeps its open tag (`raw`) and its inner source.
+function parseJsx(src) {
+  const root = { name: "#root", raw: "", contentStart: 0, children: [] };
+  const stack = [root];
+  for (const t of scanTags(src)) {
+    if (t.close) {
+      if (stack.length > 1) {
+        const node = stack.pop();
+        node.inner = src.slice(node.contentStart, t.start);
+      }
+      continue;
+    }
+    const node = {
+      name: t.name,
+      raw: t.raw,
+      start: t.start,
+      contentStart: t.end,
+      inner: "",
+      children: [],
+    };
+    stack[stack.length - 1].children.push(node);
+    if (!t.selfClose) stack.push(node);
+  }
+  while (stack.length > 1) {
+    const node = stack.pop();
+    node.inner = src.slice(node.contentStart);
+  }
+  return root;
+}
+
+function* walk(node) {
+  for (const child of node.children) {
+    yield child;
+    yield* walk(child);
+  }
+}
+
+const unescapeAttr = (s) =>
+  s
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&");
+
+function attr(node, name) {
+  const m = new RegExp(`\\s${name}="([^"]*)"`).exec(node.raw);
+  return m ? unescapeAttr(m[1]) : null;
+}
+
+function jsonAttr(node, name) {
+  const raw = attr(node, name);
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+// `style={{ width: "279.685px", padding: "3px 4px", fontSize: "14pt" }}`
+function styleProp(node, prop) {
+  const m = new RegExp(`\\b${prop}:\\s*"([^"]*)"`).exec(node.raw);
+  return m ? m[1] : null;
+}
+
+const px = (value) => {
+  const n = Number.parseFloat(String(value ?? ""));
+  return Number.isFinite(n) ? n : 0;
+};
+
+// CSS shorthand, 1–4 values → { top, right, bottom, left }.
+function padding(node) {
+  const parts = (styleProp(node, "padding") ?? "0")
+    .trim()
+    .split(/\s+/)
+    .map(px);
+  const [t, r = t, b = t, l = r] = parts;
+  return { top: t, right: r, bottom: b, left: l };
+}
+
+// Slide text lives in JSX string expressions: `{"Strategy & "}`.
+const TEXT_RE = /\{\s*"((?:[^"\\]|\\.)*)"\s*\}/g;
+
+function textOf(source) {
+  let out = "";
+  for (const m of String(source ?? "").matchAll(TEXT_RE)) {
+    try {
+      out += JSON.parse(`"${m[1]}"`);
+    } catch {
+      out += m[1];
+    }
+  }
+  return out;
+}
+
+const lineAt = (src, offset) => src.slice(0, offset).split("\n").length;
+
+// ---------------------------------------------------------------------------
+
+/**
+ * Lint ONE converted slide. Returns `[{ rule, severity, line, message }]`.
+ * `strict` promotes warnings to errors.
+ */
+export function lintConvertedSource(fileName, source, { strict = false } = {}) {
+  const findings = [];
+  const add = (severity, rule, offset, message, meta = null) =>
+    findings.push({
+      rule,
+      severity: severity === "warn" && strict ? "error" : severity,
+      line: lineAt(source, offset),
+      message,
+      ...(meta ? { meta } : {}),
+    });
+
+  // (a) A master prompt that survived the authoring pass. Checked over every
+  // text expression in the file, wherever it sits.
+  for (const m of source.matchAll(TEXT_RE)) {
+    let text;
+    try {
+      text = JSON.parse(`"${m[1]}"`);
+    } catch {
+      text = m[1];
+    }
+    const trimmed = text.trim();
+    if (!trimmed) continue;
+    if (isPromptText(trimmed)) {
+      add(
+        "error",
+        "converted:prompt-literal",
+        m.index,
+        `converted:prompt-literal — ${JSON.stringify(trimmed.slice(0, 60))} is master prompt text, not content. Replace it or delete the shape.`,
+      );
+    }
+  }
+
+  const root = parseJsx(source);
+  const nodes = [...walk(root)];
+  // The host's name carries the source canvas (`ConvertedHost<cx>x<cy>`, EMU).
+  const canvasWidth =
+    Number(/<ConvertedHost(\d+)x\d+/.exec(source)?.[1] ?? 0) / 9525 || CANVAS_DEFAULT_W;
+  const frames = nodes.filter((n) => attr(n, "data-sm-text-frame") !== null);
+  // Older conversions carry no data-sm-ph at all; then an empty frame is the
+  // only signal an unfilled placeholder leaves behind.
+  const hasPlaceholderAttrs = nodes.some((n) => attr(n, "data-sm-ph") !== null);
+
+  for (const frame of frames) {
+    const ph = attr(frame, "data-sm-ph");
+    const sourceId = /data-sm-source-id=\{(\d+)\}/.exec(frame.raw)?.[1] ?? null;
+    const text = textOf(frame.inner).trim();
+    const paras = [...walk(frame)].filter((n) => attr(n, "data-sm-para") !== null);
+
+    // (b) An empty title/body placeholder — a slide that lost its headline.
+    const isContentPlaceholder = ph
+      ? CONTENT_PLACEHOLDERS.has(ph.split(":")[0])
+      : !hasPlaceholderAttrs &&
+        /<br data-sm-pad=""\s*\/>/.test(frame.inner) &&
+        looksLikeTitleFrame(frame, canvasWidth);
+    if (isContentPlaceholder && !text) {
+      add(
+        "warn",
+        "converted:empty-placeholder",
+        frame.start,
+        `converted:empty-placeholder — ${ph ? `the ${ph} frame` : "the action-title frame"}${sourceId ? ` (data-sm-source-id={${sourceId}})` : ""} has no text. Fill it or remove the shape.`,
+      );
+    }
+
+    // (c) A field frame (slide number, date, footer) is not a text box.
+    for (const para of paras) {
+      const runs = [...walk(para)].filter(
+        (n) => attr(n, "data-sm-rpr") !== null || attr(n, "data-sm-field") !== null,
+      );
+      const fieldRuns = runs.filter((n) => attr(n, "data-sm-field") !== null);
+      if (fieldRuns.length === 0) continue;
+      const field = attr(fieldRuns[0], "data-sm-field");
+      const extra = runs
+        .filter((n) => attr(n, "data-sm-field") === null)
+        .map((n) => textOf(n.inner))
+        .join("")
+        .trim();
+      const fieldText = textOf(para.inner).trim();
+      if (extra) {
+        add(
+          "error",
+          "converted:field-frame-text",
+          para.start,
+          `converted:field-frame-text — ${JSON.stringify(extra.slice(0, 60))} was written into the ${field} field frame. Field frames render the ${field}; put the copy in a real text box.`,
+        );
+      } else if (fieldText.length > FIELD_TEXT_MAX) {
+        add(
+          "error",
+          "converted:field-frame-text",
+          para.start,
+          `converted:field-frame-text — the ${field} field frame holds ${fieldText.length} characters (max ${FIELD_TEXT_MAX}). Field frames render the ${field}, not copy.`,
+        );
+      }
+    }
+
+    // (d) Text fit. `normAutofit` shrinks the copy to the shape, so only it is
+    // exempt: `noAutofit` spills, and `spAutoFit` only re-grows the shape when
+    // PowerPoint re-lays the text out, which an edit to the jsx never triggers.
+    // A frame still holding master prompt text is judged by rule (a), not here —
+    // the fit of a prompt says nothing about the fit of the copy replacing it.
+    const meta = jsonAttr(frame, "data-sm-text-frame");
+    if (!meta || meta.autofit === "normAutofit" || !text) continue;
+    if ([...frame.inner.matchAll(TEXT_RE)].some((m) => isPromptText(textOf(m[0])))) continue;
+    const pad = padding(frame);
+    const innerWidth = px(styleProp(frame, "width")) - pad.left - pad.right;
+    // Height is the SHAPE's, not the inset box's: PowerPoint lets text bleed
+    // into the vertical insets, and a master's thin label frames (a 13px box
+    // with 10px of padding) are drawn that way on purpose.
+    const frameHeight = px(styleProp(frame, "height"));
+    if (!(innerWidth > 0) || !(frameHeight > 0)) continue;
+    // `wrap: "none"` shapes never break a line — the text runs on past the
+    // shape edge, which is a width problem this rule does not judge.
+    const wraps = meta.wrap !== "none";
+
+    // A trailing empty paragraph (PowerPoint's endParaRPr carrier) takes a line
+    // but pushes nothing out of view — it is not an overflow.
+    const fitParas = [...paras];
+    while (fitParas.length > 0 && !textOf(fitParas[fitParas.length - 1].inner).trim()) {
+      fitParas.pop();
+    }
+    let used = 0;
+    let lines = 0;
+    let authored = 0;
+    let firstLeading = 0;
+    fitParas.forEach((para, i) => {
+      const runs = [...walk(para)].filter((n) => attr(n, "data-sm-rpr") !== null);
+      const rprs = runs.map((n) => jsonAttr(n, "data-sm-rpr") ?? {});
+      const pt =
+        Math.max(0, ...rprs.map((r) => px(r.sz) / 100)) ||
+        px(styleProp(para, "fontSize")) ||
+        18;
+      const bold = rprs.some((r) => r.b === true);
+      const paraMeta = jsonAttr(para, "data-sm-para") ?? {};
+      const fontPx = pt * PT_TO_PX;
+      const spacing = (spec) => {
+        if (spec?.kind === "pts") return px(spec.pts) * PT_TO_PX;
+        if (spec?.kind === "pct") return (px(spec.pct) / 100) * fontPx;
+        return 0;
+      };
+      const lineHeight =
+        paraMeta.lineSpacing?.kind === "pts"
+          ? px(paraMeta.lineSpacing.pts) * PT_TO_PX
+          : fontPx *
+            1.2 *
+            (paraMeta.lineSpacing?.kind === "pct" ? px(paraMeta.lineSpacing.pct) / 100 : 1);
+      // An explicit <br /> inside the paragraph starts a new line before wrap.
+      let paraLines = 0;
+      const segments = para.inner.split(/<br\b[^>]*\/>/);
+      for (const segment of segments) {
+        paraLines += wraps ? estimateLines(textOf(segment), pt, innerWidth, { bold }) : 1;
+      }
+      lines += paraLines;
+      authored += segments.length;
+      if (i === 0) firstLeading = Math.max(0, lineHeight - fontPx);
+      // PowerPoint hangs the first paragraph's space-before and the last one's
+      // space-after outside the visible stack — counting them flagged every
+      // tight one-line box in a pristine master.
+      used +=
+        (i === 0 ? 0 : spacing(paraMeta.spaceBefore)) +
+        paraLines * lineHeight +
+        (i === fitParas.length - 1 ? 0 : spacing(paraMeta.spaceAfter));
+    });
+    // Half-leading above the first line and below the last is air, not ink: a
+    // master's boxes routinely hug the cap height of a single line.
+    used = Math.max(0, used - firstLeading);
+    // Only text that WRAPS past the lines the author wrote is an overflow. A
+    // short stack in a box that was always too small for it (a master's three
+    // one-word bullets in a two-line placeholder) is the source deck's own
+    // layout, and PowerPoint has drawn it that way from the start.
+    if (used > frameHeight + 2 && lines > authored) {
+      add(
+        "error",
+        "converted:overflow",
+        frame.start,
+        `converted:overflow — ${lines} line${lines === 1 ? "" : "s"} / ${Math.round(used)}px into ${Math.round(frameHeight)}px` +
+          `${sourceId ? ` (data-sm-source-id={${sourceId}})` : ""}. The text wraps past the ${authored} line${authored === 1 ? "" : "s"} it was written as: shorten it or grow the shape.`,
+        { lines, authored, used: Math.round(used), height: Math.round(frameHeight) },
+      );
+    }
+  }
+
+  findings.sort((a, b) => a.line - b.line);
+  return findings;
+}
+
+/**
+ * Lint a deck's converted slides, in the bundle lint's vocabulary
+ * (`[lint:error] file:line — …`).
+ *
+ * `enforce` is the difference between looking and shipping: `view-draft` runs
+ * it advisory (every finding prints as a warning, nothing throws) because the
+ * main lane previews slides while they are still half-authored, and a raw
+ * adopted master must be viewable. `review` and the render path enforce, so a
+ * deck still carrying master prompts cannot ship. `--strict` makes view-draft
+ * enforce too, and promotes the empty-placeholder warning to an error.
+ */
+export function lintConvertedOrThrow({ slideFiles, strict = false, enforce = true }) {
+  const lines = [];
+  let errors = 0;
+  let warnings = 0;
+  for (const file of slideFiles) {
+    const fileName = path.basename(file);
+    let findings;
+    try {
+      findings = lintConvertedSource(fileName, fs.readFileSync(file, "utf8"), { strict });
+    } catch {
+      continue; // unreadable slide — the build reports that on its own
+    }
+    for (const f of findings) {
+      if (f.severity === "error") errors++;
+      else warnings++;
+      const shown = enforce ? f.severity : "warn";
+      lines.push(`  [lint:${shown}] ${fileName}:${f.line} — ${f.message}`);
+    }
+  }
+  for (const line of lines) process.stderr.write(`${line}\n`);
+  if (errors > 0 && !enforce) {
+    process.stderr.write(
+      `  [lint:note] ${errors} converted-slide finding${errors === 1 ? "" : "s"} above ` +
+        `will block 'slidemind review' and 'build-pptx' until fixed\n`,
+    );
+  }
+  if (errors > 0 && enforce) {
+    throw new Error(
+      `converted slide lint: ${errors} error${errors === 1 ? "" : "s"}` +
+        (warnings ? `, ${warnings} warning${warnings === 1 ? "" : "s"}` : "") +
+        `\n${lines.join("\n")}`,
+    );
+  }
+  return { ok: errors === 0, errors, warnings, lines };
+}

package/src/lib/text-fit.mjs

@@ -0,0 +1,94 @@
+// How much room does this text actually need? — the cheap half of a fit check.
+//
+// Converted slides (`slidemind adopt`) keep PowerPoint's fixed text boxes:
+// `autofit: "noAutofit"` means the box does NOT grow and PowerPoint does NOT
+// shrink the text — an over-long line simply spills out of the shape and ships
+// that way. Nothing in the local toolchain measured it, so 12pt bold overflow
+// reached a delivered deck.
+//
+// Real measurement needs a browser; this is Arial's advance-width table
+// instead (1000 units/em, the AFM metrics Arial shares with Helvetica), which
+// is exact for the master's Arial runs and close enough elsewhere to catch a
+// line that is 30% too long. ponytail: regular-weight table × a flat bold
+// factor; swap in per-face metrics if a non-Arial brand ever adopts.
+
+const PT_TO_PX = 96 / 72;
+
+// prettier-ignore
+const W = {
+  " ": 278, "!": 278, '"': 355, "#": 556, $: 556, "%": 889, "&": 667, "'": 191,
+  "(": 333, ")": 333, "*": 389, "+": 584, ",": 278, "-": 333, ".": 278, "/": 278,
+  0: 556, 1: 556, 2: 556, 3: 556, 4: 556, 5: 556, 6: 556, 7: 556, 8: 556, 9: 556,
+  ":": 278, ";": 278, "<": 584, "=": 584, ">": 584, "?": 556, "@": 1015,
+  A: 667, B: 667, C: 722, D: 722, E: 667, F: 611, G: 778, H: 722, I: 278, J: 500,
+  K: 667, L: 556, M: 833, N: 722, O: 778, P: 667, Q: 778, R: 722, S: 667, T: 611,
+  U: 722, V: 667, W: 944, X: 667, Y: 667, Z: 611,
+  "[": 278, "\\": 278, "]": 278, "^": 469, _: 556, "`": 333,
+  a: 556, b: 556, c: 500, d: 556, e: 556, f: 278, g: 556, h: 556, i: 222, j: 222,
+  k: 500, l: 222, m: 833, n: 556, o: 556, p: 556, q: 556, r: 333, s: 500, t: 278,
+  u: 556, v: 500, w: 722, x: 500, y: 500, z: 500,
+  "{": 334, "|": 260, "}": 334, "~": 584,
+  // Latin-1 / typographic characters the master's German and English copy uses.
+  "\u00A0": 278, "«": 556, "»": 556, "°": 400, "·": 278,
+  "×": 584, "÷": 584, "©": 737, "®": 737, "–": 556,
+  "—": 1000, "‘": 222, "’": 222, "‚": 222, "“": 333,
+  "”": 333, "„": 333, "…": 1000, "€": 556, "ß": 556,
+  "£": 556, "§": 556, "•": 350, "−": 584, "\u00AD": 333,
+};
+
+// Accented letters carry their base letter's advance in Arial (the diacritic
+// sits above the glyph box), so strip the combining marks and reuse the table.
+function widthOf(ch) {
+  const w = W[ch];
+  if (w !== undefined) return w;
+  const base = ch.normalize("NFD")[0];
+  return W[base] ?? 556;
+}
+
+/** Rendered width of `text` in px at `pt`, Arial metrics. */
+export function textWidth(text, pt, { bold = false } = {}) {
+  let units = 0;
+  for (const ch of String(text ?? "")) units += widthOf(ch);
+  return (units / 1000) * pt * PT_TO_PX * (bold ? 1.07 : 1);
+}
+
+/**
+ * How many lines `text` takes in a box `widthPx` wide — greedy word wrap, the
+ * way PowerPoint breaks (on spaces, and inside a word that cannot fit alone).
+ * Always at least 1.
+ */
+export function estimateLines(text, pt, widthPx, { bold = false } = {}) {
+  const str = String(text ?? "");
+  if (!str.trim()) return 1;
+  if (!(widthPx > 0)) return 1;
+  const opts = { bold };
+  let lines = 1;
+  let used = 0;
+  for (const word of str.split(/(\s+)/)) {
+    if (!word) continue;
+    const w = textWidth(word, pt, opts);
+    if (/^\s+$/.test(word)) {
+      // Trailing whitespace never pushes a wrap on its own.
+      used += w;
+      continue;
+    }
+    if (used > 0 && used + w > widthPx) {
+      lines++;
+      used = 0;
+    }
+    if (w > widthPx) {
+      // A single word wider than the box breaks mid-word.
+      for (const ch of word) {
+        const cw = textWidth(ch, pt, opts);
+        if (used > 0 && used + cw > widthPx) {
+          lines++;
+          used = 0;
+        }
+        used += cw;
+      }
+      continue;
+    }
+    used += w;
+  }
+  return lines;
+}