@markdstage/markdstage 0.1.3 → 2.4.0

package/shared/runtime/architecture-source.mjs

@@ -0,0 +1,195 @@
+import { readFile, realpath, stat } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+import { parseArchitecture } from "../renderer/architecture.mjs";
+import {
+  findArchitectureBlocks,
+  replaceArchitectureBlock,
+} from "../scripts/markdown-blocks.mjs";
+import { isMarkdownPath, MARKDOWN_MAX_BYTES } from "../scripts/markdown-files.mjs";
+import { serializeMarkdownSave } from "../scripts/markdown-save-coordinator.mjs";
+import { atomicReplaceMarkdown } from "../scripts/atomic-markdown-replace.mjs";
+import { isPathInside } from "./output-paths.mjs";
+
+function sourceError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+export async function resolveArchitectureSourceTarget(workspaceRoot, sourcePath) {
+  const root = resolve(workspaceRoot);
+  if (
+    typeof sourcePath !== "string" ||
+    !sourcePath ||
+    isAbsolute(sourcePath) ||
+    sourcePath.includes("\0")
+  ) {
+    throw sourceError(
+      "invalid_source_path",
+      "sourcePath must be a Markdown file inside the workspace.",
+    );
+  }
+  const candidate = resolve(root, sourcePath);
+  if (!isPathInside(root, candidate) || !isMarkdownPath(candidate)) {
+    throw sourceError(
+      "invalid_source_path",
+      "sourcePath must be a Markdown file inside the workspace.",
+    );
+  }
+
+  let canonicalRoot;
+  let canonicalSource;
+  try {
+    [canonicalRoot, canonicalSource] = await Promise.all([realpath(root), realpath(candidate)]);
+  } catch (_) {
+    throw sourceError("source_file_not_found", `Markdown file not found: ${sourcePath}`);
+  }
+  if (
+    !isPathInside(canonicalRoot, canonicalSource) ||
+    resolve(canonicalSource) !== resolve(candidate)
+  ) {
+    throw sourceError(
+      "invalid_source_path",
+      "sourcePath must resolve directly to a Markdown file inside the workspace.",
+    );
+  }
+  const info = await stat(canonicalSource);
+  if (!info.isFile()) {
+    throw sourceError("source_file_not_found", `Markdown file not found: ${sourcePath}`);
+  }
+  if (info.size > MARKDOWN_MAX_BYTES) {
+    throw sourceError("source_file_too_large", "The Markdown file is too large to edit.");
+  }
+  return {
+    root: canonicalRoot,
+    path: canonicalSource,
+    relativePath: relative(canonicalRoot, canonicalSource),
+    mode: info.mode,
+  };
+}
+
+export async function readArchitectureSourceTarget(workspaceRoot, sourcePath, blockIndex) {
+  if (!Number.isInteger(blockIndex) || blockIndex < 0) {
+    throw sourceError("invalid_block_index", "blockIndex must be a non-negative integer.");
+  }
+  const target = await resolveArchitectureSourceTarget(workspaceRoot, sourcePath);
+  const markdown = await readFile(target.path, "utf8");
+  const block = findArchitectureBlocks(markdown)[blockIndex];
+  if (!block) {
+    throw sourceError(
+      "block_not_found",
+      `Architecture block ${blockIndex} was not found in ${sourcePath}.`,
+    );
+  }
+  try {
+    parseArchitecture(block.body);
+  } catch (error) {
+    throw sourceError("invalid_architecture", error?.message || "Invalid Architecture DSL.");
+  }
+  return { ...target, markdown, source: block.body };
+}
+
+export function saveArchitectureSource({
+  workspaceRoot,
+  sourcePath,
+  sourceFile,
+  blockIndex,
+  source,
+  expectedMarkdown,
+}) {
+  const queuePath = sourceFile || resolve(workspaceRoot, sourcePath);
+  return serializeMarkdownSave(queuePath, async () => {
+    try {
+      parseArchitecture(source);
+    } catch (error) {
+      return {
+        ok: false,
+        error: "invalid_architecture",
+        message: error?.message || "The diagram is invalid.",
+      };
+    }
+
+    let target;
+    try {
+      target = await resolveArchitectureSourceTarget(workspaceRoot, sourcePath);
+    } catch (error) {
+      return {
+        ok: false,
+        error:
+          error?.code === "source_file_too_large" ? "source_file_too_large" : "source_changed",
+        message: "The source Markdown target changed outside the editor. Reload before saving.",
+      };
+    }
+    if (sourceFile && resolve(target.path) !== resolve(sourceFile)) {
+      return {
+        ok: false,
+        error: "source_changed",
+        message: "The source Markdown target changed outside the editor. Reload before saving.",
+      };
+    }
+
+    let markdown;
+    try {
+      markdown = await readFile(target.path, "utf8");
+    } catch (_) {
+      return {
+        ok: false,
+        error: "source_file_not_found",
+        message: "The source Markdown file no longer exists.",
+      };
+    }
+    if (markdown !== expectedMarkdown) {
+      return {
+        ok: false,
+        error: "source_changed",
+        message: "The source Markdown changed outside the editor. Reload before saving.",
+      };
+    }
+
+    const next = replaceArchitectureBlock(markdown, blockIndex, source);
+    if (next === null) {
+      return {
+        ok: false,
+        error: "block_not_found",
+        message: "The Architecture block no longer exists.",
+      };
+    }
+    try {
+      await atomicReplaceMarkdown({
+        path: target.path,
+        markdown: next,
+        expectedMarkdown: markdown,
+        mode: target.mode,
+        revalidate: async () => {
+          try {
+            const verified = await resolveArchitectureSourceTarget(workspaceRoot, sourcePath);
+            if (resolve(verified.path) === resolve(target.path)) return;
+          } catch (_) {
+            // Target replacement and removal are both write conflicts.
+          }
+          throw sourceError("SOURCE_CHANGED", "source_changed");
+        },
+      });
+    } catch (error) {
+      if (error?.code === "SOURCE_CHANGED") {
+        return {
+          ok: false,
+          error: "source_changed",
+          message: "The source Markdown changed while it was being saved.",
+        };
+      }
+      return {
+        ok: false,
+        error: "source_write_failed",
+        message: error?.message || "The source Markdown could not be saved.",
+      };
+    }
+    return {
+      ok: true,
+      sourcePath: target.relativePath.split(sep).join("/"),
+      blockIndex,
+      markdown: next,
+    };
+  });
+}

