slidemind 0.3.17 → 0.3.19

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 };
+}