slidemind 0.3.20 → 0.4.0

package/src/builders/image-intent-check.mjs

@@ -0,0 +1,308 @@
+// Image-intent evidence, CLI side — the local half of design decision 7.
+//
+// Three questions, and only three, because the other half of the answer is the
+// add-in's:
+//
+//   1. **Are the sources still there?** Every `original` use resolves to bytes
+//      on disk that still hash to what the registry recorded. Purely local, so
+//      it runs host-free in `view-draft` and again before any render.
+//   2. **Did the slide actually place them?** Counted off the CAPTURED boxes
+//      (`box.assetUseId`, set by the add-in's DOM serialiser from
+//      `data-asset-use`), never off the .jsx text: a use id in a comment, in a
+//      prop the helper never forwards, or beside an unused file is not
+//      fulfillment (guide §6, A20). The transcriber emits `use="…"` as a helper
+//      prop, so a text scan would not even find the real bindings.
+//   3. **Did the server validate?** The verdict is the add-in's
+//      `imageIntentValidation`, consumed verbatim. This module measures no
+//      geometry, no crop, no visible intersection — those are renderer rules
+//      and they live where the renderer lives (AGENTS.md: "No CLI fallbacks for
+//      add-in-owned rules").
+//
+// The asymmetry between the two consumers is deliberate:
+//
+//   * `view-draft` REPORTS. A missing source or an unplaced use is an
+//     actionable repair issue printed next to the preview, recorded as a draft
+//     defect so `review` holds — but the preview is still written, because
+//     looking at the slide is how the repair gets made.
+//   * `build-pptx` / `push` REFUSE. An unresolved obligation, a failed verdict,
+//     or a verdict that never ran all stop the build before any .pptx exists.
+//     "The validation was skipped" is NEVER success: the export gate next door
+//     may degrade to a note when the backend is unreachable, and this one may
+//     not — a skipped picture check ships a deck missing the user's picture.
+
+import { resolveBoundImageUses } from "./spec-assets.mjs";
+
+/** The slide number a deck file name carries, or null (unnumbered file). */
+export function slideNumberOf(fileName) {
+  const m = /^(\d{1,3})[-_.]/.exec(String(fileName ?? ""));
+  return m ? Number(m[1]) : null;
+}
+
+/** The distinct slide numbers a set of deck file names covers, ascending. */
+export function slideNumbersOf(fileNames) {
+  const out = [];
+  for (const file of fileNames ?? []) {
+    const n = slideNumberOf(file);
+    if (n !== null && !out.includes(n)) out.push(n);
+  }
+  return out.sort((a, b) => a - b);
+}
+
+const stemOf = (fileName) => String(fileName ?? "").replace(/\.[^.]+$/, "");
+
+/** One issue as a printable draft line. */
+export function formatIssue(issue) {
+  const where = issue.file ? stemOf(issue.file) : issue.slide ? `slide ${issue.slide}` : "deck";
+  const action = issue.action ? ` ${issue.action}` : "";
+  return `[image-intent:error] ${where} — ${issue.message}.${action}`;
+}
+
+// ---------------------------------------------------------------------------
+// 1 + 2: what this machine can answer
+// ---------------------------------------------------------------------------
+
+/** Every `assetUseId` the captured render actually placed: `Map<useId, count>`. */
+export function capturedUseIds(render) {
+  const counts = new Map();
+  const walk = (box) => {
+    if (!box || typeof box !== "object") return;
+    if (typeof box.assetUseId === "string" && box.assetUseId) {
+      counts.set(box.assetUseId, (counts.get(box.assetUseId) ?? 0) + 1);
+    }
+    for (const child of box.children ?? []) walk(child);
+  };
+  for (const box of render?.boxes ?? []) walk(box);
+  return counts;
+}
+
+/**
+ * Local image-intent issues for a set of captured slides.
+ *
+ * @param {string} deckDir
+ * @param {Array<{fileName: string, status?: string, render?: object}>} slides
+ *   the `view-draft` slide records — `render` present means the slide was
+ *   captured, so its bindings can be counted; absent means only the source
+ *   half can be answered for it.
+ * @returns {{issues: Array, byFile: Map<string, Array>}}
+ */
+export function localImageIntentIssues(deckDir, slides, { planMarkdown = null } = {}) {
+  const files = (slides ?? []).map((s) => s.fileName).filter(Boolean);
+  const numbers = slideNumbersOf(files);
+  const issues = [];
+  const byFile = new Map();
+  if (!numbers.length) return { issues, byFile };
+
+  const fileForSlide = new Map();
+  for (const file of files) {
+    const n = slideNumberOf(file);
+    if (n !== null && !fileForSlide.has(n)) fileForSlide.set(n, file);
+  }
+  const push = (issue) => {
+    issues.push(issue);
+    const key = issue.file ?? "";
+    if (!byFile.has(key)) byFile.set(key, []);
+    byFile.get(key).push(issue);
+  };
+
+  // The source half. `resolveBoundImageUses` is the same resolver the
+  // transcriber places pictures with, so "the draft says it is missing" and
+  // "transcribe could not place it" are one answer, not two.
+  let bound;
+  let sourceIssues;
+  try {
+    ({ bound, issues: sourceIssues } = resolveBoundImageUses(deckDir, numbers, { planMarkdown }));
+  } catch (err) {
+    push({
+      code: err?.code ?? "image_intent_invalid",
+      message: `the deck's image obligations could not be read (${err?.message ?? err})`,
+      action: "Fix state/image-assets.json or state/image-use-overrides.json, then re-run.",
+      file: null,
+      slide: null,
+    });
+    return { issues, byFile };
+  }
+  for (const issue of sourceIssues) {
+    push({
+      code: issue.code,
+      message: issue.message,
+      action:
+        issue.code === "image_asset_changed"
+          ? "Re-import the new bytes as their own asset and rebind the use through the plan."
+          : "Restore or re-import the source (`slidemind assets import <deck> <file>`) and rebind the use.",
+      file: issue.slide == null ? null : fileForSlide.get(issue.slide) ?? null,
+      slide: issue.slide,
+      useId: issue.useId,
+      assetId: issue.assetId,
+    });
+  }
+
+  // The placement half, per captured slide. Only originals oblige a picture.
+  const wanted = new Map();
+  for (const use of bound.values()) {
+    if (!wanted.has(use.slide)) wanted.set(use.slide, []);
+    wanted.get(use.slide).push(use);
+  }
+  for (const slide of slides ?? []) {
+    const n = slideNumberOf(slide.fileName);
+    const expected = n === null ? null : wanted.get(n);
+    if (!expected?.length) continue;
+    // Without a captured render there is nothing to count — a native .pptx
+    // slide, or one the capture could not produce. Its evidence is the server
+    // verdict's job, not a guess made here.
+    if (!slide.render?.boxes) continue;
+    const placed = capturedUseIds(slide.render);
+    for (const use of expected) {
+      const count = placed.get(use.useId) ?? 0;
+      if (count === 1) continue;
+      push(
+        count === 0
+          ? {
+              code: "image_use_unresolved",
+              message:
+                `${use.displayName} is an approved original for this slide and the render places it nowhere ` +
+                `(no picture carries data-asset-use="${use.useId}")`,
+              action: `Place it: <img data-asset-use="${use.useId}" src="./${use.workspacePath}" /> — never a search result or a look-alike.`,
+              file: slide.fileName,
+              slide: n,
+              useId: use.useId,
+              assetId: use.assetId,
+            }
+          : {
+              code: "image_use_mismatch",
+              message:
+                `${use.displayName} is placed ${count} times on this slide; one use is one occurrence`,
+              action: "Remove the extra picture, or record a second use in the plan for the intended repeat.",
+              file: slide.fileName,
+              slide: n,
+              useId: use.useId,
+              assetId: use.assetId,
+            },
+      );
+    }
+  }
+  return { issues, byFile };
+}
+
+/** `Map<fileName, string[]>` of printable draft lines, deck-level under "". */
+export function draftImageIntentLines(deckDir, slides, opts = {}) {
+  const { byFile } = localImageIntentIssues(deckDir, slides, opts);
+  const out = new Map();
+  for (const [file, issues] of byFile) out.set(file, issues.map(formatIssue));
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// 3: the server's verdict
+// ---------------------------------------------------------------------------
+
+// The request only gets this far on a backend that ADVERTISED `imageIntentV1`
+// (the capability gate in the transport refuses the rest before sending), so a
+// response with no verdict is that backend breaking its own contract — not an
+// old deployment. Either way the deck is not built: nothing proved the pictures
+// reached the slides, and a skipped check is not a pass.
+const MISSING_VERDICT =
+  "the add-in advertises image-intent support but returned no imageIntentValidation for a deck " +
+  "that carries approved image obligations, so nothing proved the pictures reached the slides. " +
+  "A check that did not run is not a pass: this deck is not built";
+
+const MISSING_VERDICT_ACTION =
+  "Report the backend version — it answers the capability but not the check. Nothing was written " +
+  "and the deck, its plan and its imported sources are exactly as they were.";
+
+/**
+ * The verdict as the CLI reads it.
+ *
+ * `ran: false` is the fail-closed case — the request carried expectations and
+ * the response carried no verdict. It is never downgraded to a warning on the
+ * final path, and the `issues` it returns say why.
+ *
+ * The wire shape (add-in `RT/image-intent-validation.ts`, agreed 2026-09-21):
+ *
+ *   {version: 1, ok, uses: [{useId, assetId, sourceSha256, slide, stem,
+ *                            pictureId, mediaPart, rect, fit, crop?, derivative?}],
+ *                issues: [{code, message, action, useId?, assetId?, slide?, stem?}]}
+ *
+ * Only `ok` and `issues` are read here. `uses` is the evidence array (named
+ * `uses`, not `checked`), its `crop` is the EMITTED `<a:srcRect>` in OOXML
+ * 100000ths rather than the contract's `{x,y,w,h}` fractions, and `derivative`
+ * carries `{sha256, parentSha256, mediaPart, transforms}` (the `renderTransforms`
+ * names of `src/lib/image-derivatives.mjs`) — three shapes
+ * worth knowing before anything starts reading them, because none is the shape
+ * the plan-side record uses.
+ *
+ * **What the verdict does and does not prove.** It compares the bytes that
+ * actually became the `ppt/media` part against the digest the request DECLARED.
+ * It cannot see this machine, so it never proves that digest still describes a
+ * file on disk — `localImageIntentIssues` above is that half. Neither alone is
+ * the whole guarantee; the build path runs both.
+ *
+ * @param {object|null} envelope the `imageIntent` the request carried
+ * @param {object|null} result the render/translate response
+ */
+export function imageIntentVerdict(envelope, result) {
+  if (!envelope) return { expected: false, ran: true, ok: true, issues: [] };
+  const verdict = result?.imageIntentValidation;
+  if (!verdict || typeof verdict !== "object") {
+    return {
+      expected: true,
+      ran: false,
+      ok: false,
+      issues: [
+        {
+          code: "image_intent_unsupported",
+          message: MISSING_VERDICT,
+          action: MISSING_VERDICT_ACTION,
+          file: null,
+          slide: null,
+        },
+      ],
+    };
+  }
+  const raw = Array.isArray(verdict.issues) ? verdict.issues : [];
+  const issues = raw.map((issue) => ({
+    code: issue?.code ?? "image_use_mismatch",
+    message: issue?.message ?? "the rendered deck did not satisfy an image obligation",
+    action: issue?.action ?? "Fix the slide's binding and re-run the build.",
+    // The add-in attributes an issue by `stem` — the `<name>` of `<name>.jsx`,
+    // which is the key it has and we have. Taking it is what puts a server
+    // issue on the right slide in the draft instead of on the deck.
+    file: issue?.file ?? (issue?.stem ? `${issue.stem}.jsx` : null),
+    slide: Number.isInteger(issue?.slide) ? issue.slide : null,
+    useId: issue?.useId,
+    assetId: issue?.assetId,
+  }));
+  // `ok` is the verdict's own word. An `ok: true` that still carries issues is
+  // reported (they are advisory there), an `ok` that is not exactly true fails
+  // — a verdict that cannot say it passed did not pass.
+  const ok = verdict.ok === true;
+  if (!ok && issues.length === 0) {
+    issues.push({
+      code: "image_use_unresolved",
+      message: "the add-in refused the deck's image obligations without naming one",
+      action: "Re-run `slidemind view-draft <deck>` to see which slide is missing its picture.",
+      file: null,
+      slide: null,
+    });
+  }
+  return { expected: true, ran: true, ok, issues };
+}
+
+/**
+ * Refuse a final deliverable whose image obligations are unproven.
+ *
+ * Called on the ONE choke point every .pptx passes through, after the render
+ * and before any bytes are written or inserted, so a refusal leaves the deck
+ * exactly as it was.
+ */
+export function assertImageIntentSatisfied(envelope, result) {
+  const verdict = imageIntentVerdict(envelope, result);
+  if (!verdict.expected || verdict.ok) return verdict;
+  const err = new Error(
+    `this deck's image obligations are not satisfied — no .pptx was written:\n` +
+      verdict.issues.map((i) => `  ${formatIssue(i)}`).join("\n"),
+  );
+  err.code = verdict.ran ? verdict.issues[0]?.code ?? "image_use_unresolved" : "image_intent_unsupported";
+  err.imageIntentIssues = verdict.issues;
+  throw err;
+}
+

package/src/builders/image-use-reconcile.mjs

@@ -0,0 +1,107 @@
+// Folding targeted-edit image uses back into an approved plan.
+//
+// A targeted edit records a slide's uses in `state/image-use-overrides.json`
+// (src/lib/image-use-overrides.mjs) because there is no plan stage to approve
+// them at. The moment a plan revision IS approved, the plan becomes the source
+// of approved intent again — so each override whose slide the new plan still
+// carries is written into that slide's storyboard and its entry is cleared.
+//
+// Three properties this exists to hold:
+//
+//   * **Only what it supersedes is cleared.** An override whose slide the plan
+//     does not have (the slide was deleted, or the deck has no slide file for
+//     that GUID yet) is left exactly where it is. Clearing it would silently
+//     discard an obligation nobody re-approved.
+//   * **A cleared obligation is never resurrected.** An override recording an
+//     empty list writes "no uses" into the plan and is then cleared, so the
+//     next read of the plan agrees with the edit instead of restoring the uses
+//     the edit removed.
+//   * **Atomic in the order that matters.** plan.md is written first, the
+//     overrides file second, each by write-then-rename. A crash between the two
+//     leaves an entry that still describes what the plan already says — the
+//     next reconcile re-applies it to the same result. The reverse order would
+//     lose the obligation outright.
+//
+// Called from the plan gate's two approve paths (src/builders/plan.mjs) BEFORE
+// the approved plan is hashed, so the recorded planHash is the hash of the plan
+// the uses were folded into.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  clearSlideOverrides,
+  readImageUseOverrides,
+  slideNumberForId,
+} from "../lib/image-use-overrides.mjs";
+import { replaceStoryboardSegment, splitPlanMarkdownIntoSegments } from "./storyboard-markdown.mjs";
+
+/**
+ * Fold every applicable override into `<deckDir>/plan.md` and clear it.
+ *
+ * Never throws for a deck that has none: a plan with no image intent is the
+ * ordinary case, and approving it must cost nothing. A registry or overrides
+ * file that does not parse is reported, not thrown — refusing a human's
+ * approval over a sidecar would strand the deck.
+ *
+ * @returns {{applied: Array<{slideId: string, slide: number, uses: number}>,
+ *            kept: Array<{slideId: string, why: string}>, error: string|null}}
+ */
+export function reconcileImageUseOverrides(deckDir) {
+  const out = { applied: [], kept: [], error: null };
+  const planPath = path.join(deckDir, "plan.md");
+
+  let overrides;
+  try {
+    overrides = readImageUseOverrides(deckDir);
+  } catch (err) {
+    return { ...out, error: err?.message ?? String(err) };
+  }
+  if (!overrides.slides.length) return out;
+
+  let markdown;
+  try {
+    markdown = fs.readFileSync(planPath, "utf8");
+  } catch {
+    // No plan to fold into: every entry stays, still governing its slide.
+    return {
+      ...out,
+      kept: overrides.slides.map((entry) => ({ slideId: entry.slideId, why: "no plan.md" })),
+    };
+  }
+
+  const keep = [];
+  for (const entry of overrides.slides) {
+    const slide = slideNumberForId(deckDir, entry.slideId);
+    if (slide == null) {
+      keep.push({ slideId: entry.slideId, why: "no slide carries this id" });
+      continue;
+    }
+    // Re-segment each round: every splice moves the offsets of the fences after
+    // it, and two overrides on one plan is the normal case.
+    const board = splitPlanMarkdownIntoSegments(markdown).find(
+      (segment) => segment.type === "storyboard" && segment.data?.slide === slide,
+    );
+    if (!board) {
+      keep.push({ slideId: entry.slideId, why: `the plan has no storyboard for slide ${slide}` });
+      continue;
+    }
+    const next = { ...board.data };
+    if (entry.assetUses.length) next.assetUses = entry.assetUses;
+    else delete next.assetUses;
+    markdown = replaceStoryboardSegment(markdown, board, next);
+    out.applied.push({ slideId: entry.slideId, slide, uses: entry.assetUses.length });
+  }
+
+  if (!out.applied.length) return { ...out, kept: keep };
+
+  // Write-then-rename, as this module's header promises: `respondPlan` hashes
+  // plan.md immediately after this returns, so a crash mid-write would leave a
+  // truncated file as the APPROVED plan — and, since clearSlideOverrides had
+  // not run, the next reconcile would re-splice into that truncation.
+  const tmp = `${planPath}.${process.pid}.sm-tmp`;
+  fs.writeFileSync(tmp, markdown);
+  fs.renameSync(tmp, planPath);
+  clearSlideOverrides(deckDir, out.applied.map((a) => a.slideId));
+  return { ...out, kept: keep };
+}

