ppt-template-reuse 0.4.0-rc.2

package/src/core/universal-engine.mjs

@@ -0,0 +1,1075 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+
+import { buildAdaptiveContentPlan } from "./adaptive-planner.mjs";
+import { auditContentPlan } from "./content-audit.mjs";
+import { buildFrameMap } from "./frame-map.mjs";
+import {
+  assertAllowedPath,
+  exists,
+  fingerprint,
+  readJson,
+  sha256File,
+  writeJsonAtomic,
+} from "./io.mjs";
+import { editPptxNative, inspectPptxPackage } from "./ooxml-editor.mjs";
+import {
+  resolveEngineHome,
+  resolveLibraryDir,
+  resolveSessionsDir,
+} from "./paths.mjs";
+import {
+  compareProtectedPng,
+  compareRenderedTextFidelity,
+  renderPdfPages,
+  renderPptx,
+  rendererDoctor,
+} from "./renderer.mjs";
+import { extractSource } from "./source-extractor.mjs";
+import { inspectTemplate } from "./template-inspector.mjs";
+import { loadPptx, parseXml, slideRecords, textOf, xmlFrom } from "./pptx-package.mjs";
+
+export const engineVersion = "0.4.0-rc.2";
+
+const jobs = new Map();
+const PLACEHOLDER =
+  /(插入图片|相关图片|点击添加|请在此|占位|type here|add title|add text|replace image|sample text)/i;
+const VALID_KINDS = new Set([
+  "background",
+  "fact",
+  "timeline",
+  "issue",
+  "rule",
+  "theory",
+  "method",
+  "evidence",
+  "data",
+  "application",
+  "analysis",
+  "counterargument",
+  "rebuttal",
+  "conclusion",
+  "recommendation",
+]);
+
+function sessionId() {
+  return `${new Date().toISOString().replace(/[-:.TZ]/g, "").slice(0, 14)}-${crypto
+    .randomBytes(6)
+    .toString("hex")}`;
+}
+
+function normalizeRoots(roots = []) {
+  return [...new Set([process.cwd(), os.tmpdir(), ...roots].map((item) => path.resolve(item)))];
+}
+
+function sessionDir(id, home) {
+  if (!/^[a-zA-Z0-9._-]+$/.test(String(id))) throw new Error("Invalid session id");
+  return path.join(resolveSessionsDir(home), String(id));
+}
+
+function statusPath(id, home) {
+  return path.join(sessionDir(id, home), "session.json");
+}
+
+async function loadSession(id, home) {
+  const candidate = statusPath(id, home);
+  if (!(await exists(candidate))) throw new Error(`Unknown session: ${id}`);
+  return readJson(candidate);
+}
+
+async function saveSession(session, home) {
+  session.updatedAt = new Date().toISOString();
+  session.sessionFingerprint = fingerprint({
+    id: session.id,
+    state: session.state,
+    input: session.input,
+    artifacts: session.artifacts,
+    warnings: session.warnings,
+  });
+  await writeJsonAtomic(statusPath(session.id, home), session);
+  return session;
+}
+
+async function failSession(session, error, home) {
+  session.state = "failed";
+  session.error = {
+    code: error.code || "ENGINE_ERROR",
+    message: error.message || String(error),
+  };
+  await saveSession(session, home);
+}
+
+function action(type, instructions, extra = {}) {
+  return { type, instructions, ...extra };
+}
+
+function durationSeconds(requirements = {}) {
+  if (requirements.durationSeconds) return requirements.durationSeconds;
+  const value = String(requirements.duration || "").trim();
+  const match = value.match(/^(\d+)(?:\s*[-–]\s*(\d+))?$/);
+  if (!match) return {};
+  return {
+    min: Number(match[1]) * 60,
+    max: Number(match[2] || match[1]) * 60,
+  };
+}
+
+function semanticKind(value) {
+  const normalized = String(value || "analysis").trim().toLowerCase();
+  const aliases = {
+    chronology: "timeline",
+    sequence: "timeline",
+    argument: "analysis",
+    claim: "analysis",
+    recommendation: "recommendation",
+  };
+  return VALID_KINDS.has(normalized)
+    ? normalized
+    : aliases[normalized] || "analysis";
+}
+
+function validateSourceSemantics(extraction, semantics, requirements) {
+  const supplied = Array.isArray(semantics?.sourceUnits)
+    ? semantics.sourceUnits
+    : Array.isArray(semantics)
+      ? semantics
+      : [];
+  const byId = new Map(supplied.map((unit) => [String(unit.id), unit]));
+  const expected = new Set(extraction.units.map((unit) => unit.id));
+  const extras = [...byId.keys()].filter((id) => !expected.has(id));
+  const missing = [...expected].filter((id) => !byId.has(id));
+  if (extras.length || missing.length) {
+    const error = new Error(
+      `Source semantics must preserve every extracted unit exactly; missing=[${missing.join(
+        ", ",
+      )}], extra=[${extras.join(", ")}]`,
+    );
+    error.code = "SOURCE_ANCHOR_MISMATCH";
+    throw error;
+  }
+  const sourceUnits = extraction.units.map((raw) => {
+    const next = byId.get(raw.id);
+    if (next.anchor && next.anchor !== raw.anchor) {
+      const error = new Error(`Anchor changed for ${raw.id}`);
+      error.code = "SOURCE_ANCHOR_MISMATCH";
+      throw error;
+    }
+    const priority = String(next.priority || "supporting").toLowerCase();
+    const presentationRelevance = String(
+      next.presentationRelevance || (priority === "optional" ? "appendix" : "core"),
+    ).toLowerCase();
+    if (!["critical", "supporting", "optional"].includes(priority)) {
+      throw new Error(`Invalid priority for ${raw.id}: ${priority}`);
+    }
+    if (!["core", "appendix", "exclude"].includes(presentationRelevance)) {
+      throw new Error(
+        `Invalid presentationRelevance for ${raw.id}: ${presentationRelevance}`,
+      );
+    }
+    if (presentationRelevance === "exclude" && priority === "critical") {
+      throw new Error(`Critical source unit ${raw.id} cannot be excluded`);
+    }
+    if (
+      presentationRelevance === "exclude" &&
+      !String(next.exclusionReason || "").trim()
+    ) {
+      throw new Error(
+        `Excluded source unit ${raw.id} requires an explicit exclusionReason`,
+      );
+    }
+    const summary = String(next.summary || "").trim();
+    const detail = String(next.detail || raw.detail || raw.text).trim();
+    const claim = String(next.claim || "").trim();
+    const evidence = Array.isArray(next.evidence)
+      ? next.evidence.map(String).map((value) => value.trim()).filter(Boolean)
+      : next.evidence
+        ? [String(next.evidence).trim()]
+        : [];
+    const whyItMatters = String(next.whyItMatters || "").trim();
+    const displayFragments = Array.isArray(next.displayFragments)
+      ? next.displayFragments
+          .map((fragment) =>
+            typeof fragment === "string"
+              ? { role: "label", text: fragment.trim() }
+              : {
+                  role: String(fragment?.role || "label")
+                    .trim()
+                    .toLowerCase(),
+                  text: String(fragment?.text || "").trim(),
+                },
+          )
+          .filter((fragment) => fragment.text)
+      : [];
+    const requiredFields = [
+      ["summary", summary],
+      ["claim", claim],
+      ["evidence", evidence.join("")],
+      ["whyItMatters", whyItMatters],
+    ].filter(([, value]) => !value);
+    if (requiredFields.length) {
+      const error = new Error(
+        `Source unit ${raw.id} is missing required semantic fields: ${requiredFields
+          .map(([field]) => field)
+          .join(", ")}`,
+      );
+      error.code = "SOURCE_SEMANTICS_INCOMPLETE";
+      throw error;
+    }
+    const limits = [
+      ["summary", summary, 100],
+      ["claim", claim, 90],
+      ["whyItMatters", whyItMatters, 120],
+      ...evidence.map((value, index) => [
+        `evidence[${index}]`,
+        value,
+        140,
+      ]),
+      ...displayFragments.map((fragment, index) => [
+        `displayFragments[${index}].text`,
+        fragment.text,
+        80,
+      ]),
+    ];
+    const overlong = limits.filter(([, value, maximum]) => {
+      return [...String(value).replace(/\s+/gu, "")].length > maximum;
+    });
+    if (overlong.length) {
+      const error = new Error(
+        `Source unit ${raw.id} has semantic fields that exceed safe visible capacity: ${overlong
+          .map(([field, , maximum]) => `${field}>${maximum}`)
+          .join(", ")}`,
+      );
+      error.code = "SOURCE_SEMANTIC_CAPACITY_INVALID";
+      throw error;
+    }
+    return {
+      ...raw,
+      ...next,
+      id: raw.id,
+      anchor: raw.anchor,
+      parentAnchor: raw.parentAnchor,
+      segmentIndex: raw.segmentIndex,
+      segmentCount: raw.segmentCount,
+      text: raw.text,
+      kind: semanticKind(next.kind),
+      priority,
+      presentationRelevance,
+      summary,
+      detail,
+      claim,
+      evidence,
+      whyItMatters,
+      displayFragments,
+    };
+  });
+  return {
+    schemaVersion: 2,
+    presentationBrief: {
+      title: requirements.title || semantics.presentationBrief?.title || "演示文稿",
+      subtitle: requirements.subtitle || semantics.presentationBrief?.subtitle || "",
+      audience: requirements.audience || semantics.presentationBrief?.audience || "",
+      communicationJob:
+        requirements.communicationJob ||
+        semantics.presentationBrief?.communicationJob ||
+        "完整解释材料中的事实、依据、分析和结论",
+      useCase:
+        requirements.useCase ||
+        semantics.presentationBrief?.useCase ||
+        "general-report",
+      density: requirements.density || semantics.presentationBrief?.density || "rich",
+      scope:
+        requirements.scope ||
+        semantics.presentationBrief?.scope ||
+        "core-and-appendix",
+      durationSeconds: durationSeconds(requirements),
+      author: requirements.author || semantics.presentationBrief?.author || "",
+      organization:
+        requirements.organization || semantics.presentationBrief?.organization || "",
+      date: requirements.date || semantics.presentationBrief?.date || "",
+    },
+    sourceUnits,
+  };
+}
+
+function validateTemplateSemantics(inspection, submitted) {
+  if (!submitted) return inspection;
+  if (
+    submitted.source?.sha256 &&
+    submitted.source.sha256 !== inspection.source.sha256
+  ) {
+    throw new Error("Template semantics were produced for a different file");
+  }
+  const expectedSlides = new Set(
+    inspection.slides.map((slide) => Number(slide.sourceSlide)),
+  );
+  const slides = submitted.slides || inspection.slides;
+  const extras = slides.filter(
+    (slide) => !expectedSlides.has(Number(slide.sourceSlide)),
+  );
+  if (extras.length) throw new Error("Template semantics contain unknown slides");
+  const bySlide = new Map(
+    slides.map((slide) => [Number(slide.sourceSlide), slide]),
+  );
+  const merged = {
+    ...inspection,
+    ...submitted,
+    source: inspection.source,
+    slides: inspection.slides.map((slide) => ({
+      ...slide,
+      ...(bySlide.get(Number(slide.sourceSlide)) || {}),
+      sourceSlide: slide.sourceSlide,
+      sourcePart: slide.sourcePart,
+      slotSchema:
+        bySlide.get(Number(slide.sourceSlide))?.slotSchema || slide.slotSchema,
+    })),
+  };
+  const unsafe = merged.slides.filter(
+    (slide) =>
+      slide.safetyStatus === "automatic" &&
+      !(slide.slotSchema || []).some((slot) => slot.purpose === "title"),
+  );
+  if (unsafe.length) {
+    throw new Error(
+      `Automatic slides require an explicit title slot: ${unsafe
+        .map((slide) => slide.sourceSlide)
+        .join(", ")}`,
+    );
+  }
+  merged.reviewSummary = {
+    automaticSlides: merged.slides
+      .filter((slide) => slide.safetyStatus === "automatic")
+      .map((slide) => slide.sourceSlide),
+    reviewSlides: merged.slides
+      .filter((slide) => slide.safetyStatus === "review")
+      .map((slide) => slide.sourceSlide),
+    blockedSlides: merged.slides
+      .filter((slide) => slide.safetyStatus === "blocked")
+      .map((slide) => slide.sourceSlide),
+  };
+  const unresolvedVariants = Object.fromEntries(
+    Object.entries(inspection.variantSelections || {}).filter(
+      ([, sourceSlides]) =>
+        merged.slides.filter(
+          (slide) =>
+            sourceSlides.map(Number).includes(Number(slide.sourceSlide)) &&
+            slide.safetyStatus === "automatic",
+        ).length !== 1,
+    ),
+  );
+  merged.profileFingerprint = fingerprint({
+    source: merged.source,
+    slides: merged.slides,
+    purposeProfile: merged.purposeProfile,
+  });
+  merged.actionRequired =
+    merged.reviewSummary.reviewSlides.length ||
+    Object.keys(unresolvedVariants).length
+    ? action(
+        "template-semantics",
+        [
+          "Review or block every unresolved template slide before planning.",
+          "For every opening or closing variant group, approve exactly one source slide and block the alternatives.",
+        ],
+        {
+          slides: merged.reviewSummary.reviewSlides,
+          variantSelections: unresolvedVariants,
+        },
+      )
+    : null;
+  return merged;
+}
+
+function requiredAssets(contentPlan) {
+  const missing = [];
+  for (const slide of contentPlan.slides || []) {
+    for (const [slotId, value] of Object.entries(slide.fields || {})) {
+      if (
+        value &&
+        typeof value === "object" &&
+        ["image", "icon"].includes(String(value.type || "").toLowerCase()) &&
+        !value.path
+      ) {
+        missing.push({ outputSlide: slide.outputSlide, slotId, type: value.type });
+      }
+    }
+  }
+  return missing;
+}
+
+async function allSlideText(pptxPath) {
+  const zip = await loadPptx(pptxPath);
+  const order = await slideRecords(zip);
+  const slides = [];
+  for (const slide of order.slides) {
+    const document = parseXml(await xmlFrom(zip, slide.partName));
+    slides.push({ slide: slide.slideNumber, text: textOf(document) });
+  }
+  return slides;
+}
+
+export async function createSession(input, options = {}) {
+  const home = resolveEngineHome(options.home);
+  const roots = normalizeRoots(input.roots || options.roots || []);
+  const template = assertAllowedPath(input.template, roots);
+  const source = assertAllowedPath(input.source, roots);
+  const output = assertAllowedPath(input.output, roots);
+  if (!(await exists(template))) throw new Error(`Template not found: ${template}`);
+  if (!(await exists(source))) throw new Error(`Source not found: ${source}`);
+  const id = sessionId();
+  const directory = sessionDir(id, home);
+  await fs.mkdir(directory, { recursive: true });
+  const session = {
+    schemaVersion: 1,
+    engineVersion,
+    id,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+    state: "created",
+    input: {
+      template,
+      source,
+      output,
+      roots,
+      requirements: input.requirements || {},
+      templateSha256: await sha256File(template),
+      sourceSha256: await sha256File(source),
+    },
+    artifacts: {},
+    warnings: [],
+    events: [],
+  };
+  await saveSession(session, home);
+  return session;
+}
+
+export async function inspectSession(id, options = {}) {
+  const home = resolveEngineHome(options.home);
+  const session = await loadSession(id, home);
+  try {
+    const capsuleDirectory = path.join(
+      resolveLibraryDir(home),
+      session.input.templateSha256,
+    );
+    const capsuleProfilePath = path.join(
+      capsuleDirectory,
+      "template-profile.lock.json",
+    );
+    const cachedProfile = (await exists(capsuleProfilePath))
+      ? await readJson(capsuleProfilePath)
+      : null;
+    const capsuleReused =
+      cachedProfile?.source?.sha256 === session.input.templateSha256;
+    const templateProfile = capsuleReused
+      ? cachedProfile
+      : await inspectTemplate(session.input.template);
+    const sourceExtraction = await extractSource(session.input.source);
+    const directory = sessionDir(id, home);
+    let templateRendering;
+    try {
+      templateRendering = await renderPptx({
+        pptxPath: session.input.template,
+        workspace: path.join(directory, "template-preview"),
+        libreOffice: options.libreOffice,
+      });
+      session.artifacts.templatePreviews = templateRendering.pages.map(
+        (page) => page.path,
+      );
+      session.artifacts.templateMontage = templateRendering.montage.path;
+    } catch (error) {
+      session.warnings.push(
+        `Template preview rendering is unavailable: ${error.message}`,
+      );
+    }
+    if (sourceExtraction.scannedPages?.length) {
+      try {
+        const rendered = await renderPdfPages({
+          pdfPath: session.input.source,
+          outputDir: path.join(directory, "scanned-source-pages"),
+          prefix: "source-page",
+        });
+        sourceExtraction.scannedPageImages = rendered.filter((page) =>
+          sourceExtraction.scannedPages.includes(page.page),
+        );
+        sourceExtraction.actionRequired.scannedPageImages =
+          sourceExtraction.scannedPageImages;
+        session.artifacts.scannedSourcePages =
+          sourceExtraction.scannedPageImages.map((page) => page.path);
+      } catch (error) {
+        session.warnings.push(
+          `Scanned PDF pages require host visual review, but page rendering failed: ${error.message}`,
+        );
+      }
+    }
+    const templatePath = path.join(directory, "template-profile.auto.json");
+    const sourcePath = path.join(directory, "source-extraction.json");
+    await writeJsonAtomic(templatePath, templateProfile);
+    await writeJsonAtomic(sourcePath, sourceExtraction);
+    session.artifacts.templateInspection = templatePath;
+    session.artifacts.sourceExtraction = sourcePath;
+    const actions = [];
+    if (templateProfile.actionRequired) {
+      actions.push({
+        ...templateProfile.actionRequired,
+        previewResources: session.artifacts.templatePreviews || [],
+        montageResource: session.artifacts.templateMontage,
+      });
+    }
+    actions.push(sourceExtraction.actionRequired);
+    session.actionRequired = actions;
+    session.templateCapsule = {
+      sha256: session.input.templateSha256,
+      path: capsuleDirectory,
+      reused: capsuleReused,
+    };
+    session.state = actions.some((item) => item.type === "template-semantics")
+      ? "needs-template-and-source-semantics"
+      : "needs-source-semantics";
+    await saveSession(session, home);
+    return {
+      session,
+      templateInspection: templateProfile,
+      sourceExtraction,
+      templateRendering,
+      actionRequired: actions,
+      capsuleReused,
+    };
+  } catch (error) {
+    await failSession(session, error, home);
+    throw error;
+  }
+}
+
+export async function submitSemantics(id, payload, options = {}) {
+  const home = resolveEngineHome(options.home);
+  const session = await loadSession(id, home);
+  const directory = sessionDir(id, home);
+  const inspection = await readJson(session.artifacts.templateInspection);
+  const extraction = await readJson(session.artifacts.sourceExtraction);
+  const templateProfile = validateTemplateSemantics(
+    inspection,
+    payload.templateProfile,
+  );
+  const sourceMap = validateSourceSemantics(
+    extraction,
+    payload.sourceSemantics,
+    session.input.requirements,
+  );
+  if (templateProfile.actionRequired) {
+    const error = new Error("Template review is still unresolved");
+    error.code = "TEMPLATE_REVIEW_REQUIRED";
+    throw error;
+  }
+  const templatePath = path.join(directory, "template-profile.lock.json");
+  const sourcePath = path.join(directory, "source-map.lock.json");
+  await writeJsonAtomic(templatePath, templateProfile);
+  await writeJsonAtomic(sourcePath, sourceMap);
+  const capsuleDirectory = path.join(
+    resolveLibraryDir(home),
+    session.input.templateSha256,
+  );
+  await fs.mkdir(capsuleDirectory, { recursive: true });
+  await writeJsonAtomic(
+    path.join(capsuleDirectory, "template-profile.lock.json"),
+    templateProfile,
+  );
+  await writeJsonAtomic(path.join(capsuleDirectory, "manifest.json"), {
+    schemaVersion: 1,
+    engineVersion,
+    sourceSha256: session.input.templateSha256,
+    profileFingerprint: templateProfile.profileFingerprint,
+    updatedAt: new Date().toISOString(),
+  });
+  session.artifacts.templateProfile = templatePath;
+  session.artifacts.sourceMap = sourcePath;
+  session.state = "semantics-ready";
+  session.actionRequired = [];
+  await saveSession(session, home);
+  return { session, templateProfile, sourceMap };
+}
+
+export async function planSession(id, planningOptions = {}, options = {}) {
+  const home = resolveEngineHome(options.home);
+  const session = await loadSession(id, home);
+  const sourceMap = await readJson(session.artifacts.sourceMap);
+  const templateProfile = await readJson(session.artifacts.templateProfile);
+  let contentPlan;
+  try {
+    contentPlan = buildAdaptiveContentPlan(sourceMap, templateProfile, {
+      density: planningOptions.density,
+      scope: planningOptions.scope,
+      templateMode: planningOptions.templateMode,
+      allowLowFit: planningOptions.allowLowFit === true,
+      durationSeconds:
+        planningOptions.durationSeconds ||
+        sourceMap.presentationBrief?.durationSeconds,
+    });
+  } catch (error) {
+    if (error.code === "TEMPLATE_SELECTION_AMBIGUOUS") {
+      session.state = "needs-template-selection";
+      session.actionRequired = [
+        action(
+          "template-selection",
+          [
+            "Inspect the full-size candidate previews and approve one source slide for this content role.",
+            "Do not choose automatically while the leading candidates remain near-tied.",
+          ],
+          error.details || {},
+        ),
+      ];
+      await saveSession(session, home);
+      return { session, actionRequired: session.actionRequired };
+    }
+    if (/^Template fit is /.test(error.message)) {
+      session.state = "needs-template-fit-decision";
+      session.actionRequired = [
+        action(
+          "template-fit",
+          [
+            "The template lacks one or more safe capabilities required by this presentation.",
+            "Choose another template or explicitly approve style-only mode; do not silently force a poor fit.",
+          ],
+          { planningError: error.message },
+        ),
+      ];
+      await saveSession(session, home);
+      return { session, actionRequired: session.actionRequired };
+    }
+    if (error.code === "DURATION_CONFLICT") {
+      session.state = "needs-duration-decision";
+      session.actionRequired = [
+        action(
+          "duration",
+          [
+            "The complete traced content cannot fit the requested speaking time.",
+            "Ask the user to extend the duration, narrow scope explicitly, or split the presentation. Never delete critical reasons.",
+          ],
+          error.details || {},
+        ),
+      ];
+      await saveSession(session, home);
+      return { session, actionRequired: session.actionRequired };
+    }
+    const assetTypes = [
+      ...new Set(
+        templateProfile.slides
+          .flatMap((slide) => slide.assetRequirements || [])
+          .filter((item) => item.required)
+          .map((item) => item.type),
+      ),
+    ];
+    if (
+      assetTypes.length &&
+      /No approved template page can safely express|supply required assets/i.test(
+        error.message,
+      )
+    ) {
+      session.state = "needs-assets";
+      session.actionRequired = [
+        action(
+          "assets",
+          [
+            "The available approved layouts require visual assets for one or more source units.",
+            "Use the host image search/generation capability when authorized, or ask the user once for all missing assets.",
+            "Register assets against sourceUnitId, then call ppt_plan again.",
+          ],
+          { requiredTypes: assetTypes, planningError: error.message },
+        ),
+      ];
+      await saveSession(session, home);
+      return { session, actionRequired: session.actionRequired };
+    }
+    throw error;
+  }
+  const audit = auditContentPlan(contentPlan);
+  if (!audit.passed) {
+    const error = new Error(`Content audit failed:\n${audit.errors.join("\n")}`);
+    error.code = "CONTENT_AUDIT_FAILED";
+    error.details = audit;
+    throw error;
+  }
+  const frameMap = buildFrameMap(contentPlan, templateProfile);
+  const directory = sessionDir(id, home);
+  const contentPath = path.join(directory, "content-plan.lock.json");
+  const framePath = path.join(directory, "frame-map.lock.json");
+  const auditPath = path.join(directory, "content-audit.json");
+  await writeJsonAtomic(contentPath, contentPlan);
+  await writeJsonAtomic(framePath, frameMap);
+  await writeJsonAtomic(auditPath, audit);
+  session.artifacts.contentPlan = contentPath;
+  session.artifacts.frameMap = framePath;
+  session.artifacts.contentAudit = auditPath;
+  const missingAssets = requiredAssets(contentPlan);
+  session.state = missingAssets.length ? "needs-assets" : "ready";
+  session.actionRequired = missingAssets.length
+    ? [
+        action(
+          "assets",
+          [
+            "Supply every required image, chart, table, or icon before generation.",
+            "The engine will not emit gray placeholders or temporary stock graphics.",
+          ],
+          { missing: missingAssets },
+        ),
+      ]
+    : [];
+  await saveSession(session, home);
+  return { session, contentPlan, frameMap, audit };
+}
+
+export async function supplyAssets(id, assets, options = {}) {
+  const home = resolveEngineHome(options.home);
+  const session = await loadSession(id, home);
+  const hasPlan = Boolean(session.artifacts.contentPlan);
+  const document = await readJson(
+    hasPlan ? session.artifacts.contentPlan : session.artifacts.sourceMap,
+  );
+  const roots = session.input.roots;
+  const units = new Map(document.sourceUnits.map((unit) => [unit.id, unit]));
+  for (const asset of assets || []) {
+    const unit = units.get(String(asset.sourceUnitId));
+    if (!unit) throw new Error(`Unknown sourceUnitId: ${asset.sourceUnitId}`);
+    const pathValue = asset.path
+      ? assertAllowedPath(asset.path, roots)
+      : undefined;
+    if (pathValue && !(await exists(pathValue))) {
+      throw new Error(`Asset not found: ${pathValue}`);
+    }
+    unit.assets ||= [];
+    unit.assets.push({
+      type: asset.type || "image",
+      value: pathValue || asset.value,
+      path: pathValue,
+      alt: asset.alt || "",
+    });
+  }
+  if (!hasPlan) {
+    await writeJsonAtomic(session.artifacts.sourceMap, document);
+    session.state = "semantics-ready";
+    session.actionRequired = [];
+    await saveSession(session, home);
+    return { session, sourceMap: document, missingAssets: [] };
+  }
+  const templateProfile = await readJson(session.artifacts.templateProfile);
+  const replanned = buildAdaptiveContentPlan(document, templateProfile, {
+    durationSeconds: document.presentationBrief?.durationSeconds,
+    allowLowFit: true,
+  });
+  const audit = auditContentPlan(replanned);
+  if (!audit.passed) throw new Error(`Content audit failed:\n${audit.errors.join("\n")}`);
+  const frameMap = buildFrameMap(replanned, templateProfile);
+  await writeJsonAtomic(session.artifacts.contentPlan, replanned);
+  await writeJsonAtomic(session.artifacts.frameMap, frameMap);
+  await writeJsonAtomic(session.artifacts.contentAudit, audit);
+  const missingAssets = requiredAssets(replanned);
+  session.state = missingAssets.length ? "needs-assets" : "ready";
+  session.actionRequired = missingAssets.length
+    ? [action("assets", ["Additional required assets are still missing."], { missing: missingAssets })]
+    : [];
+  await saveSession(session, home);
+  return { session, missingAssets, contentPlan: replanned, frameMap };
+}
+
+async function appendProgress(session, event, home) {
+  const latest = await loadSession(session.id, home);
+  if (latest.state === "cancelled") {
+    const error = new Error("Generation was cancelled");
+    error.code = "JOB_CANCELLED";
+    throw error;
+  }
+  session.events.push({ ...event, at: new Date().toISOString() });
+  if (session.events.length > 500) session.events = session.events.slice(-500);
+  await saveSession(session, home);
+}
+
+export async function generateSession(id, options = {}) {
+  const home = resolveEngineHome(options.home);
+  const session = await loadSession(id, home);
+  if (!["ready", "generated", "validation-failed"].includes(session.state)) {
+    throw new Error(`Session ${id} is not ready; current state is ${session.state}`);
+  }
+  session.state = "generating";
+  session.actionRequired = [];
+  const jobId =
+    options.jobId || `job-${crypto.randomBytes(6).toString("hex")}`;
+  session.jobId = jobId;
+  await saveSession(session, home);
+  try {
+    const frameMap = await readJson(session.artifacts.frameMap);
+    const directory = sessionDir(id, home);
+    const livePreview = options.livePreview === true;
+    const snapshotPath = livePreview
+      ? path.join(directory, "progress", "working.pptx")
+      : undefined;
+    const authoring = await editPptxNative({
+      templatePath: session.input.template,
+      frameMap,
+      outputPath: session.input.output,
+      progressSnapshotPath: snapshotPath,
+      progress: async (event) => {
+        await appendProgress(session, event, home);
+        if (!livePreview || !event.snapshotPptx) return;
+        const liveRendering = await renderPptx({
+          pptxPath: event.snapshotPptx,
+          workspace: path.join(
+            directory,
+            "progress",
+            `render-${String(event.outputSlide).padStart(2, "0")}`,
+          ),
+          libreOffice: options.libreOffice,
+        });
+        const page = liveRendering.pages.at(-1);
+        const previewPath = path.join(
+          directory,
+          "progress",
+          "previews",
+          `slide-${String(event.outputSlide).padStart(2, "0")}.png`,
+        );
+        await fs.mkdir(path.dirname(previewPath), { recursive: true });
+        await fs.copyFile(page.path, previewPath);
+        session.artifacts.livePreviews ||= [];
+        session.artifacts.livePreviews[event.outputSlide - 1] = previewPath;
+        await appendProgress(
+          session,
+          {
+            event: "preview-ready",
+            outputSlide: event.outputSlide,
+            slideCount: event.slideCount,
+            preview: previewPath,
+            renderSha256: await sha256File(previewPath),
+          },
+          home,
+        );
+      },
+    });
+    session.artifacts.output = authoring.output;
+    session.artifacts.authoring = path.join(sessionDir(id, home), "authoring.json");
+    await writeJsonAtomic(session.artifacts.authoring, authoring);
+    session.state = "generated";
+    await saveSession(session, home);
+    if (options.validate !== false) return validateSession(id, options);
+    return { session, authoring };
+  } catch (error) {
+    if (error.code === "JOB_CANCELLED") {
+      session.state = "cancelled";
+      session.error = undefined;
+      await saveSession(session, home);
+      return { session, cancelled: true };
+    }
+    await failSession(session, error, home);
+    throw error;
+  }
+}
+
+export function startGeneration(id, options = {}) {
+  if (jobs.has(id)) return jobs.get(id).descriptor;
+  const descriptor = {
+    sessionId: id,
+    jobId: `job-${crypto.randomBytes(6).toString("hex")}`,
+    startedAt: new Date().toISOString(),
+  };
+  const promise = generateSession(id, {
+    ...options,
+    jobId: descriptor.jobId,
+  })
+    .catch((error) => ({
+      error: {
+        code: error.code || "PPT_REUSE_GENERATION_FAILED",
+        message: error.message || String(error),
+      },
+    }))
+    .finally(() => jobs.delete(id));
+  jobs.set(id, { descriptor, promise });
+  return descriptor;
+}
+
+export async function validateSession(id, options = {}) {
+  const home = resolveEngineHome(options.home);
+  const session = await loadSession(id, home);
+  if (!session.artifacts.output || !(await exists(session.artifacts.output))) {
+    throw new Error("No generated PPTX is available for validation");
+  }
+  session.state = "validating";
+  await saveSession(session, home);
+  const packageReport = await inspectPptxPackage(session.artifacts.output);
+  const contentAudit = await readJson(session.artifacts.contentAudit);
+  const slideText = await allSlideText(session.artifacts.output);
+  const residualPlaceholders = slideText.filter((slide) =>
+    PLACEHOLDER.test(slide.text),
+  );
+  const chartWorkbookWarnings = session.artifacts.authoring
+    ? (await readJson(session.artifacts.authoring)).editLog.filter(
+        (entry) => entry.type === "chart" && entry.workbookSynced === false,
+      )
+    : [];
+  let rendering;
+  let protectedRegions = [];
+  let renderedTextFidelity;
+  let rendererError;
+  try {
+    rendering = await renderPptx({
+      pptxPath: session.artifacts.output,
+      workspace: path.join(sessionDir(id, home), "render"),
+      libreOffice: options.libreOffice,
+    });
+    renderedTextFidelity = await compareRenderedTextFidelity({
+      pptxPath: session.artifacts.output,
+      pdfPath: rendering.pdfPath,
+    });
+    const frameMap = await readJson(session.artifacts.frameMap);
+    const templateProfile = await readJson(session.artifacts.templateProfile);
+    const templateRendering = await renderPptx({
+      pptxPath: session.input.template,
+      workspace: path.join(sessionDir(id, home), "render-template"),
+      libreOffice: options.libreOffice,
+    });
+    for (const outputSlide of frameMap.outputSlides) {
+      const expected = templateRendering.pages[Number(outputSlide.sourceSlide) - 1];
+      const actual = rendering.pages[Number(outputSlide.outputSlide) - 1];
+      if (!expected || !actual) {
+        protectedRegions.push({
+          outputSlide: outputSlide.outputSlide,
+          passed: false,
+          reason: "missing-rendered-page",
+        });
+        continue;
+      }
+      protectedRegions.push({
+        outputSlide: outputSlide.outputSlide,
+        sourceSlide: outputSlide.sourceSlide,
+        ...(await compareProtectedPng({
+          expectedPath: expected.path,
+          actualPath: actual.path,
+          editableBoxes: outputSlide.editTargets
+            .map((target) => target.sourceBbox)
+            .filter(Boolean),
+          canvas: templateProfile.canvas,
+          diffPath: path.join(
+            sessionDir(id, home),
+            "render",
+            "protected-diffs",
+            `slide-${String(outputSlide.outputSlide).padStart(2, "0")}.png`,
+          ),
+        })),
+      });
+    }
+  } catch (error) {
+    rendererError = { code: error.code || "RENDER_FAILED", message: error.message };
+  }
+  const errors = [];
+  if (!contentAudit.passed) errors.push(...contentAudit.errors);
+  if (packageReport.slideCount !== contentAudit.metrics.slideCount) {
+    errors.push("PPTX slide count does not match the frozen content plan");
+  }
+  if (packageReport.notesSlideCount < contentAudit.metrics.slideCount) {
+    errors.push("One or more slides are missing native speaker notes");
+  }
+  if (residualPlaceholders.length) {
+    errors.push(
+      `Residual placeholder text on slides: ${residualPlaceholders
+        .map((item) => item.slide)
+        .join(", ")}`,
+    );
+  }
+  if (chartWorkbookWarnings.length) {
+    errors.push("Chart cache changed without synchronizing the embedded workbook");
+  }
+  if (rendererError) {
+    errors.push(`Final rendering unavailable: ${rendererError.message}`);
+  }
+  if (
+    rendering &&
+    rendering.pages.length !== packageReport.slideCount
+  ) {
+    errors.push("Rendered page count does not match PPTX slide count");
+  }
+  if (renderedTextFidelity && !renderedTextFidelity.passed) {
+    errors.push(
+      "Rendered text fidelity could not be verified; complete a manual WPS or PowerPoint review before claiming visual acceptance",
+    );
+  }
+  const protectedFailures = protectedRegions.filter((item) => !item.passed);
+  if (protectedFailures.length) {
+    errors.push(
+      `Protected-region pixel checks failed on slides: ${protectedFailures
+        .map((item) => item.outputSlide)
+        .join(", ")}`,
+    );
+  }
+  const qa = {
+    schemaVersion: 1,
+    passed: errors.length === 0,
+    errors,
+    warnings: session.warnings,
+    package: packageReport,
+    content: contentAudit,
+    rendering,
+    renderedTextFidelity,
+    protectedRegions,
+    rendererError,
+    residualPlaceholders,
+  };
+  const qaPath = path.join(sessionDir(id, home), "qa-report.json");
+  await writeJsonAtomic(qaPath, qa);
+  session.artifacts.qa = qaPath;
+  if (rendering) {
+    session.artifacts.previews = rendering.pages.map((page) => page.path);
+    session.artifacts.montage = rendering.montage.path;
+    for (const page of rendering.pages) {
+      await appendProgress(
+        session,
+        {
+          event: "preview-ready",
+          outputSlide: page.page,
+          slideCount: rendering.pages.length,
+          preview: page.path,
+          renderSha256: page.sha256,
+        },
+        home,
+      );
+    }
+  }
+  session.state = qa.passed ? "completed" : "validation-failed";
+  session.actionRequired = qa.passed
+    ? []
+    : [
+        action("validation", [
+          "Resolve every validation error before calling the deck complete.",
+        ], { errors }),
+      ];
+  await saveSession(session, home);
+  return { session, qa };
+}
+
+export async function cancelSession(id, options = {}) {
+  const home = resolveEngineHome(options.home);
+  const session = await loadSession(id, home);
+  session.state = "cancelled";
+  session.cancelledAt = new Date().toISOString();
+  session.actionRequired = [];
+  await saveSession(session, home);
+  return session;
+}
+
+export async function getSessionStatus(id, options = {}) {
+  const home = resolveEngineHome(options.home);
+  const session = await loadSession(id, home);
+  const after = Number(options.afterEvent || 0);
+  return {
+    ...session,
+    events: session.events.slice(Math.max(0, after)),
+    nextEvent: session.events.length,
+    runningInCurrentProcess: jobs.has(id),
+  };
+}
+
+export async function engineDoctor(options = {}) {
+  return {
+    engineVersion,
+    home: resolveEngineHome(options.home),
+    renderer: await rendererDoctor(options),
+    supportedInputs: [".pptx", ".potx", ".docx", ".pdf", ".md", ".txt"],
+    macroPolicy: "pptm-rejected-no-macro-execution",
+  };
+}