@markdstage/markdstage 3.2.0 → 3.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markdstage/markdstage",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Present, validate, inspect, capture, and export MarkdStage Markdown decks from the command line — no Copilot canvas required.",
   "license": "MIT",
   "author": "runceel",

package/shared/README.md

@@ -108,6 +108,16 @@ The themed slide is displayed and updates automatically
   notes are converted from Markdown to readable plain text in the corresponding
   PowerPoint notes pane. AI may call `export_pptx` with another
   workspace-confined `.pptx` path.
+- **Both export buttons show a visible notification outside More controls.**
+  Progress remains visible while saving, and both buttons are disabled until
+  the operation finishes. Export buttons return to their normal appearance and
+  tooltips after success or failure; the notification carries the result.
+  Success appears only after the file has been saved,
+  with its file name and selectable save location. It dismisses after eight
+  seconds, pausing while hovered or keyboard-focused. Errors remain until
+  dismissed or another export starts. Success and error notifications also have
+  a dismiss button and are announced to screen readers. Notifications never
+  appear in exported files or the external presentation window.
 - Use **More controls > Output preview** to letterbox the current slide inside
   the canvas with
   the same fixed 1280×720 typography, spacing, diagram limits, and clipping used
@@ -1038,7 +1048,7 @@ fails with `invalid_input`; pass the complete `slides` array or call
 | `inspect_layout` | `{ index?: number, includeFits?: boolean }`. Render the registered in-memory PDF snapshot with the fixed 1280×720 output layout; this does not inspect the source file on disk. Omit `index` for one preferred whole-deck inspection. Serialize targeted calls because PDF, layout, and PNG jobs are exclusive. By default, return only clipped pages; `includeFits` includes successful pages. Returns dimensions, issue counts, overflow measurements, nested scroll containers, and a bounded list of element hints. Requires Edge, Chrome, or Chromium. |
 | `capture_slides` | `{ indexes?: number[], outputDirectory?: string, theme?: "dark" | "light" | "microsoft" | "custom" }`. Generate PDF-equivalent 1280×720 PNGs for at most 10 zero-based indexes. When `indexes` is omitted, inspect the deck and capture only clipped pages. Paths stay inside the workspace; results contain paths and layout summaries, not image bytes. Requires Edge, Chrome, or Chromium. |
 | `export_pdf` | `{ outputPath?: string, theme?: "dark" | "light" | "microsoft" | "custom" }`. Export one 16:9 page per slide. Relative paths use workspace root; default is `markdstage.pdf`. Theme affects PDF only. Reject paths outside workspace and non-`.pdf` files. Temporary slide replacement and the automatic back cover are included. Returns `{ ok, path, total, theme, bytes }`. Requires Edge, Chrome, or Chromium. |
-| `export_pptx` | `{ outputPath?: string, theme?: "dark" | "light" | "microsoft" | "custom" }`. Export a hybrid editable 16:9 PowerPoint deck. Supported text, lists, links, tables, fenced code blocks, raster images, and Architecture DSL objects remain native. Code blocks preserve syntax-colored editable runs, whitespace, monospace typography, and block decoration; unsupported effects such as shadows remain reported background fallbacks. Speaker-note Markdown is exported as readable plain text in the corresponding PowerPoint notes pane. Architecture nodes, groups, and connector-label pills are visible AutoShapes with integrated text; icons are foreground pictures. Mermaid and unsupported visuals become reported background fallbacks. Relative paths use workspace root; default is `markdstage.pptx`. Reject paths outside workspace and non-`.pptx` files. Temporary slide replacement and the automatic back cover are included. Returns `{ ok, path, total, theme, bytes, format, fallbackCount, fallbacks }`. Requires Edge, Chrome, or Chromium. |
+| `export_pptx` | `{ outputPath?: string, theme?: "dark" | "light" | "microsoft" | "custom" }`. Export a hybrid editable 16:9 PowerPoint deck. Supported text, lists, links, tables, fenced code blocks, raster images, Mermaid diagrams, and Architecture DSL objects remain native. Code blocks preserve syntax-colored editable runs, whitespace, monospace typography, and block decoration; unsupported effects such as shadows remain reported background fallbacks. Speaker-note Markdown is exported as readable plain text in the corresponding PowerPoint notes pane. Architecture nodes, groups, and connector-label pills are visible AutoShapes with integrated text; icons are foreground pictures. Mermaid diagrams export as editable shapes, text, and connectors with unsupported SVG details preserved as per-element fallback pictures. Unsupported visuals become reported background fallbacks. Relative paths use workspace root; default is `markdstage.pptx`. Reject paths outside workspace and non-`.pptx` files. Temporary slide replacement and the automatic back cover are included. Returns `{ ok, path, total, theme, bytes, format, fallbackCount, fallbacks }`. Requires Edge, Chrome, or Chromium. |
 | `edit_architecture` | `{ enabled: boolean }`. Toggle placement editing. Imported decks also write to the source fence; direct decks write to canvas state. Presenter/print omit UI. Mode is not persisted and `reset` disables it. Returns `{ ok, enabled, version }`. |
 | `reset` | No input. Clear deck/slide state, disable editing, and return to the waiting view. |
 