package/src/builders/kit-helpers.mjs

@@ -0,0 +1,121 @@
+// The generated text-and-shape kit of a transcribed slide: the helper
+// definitions transcribe.mjs writes at the top of every slide (`KIT`'s B and T,
+// then `KIT_EXTRAS`' I, L, P and R — always all of them, so an author who adds
+// a picture, a list, a paragraph or a run finds its helper already there; x111–
+// x113 each lost a draft round to "<R> is not a registered layout component"). They are the one owner of
+// how a box, a text, a picture, a paragraph, a list and a run render: sizes
+// come from ROLE, paint from FILL/TONE, list markers from the design's CSS.
+// The slide lint holds every helper on a transcribed slide to these exact
+// definitions (build-pptx/lint-role-type.ts): a helper edited by hand — a list
+// whose markers it hides, a paragraph it shrinks — is refused, and a helper a
+// slide uses without declaring it is named with its definition to restore
+// (build-pptx/lint-kit-helpers.ts, for slides transcribed before KIT_EXTRAS).
+// Pure; mirrored into the add-in by scripts/sync-transcription-runtime.mjs.
+import { LIST_HELPER, RUN_HELPER } from "./list-jsx.mjs";
+
+// I = an icon, or a picture the user supplied. Its `<img src={src}>` is
+// dynamic; the lint checks the asset literals at its call sites, and a slide
+// with no call site renders no image (holdout QBR 3 refused the unused helper
+// before lint-kit-helpers.ts knew the canonical I).
+//
+// The five extra props are how an approved image use reaches BOTH renderers at
+// once, and an engine icon passes none of them, so its markup is unchanged:
+//   use   — `data-asset-use`, the identity the render evidence is matched on.
+//   fit   — `object-fit`, which the exporter's own image-fit adapter reads.
+//   pos   — `object-position`, same.
+//   crop  — the approved source region on the renderer's DECLARED-crop channel
+//           (`data-sm-src-crop`, OOXML 100000ths "l,t,r,b" — the same channel a
+//           converted deck's `<a:srcRect>` rides).
+//   view  — those same four numbers as an `object-view-box` inset, so the
+//           preview shows the region the .pptx will carry. A crop expressed
+//           only in CSS would export as the whole picture.
+export const ICON_HELPER = `  const I = ({ id, x, y, w, h, src, use, fit = "contain", pos, crop, view, stack }) => (
+    <img id={id} src={src} data-asset-use={use} data-sm-src-crop={crop} data-sm-stack={stack}
+      style={{ position: "absolute", left: x, top: y, width: w, height: h, objectFit: fit,
+        ...(pos ? { objectPosition: pos } : {}), ...(view ? { objectViewBox: view } : {}) }} />
+  );
+`;
+
+// L = a native list (list-jsx.mjs).
+
+// P = one paragraph of a text block (a title and the description under it).
+// The block's T places the block; its paragraphs stack in normal flow on the
+// design's line-height, so a longer title pushes its description down instead
+// of running into it, and the export ships the block as ONE text frame.
+export const PARAGRAPH_HELPER = `  const P = ({ role = "body", bold, tone = "dark", colorVar, align = "left", nowrap, indent, children }) => (
+    <div style={{ textAlign: align, ...ROLE[role], color: colorVar ?? TONE[tone], lineHeight: "var(--lh-tight)", ...(indent ? { marginLeft: indent } : {}),
+      ...(nowrap ? { whiteSpace: "nowrap" } : {}), ...(bold ? { fontWeight: "var(--fw-bold)" } : {}) }}>{children}</div>
+  );
+`;
+
+export const KIT = `  // Maps from the spec's vocabulary to the design's tokens.
+  const FILL = {};
+  const TONE = {};
+  const ROLE = {
+    subtitle: { fontSize: "var(--fs-caption)", color: TONE.muted },
+    section: { fontSize: "var(--fs-body-sm)", fontWeight: "var(--fw-bold)" },
+    title: { fontSize: "var(--fs-body-sm)", fontWeight: "var(--fw-bold)" },
+    body: { fontSize: "var(--fs-caption)" },
+    label: { fontSize: "var(--fs-caption)", color: TONE.muted },
+    caption: { fontSize: "var(--fs-caption)" },
+    number: { fontSize: "var(--fs-h3)", fontWeight: "var(--fw-bold)" },
+    badge: { fontSize: "var(--fs-caption)", fontWeight: "var(--fw-bold)" },
+  };
+  const RADIUS = { rounded: "var(--r-md)", pill: "var(--r-pill)", circle: "var(--r-pill)", ring: "var(--r-pill)", ellipse: "50%" };
+  // ROLE is the slide's one type hierarchy on the design's ramp, on tight
+  // leading: titles and body on one step, labels and captions one under it,
+  // numbers above. A slide whose text does not fit moves the whole ladder
+  // down one step, never one text. The transcriber never reads a size off
+  // the image. \`px\` on a T or L is the author's step off the ramp (never
+  // below the design's minimum), on PowerPoint's half-point grid.
+  const HALF_PT = (px) => Math.round(px * 1.5) / 1.5;
+  // B = a painted or positioned box. T = a text line (no height: text takes what it needs;
+  // a single-line text never wraps). I = an icon or picture. A T or an I inside
+  // a B with no x/y is seated: the B centres it (align/valign), so a glyph,
+  // digit or icon on a disc is never placed by its own coordinates. Every line — connector, rule,
+  // arc, bracket, mark — is written out in full below as a native line directive.
+  // Figure = a drawn shape as a structural sketch (circles, outline points, typed
+  // edges), compiled exactly at render: edit its points, circles and relations.
+  // prst / adj on a B: the preset a line glues to (its connection sites).
+  // fillVar / colorVar: the design token nearest the colour the image shows
+  // (snapped by the CLI from corporate-design.css); the tone word is the
+  // fallback when the design has no such colour.
+  // stack="n:r": this part belongs to row r of declared stack n ("n:gR:F" =
+  // drawn in the gap under row R, at fraction F of it); STACKS holds each
+  // stack's align and spacing. A
+  // row moves as one — move all its parts, or let preparation re-lay it.
+  // align / valign: the box's own words ride ON the shape — one PowerPoint
+  // shape with a text body, never a text box parked over it. Where they sit
+  // inside the box is what the image measured, so this works the same for a
+  // circle, a chip, a band or a card.
+  const PLACE = { left: "flex-start", top: "flex-start", center: "center", middle: "center", right: "flex-end", bottom: "flex-end" };
+  const B = ({ id, x, y, w, h, plotOwner, prst, adj, fill = "none", fillVar, shape, shadow, align, valign, stack, style, children }) => (
+    <div id={id} data-sm-plot-owner={plotOwner} data-prst={prst} data-adj={adj} data-sm-stack={stack} style={{ position: "absolute", left: x, top: y, width: w, height: h, boxSizing: "border-box",
+      background: fillVar ?? FILL[fill], borderRadius: RADIUS[shape], ...(shadow ? { boxShadow: "var(--shadow-md)" } : {}),
+      ...(align || valign ? { display: "flex", justifyContent: PLACE[align] ?? "center", alignItems: PLACE[valign] ?? "center", textAlign: align ?? "center" } : {}), ...style }}>{children}</div>
+  );
+  const T = ({ id, x, y, w, h, rotation, valign, px, role = "body", bold, tone = "dark", colorVar, align = "left", nowrap, stack, block, children }) => (
+    <div id={id} data-sm-stack={stack} data-sm-block={block} style={{ position: "absolute", left: x, top: y, width: w, ...(valign === "middle" ? { height: h, display: "flex", alignItems: "center", justifyContent: "center" } : {}), textAlign: align, ...ROLE[role], color: colorVar ?? TONE[tone],
+       ...(rotation ? { height: h, transform: "rotate(" + rotation + "deg)", transformOrigin: "center" } : {}),
+       ...(px ? { fontSize: HALF_PT(px) } : {}), lineHeight: role === "number" ? 1 : "var(--lh-tight)",
+      ...(nowrap ? { whiteSpace: "nowrap" } : {}), ...(bold ? { fontWeight: "var(--fw-bold)" } : {}) }}>{children}</div>
+  );
+`;
+
+// The canonical definition of each kit helper, `const X = (…) => …;` exactly
+// as a slide carries it, by name.
+function definitions(src) {
+  const out = {};
+  for (const m of src.matchAll(/^ {2}const ([A-Z]) = \([\s\S]*?\n {2}(?:\);|\};)$/gm)) out[m[1]] = m[0];
+  return out;
+}
+// The helpers after `KIT` on every transcribed slide, in this order.
+export const KIT_EXTRAS = ICON_HELPER + LIST_HELPER + PARAGRAPH_HELPER + RUN_HELPER;
+
+export const KIT_HELPER_SOURCES = Object.freeze({
+  ...definitions(KIT),
+  ...definitions(ICON_HELPER),
+  ...definitions(PARAGRAPH_HELPER),
+  ...definitions(LIST_HELPER),
+  ...definitions(RUN_HELPER),
+});