package/shared/runtime/browser.mjs

@@ -427,9 +427,8 @@ async function waitForOutputJob(job, child, diagnostics) {
   }
 }
 
-export async function runCdpOutputBrowser(browser, pageUrl, profileDir, job, capturePng) {
+function launchCdpOutputBrowser(browser, profileDir) {
   const diagnostics = { value: "" };
-  await rm(join(profileDir, "DevToolsActivePort"), { force: true }).catch(() => {});
   const args = withSandboxFallback([
     "--headless=new",
     "--disable-gpu",
@@ -457,7 +456,12 @@ export async function runCdpOutputBrowser(browser, pageUrl, profileDir, job, cap
   };
   child.stdout.on("data", appendDiagnostics);
   child.stderr.on("data", appendDiagnostics);
+  return { child, diagnostics };
+}
 
+async function openCdpOutputPage(browser, pageUrl, profileDir, job) {
+  await rm(join(profileDir, "DevToolsActivePort"), { force: true }).catch(() => {});
+  const { child, diagnostics } = launchCdpOutputBrowser(browser, profileDir);
   let cdp = null;
   try {
     const port = await waitForDevToolsPort(profileDir, child, diagnostics);
@@ -475,6 +479,22 @@ export async function runCdpOutputBrowser(browser, pageUrl, profileDir, job, cap
       throw new Error(`Chromium could not open the renderer: ${navigation.errorText}`);
     }
     await waitForOutputJob(job, child, diagnostics);
+    return { cdp, child };
+  } catch (error) {
+    cdp?.close();
+    if (isProcessRunning(child)) await terminateProcessTree(child);
+    throw error;
+  }
+}
+
+async function closeCdpOutputPage(cdp, child) {
+  cdp?.close();
+  if (isProcessRunning(child)) await terminateProcessTree(child);
+}
+
+export async function runCdpOutputBrowser(browser, pageUrl, profileDir, job, capturePng) {
+  const { cdp, child } = await openCdpOutputPage(browser, pageUrl, profileDir, job);
+  try {
     if (!capturePng) return null;
     await cdp.send("Runtime.evaluate", {
       expression:
@@ -491,8 +511,55 @@ export async function runCdpOutputBrowser(browser, pageUrl, profileDir, job, cap
     }
     return Buffer.from(screenshot.data, "base64");
   } finally {
-    cdp?.close();
-    if (isProcessRunning(child)) await terminateProcessTree(child);
+    await closeCdpOutputPage(cdp, child);
+  }
+}
+
+export async function runPptxOutputBrowser(browser, pageUrl, profileDir, job, total) {
+  const { cdp, child } = await openCdpOutputPage(browser, pageUrl, profileDir, job);
+  try {
+    const evaluated = await cdp.send("Runtime.evaluate", {
+      expression: "window.__presentationPptxModel",
+      returnByValue: true,
+    });
+    if (evaluated.exceptionDetails) {
+      throw new Error(
+        evaluated.exceptionDetails.text || "The renderer could not expose the PowerPoint model.",
+      );
+    }
+    const model = evaluated.result?.value;
+    if (!model || !Array.isArray(model.slides) || model.slides.length !== total) {
+      throw new Error("The renderer returned an invalid PowerPoint export model.");
+    }
+
+    await cdp.send("Runtime.evaluate", {
+      expression:
+        "new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))",
+      awaitPromise: true,
+    });
+
+    const backgrounds = [];
+    for (let index = 0; index < total; index += 1) {
+      const screenshot = await cdp.send("Page.captureScreenshot", {
+        format: "png",
+        fromSurface: true,
+        captureBeyondViewport: true,
+        clip: {
+          x: 0,
+          y: index * 720,
+          width: 1280,
+          height: 720,
+          scale: 1,
+        },
+      });
+      if (typeof screenshot.data !== "string" || screenshot.data.length === 0) {
+        throw new Error(`Chromium did not return fallback artwork for slide ${index + 1}.`);
+      }
+      backgrounds.push(Buffer.from(screenshot.data, "base64"));
+    }
+    return { model, backgrounds };
+  } finally {
+    await closeCdpOutputPage(cdp, child);
   }
 }
 

package/shared/runtime/deck-session.mjs

@@ -123,6 +123,7 @@ export async function createDeckSession({
     url: "",
     version: 0,
     deckVersion: 0,
+    sourceMarkdown: "",
     markdown: "",
     slides: [],
     index: 0,
@@ -144,7 +145,7 @@ export async function createDeckSession({
   };
 
   session.load = async ({ preserveIndex = false } = {}) => {
-    const { slides } = await readDeckSlides(session.file);
+    const { markdown, slides } = await readDeckSlides(session.file);
     const selection = resolveDeckTheme({
       slides,
       explicitTheme: session.requestedTheme,
@@ -166,6 +167,7 @@ export async function createDeckSession({
     session.customThemeDir = custom.dir;
     session.customThemeMeta = custom.metadata;
     session.customThemeAssets = new Set(custom.assets);
+    session.sourceMarkdown = markdown;
     session.slides = ensureBackCover(slides.slice());
     session.index = clampIndex(preserveIndex ? session.index : 0, session.slides.length);
     session.markdown = session.slides[session.index] ?? "";

package/shared/runtime/output-paths.mjs

@@ -1,7 +1,7 @@
 // Workspace-confined output path resolution shared by the Canvas Extension and
 // the MarkdStage CLI.
 //
-// Every generated file (PDF, PNG) must land inside the resolved workspace, and
+// Every generated file (PDF, PPTX, PNG) must land inside the resolved workspace, and
 // no intermediate directory may traverse a symlink or junction that escapes it.
 
 import { mkdir, realpath, stat } from "node:fs/promises";
@@ -18,6 +18,7 @@ import {
 import { MarkdStageError } from "./errors.mjs";
 
 export const DEFAULT_PDF_NAME = "markdstage.pdf";
+export const DEFAULT_PPTX_NAME = "markdstage.pptx";
 export const DEFAULT_CAPTURE_DIR = "markdstage-previews";
 
 function safeBaseName(sourceName) {
@@ -33,6 +34,10 @@ export function pdfNameForSource(sourceName) {
   return `${safeBaseName(sourceName) || basename(DEFAULT_PDF_NAME, ".pdf")}.pdf`;
 }
 
+export function pptxNameForSource(sourceName) {
+  return `${safeBaseName(sourceName) || basename(DEFAULT_PPTX_NAME, ".pptx")}.pptx`;
+}
+
 export function captureDirectoryName(sourceName) {
   const safeBase = safeBaseName(sourceName);
   return safeBase ? `${safeBase}-previews` : DEFAULT_CAPTURE_DIR;
@@ -95,6 +100,14 @@ export function resolvePdfOutputPath(workspaceRoot, requestedPath) {
   });
 }
 
+export function resolvePptxOutputPath(workspaceRoot, requestedPath) {
+  return resolveWorkspaceOutputPath(workspaceRoot, requestedPath, {
+    defaultName: DEFAULT_PPTX_NAME,
+    extension: ".pptx",
+    label: "PowerPoint",
+  });
+}
+
 export function resolveCaptureOutputDirectory(workspaceRoot, sourceName, requestedPath) {
   const root = resolve(workspaceRoot);
   const requested =
@@ -157,3 +170,7 @@ export async function prepareWorkspaceDirectory(workspaceRoot, outputParent, lab
 export async function preparePdfOutputDirectory(workspaceRoot, outputPath) {
   return prepareWorkspaceDirectory(workspaceRoot, dirname(outputPath), "PDF");
 }
+
+export async function preparePptxOutputDirectory(workspaceRoot, outputPath) {
+  return prepareWorkspaceDirectory(workspaceRoot, dirname(outputPath), "PowerPoint");
+}

package/shared/runtime/output.mjs

@@ -1,4 +1,4 @@
-// PDF export, PNG capture, and fixed 16:9 layout inspection.
+// PDF/PowerPoint export, PNG capture, and fixed 16:9 layout inspection.
 //
 // The Canvas Extension and the MarkdStage CLI share this implementation so both
 // produce byte-identical output. Callers provide a session object with:
@@ -17,17 +17,27 @@ import {
   findChromiumBrowser,
   runCdpOutputBrowser,
   runPdfBrowser,
+  runPptxOutputBrowser,
   verifyPdf,
   verifyPng,
 } from "./browser.mjs";
 import {
   prepareWorkspaceDirectory,
   preparePdfOutputDirectory,
+  preparePptxOutputDirectory,
   resolveCaptureOutputDirectory,
   resolvePdfOutputPath,
+  resolvePptxOutputPath,
 } from "./output-paths.mjs";
+import {
+  buildPptxPackage,
+  inspectPptxPackage,
+  PPTX_DIMENSIONS,
+} from "./pptx-package.mjs";
 
 export const MAX_CAPTURE_SLIDES = 10;
+export const MAX_PPTX_ASSET_BYTES = 10 * 1024 * 1024;
+export const MAX_PPTX_TOTAL_ASSET_BYTES = 100 * 1024 * 1024;
 
 function logFor(inst, message, level = "info") {
   try {
@@ -70,6 +80,142 @@ export function createOutputJob(snapshot, kind) {
   };
 }
 
+function decodeDataImage(source) {
+  const match = /^data:(image\/(?:png|jpeg|gif))(;base64)?,([\s\S]*)$/i.exec(source);
+  if (!match) {
+    throw new Error("Only PNG, JPEG, or GIF data URLs can be embedded in PowerPoint.");
+  }
+  const data = match[2]
+    ? Buffer.from(match[3], "base64")
+    : Buffer.from(decodeURIComponent(match[3]), "binary");
+  return { data, contentType: match[1].toLowerCase() };
+}
+
+function ensurePptxAssetSize(data, source, currentTotal) {
+  if (data.length > MAX_PPTX_ASSET_BYTES) {
+    throw new Error(
+      `PowerPoint image exceeds ${MAX_PPTX_ASSET_BYTES} bytes: ${source}`,
+    );
+  }
+  if (currentTotal + data.length > MAX_PPTX_TOTAL_ASSET_BYTES) {
+    throw new Error(
+      `PowerPoint image assets exceed ${MAX_PPTX_TOTAL_ASSET_BYTES} bytes in total.`,
+    );
+  }
+}
+
+async function loadPptxImage(inst, source, fetchImpl, currentTotal) {
+  if (typeof source !== "string" || !source) {
+    throw new Error("PowerPoint image is missing its source URL.");
+  }
+  if (source.startsWith("data:")) {
+    const decoded = decodeDataImage(source);
+    ensurePptxAssetSize(decoded.data, "data URL", currentTotal);
+    return decoded;
+  }
+
+  const base = new URL(inst.url);
+  const url = new URL(source, base);
+  if (url.origin !== base.origin) {
+    throw new Error(`PowerPoint image must be served by the MarkdStage workspace: ${source}`);
+  }
+  const response = await fetchImpl(url, { cache: "no-store" });
+  if (!response.ok) {
+    throw new Error(`Could not load PowerPoint image (${response.status}): ${source}`);
+  }
+  const data = Buffer.from(await response.arrayBuffer());
+  ensurePptxAssetSize(data, source, currentTotal);
+  const responseType = response.headers.get("content-type")?.split(";")[0].trim().toLowerCase();
+  const contentType = ["image/png", "image/jpeg", "image/gif"].includes(responseType)
+    ? responseType
+    : undefined;
+  return { data, contentType };
+}
+
+export async function preparePptxPackageModel(
+  inst,
+  model,
+  backgrounds,
+  fetchImpl = fetch,
+) {
+  if (
+    !model ||
+    model.version !== 1 ||
+    model.width !== PPTX_DIMENSIONS.widthPx ||
+    model.height !== PPTX_DIMENSIONS.heightPx ||
+    !Array.isArray(model.slides) ||
+    model.slides.length === 0
+  ) {
+    throw new Error("The renderer returned an unsupported PowerPoint export model.");
+  }
+  if (!Array.isArray(backgrounds) || backgrounds.length !== model.slides.length) {
+    throw new Error("PowerPoint fallback artwork does not match the slide count.");
+  }
+
+  const assets = [];
+  const sourceAssets = new Map();
+  let totalAssetBytes = 0;
+  for (const [index, background] of backgrounds.entries()) {
+    if (!Buffer.isBuffer(background)) {
+      throw new Error(`PowerPoint fallback artwork for slide ${index + 1} is invalid.`);
+    }
+    ensurePptxAssetSize(background, `slide ${index + 1} fallback artwork`, totalAssetBytes);
+    totalAssetBytes += background.length;
+    assets.push({
+      id: `markdstage-background-${index + 1}`,
+      contentType: "image/png",
+      data: background,
+    });
+  }
+
+  const slides = [];
+  for (const [slideIndex, sourceSlide] of model.slides.entries()) {
+    if (!sourceSlide || !Array.isArray(sourceSlide.elements)) {
+      throw new Error(`PowerPoint slide ${slideIndex + 1} has an invalid element list.`);
+    }
+    const elements = [];
+    for (const sourceElement of sourceSlide.elements) {
+      if (sourceElement?.type !== "image") {
+        elements.push(sourceElement);
+        continue;
+      }
+      const source = sourceElement.src;
+      let assetId = sourceAssets.get(source);
+      if (!assetId) {
+        const loaded = await loadPptxImage(inst, source, fetchImpl, totalAssetBytes);
+        totalAssetBytes += loaded.data.length;
+        assetId = `markdstage-image-${sourceAssets.size + 1}`;
+        sourceAssets.set(source, assetId);
+        assets.push({ id: assetId, ...loaded });
+      }
+      const { src: _src, source: _source, ...image } = sourceElement;
+      if (
+        (image.fit === "contain" || image.fit === "scale-down") &&
+        image.naturalWidth > 0 &&
+        image.naturalHeight > 0
+      ) {
+        const scale = Math.min(
+          image.width / image.naturalWidth,
+          image.height / image.naturalHeight,
+          image.fit === "scale-down" ? 1 : Number.POSITIVE_INFINITY,
+        );
+        const width = image.naturalWidth * scale;
+        const height = image.naturalHeight * scale;
+        image.x += (image.width - width) / 2;
+        image.y += (image.height - height) / 2;
+        image.width = width;
+        image.height = height;
+      }
+      elements.push({ ...image, assetId });
+    }
+    slides.push({
+      backgroundAssetId: `markdstage-background-${slideIndex + 1}`,
+      elements,
+    });
+  }
+  return { slides, assets };
+}
+
 async function runLayoutInspectionJob(inst, snapshot, browser) {
   const token = randomUUID();
   const profileDir = await mkdtemp(join(tmpdir(), "markdstage-inspect-"));
@@ -114,7 +260,7 @@ export async function inspectLayout(inst, requestedIndex, includeFits = false) {
   if (inst.exporting) {
     throw new MarkdStageError(
       "output_in_progress",
-      "Another PDF, layout inspection, or PNG output job is already running for this canvas.",
+      "Another PDF, PowerPoint, layout inspection, or PNG output job is already running for this canvas.",
     );
   }
   const snapshot = createOutputSnapshot(inst);
@@ -194,7 +340,7 @@ export async function captureSlides(
   if (inst.exporting) {
     throw new MarkdStageError(
       "output_in_progress",
-      "Another PDF, layout inspection, or PNG output job is already running for this canvas.",
+      "Another PDF, PowerPoint, layout inspection, or PNG output job is already running for this canvas.",
     );
   }
   const snapshot = createOutputSnapshot(inst, requestedTheme);
@@ -315,9 +461,10 @@ export async function exportPdf(inst, requestedPath, requestedTheme) {
   if (inst.exporting) {
     throw new MarkdStageError(
       "export_in_progress",
-      "Another PDF, layout inspection, or PNG output job is already running for this canvas.",
+      "Another PDF, PowerPoint, layout inspection, or PNG output job is already running for this canvas.",
     );
   }
+
   inst.exporting = true;
   let token = "";
   let profileDir = "";
@@ -362,6 +509,7 @@ export async function exportPdf(inst, requestedPath, requestedTheme) {
     logFor(inst, `MarkdStage: exported ${snapshot.slides.length} slides to ${outputPath}`);
     return {
       ok: true,
+      format: "pdf",
       path: outputPath,
       total: snapshot.slides.length,
       theme: snapshot.theme,
@@ -383,3 +531,118 @@ export async function exportPdf(inst, requestedPath, requestedTheme) {
     }
   }
 }
+
+export async function exportPptx(
+    inst,
+    requestedPath,
+    requestedTheme,
+    dependencies = {},
+) {
+    const findBrowser = dependencies.findChromiumBrowser ?? findChromiumBrowser;
+    const runBrowser = dependencies.runPptxOutputBrowser ?? runPptxOutputBrowser;
+    const prepareModel = dependencies.preparePptxPackageModel ?? preparePptxPackageModel;
+    const buildPackage = dependencies.buildPptxPackage ?? buildPptxPackage;
+    const inspectPackage = dependencies.inspectPptxPackage ?? inspectPptxPackage;
+    if (inst.exporting) {
+      throw new MarkdStageError(
+        "export_in_progress",
+        "Another PDF, PowerPoint, layout inspection, or PNG output job is already running for this canvas.",
+      );
+    }
+    inst.exporting = true;
+    let token = "";
+    let profileDir = "";
+    let temporaryOutputPath = "";
+
+    try {
+      const snapshot = createOutputSnapshot(inst, requestedTheme);
+      if (!snapshot.slides.length) {
+        throw new MarkdStageError(
+          "no_deck",
+          "No slides are loaded. Load a deck before exporting PowerPoint.",
+        );
+      }
+
+      const browser = findBrowser();
+      if (!browser) {
+        throw new MarkdStageError(
+          "pptx_browser_not_found",
+          "PowerPoint export requires Microsoft Edge, Google Chrome, or Chromium.",
+        );
+      }
+
+      const outputPath = resolvePptxOutputPath(inst.workspaceRoot, requestedPath);
+      const outputParent = await preparePptxOutputDirectory(inst.workspaceRoot, outputPath);
+      token = randomUUID();
+      profileDir = await mkdtemp(join(tmpdir(), "markdstage-pptx-"));
+      const outputBase = basename(outputPath, extname(outputPath)) || "markdstage";
+      temporaryOutputPath = join(outputParent, `.${outputBase}.${token}.tmp.pptx`);
+      const job = createOutputJob(snapshot, "pptx");
+      inst.exportJobs.set(token, job);
+
+      const pageUrl = pageUrlFor(inst, { pptx: 1, token });
+      const { model, backgrounds } = await runBrowser(
+        browser,
+        pageUrl,
+        profileDir,
+        job,
+        snapshot.slides.length,
+      );
+      const packageModel = await prepareModel(inst, model, backgrounds);
+      const buffer = buildPackage({
+        title: model.slides[0]?.title || outputBase,
+        ...packageModel,
+      });
+      const packageSummary = inspectPackage(buffer);
+      if (
+        !packageSummary.valid ||
+        packageSummary.slideCount !== snapshot.slides.length ||
+        packageSummary.dimensions.widthEmu !== PPTX_DIMENSIONS.widthEmu ||
+        packageSummary.dimensions.heightEmu !== PPTX_DIMENSIONS.heightEmu
+      ) {
+        throw new Error("The generated PowerPoint package failed validation.");
+      }
+
+      await writeFile(temporaryOutputPath, buffer);
+      await rename(temporaryOutputPath, outputPath);
+      temporaryOutputPath = "";
+      const fallbacks = model.slides.flatMap((slide, slideIndex) =>
+        (Array.isArray(slide.fallbacks) ? slide.fallbacks : []).map((fallback) => ({
+          slideIndex,
+          page: slideIndex + 1,
+          ...fallback,
+        })),
+      );
+      logFor(
+        inst,
+        `MarkdStage: exported ${snapshot.slides.length} slides to ${outputPath} (${fallbacks.length} fallbacks)`,
+      );
+      return {
+        ok: true,
+        format: "pptx",
+        path: outputPath,
+        total: snapshot.slides.length,
+        theme: snapshot.theme,
+        bytes: buffer.length,
+        fallbackCount: fallbacks.length,
+        fallbacks,
+      };
+    } catch (error) {
+      if (error instanceof MarkdStageError) throw error;
+      throw new MarkdStageError(
+        "pptx_export_failed",
+        error?.message || "PowerPoint export failed.",
+      );
+    } finally {
+      if (token) {
+        inst.exportJobs.delete(token);
+      }
+      if (temporaryOutputPath) {
+        await rm(temporaryOutputPath, { force: true }).catch(() => {});
+      }
+      inst.exporting = false;
+      if (profileDir) {
+        await rm(profileDir, { recursive: true, force: true }).catch(() => {});
+    }
+  }
+}