package/shared/renderer/architecture-scene.mjs

@@ -0,0 +1,312 @@
+import {
+  createScene,
+  normalizeScene,
+  validateScene,
+} from "./scene-graph.mjs";
+
+const DEFAULT_SOURCE_PATH = "architecture";
+
+function roundedMetric(value) {
+  return Math.round(Math.max(0, Number(value) || 0) * 10) / 10;
+}
+
+function finiteNumberOr(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+
+function nonEmptyStringOr(value, fallback) {
+  return typeof value === "string" && value ? value : fallback;
+}
+
+function transformBounds(bounds, options) {
+  return {
+    x: roundedMetric(options.originX + finiteNumberOr(bounds?.x, 0) * options.scale),
+    y: roundedMetric(options.originY + finiteNumberOr(bounds?.y, 0) * options.scale),
+    width: roundedMetric(finiteNumberOr(bounds?.width, 0) * options.scale),
+    height: roundedMetric(finiteNumberOr(bounds?.height, 0) * options.scale),
+  };
+}
+
+function transformPoint(point, options) {
+  return {
+    x: roundedMetric(options.originX + finiteNumberOr(point?.x, 0) * options.scale),
+    y: roundedMetric(options.originY + finiteNumberOr(point?.y, 0) * options.scale),
+  };
+}
+
+function scaledMetric(value, options) {
+  return value === undefined ? undefined : roundedMetric(finiteNumberOr(value, 0) * options.scale);
+}
+
+function isSceneColor(value) {
+  if (value === null || value === undefined) return true;
+  if (typeof value !== "string") return false;
+  const text = value.trim();
+  if (/^#(?:[0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(text)) return true;
+  return /^rgba?\((.*)\)$/i.test(text);
+}
+
+function normalizeColor(value, path, options, diagnostics) {
+  if (value === undefined) return undefined;
+  const resolved = options.resolveColor(value, path);
+  if (resolved === undefined) return undefined;
+  if (resolved === null || resolved === "" || resolved === "none" || resolved === "transparent") return null;
+  if (isSceneColor(resolved)) return resolved;
+  diagnostics.push({
+    path,
+    kind: "color",
+    reason: `color is not resolved for scene graph: ${String(value)}`,
+  });
+  return null;
+}
+
+function definedEntries(object) {
+  return Object.fromEntries(Object.entries(object).filter(([, value]) => value !== undefined));
+}
+
+function mapStyle(object, path, options, diagnostics) {
+  const dash = object.dash === undefined ? undefined : options.resolveDash(object.dash, path);
+  const sceneDash = (() => {
+    if (dash === undefined) return undefined;
+    if (dash === "" || dash === "solid" || dash === "dash" || dash === "dashDot" || dash === "dot") return dash;
+    if (dash === "dotted") return "dot";
+    const values = String(dash)
+      .trim()
+      .split(/[ ,]+/)
+      .map(Number)
+      .filter(Number.isFinite);
+    if (values.length >= 2 && values[0] <= 2 && values[1] >= values[0] * 2) return "dot";
+    if (values.length >= 2) return "dash";
+    return "solid";
+  })();
+  return definedEntries({
+    fill: normalizeColor(object.fill, `${path}.fill`, options, diagnostics),
+    stroke: normalizeColor(object.stroke, `${path}.stroke`, options, diagnostics),
+    strokeWidth: scaledMetric(object.strokeWidth, options),
+    dash: sceneDash,
+    opacity: object.opacity,
+    cornerRadius: scaledMetric(object.cornerRadius, options),
+  });
+}
+
+function mapText(text, path, options, diagnostics) {
+  if (!text?.paragraphs) return text;
+  return {
+    paragraphs: text.paragraphs.map((paragraph, paragraphIndex) => ({
+      ...paragraph,
+      runs: paragraph.runs.map((run, runIndex) => {
+        const runPath = `${path}.paragraphs[${paragraphIndex}].runs[${runIndex}]`;
+        return definedEntries({
+          ...run,
+          fontFace: options.fontFace || run.fontFace,
+          fontSize: scaledMetric(run.fontSize, options),
+          bold: Number(run.fontWeight) >= 600,
+          color: normalizeColor(run.color, `${runPath}.color`, options, diagnostics),
+        });
+      }),
+    })),
+  };
+}
+
+function mapTextLayout(object, options) {
+  return definedEntries({
+    alignment: object.alignment,
+    verticalAlignment: object.verticalAlignment,
+    textWrap: object.textWrap,
+    textInsets: object.textInsets
+      ? Object.fromEntries(
+          Object.entries(object.textInsets).map(([key, value]) => [key, scaledMetric(value, options)]),
+        )
+      : undefined,
+  });
+}
+
+function applyShapeOpacityToText(text, opacity) {
+  if (!text?.paragraphs || !Number.isFinite(opacity)) return text;
+  return {
+    ...text,
+    paragraphs: text.paragraphs.map((paragraph) => ({
+      ...paragraph,
+      runs: paragraph.runs.map((run) => ({
+        ...run,
+        opacity: (Number.isFinite(run.opacity) ? run.opacity : 1) * opacity,
+      })),
+    })),
+  };
+}
+
+function sourcePathFor(object, fallback) {
+  return nonEmptyStringOr(object.architecture?.sourcePath, nonEmptyStringOr(object.sourcePath, fallback));
+}
+
+function sourceIdFor(object) {
+  return nonEmptyStringOr(object.architecture?.id, nonEmptyStringOr(object.id, ""));
+}
+
+function shapePreset(object) {
+  return nonEmptyStringOr(object.shape, "rect");
+}
+
+function arrowEndFor(value) {
+  if (value === true) return "triangle";
+  if (value === false || value === undefined || value === null) return "none";
+  return value;
+}
+
+function imageResult(entry, kind, options) {
+  const resolved = options.resolveImage(entry, kind);
+  if (typeof resolved === "string") return { src: resolved };
+  if (resolved && typeof resolved === "object") return resolved;
+  return { src: "" };
+}
+
+function imageNode(entry, kind, index, options) {
+  const image = imageResult(entry, kind, options);
+  const bounds = image.bounds || transformBounds(entry, options);
+  const architecture = definedEntries({
+    ...(entry.architecture || {}),
+    kind,
+    id: entry.architecture?.id || entry.id || "",
+    sourcePath: entry.architecture?.sourcePath || entry.sourcePath,
+    order: entry.architecture?.order ?? entry.order,
+    z: entry.architecture?.z ?? entry.z,
+  });
+  if (!image.src) {
+    return {
+      kind: "fallback",
+      ...(sourceIdFor({ ...entry, architecture }) ? { id: sourceIdFor({ ...entry, architecture }) } : {}),
+      sourcePath: sourcePathFor({ ...entry, architecture }, `${kind}s[${index}]`),
+      z: finiteNumberOr(image.z, index),
+      bounds,
+      reason: `${kind}-image-unavailable`,
+      meta: { architecture },
+    };
+  }
+  return {
+    kind: "image",
+    ...(sourceIdFor({ ...entry, architecture }) ? { id: sourceIdFor({ ...entry, architecture }) } : {}),
+    sourcePath: sourcePathFor({ ...entry, architecture }, `${kind}s[${index}]`),
+    z: finiteNumberOr(image.z, index),
+    bounds,
+    src: image.src,
+    alt: nonEmptyStringOr(image.alt, kind === "icon-picture" ? `${entry.icon} icon` : `${architecture.id} image`),
+    fit: image.fit || "fill",
+    opacity: image.opacity ?? 1,
+    meta: { architecture },
+  };
+}
+
+function objectNode(object, index, options, diagnostics) {
+  const path = `objects[${index}]`;
+  if (object.type === "connector") {
+    return {
+      kind: "connector",
+      ...(sourceIdFor(object) ? { id: sourceIdFor(object) } : {}),
+      sourcePath: sourcePathFor(object, path),
+      z: index,
+      points: (object.points || []).map((point) => transformPoint(point, options)),
+      style: mapStyle(object, path, options, diagnostics),
+      arrowStart: "none",
+      arrowEnd: arrowEndFor(object.arrowEnd),
+      meta: definedEntries({
+        architecture: object.architecture,
+        from: object.from,
+        to: object.to,
+      }),
+    };
+  }
+  if (object.type === "image") {
+    return imageNode(object, "image-picture", index, options);
+  }
+  if (object.type === "shape") {
+    const text = object.text === undefined
+      ? undefined
+      : applyShapeOpacityToText(mapText(object.text, `${path}.text`, options, diagnostics), object.opacity);
+    return {
+      kind: "shape",
+      ...(sourceIdFor(object) ? { id: sourceIdFor(object) } : {}),
+      sourcePath: sourcePathFor(object, path),
+      z: index,
+      bounds: transformBounds(object, options),
+      preset: shapePreset(object),
+      style: mapStyle(object, path, options, diagnostics),
+      ...(text !== undefined ? { text } : {}),
+      textLayout: mapTextLayout(object, options),
+      meta: definedEntries({
+        architecture: object.architecture,
+        icon: object.icon,
+      }),
+    };
+  }
+  return {
+    kind: "fallback",
+    sourcePath: sourcePathFor(object, path),
+    z: index,
+    bounds: transformBounds(object, options),
+    reason: `unsupported architecture object type: ${String(object.type)}`,
+    meta: definedEntries({ architecture: object.architecture }),
+  };
+}
+
+function fallbackNode(fallback, index, objectCount, options) {
+  return {
+    kind: "fallback",
+    sourcePath: nonEmptyStringOr(fallback.sourcePath, nonEmptyStringOr(fallback.path, `fallbacks[${index}]`)),
+    z: objectCount + index,
+    bounds: transformBounds(fallback, options),
+    reason: nonEmptyStringOr(fallback.reason, "architecture-rendered-as-artwork"),
+  };
+}
+
+function normalizeOptions(options = {}) {
+  return {
+    path: nonEmptyStringOr(options.path, DEFAULT_SOURCE_PATH),
+    resolveColor: typeof options.resolveColor === "function" ? options.resolveColor : (value) => value,
+    resolveImage: typeof options.resolveImage === "function" ? options.resolveImage : (entry) => entry?.src || "",
+    resolveDash: typeof options.resolveDash === "function" ? options.resolveDash : (value) => value,
+    scale: finiteNumberOr(options.scale, 1),
+    originX: finiteNumberOr(options.originX, 0),
+    originY: finiteNumberOr(options.originY, 0),
+    fontFace: typeof options.fontFace === "string" && options.fontFace ? options.fontFace : undefined,
+  };
+}
+
+export function architectureSnapshotToScene(snapshot, options = {}) {
+  const normalizedOptions = normalizeOptions(options);
+  const diagnostics = [];
+  const objects = Array.isArray(snapshot?.objects) ? snapshot.objects : [];
+  const icons = Array.isArray(snapshot?.icons) ? snapshot.icons : [];
+  const fallbacks = Array.isArray(snapshot?.fallbacks) ? snapshot.fallbacks : [];
+  const nodes = objects.flatMap((object, index) => {
+    const mapped = [objectNode(object, index, normalizedOptions, diagnostics)];
+    if (object.type === "shape" && object.icon) {
+      const icon = icons.find((candidate) => candidate.id === object.architecture?.id);
+      if (icon) mapped.push(imageNode(icon, "icon-picture", index + 1 / 2, normalizedOptions));
+    }
+    return mapped;
+  });
+  const iconObjectIds = new Set(
+    objects
+      .filter((object) => object.type === "shape" && object.icon)
+      .map((object) => object.architecture?.id),
+  );
+  icons
+    .filter((icon) => !iconObjectIds.has(icon.id))
+    .forEach((icon, index) => nodes.push(imageNode(icon, "icon-picture", objects.length + index, normalizedOptions)));
+  fallbacks.forEach((fallback, index) => nodes.push(fallbackNode(fallback, index, nodes.length, normalizedOptions)));
+
+  const accessibility = definedEntries({
+    title: snapshot?.title,
+    description: snapshot?.description,
+  });
+  const result = normalizeScene(createScene({
+    width: finiteNumberOr(snapshot?.canvas?.width, 0) * normalizedOptions.scale,
+    height: finiteNumberOr(snapshot?.canvas?.height, 0) * normalizedOptions.scale,
+    source: { kind: "architecture", path: normalizedOptions.path },
+    ...(Object.keys(accessibility).length ? { accessibility } : {}),
+    nodes,
+  }));
+  result.diagnostics.unshift(...diagnostics);
+  validateScene(result.scene);
+  return result;
+}

package/shared/renderer/architecture.mjs

@@ -1,4 +1,6 @@
 import { architectureContract } from "./architecture-contract.mjs";
+import { architectureSnapshotToScene } from "./architecture-scene.mjs";
+import { sceneToSvg, svgPrimitive } from "./scene-svg.mjs";
 import {
   ArchitectureError,
   architectureCompatibilityWarnings,
@@ -11,7 +13,6 @@ import {
   unknownArchitectureField,
 } from "./architecture-diagnostics.mjs";
 
-const SVG_NS = "http://www.w3.org/2000/svg";
 const DEFAULT_CANVAS = Object.freeze({ width: 1600, height: 900 });
 const DSL_VERSION = architectureContract.root.properties.version.const;
 const EMPTY_ARCHITECTURE_SOURCE = '{\n  "version": 1,\n  "elements": []\n}\n';
@@ -1307,11 +1308,8 @@ export function parseArchitecture(source) {
 }
 
 function svgElement(documentRef, tag, attributes = {}) {
-  const element = documentRef.createElementNS(SVG_NS, tag);
-  for (const [name, value] of Object.entries(attributes)) {
-    if (value !== undefined && value !== "") element.setAttribute(name, String(value));
-  }
-  return element;
+  // Produce portable visual detail; scene-svg is the only SVG DOM writer.
+  return svgPrimitive(tag, attributes);
 }
 
 function appendSvgTitle(documentRef, parent, text) {
@@ -3895,13 +3893,13 @@ export function architectureSemanticSnapshot(model) {
  * export. Coordinates remain in Architecture canvas units here; renderer.js
  * maps them through the rendered SVG viewBox into slide pixels.
  */
-export function architecturePowerPointSnapshot(model, documentRef = globalThis.document) {
+export function architecturePowerPointSnapshot(model, documentRef = globalThis.document, routingPlan) {
   const lookup = new Map(
     model.elements
       .filter((element) => element.type !== "connector")
       .map((element) => [element.id, element]),
   );
-  const { routes, diagnostics } = planConnectorRoutes(model, lookup);
+  const { routes, diagnostics } = routingPlan || planConnectorRoutes(model, lookup);
   const objects = [];
   const fallbacks = [];
   const icons = [];
@@ -4152,8 +4150,8 @@ export function renderArchitectureDiagram(
       .filter((element) => element.type !== "connector")
       .map((element) => [element.id, element]),
   );
-  const { routes: connectorRoutes, diagnostics: routingDiagnostics } =
-    planConnectorRoutes(model, lookup);
+  const routingPlan = planConnectorRoutes(model, lookup);
+  const { routes: connectorRoutes, diagnostics: routingDiagnostics } = routingPlan;
   model.elements.forEach((element, index) => {
     if (element.type === "image") {
       const clipPath = svgElement(documentRef, "clipPath", {
@@ -4195,16 +4193,21 @@ export function renderArchitectureDiagram(
   // Table for announcing connector endpoints by visible label; traverse elements only once.
   const endpointNames = endpointDisplayNames(model.elements);
   const frontLabels = [];
+  const visuals = new Map();
 
   model.elements.forEach((element, index) => {
     if (element.type === "group") {
-      svg.appendChild(renderGroup(documentRef, element));
+      const primitive = renderGroup(documentRef, element);
+      visuals.set(`group:${element.order}`, primitive);
+      svg.appendChild(primitive);
     } else if (element.type === "node") {
-      svg.appendChild(renderNode(documentRef, element));
+      const primitive = renderNode(documentRef, element);
+      visuals.set(`node:${element.order}`, primitive);
+      svg.appendChild(primitive);
     } else if (element.type === "image") {
-      svg.appendChild(
-        renderImage(documentRef, element, `architecture-image-clip-${renderId}-${index}`),
-      );
+      const primitive = renderImage(documentRef, element, `architecture-image-clip-${renderId}-${index}`);
+      visuals.set(`image-picture:${element.order}`, primitive);
+      svg.appendChild(primitive);
     } else {
       const rendered = renderConnector(
         documentRef,
@@ -4214,13 +4217,33 @@ export function renderArchitectureDiagram(
         endpointNames,
         model.canvas,
       );
+      visuals.set(`connector:${element.order}`, rendered.group);
       svg.appendChild(rendered.group);
-      if (rendered.frontLabel) frontLabels.push(rendered.frontLabel);
+      if (rendered.frontLabel) {
+        visuals.set(`connector-label:${element.order}`, rendered.frontLabel);
+        frontLabels.push(rendered.frontLabel);
+      }
     }
   });
   frontLabels.forEach((label) => svg.appendChild(label));
-  wrapper.appendChild(svg);
-  const powerPointSnapshot = architecturePowerPointSnapshot(model, documentRef);
+  const powerPointSnapshot = architecturePowerPointSnapshot(model, documentRef, routingPlan);
+  const { scene } = architectureSnapshotToScene(powerPointSnapshot);
+  const slots = new Map();
+  scene.nodes.forEach((node, index) => {
+    const source = node.meta?.architecture;
+    const visual = visuals.get(`${source?.kind}:${source?.order}`);
+    if (visual) {
+      node.meta.svg = visual;
+      slots.set(visual, index);
+    } else {
+      // Icons and back-layer labels are painted within their owning node/connector
+      // so opacity, accessible names and editor hit targets remain a single subtree.
+      node.meta = { ...node.meta, svgOwner: source?.order ?? index };
+    }
+  });
+  svg.children = svg.children.map((child) => slots.has(child) ? { sceneNode: slots.get(child) } : child);
+  scene.meta = { svgRoot: svg };
+  wrapper.appendChild(sceneToSvg(scene, { document: documentRef, template: svg }));
   Object.defineProperty(wrapper, "__presentationPptxSnapshot", {
     value: powerPointSnapshot,
     enumerable: true,

package/shared/renderer/index.html

@@ -72,9 +72,17 @@
       </section>
     </div>
     <span id="presentStatus" class="sr-only" aria-live="polite"></span>
-    <span id="exportStatus" class="sr-only" aria-live="polite"></span>
     <span id="sourceStatus" class="sr-only" aria-live="polite"></span>
   </nav>
+  <span id="exportStatus" class="export-feedback sr-only" role="status" aria-live="polite" aria-atomic="true"></span>
+  <span id="exportErrorStatus" class="export-feedback sr-only" role="alert" aria-atomic="true"></span>
+  <section id="exportNotification" class="export-feedback export-notification" aria-label="Export notification" hidden>
+    <div class="export-notification-content">
+      <p id="exportNotificationMessage" class="export-notification-message"></p>
+      <p id="exportNotificationPath" class="export-notification-path" tabindex="0" hidden></p>
+    </div>
+    <button id="exportNotificationClose" class="nav-btn" type="button" aria-label="Dismiss export notification" hidden>&#10005;</button>
+  </section>
   <div id="layoutWarning" class="layout-warning" role="status" aria-live="polite" hidden></div>
 
   <section id="presenterView" class="presenter-view" hidden aria-label="Presenter view">