@markdstage/markdstage 3.4.0 → 3.8.1

package/shared/renderer/renderer.js

@@ -6,10 +6,13 @@ import { sceneToPptxElements } from "./scene-pptx.mjs";
 import { attachArchitectureEditor } from "./architecture-editor.mjs";
 import {
   DEFAULT_THEME,
+  mermaidC4ThemeVariables,
   mermaidThemeVariables,
   normalizeTheme,
   parseFrontMatter,
+  resolveThemeBackground,
 } from "./theme.mjs";
+import { parseSlideBackground } from "./slide-background.mjs";
 import {
   extractSpeakerNotes,
   speakerNotesToPlainText,
@@ -17,6 +20,7 @@ import {
   stripSpeakerNotes,
 } from "./speaker-notes.mjs";
 import { splitImportPath } from "./import-path.mjs";
+import { createSlideViewport, OUTPUT_WIDTH, OUTPUT_HEIGHT } from "./slide-viewport.mjs";
 
 // Client-side slide renderer for the MarkdStage canvas.
 //
@@ -102,6 +106,11 @@ let previewMode = false;
 let previewOffset = 0;
 let navigationEnabled = true;
 let fixedPreviewMode = false;
+let surfaceMode = false;
+let outputViewport = null;
+let currentViewport = null;
+let nextViewport = null;
+let surfaceDiagnostic = null;
 let moreControlsOpen = false;
 // Markdown for the most recently rendered slide, retained for editing-mode rerenders.
 let lastMarkdown = "";
@@ -119,8 +128,6 @@ let layoutFrame = 0;
 // past clientHeight, which is invisible but still enough for `overflow:auto` to
 // draw a scrollbar.
 const SCROLL_EPSILON = 2;
-const OUTPUT_WIDTH = 1280;
-const OUTPUT_HEIGHT = 720;
 const PPTX_LAYOUT_NAMES = ["title", "default", "center", "section", "backcover"];
 const LAYOUT_HINT_LIMIT = 5;
 
@@ -265,11 +272,8 @@ function elementPath(element, root) {
   return parts.join(" > ");
 }
 
-// The live 16:9 preview scales #stage with a CSS transform, so getBoundingClientRect()
-// reports scaled pixels while scrollWidth/clientWidth stay in the untransformed 1280x720
-// layout space. Every rect-derived delta is divided by this factor before the two kinds of
-// measurement are combined, keeping the preview, PDF, and PNG diagnostics in one coordinate
-// system.
+// Normalize any content-authored transform before combining rect and scroll metrics.
+// Display scaling happens outside the fixed browsing context and is not measured here.
 function layoutScale(deck) {
   const width = deck.offsetWidth;
   if (!width) return 1;
@@ -427,7 +431,9 @@ function updateFixedPreviewWarning() {
   const warning = document.getElementById("layoutWarning");
   const button = document.getElementById("navFixedPreview");
   const empty = document.body.classList.contains("markdstage-empty");
-  if (!fixedPreviewMode || !layoutTarget || empty) {
+  const diagnostic = fixedPreviewMode && !presenterMode &&
+    (surfaceDiagnostic || (layoutTarget && collectSlideLayout(layoutTarget, navIndex)));
+  if (!fixedPreviewMode || !diagnostic || empty || presenterMode) {
     document.body.classList.remove("fixed-preview-overflow");
     if (warning) {
       warning.hidden = true;
@@ -438,7 +444,6 @@ function updateFixedPreviewWarning() {
     return;
   }
 
-  const diagnostic = collectSlideLayout(layoutTarget, navIndex);
   document.body.classList.toggle("fixed-preview-overflow", diagnostic.pdfClipped);
   if (button) button.dataset.state = diagnostic.pdfClipped ? "error" : "active";
   syncMoreControls();
@@ -459,20 +464,17 @@ function updateFixedPreviewWarning() {
   warning.hidden = false;
 }
 
-function updateFixedPreviewScale() {
-  if (!fixedPreviewMode) return;
-  const availableWidth = Math.max(1, window.innerWidth - 24);
-  const availableHeight = Math.max(1, window.innerHeight - 88);
-  const scale = Math.min(availableWidth / OUTPUT_WIDTH, availableHeight / OUTPUT_HEIGHT, 1);
-  document.body.style.setProperty("--fixed-preview-scale", String(scale));
-}
-
 function refreshLayout() {
   const target = layoutTarget;
   if (!target || !target.deck.isConnected) return;
   if (target.autoSize) applyAutoSize(target.deck, target.bodyEl);
   updateBodyScroll(target.bodyEl);
   updateFixedPreviewWarning();
+  if (surfaceMode && !document.body.classList.contains("mermaid-loading")) {
+    window.frameElement?.dispatchEvent(new CustomEvent("slide-layout", {
+      detail: collectSlideLayout(target, navIndex),
+    }));
+  }
 }
 
 // Coalesce the (re)layout into one frame: several triggers — render, resize,
@@ -583,13 +585,19 @@ function runMermaid(scope, deckEl, token, revealWhenDone = true) {
     return Promise.resolve();
   }
   try {
-    const themeVariables = mermaidThemeVariables(getComputedStyle(deckEl));
+    const sources = [...nodes].map((node) => node.textContent || "");
+    const themeVariables = mermaidThemeVariables(
+      getComputedStyle(deckEl),
+      (value) => resolveModelColor(value, deckEl),
+    );
+    const c4ThemeVariables = mermaidC4ThemeVariables(themeVariables);
     const serializedThemeVariables = JSON.stringify(themeVariables);
     if (serializedThemeVariables !== lastMermaidThemeVariables) {
       window.mermaid.initialize({
         startOnLoad: false,
         theme: "base",
         themeVariables,
+        c4: c4ThemeVariables,
         securityLevel: "strict",
       });
       lastMermaidThemeVariables = serializedThemeVariables;
@@ -601,11 +609,60 @@ function runMermaid(scope, deckEl, token, revealWhenDone = true) {
           const source = host.querySelector("svg");
           if (!source || source.hasAttribute("data-scene-backend")) continue;
           try {
+            repairC4ThemeDefaults(source, sources[index], themeVariables);
             renderMermaidScene(source, deckEl, index);
           } catch (e) {
             console.error("Mermaid scene render failed", e);
           }
         }
+
+        // Mermaid 11.15.0 does not expose theme variables for C4 boundary/relation
+        // paint or its arrow markers. Repair only those known renderer defaults, and
+        // leave diagrams with explicit C4 style updates untouched so source colors
+        // remain authoritative.
+        function repairC4ThemeDefaults(svg, source, themeVariables) {
+          if (svg.getAttribute("aria-roledescription") !== "c4") return;
+          const commands = source.replace(/^\s*%%.*$/gm, "");
+          const hasElementStyles = /\bUpdateElementStyle\s*\(/i.test(commands);
+          const hasRelationStyles = /\bUpdateRelStyle\s*\(/i.test(commands);
+          const boundaryGroups = new Set(
+            [...svg.querySelectorAll('rect[stroke-dasharray="7.0,7.0"], rect[fill="none"]')]
+              .map((element) => element.parentElement),
+          );
+          const relationGroups = new Set(
+            [...svg.querySelectorAll("[marker-end], [marker-start]")].map((element) => element.parentElement),
+          );
+          const boundaryPaint = new Set(["#444", "#444444", "rgb(68, 68, 68)"]);
+          const relationPaint = new Set(["#444", "#444444", "rgb(68, 68, 68)"]);
+          const setDefaultPaint = (element, property, defaults, value) => {
+            const current = element.getAttribute(property)?.trim().toLowerCase();
+            if (!defaults.has(current)) return;
+            element.setAttribute(property, value);
+            if (element.style?.getPropertyValue(property)) {
+              element.style.setProperty(property, value);
+            }
+          };
+
+          for (const element of svg.querySelectorAll("rect, line, path, text")) {
+            const parent = element.parentElement;
+            if (!hasElementStyles && boundaryGroups.has(parent)) {
+              setDefaultPaint(element, "stroke", boundaryPaint, themeVariables.lineColor);
+              setDefaultPaint(element, "fill", boundaryPaint, themeVariables.textColor);
+            }
+            if (!hasRelationStyles && relationGroups.has(parent)) {
+              setDefaultPaint(element, "stroke", relationPaint, themeVariables.lineColor);
+              setDefaultPaint(element, "fill", relationPaint, themeVariables.textColor);
+            }
+          }
+          if (!hasRelationStyles) {
+            for (const marker of svg.querySelectorAll("marker")) {
+              for (const element of marker.querySelectorAll("path, polygon, line")) {
+                setDefaultPaint(element, "stroke", new Set(["black", "#000", "#000000", "rgb(0, 0, 0)"]), themeVariables.lineColor);
+                setDefaultPaint(element, "fill", new Set([undefined, "black", "#000", "#000000", "rgb(0, 0, 0)"]), themeVariables.lineColor);
+              }
+            }
+          }
+        }
       })
       .finally(reveal);
   } catch (e) {
@@ -615,26 +672,28 @@ function runMermaid(scope, deckEl, token, revealWhenDone = true) {
   }
 }
 
+function withoutMermaidLoadingVeil(callback) {
+  const loading = document.body.classList.contains("mermaid-loading");
+  if (loading) document.body.classList.remove("mermaid-loading");
+  try {
+    return callback();
+  } finally {
+    if (loading) document.body.classList.add("mermaid-loading");
+  }
+}
+
 function renderMermaidScene(svg, deck, blockIndex) {
-  const result = mermaidSvgToScene(svg, {
-    path: `mermaid[${blockIndex}]`,
-    deck,
-    includeSourceElements: true,
-    resolveColor: (value) => resolveModelColor(value, deck),
-  });
+  const result = withoutMermaidLoadingVeil(() =>
+    mermaidSvgToScene(svg, {
+      path: `mermaid[${blockIndex}]`,
+      deck,
+      includeSourceElements: true,
+      resolveColor: (value) => resolveModelColor(value, deck),
+    }),
+  );
   let { scene } = result;
-  const computedStyle = (element) => {
-    const style = getComputedStyle(element);
-    return {
-      getPropertyValue(property) {
-        // The loading veil is inherited by every SVG descendant, not diagram style.
-        if (property === "visibility" && document.body.classList.contains("mermaid-loading")) {
-          return element.style?.visibility || element.getAttribute("visibility") || "";
-        }
-        return style.getPropertyValue(property);
-      },
-    };
-  };
+  const capture = (element, options) =>
+    withoutMermaidLoadingVeil(() => captureSvgTree(element, options));
   const slots = new Map();
   try {
     for (const [index, node] of scene.nodes.entries()) {
@@ -657,7 +716,7 @@ function renderMermaidScene(svg, deck, blockIndex) {
         node.meta = { ...node.meta, svgOwner: slots.get(source) };
         continue;
       }
-      node.meta = { ...node.meta, svg: captureSvgTree(source, { computedStyle }) };
+      node.meta = { ...node.meta, svg: capture(source) };
       slots.set(source, index);
     }
     for (const [source, index] of slots) {
@@ -676,14 +735,14 @@ function renderMermaidScene(svg, deck, blockIndex) {
       kind: "fallback", sourcePath: "svg", z: 0,
       bounds: { x: 0, y: 0, width: scene.width, height: scene.height },
       capability: { pptx: "fallback", reason }, reason,
-      meta: { svg: captureSvgTree(svg, { computedStyle }) },
+      meta: { svg: capture(svg) },
     }] };
     slots.clear();
     slots.set(svg, 0);
   }
   const template = slots.has(svg)
     ? { sceneNode: slots.get(svg) }
-    : captureSvgTree(svg, { slots, computedStyle });
+    : capture(svg, { slots });
   scene.meta = { ...scene.meta, svgRoot: template };
   svg.replaceWith(sceneToSvg(scene, { document, template }));
 }
@@ -698,7 +757,12 @@ function moveLeadingSlideTitle(header, bodyEl, specialLayout) {
   return title;
 }
 
-function createSlide(markdown, fallbackTheme, themeLocked = deckThemeLocked) {
+function createSlide(
+  markdown,
+  fallbackTheme,
+  themeLocked = deckThemeLocked,
+  { backgroundImage: backgroundOverride } = {},
+) {
   const placeholder = !nonEmpty(markdown);
   const md = placeholder ? PLACEHOLDER : markdown;
   const { meta, body: rawBody } = splitFrontMatter(md);
@@ -721,6 +785,11 @@ function createSlide(markdown, fallbackTheme, themeLocked = deckThemeLocked) {
   // as well as <html> so print mode can render differently themed pages together.
   const theme = normalizeTheme(themeLocked ? fallbackTheme : meta.theme || fallbackTheme);
   const themeMetadata = theme === "custom" ? customThemeMeta : null;
+  const backgroundImage = parseSlideBackground(backgroundOverride ?? meta["background-image"]);
+  const backgroundUrl = backgroundImage
+    ? localAssetUrl(backgroundImage.replace(/^\/assets\//, "/background-assets/")
+        .split("/").map(encodeURIComponent).join("/"))
+    : "";
 
   const deck = document.createElement("div");
   deck.className = "deck";
@@ -732,13 +801,18 @@ function createSlide(markdown, fallbackTheme, themeLocked = deckThemeLocked) {
   if (placeholder) deck.classList.add("markdstage-placeholder");
   if (sizeMode !== "auto") setSizeLevel(deck, sizeMode);
 
+  const background = themeImage(
+    backgroundUrl
+      ? { image: backgroundUrl }
+      : resolveThemeBackground(themeMetadata, layout),
+    titleSlide ? "slide-background theme-cover-background" : "slide-background",
+    { decorative: true },
+  );
+  if (background) {
+    deck.classList.add("has-slide-background");
+    deck.appendChild(background);
+  }
   if (titleSlide) {
-    const background = themeImage(
-      themeMetadata?.cover?.background,
-      "theme-cover-background",
-      { decorative: true },
-    );
-    if (background) deck.appendChild(background);
     const logo = themeImage(themeMetadata?.cover?.logo, "theme-cover-logo");
     if (logo) deck.appendChild(logo);
   }
@@ -870,6 +944,7 @@ function createSlide(markdown, fallbackTheme, themeLocked = deckThemeLocked) {
     deck,
     bodyEl,
     theme,
+    backgroundImage,
     sizeMode,
     titleSlide,
     sectionSlide,
@@ -889,6 +964,19 @@ function renderSlide(markdown) {
   architectureEditors = [];
   applyCustomThemeCss(customThemeCss);
   const token = ++renderToken;
+  if (!surfaceMode && (fixedPreviewMode || presenterViewOpen)) {
+    const { meta } = splitFrontMatter(lastMarkdown);
+    document.title = meta.title || meta.deck || "Slide";
+    document.documentElement.setAttribute("data-theme",
+      deckThemeLocked ? deckTheme : normalizeTheme(meta.theme || deckTheme));
+    layoutTarget = null;
+    surfaceDiagnostic = null;
+    if (layoutFrame) cancelAnimationFrame(layoutFrame);
+    layoutFrame = 0;
+    if (!presenterViewRequested || !presenterViewAvailable || navTotal <= 0) updateSlideViewports();
+    updateFixedPreviewWarning();
+    return;
+  }
   const slide = createSlide(markdown, deckTheme);
   document.title = slide.title;
   document.documentElement.setAttribute("data-theme", slide.theme);
@@ -917,14 +1005,30 @@ function renderSlide(markdown) {
   // that the slide is fully painted, and PDF export and the visual regression
   // suite rely on it. Revealing while an architecture icon under `assets/` is
   // still loading would capture a half-drawn slide.
-  const images = waitForImages(slide.deck).then(() => {
-    if (token === renderToken) scheduleLayoutRefresh();
-  });
-  const mermaid = runMermaid(slide.bodyEl, slide.deck, token, false).finally(() => {
+  const images = waitForImages(slide.deck)
+    .then(() => {
+      if (token === renderToken) scheduleLayoutRefresh();
+    })
+    .catch((error) => {
+      if (token !== renderToken) return;
+      console.error(error.message);
+      if (surfaceMode) {
+        window.frameElement?.dispatchEvent(new CustomEvent("slide-error", { detail: error.message }));
+      } else {
+        showExportNotification("error", error.message);
+      }
+    });
+  const mermaid = Promise.resolve(document.fonts?.ready).then(() => {
+    if (token === renderToken) return runMermaid(slide.bodyEl, slide.deck, token, false);
+  }).finally(() => {
     if (token === renderToken) scheduleLayoutRefresh();
   });
-  Promise.all([mermaid, images]).finally(() => {
-    if (token === renderToken) document.body.classList.remove("mermaid-loading");
+  Promise.all([mermaid, images]).finally(async () => {
+    await afterLayout();
+    if (token === renderToken) {
+      document.body.classList.remove("mermaid-loading");
+      refreshLayout();
+    }
   });
 }
 
@@ -961,7 +1065,14 @@ function waitForImages(root) {
       }),
     );
   }
-  return Promise.all(pending);
+  return Promise.all(pending).then(() => {
+    const failedBackground = [...root.querySelectorAll("img.slide-background")].find(
+      (image) => !image.naturalWidth,
+    );
+    if (failedBackground) {
+      throw new Error(`Could not load slide background: ${failedBackground.getAttribute("src")}`);
+    }
+  });
 }
 
 async function reportOutputStatus(token, status, error = "", layout = null) {
@@ -2033,7 +2144,7 @@ function markMermaidNativeElements(svg, mappedElements, pathPrefix, sourceElemen
       source = sourceElements.get(ownerPath);
     }
     if (source && !source.hasAttribute("data-pptx-native")) {
-      const nativeKind = element.type === "shape" ? "shape" : element.type;
+      const nativeKind = element.mermaid?.nativeMask || (element.type === "shape" ? "shape" : element.type);
       source.setAttribute("data-pptx-native", nativeKind);
     }
     if (!sourceElements && element.type === "connector") {
@@ -2098,10 +2209,17 @@ function collectMermaidObjects(element, deck, blockIndex) {
       mermaidElementForSourcePath(svg, sourcePath) ||
       mermaidFallbackElementForBounds(svg, deck, fallback) ||
       svg;
-    const sourceBounds = source.getBoundingClientRect();
-    const padding = ["path", "line", "polyline"].includes(source.localName)
-      ? Math.max(1, (fallback.width - sourceBounds.width) / 2, (fallback.height - sourceBounds.height) / 2)
-      : 0;
+    const sourceBounds = fallbackBounds(source, deck, 0, true);
+    const inferredPadding = Math.max(
+      0,
+      (fallback.width - sourceBounds.width) / 2,
+      (fallback.height - sourceBounds.height) / 2,
+    );
+    const geometryPadding = ["path", "line", "polyline"].includes(source.localName)
+      ? Math.max(1, inferredPadding)
+      : inferredPadding;
+    const effectPadding = subtreeEffectPaintPadding(source);
+    const padding = Math.max(geometryPadding, effectPadding);
     const captured = pptxFallback("mermaid", source, deck, fallback.reason, {
       captureElement: source,
       includeDescendants: true,
@@ -2113,10 +2231,14 @@ function collectMermaidObjects(element, deck, blockIndex) {
       path: fallback.path,
       sourcePath,
       reason: fallback.reason,
-      x: fallback.x,
-      y: fallback.y,
-      width: fallback.width,
-      height: fallback.height,
+      ...(effectPadding
+        ? {}
+        : {
+            x: fallback.x,
+            y: fallback.y,
+            width: fallback.width,
+            height: fallback.height,
+          }),
       zOrder: fallback.zOrder,
       ...(node?.id ? { id: node.id } : {}),
       ...(fallback.artwork === false ? { artwork: false } : {}),
@@ -2125,7 +2247,7 @@ function collectMermaidObjects(element, deck, blockIndex) {
   return { elements: mapped.elements, fallbacks };
 }
 
-async function collectPptxSlide(slide, index) {
+async function collectPptxSlide(slide, index, options = {}) {
   const { deck } = slide;
   assignPptxPaintOrder(deck);
   const elements = [];
@@ -2232,6 +2354,12 @@ async function collectPptxSlide(slide, index) {
   for (const [blockIndex, element] of [...deck.querySelectorAll("pre.mermaid")].entries()) {
     const covered = [...fallbackRoots].some((root) => root === element || root.contains(element));
     if (covered) continue;
+    if (options.mermaidImageFallback === true) {
+      // The scroll container clips the diagram; SVG definitions have no painted bounds.
+      // The capture pipeline trims transparent space inside this safe envelope.
+      addFallback("mermaid", element, "mermaid-rendered-as-artwork");
+      continue;
+    }
     try {
       const mermaid = collectMermaidObjects(element, deck, blockIndex);
       elements.push(...mermaid.elements);
@@ -2496,7 +2624,7 @@ async function collectPptxSlide(slide, index) {
   for (const image of deck.querySelectorAll("img")) {
     if (
       image.closest(".architecture-diagram") ||
-      image.classList.contains("theme-cover-background") ||
+      image.classList.contains("slide-background") ||
       image.classList.contains("theme-cover-logo") ||
       insideFallback(image)
     ) {
@@ -2597,20 +2725,20 @@ async function collectPptxSlide(slide, index) {
   };
 }
 
-function createPptxLayoutTemplate(theme, layout) {
+function createPptxLayoutTemplate(theme, layout, id = `${theme}:${layout}`, backgroundImage) {
   const markdown = `---
 layout: ${layout}
 theme: ${theme}
 ---
 `;
-  const slide = createSlide(markdown, theme, true);
+  const slide = createSlide(markdown, theme, true, { backgroundImage });
   if (layout === "backcover") {
     slide.deck
       .querySelectorAll(".theme-backcover-logo, .theme-backcover-copyright")
       .forEach((element) => element.remove());
   }
   slide.deck.classList.add("pptx-layout-template");
-  slide.deck.dataset.pptxLayoutId = `${theme}:${layout}`;
+  slide.deck.dataset.pptxLayoutId = id;
   return slide;
 }
 
@@ -2620,6 +2748,7 @@ async function renderPptxDeck(
   customCss = "",
   themeMetadata = null,
   themeLocked = false,
+  options = {},
 ) {
   deckTheme = normalizeTheme(theme);
   deckThemeLocked = Boolean(themeLocked);
@@ -2655,7 +2784,7 @@ async function renderPptxDeck(
 
   const pptxSlides = [];
   for (const [index, slide] of rendered.entries()) {
-    pptxSlides.push(await collectPptxSlide(slide, index));
+    pptxSlides.push(await collectPptxSlide(slide, index, options));
   }
   const themes = [...new Set(rendered.map((slide) => slide.theme))];
   const layoutTemplates = themes.flatMap((slideTheme) =>
@@ -2666,6 +2795,26 @@ async function renderPptxDeck(
       slide: createPptxLayoutTemplate(slideTheme, layout),
     })),
   );
+  // Per-slide overrides need their own layout artwork, not a background shared
+  // with every slide of the same theme and layout.
+  const backgroundLayouts = new Map();
+  for (const [index, slide] of rendered.entries()) {
+    if (!slide.backgroundImage) continue;
+    const model = pptxSlides[index];
+    const key = JSON.stringify([slide.theme, model.layout, slide.backgroundImage]);
+    let id = backgroundLayouts.get(key);
+    if (!id) {
+      id = `${model.layoutId}:background-${backgroundLayouts.size + 1}`;
+      backgroundLayouts.set(key, id);
+      layoutTemplates.push({
+        id,
+        name: model.layout,
+        theme: slide.theme,
+        slide: createPptxLayoutTemplate(slide.theme, model.layout, id, slide.backgroundImage),
+      });
+    }
+    model.layoutId = id;
+  }
   stage.append(...layoutTemplates.map((layout) => layout.slide.deck));
   await waitForImages(stage);
   await afterLayout();
@@ -2683,7 +2832,7 @@ async function renderPptxDeck(
     masters: themes.map((slideTheme) => ({
       id: slideTheme,
       theme: slideTheme,
-      layoutIds: PPTX_LAYOUT_NAMES.map((layout) => `${slideTheme}:${layout}`),
+      layoutIds: pptxLayouts.filter((layout) => layout.theme === slideTheme).map((layout) => layout.id),
     })),
     layouts: pptxLayouts,
     slides: pptxSlides,
@@ -2721,6 +2870,7 @@ async function initPptx(params) {
       data.customThemeCss,
       data.customThemeMeta,
       data.themeLocked,
+      { mermaidImageFallback: data.mermaidImageFallback === true },
     );
     await reportOutputStatus(token, "ready", "", output.layout);
   } catch (error) {
@@ -3021,7 +3171,7 @@ async function fetchDeck() {
 function setArchitectureEditMode(enabled) {
   const next = Boolean(enabled) && architectureEditAvailable && !presenterMode;
   if (next === architectureEditMode) return false;
-  if (next && fixedPreviewMode) setFixedPreviewMode(false);
+  if (next && fixedPreviewMode) setFixedPreviewMode(false, { rerender: false });
   architectureEditMode = next;
   document.body.classList.toggle("architecture-edit-mode", next);
   updateArchitectureEditButton(next);
@@ -3127,7 +3277,8 @@ async function requestArchitectureEditMode(enabled) {
 }
 
 function architectureDiagramOptions() {
-  return [...document.querySelectorAll(".architecture-diagram[data-architecture-block]")].map(
+  const slideDocument = document.getElementById("outputFrame")?.contentDocument || document;
+  return [...slideDocument.querySelectorAll(".architecture-diagram[data-architecture-block]")].map(
     (wrapper, index) => ({
       block: Number(wrapper.dataset.architectureBlock),
       title: wrapper.dataset.architectureTitle || `Diagram ${index + 1}`,
@@ -3453,6 +3604,10 @@ async function fetchState() {
 // re-fetches /state for an instant update (without waiting for the SSE nudge).
 async function navigate(payload) {
   if (!navigationEnabled) return;
+  if (surfaceMode) {
+    window.frameElement?.dispatchEvent(new CustomEvent("slide-navigate", { detail: payload }));
+    return;
+  }
   try {
     const res = await fetch("./navigate", {
       method: "POST",
@@ -3681,9 +3836,45 @@ function showExportNotification(state, message, path = "") {
   resumeExportNotification();
 }
 
-async function exportFromCanvas(format) {
+let pptxOptionsPending = false;
+
+async function requestPptxExport() {
+  const dialog = document.getElementById("pptxExportDialog");
+  if (exportPending || pptxOptionsPending || dialog.open || !pptxExportAvailable) return;
+  pptxOptionsPending = true;
+  let hasMermaid;
+  try {
+    const response = await fetch("./deck", { cache: "no-store" });
+    if (!response.ok) throw new Error(`Could not load the export deck (${response.status}).`);
+    const data = await response.json();
+    if (!Array.isArray(data?.slides) || !data.slides.every((slide) => typeof slide === "string")) {
+      throw new Error("The export deck is invalid.");
+    }
+    const slides = [...data.slides];
+    if (navMode === "adhoc") slides[Math.max(0, Math.min(navIndex, slides.length - 1))] = lastMarkdown;
+    hasMermaid = slides.some((markdown) => {
+      const { body } = splitFrontMatter(markdown);
+      const content = document.createElement("div");
+      content.innerHTML = window.DOMPurify.sanitize(window.marked.parse(stripSpeakerNotes(body)));
+      return codeBlocksForLanguage(content, "mermaid").length > 0 || Boolean(content.querySelector(".mermaid"));
+    });
+  } catch (error) {
+    showExportNotification("error", `Could not save PowerPoint. ${error.message}`);
+    return;
+  } finally {
+    pptxOptionsPending = false;
+  }
+  if (hasMermaid) {
+    document.getElementById("pptxExportForm").reset();
+    dialog.showModal();
+  } else {
+    await exportFromCanvas("pptx");
+  }
+}
+
+async function exportFromCanvas(format, { mermaidImageFallback = false } = {}) {
   const isPdf = format === "pdf";
-  if (exportPending || !(isPdf ? pdfExportAvailable : pptxExportAvailable)) return;
+  if (exportPending || pptxOptionsPending || !(isPdf ? pdfExportAvailable : pptxExportAvailable)) return;
   exportPending = true;
   const label = isPdf ? "PDF" : "PowerPoint";
   const pdfButton = document.getElementById("navExport");
@@ -3700,7 +3891,11 @@ async function exportFromCanvas(format) {
   try {
     const response = await fetch(isPdf ? "./export" : "./export-pptx", {
       method: "POST",
-      headers: { Accept: "application/json" },
+      headers: {
+        Accept: "application/json",
+        ...(isPdf ? {} : { "Content-Type": "application/json" }),
+      },
+      ...(isPdf ? {} : { body: JSON.stringify({ mermaidImageFallback }) }),
       cache: "no-store",
     });
     const data = await response.json();
@@ -3732,26 +3927,29 @@ async function exportFromCanvas(format) {
   }
 }
 
-function setFixedPreviewMode(enabled) {
-  fixedPreviewMode = Boolean(enabled);
+function setFixedPreviewMode(enabled, { rerender = true } = {}) {
+  fixedPreviewMode = presenterMode || Boolean(enabled);
   document.body.classList.toggle("fixed-preview-mode", fixedPreviewMode);
-  document.body.classList.toggle("fixed-output-mode", fixedPreviewMode);
+  document.body.classList.toggle("responsive-preview-mode", !fixedPreviewMode);
   const button = document.getElementById("navFixedPreview");
   if (button) {
     button.setAttribute("aria-pressed", fixedPreviewMode ? "true" : "false");
     button.dataset.state = fixedPreviewMode ? "active" : "";
     button.title = fixedPreviewMode
-      ? "Return to responsive canvas layout"
+      ? "Switch to responsive editing layout (not output-equivalent)"
       : "Preview PDF layout at 16:9";
+    button.querySelector(".nav-more-label").textContent =
+      fixedPreviewMode ? "Output preview" : "Responsive editing";
   }
   syncMoreControls();
-  if (fixedPreviewMode) {
-    updateFixedPreviewScale();
-  } else {
-    document.body.style.removeProperty("--fixed-preview-scale");
+  if (!fixedPreviewMode) {
+    outputViewport?.dispose();
+    outputViewport = null;
+    document.getElementById("stage").classList.remove("slide-viewport");
     document.body.classList.remove("fixed-preview-overflow");
   }
-  scheduleLayoutRefresh();
+  surfaceDiagnostic = null;
+  if (rerender && currentVersion >= 0) renderSlide(lastMarkdown);
   updateFixedPreviewWarning();
 }
 
@@ -3759,6 +3957,103 @@ function toggleFixedPreviewMode() {
   setFixedPreviewMode(!fixedPreviewMode);
 }
 
+function slideViewportState(markdown, index, interactive) {
+  return {
+    markdown, index, total: navTotal, theme: deckTheme, themeLocked: deckThemeLocked,
+    customThemeCss, customThemeMeta, navigationEnabled: interactive,
+  };
+}
+
+function mountSlideViewport(host, id, title, interactive) {
+  return createSlideViewport(host, {
+    id, title,
+    onNavigate: (payload) => { if (interactive) navigate(payload); },
+    onPointer: () => { if (interactive) setMoreControlsOpen(false); },
+    onError: (message) => showExportNotification("error", message),
+    onKey: (detail) => {
+      if (!interactive) return;
+      const event = new KeyboardEvent("keydown", { ...detail, bubbles: true, cancelable: true });
+      document.dispatchEvent(event);
+      detail.handled = event.defaultPrevented;
+    },
+    onLayout: (diagnostic) => {
+      if (id === "presenterNext") return;
+      surfaceDiagnostic = diagnostic;
+      document.body.classList.remove("mermaid-loading");
+      updateFixedPreviewWarning();
+    },
+  });
+}
+
+function updateSlideViewports() {
+  const stage = document.getElementById("stage");
+  document.body.classList.add("mermaid-loading");
+  if (presenterViewOpen) {
+    stage.replaceChildren();
+    currentViewport ??= mountSlideViewport(
+      document.getElementById("presenterCurrentViewport"), "presenterCurrent", "Current slide", true,
+    );
+    currentViewport.setState(slideViewportState(lastMarkdown, navIndex, true));
+    const hasNext = navMode !== "deck" || navIndex < navTotal - 1;
+    if (hasNext) {
+      const index = Math.min(navIndex + 1, navTotal - 1);
+      nextViewport ??= mountSlideViewport(
+        document.getElementById("presenterNextViewport"), "presenterNext", "Next slide", false,
+      );
+      nextViewport.setState(slideViewportState(deckSlides[index] || "", index, false));
+    }
+  } else {
+    if (!outputViewport) {
+      stage.replaceChildren();
+      stage.classList.add("slide-viewport");
+      outputViewport = mountSlideViewport(stage, "outputFrame", "Slide", navigationEnabled);
+    }
+    outputViewport.setState(slideViewportState(lastMarkdown, navIndex, navigationEnabled));
+  }
+}
+
+function initSlideSurface() {
+  surfaceMode = true;
+  presenterMode = true;
+  document.body.classList.add("surface-mode", "fixed-output-mode", "presenter-mode", "preview-mode");
+  let previousState = "";
+  window.__markdstageSurface = {
+    render(state) {
+      const key = JSON.stringify(state);
+      if (key === previousState) {
+        refreshLayout();
+        return;
+      }
+      previousState = key;
+      deckTheme = state.theme;
+      deckThemeLocked = state.themeLocked;
+      applyCustomThemeCss(state.customThemeCss);
+      customThemeMeta = state.customThemeMeta;
+      navIndex = state.index;
+      navTotal = state.total;
+      navigationEnabled = state.navigationEnabled;
+      renderSlide(state.markdown);
+    },
+  };
+  wirePointerNavigation();
+  document.addEventListener("pointerdown", () => {
+    window.frameElement?.dispatchEvent(new CustomEvent("slide-pointer"));
+  });
+  document.addEventListener("keydown", (event) => {
+    if (!navigationEnabled || event.defaultPrevented) return;
+    const target = event.target;
+    if (target?.closest("input, textarea, select, [contenteditable], button, a")) return;
+    const detail = {
+      key: event.key, code: event.code, repeat: event.repeat,
+      ctrlKey: event.ctrlKey, altKey: event.altKey, metaKey: event.metaKey, shiftKey: event.shiftKey,
+    };
+    window.frameElement?.dispatchEvent(new CustomEvent("slide-key", { detail }));
+    if (detail.handled) event.preventDefault();
+  });
+  window.addEventListener("resize", scheduleLayoutRefresh);
+  document.fonts?.addEventListener("loadingdone", scheduleLayoutRefresh);
+}
+
 function updateNav() {
   const nav = document.getElementById("nav");
   if (!nav) return;
@@ -3788,14 +4083,9 @@ function openPresenterView() {
   document.body.classList.add("presenter-view-mode");
   const view = document.getElementById("presenterView");
   if (view) view.hidden = false;
-  const current = document.getElementById("presenterCurrent");
-  const next = document.getElementById("presenterNext");
-  if (current && !current.getAttribute("src")) {
-    current.setAttribute("src", "./?preview=1&offset=0&navigate=1");
-  }
-  if (next && !next.getAttribute("src")) {
-    next.setAttribute("src", "./?preview=1&offset=1");
-  }
+  outputViewport?.dispose();
+  outputViewport = null;
+  renderSlide(lastMarkdown);
   updatePresenterView();
 }
 
@@ -3804,6 +4094,11 @@ function closePresenterView() {
   document.body.classList.remove("presenter-view-mode");
   const view = document.getElementById("presenterView");
   if (view) view.hidden = true;
+  currentViewport?.dispose();
+  nextViewport?.dispose();
+  currentViewport = null;
+  nextViewport = null;
+  renderSlide(lastMarkdown);
   document.getElementById("navMore")?.focus();
 }
 
@@ -3816,7 +4111,7 @@ function updatePresenterView() {
   if (prev) prev.disabled = navMode === "deck" && navIndex <= 0;
   if (next) next.disabled = navMode === "deck" && navIndex >= navTotal - 1;
   const hasNext = navMode !== "deck" || navIndex < navTotal - 1;
-  const nextFrame = document.getElementById("presenterNext");
+  const nextFrame = document.getElementById("presenterNextViewport");
   const nextEmpty = document.getElementById("presenterNextEmpty");
   if (nextFrame) nextFrame.hidden = !hasNext;
   if (nextEmpty) nextEmpty.hidden = hasNext;
@@ -4175,7 +4470,7 @@ function wireControls() {
   bind("navPresenterView", openPresenterView, { closeMore: true });
   bind("navFixedPreview", toggleFixedPreviewMode, { closeMore: true });
   bind("navExport", () => exportFromCanvas("pdf"), { closeMore: true });
-  bind("navExportPptx", () => exportFromCanvas("pptx"), { closeMore: true });
+  bind("navExportPptx", requestPptxExport, { closeMore: true });
   bind("navImport", toggleImportPicker, { closeMore: true });
   bind("navSourceMode", toggleSourceMode, { closeMore: true });
   bind("overviewClose", closeOverview);
@@ -4187,6 +4482,29 @@ function wireControls() {
   bind("presenterToggleButton", togglePresenterWindow);
   bind("presenterReturnButton", closePresenterView);
 
+  const pptxDialog = document.getElementById("pptxExportDialog");
+  pptxDialog.addEventListener("keydown", (event) => {
+    if (event.key !== "Tab") return;
+    const controls = [...pptxDialog.querySelectorAll("input:checked, button:not(:disabled)")];
+    const first = controls[0];
+    const last = controls.at(-1);
+    if (event.shiftKey && document.activeElement === first) {
+      event.preventDefault();
+      last.focus();
+    } else if (!event.shiftKey && document.activeElement === last) {
+      event.preventDefault();
+      first.focus();
+    }
+  });
+  document.getElementById("pptxExportCancel").addEventListener("click", () => pptxDialog.close());
+  pptxDialog.addEventListener("close", () => document.getElementById("navMore").focus());
+  document.getElementById("pptxExportForm").addEventListener("submit", (event) => {
+    event.preventDefault();
+    const mermaidImageFallback = new FormData(event.currentTarget).get("mermaidOutput") === "images";
+    pptxDialog.close();
+    exportFromCanvas("pptx", { mermaidImageFallback });
+  });
+
   const exportNotification = document.getElementById("exportNotification");
   document.getElementById("exportNotificationClose").addEventListener("click", dismissExportNotification);
   exportNotification.addEventListener("pointerenter", pauseExportNotification);
@@ -4242,6 +4560,7 @@ function wireControls() {
 
   document.addEventListener("keydown", (e) => {
     if (e.defaultPrevented || e.ctrlKey || e.metaKey || e.altKey) return;
+    if (pptxDialog.open) return;
     const t = e.target;
     // Keep Esc active while an input has focus; otherwise filtering in the import
     // dialog could leave the user unable to close it.
@@ -4320,6 +4639,10 @@ function init() {
   } catch (_) {}
 
   const params = new URLSearchParams(window.location.search);
+  if (params.get("surface") === "1") {
+    initSlideSurface();
+    return;
+  }
   presenterViewRequested = params.get("presenter") === "1";
   if (params.get("pptx") === "1") {
     initPptx(params).catch(reportPptxBootstrapFailure);
@@ -4354,15 +4677,12 @@ function init() {
     requestArchitectureEditMode(true);
   }
 
-  // Canvas and CLI preview start on the fixed 16:9 output surface. Presenter
-  // views keep their purpose-built layouts, and the control still lets users
-  // switch back to the responsive canvas layout.
-  if (
-    !presenterMode &&
-    !presenterViewRequested &&
-    params.get("responsive") !== "1"
-  ) {
+  // Only the explicitly requested editing layout is responsive. Audience and
+  // Desktop previews use the same isolated surface as Canvas and CLI previews.
+  if (presenterMode || params.get("responsive") !== "1") {
     setFixedPreviewMode(true);
+  } else {
+    setFixedPreviewMode(false);
   }
 
   updateArchitectureEditButton();
@@ -4372,7 +4692,6 @@ function init() {
     wirePreviewKeyboardNavigation();
   }
   window.addEventListener("resize", () => {
-    updateFixedPreviewScale();
     scheduleLayoutRefresh();
   });
   if (document.fonts?.ready) {