package/src/builders/layout-names.mjs

@@ -0,0 +1,32 @@
+// Layout names and content slots — canonical here, mirrored byte-identically
+// into the add-in twice: beside the transcription modules (runtime/transcription)
+// and into the browser-safe plan contract (shared/plan-contract/builders), where
+// the add-in's own layout-naming.ts takes its fold from. It imports nothing.
+
+// `// [CONTENT: 1133×503 px @ (74, 171) …]` in a layout's JSX header names the
+// content slot the slide's children are laid into.
+// The slot's size, and where it sits on the stage (`@ (x, y)`, stage px) when
+// the layout says so: the reader drops the template's own marks outside it.
+export function contentSlotFromLayoutSource(src) {
+  const m = /\[CONTENT:\s*(\d+)\s*[×x]\s*(\d+)\s*px(?:\s*@\s*\(\s*(-?\d+)\s*,\s*(-?\d+)\s*\))?/i.exec(src ?? "");
+  if (!m) return null;
+  return { w: Number(m[1]), h: Number(m[2]), ...(m[3] != null ? { x: Number(m[3]), y: Number(m[4]) } : {}) };
+}
+
+// A layout name folded for comparison: case, accents, spaces, hyphens and
+// underscores do not tell two names apart.
+export function foldLayoutName(value) {
+  return String(value).normalize("NFD").replace(/[̀-ͯ]/g, "").replace(/[\s_-]+/g, "").toLowerCase();
+}
+
+// The plan's layout name against the design's own: exact, else the one it
+// differs from only in folding (a planner's "TitleMitInhalt" is the design's
+// "TitelMitInhalt" only if the fold says so), else null. One rule on both
+// clients: the add-in's canonicalizer (concept-images.ts) calls this too.
+export function canonicalLayoutName(name, names) {
+  if (!name) return null;
+  const list = [...names];
+  if (list.includes(name)) return name;
+  const folded = foldLayoutName(name);
+  return list.find((candidate) => foldLayoutName(candidate) === folded) ?? null;
+}