@markdstage/markdstage 3.4.0 → 3.8.1

package/shared/runtime/pptx-package.mjs

@@ -19,6 +19,9 @@ const NS_REL =
 const JAPANESE_FONT_FACE = "Yu Gothic";
 const HUNDREDTH_POINTS_PER_PIXEL = 75;
 const SLIDE_LAYOUT_ID_BASE = 2147500000;
+const DRAWINGML_ANGLE_UNITS_PER_DEGREE = 60000;
+const DRAWINGML_HALF_TURN = 180 * DRAWINGML_ANGLE_UNITS_PER_DEGREE;
+const DRAWINGML_FULL_TURN = 360 * DRAWINGML_ANGLE_UNITS_PER_DEGREE;
 
 const REL = {
   officeDocument: `${NS_R}/officeDocument`,
@@ -111,6 +114,33 @@ function optionalUnitInterval(value, path, fallback = 1) {
   return number;
 }
 
+function optionalOwnUnitInterval(value, key, path, fallback = 1) {
+  if (!Object.hasOwn(value, key)) {
+    if (key in value) fail(`${path}.${key} must be an own property`);
+    return fallback;
+  }
+  return optionalUnitInterval(value[key], `${path}.${key}`, fallback);
+}
+
+function optionalOwnRotationUnits(value, path) {
+  if (!Object.hasOwn(value, "rotation")) {
+    if ("rotation" in value) fail(`${path}.rotation must be an own property`);
+    return 0;
+  }
+  const rotation = finiteNumber(value.rotation, `${path}.rotation`);
+  let units = Math.round((((rotation % 360) + 360) % 360) * DRAWINGML_ANGLE_UNITS_PER_DEGREE);
+  if (units >= DRAWINGML_HALF_TURN) units -= DRAWINGML_FULL_TURN;
+  return units === 0 ? 0 : units;
+}
+
+function paintOpacities(element, path) {
+  return {
+    opacity: optionalOwnUnitInterval(element, "opacity", path),
+    fillOpacity: optionalOwnUnitInterval(element, "fillOpacity", path),
+    strokeOpacity: optionalOwnUnitInterval(element, "strokeOpacity", path),
+  };
+}
+
 function boundsOf(value, path) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     fail(`${path} must be an object`);
@@ -127,8 +157,9 @@ function emu(value) {
   return Math.round(value * PPTX_DIMENSIONS.emusPerPx);
 }
 
-function xfrmXml(bounds, tag = "a:xfrm") {
-  return `<${tag}><a:off x="${emu(bounds.x)}" y="${emu(bounds.y)}"/><a:ext cx="${emu(bounds.width)}" cy="${emu(bounds.height)}"/></${tag}>`;
+function xfrmXml(bounds, tag = "a:xfrm", rotationUnits = 0) {
+  const rotation = rotationUnits ? ` rot="${rotationUnits}"` : "";
+  return `<${tag}${rotation}><a:off x="${emu(bounds.x)}" y="${emu(bounds.y)}"/><a:ext cx="${emu(bounds.width)}" cy="${emu(bounds.height)}"/></${tag}>`;
 }
 
 function parseChannel(value, path) {
@@ -210,16 +241,25 @@ function colorXml(value, path, opacity = 1) {
   return color ? `<a:solidFill>${color}</a:solidFill>` : "<a:noFill/>";
 }
 
-function lineXml(element, path) {
+function lineCapXml(value, path) {
+  if (value === undefined) return "";
+  const caps = { butt: "flat", round: "rnd", square: "sq" };
+  if (typeof value !== "string" || !Object.hasOwn(caps, value)) fail(`${path} is not a supported line cap`);
+  return ` cap="${caps[value]}"`;
+}
+
+function lineXml(element, path, opacities = paintOpacities(element, path)) {
   const width = element.strokeWidth === undefined
     ? 1
     : positiveNumber(element.strokeWidth, `${path}.strokeWidth`);
   const color = colorOf(element.stroke, `${path}.stroke`);
-  if (!color) return `<a:ln w="${emu(width)}"><a:noFill/></a:ln>`;
-  const opacity = optionalUnitInterval(element.opacity, `${path}.opacity`);
-  const alpha = Math.round(color.alpha * opacity * 100000);
+  const cap = lineCapXml(element.lineCap, `${path}.lineCap`);
+  if (!color) return `<a:ln w="${emu(width)}"${cap}><a:noFill/></a:ln>`;
+  const alpha = Math.round(
+    color.alpha * opacities.opacity * opacities.strokeOpacity * 100000,
+  );
   const dash = dashXml(element.dash, `${path}.dash`);
-  return `<a:ln w="${emu(width)}"><a:solidFill><a:srgbClr val="${color.hex}">${
+  return `<a:ln w="${emu(width)}"${cap}><a:solidFill><a:srgbClr val="${color.hex}">${
     alpha < 100000 ? `<a:alpha val="${alpha}"/>` : ""
   }</a:srgbClr></a:solidFill>${dash}</a:ln>`;
 }
@@ -468,9 +508,9 @@ function runXml(run, path, relationships) {
     .filter(Boolean)
     .join(" ");
   let properties = colorXml(
-    run.color ?? "#000000",
+    run.color === undefined ? "#000000" : run.color,
     `${path}.color`,
-    optionalUnitInterval(run.opacity, `${path}.opacity`),
+    optionalOwnUnitInterval(run, "opacity", path),
   );
   if (run.fontFace !== undefined) {
     if (typeof run.fontFace !== "string" || !run.fontFace) {
@@ -548,12 +588,13 @@ function textBodyXml(
   return `<${tag}>${textBodyPropertiesXml(bodyOptions, bodyPath)}<a:lstStyle/>${paragraphs}</${tag}>`;
 }
 
-function shapeBase(id, name, bounds, properties, text = "") {
-  return `<p:sp><p:nvSpPr><p:cNvPr id="${id}" name="${xmlEscape(name)}"/><p:cNvSpPr/><p:nvPr/></p:nvSpPr><p:spPr>${xfrmXml(bounds)}${properties}</p:spPr>${text}</p:sp>`;
+function shapeBase(id, name, bounds, properties, text = "", rotationUnits = 0) {
+  return `<p:sp><p:nvSpPr><p:cNvPr id="${id}" name="${xmlEscape(name)}"/><p:cNvSpPr/><p:nvPr/></p:nvSpPr><p:spPr>${xfrmXml(bounds, "a:xfrm", rotationUnits)}${properties}</p:spPr>${text}</p:sp>`;
 }
 
 function textShapeXml(element, path, id, relationships) {
   const bounds = boundsOf(element, path);
+  const rotationUnits = optionalOwnRotationUnits(element, path);
   const text = { paragraphs: element.paragraphs };
   const paragraphs = Array.isArray(text.paragraphs) ? text.paragraphs : [];
   const bulletInsetPx = Math.max(
@@ -584,6 +625,7 @@ function textShapeXml(element, path, id, relationships) {
       path,
       bulletInsetPx,
     ),
+    rotationUnits,
   );
 }
 
@@ -604,7 +646,8 @@ function shapeTextOf(element, path) {
 
 function nativeShapeXml(element, path, id, relationships) {
   const bounds = boundsOf(element, path);
-  const preset = {
+  const rotationUnits = optionalOwnRotationUnits(element, path);
+  const presets = {
     rect: "rect",
     roundedRect: "roundRect",
     ellipse: "ellipse",
@@ -612,18 +655,53 @@ function nativeShapeXml(element, path, id, relationships) {
     triangle: "triangle",
     hexagon: "hexagon",
     parallelogram: "parallelogram",
-  }[element.shape];
-  if (!preset) {
+  };
+  const customGeometries = {
+    quarterHeightHexagon: '<a:custGeom><a:avLst/><a:gdLst><a:gd name="dx" fmla="*/ h 1 4"/><a:gd name="rx" fmla="+- w 0 dx"/><a:gd name="cy" fmla="*/ h 1 2"/></a:gdLst><a:ahLst/><a:cxnLst/><a:rect l="l" t="t" r="r" b="b"/><a:pathLst><a:path><a:moveTo><a:pt x="dx" y="h"/></a:moveTo><a:lnTo><a:pt x="rx" y="h"/></a:lnTo><a:lnTo><a:pt x="w" y="cy"/></a:lnTo><a:lnTo><a:pt x="rx" y="0"/></a:lnTo><a:lnTo><a:pt x="dx" y="0"/></a:lnTo><a:lnTo><a:pt x="0" y="cy"/></a:lnTo><a:close/></a:path></a:pathLst></a:custGeom>',
+    sequenceTab: '<a:custGeom><a:avLst/><a:gdLst/><a:ahLst/><a:cxnLst/><a:rect l="l" t="t" r="r" b="b"/><a:pathLst><a:path w="50000" h="20000"><a:moveTo><a:pt x="0" y="0"/></a:moveTo><a:lnTo><a:pt x="50000" y="0"/></a:lnTo><a:lnTo><a:pt x="50000" y="13000"/></a:lnTo><a:lnTo><a:pt x="41600" y="20000"/></a:lnTo><a:lnTo><a:pt x="0" y="20000"/></a:lnTo><a:close/></a:path></a:pathLst></a:custGeom>',
+    reverseParallelogram: '<a:custGeom><a:avLst/><a:gdLst><a:gd name="dx" fmla="*/ h 1 2"/><a:gd name="rx" fmla="+- w 0 dx"/></a:gdLst><a:ahLst/><a:cxnLst/><a:rect l="l" t="t" r="r" b="b"/><a:pathLst><a:path><a:moveTo><a:pt x="dx" y="h"/></a:moveTo><a:lnTo><a:pt x="w" y="h"/></a:lnTo><a:lnTo><a:pt x="rx" y="0"/></a:lnTo><a:lnTo><a:pt x="0" y="0"/></a:lnTo><a:close/></a:path></a:pathLst></a:custGeom>',
+    trapezoid: '<a:custGeom><a:avLst/><a:gdLst><a:gd name="dx" fmla="*/ h 1 2"/><a:gd name="rx" fmla="+- w 0 dx"/></a:gdLst><a:ahLst/><a:cxnLst/><a:rect l="l" t="t" r="r" b="b"/><a:pathLst><a:path><a:moveTo><a:pt x="0" y="h"/></a:moveTo><a:lnTo><a:pt x="w" y="h"/></a:lnTo><a:lnTo><a:pt x="rx" y="0"/></a:lnTo><a:lnTo><a:pt x="dx" y="0"/></a:lnTo><a:close/></a:path></a:pathLst></a:custGeom>',
+    invertedTrapezoid: '<a:custGeom><a:avLst/><a:gdLst><a:gd name="dx" fmla="*/ h 1 2"/><a:gd name="rx" fmla="+- w 0 dx"/></a:gdLst><a:ahLst/><a:cxnLst/><a:rect l="l" t="t" r="r" b="b"/><a:pathLst><a:path><a:moveTo><a:pt x="dx" y="h"/></a:moveTo><a:lnTo><a:pt x="rx" y="h"/></a:lnTo><a:lnTo><a:pt x="w" y="0"/></a:lnTo><a:lnTo><a:pt x="0" y="0"/></a:lnTo><a:close/></a:path></a:pathLst></a:custGeom>',
+  };
+  const adjustedGeometries = {
+    stadium: '<a:prstGeom prst="roundRect"><a:avLst><a:gd name="adj" fmla="val 50000"/></a:avLst></a:prstGeom>',
+  };
+  if (element.shape === "topRoundedRect") {
+    const radius = Math.min(nonNegativeNumber(element.cornerRadius === undefined ? 5 : element.cornerRadius, `${path}.cornerRadius`),
+      bounds.width / 2, bounds.height / 2);
+    const r = Math.round(radius * 9525);
+    // This bounded preset retains Mermaid's two quadratic top corners and square bottom.
+    customGeometries.topRoundedRect = `<a:custGeom><a:avLst/><a:gdLst><a:gd name="r" fmla="val ${r}"/><a:gd name="rx" fmla="+- w 0 r"/></a:gdLst><a:ahLst/><a:cxnLst/><a:rect l="l" t="t" r="r" b="b"/><a:pathLst><a:path><a:moveTo><a:pt x="0" y="h"/></a:moveTo><a:lnTo><a:pt x="0" y="r"/></a:lnTo><a:quadBezTo><a:pt x="0" y="0"/><a:pt x="r" y="0"/></a:quadBezTo><a:lnTo><a:pt x="rx" y="0"/></a:lnTo><a:quadBezTo><a:pt x="w" y="0"/><a:pt x="w" y="r"/></a:quadBezTo><a:lnTo><a:pt x="w" y="h"/></a:lnTo><a:close/></a:path></a:pathLst></a:custGeom>`;
+  }
+  if (element.shape === "roundedRect" && element.cornerRadius !== undefined) {
+    const radius = nonNegativeNumber(element.cornerRadius, `${path}.cornerRadius`);
+    const adjustment = Math.round(Math.min(50000,
+      radius / Math.min(bounds.width, bounds.height) * 100000));
+    adjustedGeometries.roundedRect =
+      `<a:prstGeom prst="roundRect"><a:avLst><a:gd name="adj" fmla="val ${adjustment}"/></a:avLst></a:prstGeom>`;
+  }
+  const shape = Object.hasOwn(element, "shape") ? element.shape : undefined;
+  const preset = typeof shape === "string" && Object.hasOwn(presets, shape) ? presets[shape] : "";
+  const customGeometry = typeof shape === "string" && Object.hasOwn(customGeometries, shape)
+    ? customGeometries[shape]
+    : "";
+  const adjustedGeometry = typeof shape === "string" && Object.hasOwn(adjustedGeometries, shape)
+    ? adjustedGeometries[shape]
+    : "";
+  const geometry = adjustedGeometry || customGeometry || (preset
+      ? `<a:prstGeom prst="${preset}"><a:avLst/></a:prstGeom>`
+      : "");
+  if (!geometry) {
     fail(
-      `${path}.shape must be rect, roundedRect, ellipse, diamond, triangle, hexagon, or parallelogram`,
+      `${path}.shape must be rect, roundedRect, topRoundedRect, stadium, ellipse, diamond, triangle, hexagon, quarterHeightHexagon, parallelogram, reverseParallelogram, trapezoid, invertedTrapezoid, or sequenceTab`,
     );
   }
-  const opacity = optionalUnitInterval(element.opacity, `${path}.opacity`);
-  const properties = `${xfrmXml(bounds)}<a:prstGeom prst="${preset}"><a:avLst/></a:prstGeom>${colorXml(
+  const opacities = paintOpacities(element, path);
+  const properties = `${xfrmXml(bounds, "a:xfrm", rotationUnits)}${geometry}${colorXml(
     element.fill,
     `${path}.fill`,
-    opacity,
-  )}${lineXml(element, path)}`;
+    opacities.opacity * opacities.fillOpacity,
+  )}${lineXml(element, path, opacities)}`;
   const shapeText = shapeTextOf(element, path);
   if (!shapeText) textBodyPropertiesXml(element, path);
   const text = shapeText
@@ -741,9 +819,12 @@ function connectorXml(element, path, nextId, relationships) {
     : positiveNumber(element.strokeWidth, `${path}.strokeWidth`);
   const color = colorOf(element.stroke ?? "#000000", `${path}.stroke`);
   if (!color) fail(`${path}.stroke cannot be null`);
-  const opacity = optionalUnitInterval(element.opacity, `${path}.opacity`);
-  const alpha = Math.round(color.alpha * opacity * 100000);
+  const opacities = paintOpacities(element, path);
+  const alpha = Math.round(
+    color.alpha * opacities.opacity * opacities.strokeOpacity * 100000,
+  );
   const dash = dashXml(element.dash, `${path}.dash`);
+  const cap = lineCapXml(element.lineCap, `${path}.lineCap`);
   const shapes = [];
   for (let index = 0; index < points.length - 1; index += 1) {
     const start = points[index];
@@ -762,7 +843,7 @@ function connectorXml(element, path, nextId, relationships) {
         ? arrowXml(element.arrowEnd, `${path}.arrowEnd`)
         : "";
     shapes.push(
-      `<p:sp><p:nvSpPr><p:cNvPr id="${id}" name="Connector ${id}"/><p:cNvSpPr/><p:nvPr/></p:nvSpPr><p:spPr><a:xfrm${flipH}${flipV}><a:off x="${emu(x)}" y="${emu(y)}"/><a:ext cx="${emu(Math.abs(end.x - start.x))}" cy="${emu(Math.abs(end.y - start.y))}"/></a:xfrm><a:prstGeom prst="line"><a:avLst/></a:prstGeom><a:ln w="${emu(width)}"><a:solidFill><a:srgbClr val="${color.hex}">${
+      `<p:sp><p:nvSpPr><p:cNvPr id="${id}" name="Connector ${id}"/><p:cNvSpPr/><p:nvPr/></p:nvSpPr><p:spPr><a:xfrm${flipH}${flipV}><a:off x="${emu(x)}" y="${emu(y)}"/><a:ext cx="${emu(Math.abs(end.x - start.x))}" cy="${emu(Math.abs(end.y - start.y))}"/></a:xfrm><a:prstGeom prst="line"><a:avLst/></a:prstGeom><a:ln w="${emu(width)}"${cap}><a:solidFill><a:srgbClr val="${color.hex}">${
         alpha < 100000 ? `<a:alpha val="${alpha}"/>` : ""
       }</a:srgbClr></a:solidFill>${dash}${head}${tail}</a:ln></p:spPr></p:sp>`,
     );

package/shared/runtime/presentation-server.mjs

@@ -18,6 +18,7 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomBytes } from "node:crypto";
 import { resolveAssetFile } from "../scripts/asset-paths.mjs";
+import { loadSlideBackgrounds, resolveSlideBackgroundFile } from "./slide-backgrounds.mjs";
 import { importedArchitectureBlockIndex } from "../scripts/markdown-blocks.mjs";
 import { isMarkdownPath, listMarkdownFiles } from "../scripts/markdown-files.mjs";
 import { createMarkdownWatcher } from "../scripts/markdown-watcher.mjs";
@@ -26,6 +27,7 @@ import { saveArchitectureSource } from "./architecture-source.mjs";
 import { exportPdf, exportPptx } from "./output.mjs";
 import {
   isPathInside,
+  outputPathForSource,
   pdfNameForSource,
   pptxNameForSource,
 } from "./output-paths.mjs";
@@ -401,6 +403,7 @@ export async function startPresentationServer(
         themeLocked: job.themeLocked,
         customThemeCss: job.customThemeCss,
         customThemeMeta: job.customThemeMeta,
+        mermaidImageFallback: job.mermaidImageFallback === true,
       });
       return;
     }
@@ -674,6 +677,11 @@ export async function startPresentationServer(
             body: { ok: false, error: "block_not_found" },
           };
         }
+        try {
+          await loadSlideBackgrounds(session.workspaceRoot, session.sourceName, session.slides);
+        } catch (error) {
+          return { status: 400, body: { ok: false, error: error.code, message: error.message } };
+        }
         const result = await saveArchitectureSource({
           workspaceRoot: session.workspaceRoot,
           sourcePath: session.sourceName,
@@ -852,16 +860,34 @@ export async function startPresentationServer(
         return;
       }
       const pptx = route === "/export-pptx";
+      let body = {};
+      if (pptx) {
+        try {
+          body = await readJsonBody(req);
+          if (!body || typeof body !== "object" || Array.isArray(body) ||
+              (body.mermaidImageFallback !== undefined && typeof body.mermaidImageFallback !== "boolean")) {
+            throw new Error("invalid_export_options");
+          }
+        } catch (error) {
+          json(res, error?.message === "payload_too_large" ? 413 : 400, {
+            ok: false,
+            error: error?.message || "bad_request",
+          });
+          return;
+        }
+      }
       try {
         const result = pptx
           ? await exportPptxImpl(
               session,
-              pptxNameForSource(session.sourceName),
+              outputPathForSource(session.sourceName, pptxNameForSource(session.sourceName)),
               session.theme,
+              undefined,
+              { mermaidImageFallback: body.mermaidImageFallback === true },
             )
           : await exportPdfImpl(
               session,
-              pdfNameForSource(session.sourceName),
+              outputPathForSource(session.sourceName, pdfNameForSource(session.sourceName)),
               session.theme,
             );
         json(res, 200, result);
@@ -958,6 +984,22 @@ export async function startPresentationServer(
       return;
     }
 
+    if (route.startsWith("/background-assets/")) {
+      try {
+        const file = await resolveSlideBackgroundFile(
+          session.workspaceRoot,
+          session.sourceName,
+          `/assets/${route.slice("/background-assets/".length)}`,
+        );
+        await sendFile(res, file, { cache: false });
+      } catch (error) {
+        res.statusCode = error?.code === "slide_background_too_large" ? 413
+          : error?.code === "invalid_slide_background" ? 403 : 404;
+        res.end(error.message);
+      }
+      return;
+    }
+
     if (route.startsWith("/assets/")) {
       try {
         const abs = await resolveAssetFile(

package/shared/runtime/slide-backgrounds.mjs

@@ -0,0 +1,44 @@
+import { stat } from "node:fs/promises";
+import { parseSlideBackground } from "../renderer/slide-background.mjs";
+import { parseFrontMatter, THEME_ASSET_MAX_BYTES } from "../renderer/theme.mjs";
+import { resolveAssetFile } from "../scripts/asset-paths.mjs";
+import { MarkdStageError } from "./errors.mjs";
+
+export async function resolveSlideBackgroundFile(workspaceRoot, sourceName, value) {
+  let canonical;
+  try {
+    canonical = parseSlideBackground(value);
+  } catch (error) {
+    throw new MarkdStageError("invalid_slide_background", error.message);
+  }
+  if (!canonical) return null;
+  let file;
+  try {
+    file = await resolveAssetFile(workspaceRoot, sourceName, canonical.slice("/assets/".length));
+  } catch (error) {
+    throw new MarkdStageError("invalid_slide_background", `Invalid background-image ${canonical}: ${error.message}`);
+  }
+  if (!file) {
+    throw new MarkdStageError("slide_background_not_found", `Background image was not found: ${canonical}`);
+  }
+  const info = await stat(file);
+  if (!info.isFile()) {
+    throw new MarkdStageError("slide_background_not_found", `Background image is not a file: ${canonical}`);
+  }
+  if (info.size > THEME_ASSET_MAX_BYTES) {
+    throw new MarkdStageError("slide_background_too_large", `Background image must be 2 MiB or smaller: ${canonical}`);
+  }
+  return file;
+}
+
+export async function loadSlideBackgrounds(workspaceRoot, sourceName, slides) {
+  for (let index = 0; index < slides.length; index += 1) {
+    const meta = parseFrontMatter(slides[index]);
+    if (!Object.hasOwn(meta, "background-image")) continue;
+    try {
+      await resolveSlideBackgroundFile(workspaceRoot, sourceName, meta["background-image"]);
+    } catch (error) {
+      throw new MarkdStageError(error.code || "invalid_slide_background", `Slide ${index + 1}: ${error.message}`);
+    }
+  }
+}

package/shared/schema/theme-metadata-v1.schema.json

@@ -12,6 +12,22 @@
     "version": {
       "const": 1
     },
+    "background": {
+      "description": "Common decorative background for default and center layouts only.",
+      "$ref": "#/$defs/decorativeImage"
+    },
+    "layouts": {
+      "type": "object",
+      "properties": {
+        "default": {
+          "$ref": "#/$defs/layoutBackground"
+        },
+        "center": {
+          "$ref": "#/$defs/layoutBackground"
+        }
+      },
+      "additionalProperties": false
+    },
     "cover": {
       "type": "object",
       "properties": {
@@ -39,6 +55,15 @@
   },
   "additionalProperties": false,
   "$defs": {
+    "layoutBackground": {
+      "type": "object",
+      "properties": {
+        "background": {
+          "$ref": "#/$defs/decorativeImage"
+        }
+      },
+      "additionalProperties": false
+    },
     "assetPath": {
       "type": "string",
       "maxLength": 200,

package/shared/schema/theme-v1.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/runceel/markdstage/schema/theme-v1.json",
   "title": "MarkdStage custom theme v1",
-  "description": "Machine-readable catalog for CSS custom properties supported by the MarkdStage canvas custom theme. Optional cover/backcover assets live in a sibling theme.json manifest.",
+  "description": "Machine-readable catalog for CSS custom properties supported by the MarkdStage canvas custom theme. Optional common and default/center background images and cover/backcover assets live in a sibling theme.json manifest; background-image front matter overrides images per slide without CSS url().",
   "type": "object",
   "required": [
     "version",
@@ -16,7 +16,7 @@
       "type": "object",
       "description": "CSS custom property declarations. The runtime accepts any name matching the pattern.",
       "properties": {
-        "--bg": { "type": "string", "description": "Standard slide background" },
+        "--bg": { "type": "string", "description": "Standard slide background beneath optional decorative images" },
         "--fg": { "type": "string", "description": "Headings and primary text" },
         "--muted": { "type": "string", "description": "Secondary text" },
         "--body": { "type": "string", "description": "Body text" },
@@ -80,5 +80,5 @@
   "additionalProperties": false,
   "x-theme-file-format": "CSS custom property declarations, optionally wrapped in one :root block.",
   "x-value-syntax": "Any non-empty CSS value except selectors, @import, url(), javascript:, expression(), and style tags.",
-  "x-theme-metadata": "When present, theme.json beside the CSS file must conform to theme-metadata-v1.schema.json."
+  "x-theme-metadata": "When present, theme.json beside the CSS file must conform to theme-metadata-v1.schema.json. Decorative { image, alt? } entries in background and layouts.default.background/layouts.center.background use theme-local assets/ paths. Layout images override the common background for default/center only; title retains cover.background. Per-slide background-image overrides every layout and theme. Images are centered cover over existing colors; missing settings, not invalid images, trigger fallback."
 }

package/src/cli.mjs

@@ -64,7 +64,10 @@ const COMMAND_OPTIONS = {
   validate: {},
   inspect: { slide: { type: "string" }, all: { type: "boolean" }, "fail-on-issues": { type: "boolean" } },
   capture: { pages: { type: "string" }, output: { type: "string" } },
-  export: { output: { type: "string" } },
+  export: {
+    output: { type: "string" },
+    "mermaid-image-fallback": { type: "boolean" },
+  },
   guide: {},
   skill: {
     target: { type: "string" },
@@ -156,11 +159,14 @@ function usage(command) {
       "Without --pages only the slides reported as clipped are captured.",
     ],
     export: [
-      "Usage: markdstage export <file.md> [--output slides.pdf|slides.pptx]",
+      "Usage: markdstage export <file.md> [options]",
       "",
       "Produces the same 16:9 PDF or hybrid editable PowerPoint as the MarkdStage canvas.",
       "PowerPoint output includes speaker-note Markdown as readable plain text notes.",
       "The output extension selects the format; omitting --output keeps PDF as the default.",
+      "  --output <path>             Write PDF or PowerPoint to this path.",
+      "  --mermaid-image-fallback    Render each Mermaid diagram as one image in PowerPoint.",
+      "                              Applies only with an explicit .pptx output.",
     ],
     guide: [
       "Usage: markdstage guide [topic] [--json]",
@@ -421,6 +427,7 @@ export async function run(argv, io = {}) {
         const report = await exportCommand({
           ...deckOptions(file, values),
           output: values.output,
+          mermaidImageFallback: values["mermaid-image-fallback"],
         });
         if (values.json) json(report);
         else out(formatExportReport(report));

package/src/commands/export.mjs

@@ -22,6 +22,8 @@ export async function exportCommand(
         session,
         options.output || pptxNameForSource(session.sourceName),
         options.theme,
+        undefined,
+        { mermaidImageFallback: options.mermaidImageFallback === true },
       );
     }
     return exporters.pdf(session, requested, options.theme);