@markdstage/markdstage 2.4.1 → 2.5.0

package/README.md

@@ -21,6 +21,13 @@ npx @markdstage/markdstage present slides.md
 npm install --global @markdstage/markdstage
 ```
 
+For offline installation, download the versioned `.tgz` asset from the
+[GitHub Release](https://github.com/runceel/markdstage/releases) and install it locally:
+
+```console
+npm install --global .\markdstage-markdstage-<version>.tgz
+```
+
 ## Commands
 
 ```console
@@ -43,7 +50,7 @@ markdstage skill install --target claude
 | `validate` | Checks deck structure, Architecture DSL blocks, themes, and theme paths. |
 | `inspect` | Reports the same compact 1280x720 clipping diagnostics as the canvas `inspect_layout` action. `--slide <n>` limits it to one page, `--all` includes slides that fit, `--fail-on-issues` exits with code 5. |
 | `capture` | Writes 1280x720 PNG files. Without `--pages` only the slides reported as clipped are captured. |
-| `export` | Produces the same 16:9 PDF or hybrid editable PowerPoint as the canvas Extension. The `--output` extension selects the format; PDF remains the default. |
+| `export` | Produces the same 16:9 PDF or hybrid editable PowerPoint as the canvas Extension. PowerPoint output includes speaker-note Markdown as readable plain text notes. The `--output` extension selects the format; PDF remains the default. |
 | `guide` | Prints the canonical `markdstage_guide` topics. |
 | `skill` | Installs or checks the portable Agent Skills for Codex (`.agents/skills/markdstage/`), Claude Code (`.claude/skills/markdstage/`), and GitHub Copilot (`.github/skills/markdstage/`). Locally modified files are never overwritten without `--force`. |
 | `help` | Shows the overview, or the help for one command. `markdstage help <command>` prints the same text as `markdstage <command> --help`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markdstage/markdstage",
-  "version": "2.4.1",
+  "version": "2.5.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

@@ -73,8 +73,9 @@ The themed slide is displayed and updates automatically
   `auto` measures standard slides without code, tables, images, or Mermaid and
   enlarges only when ample space remains.
 - Put **speaker notes** in top-level HTML comments on each slide. Presenter view
-  renders notes as Markdown and follows navigation. Notes are absent from
-  regular slides, the external presenter, and PDF output.
+  renders notes as Markdown and follows navigation. PowerPoint export includes
+  readable plain-text notes. Notes are absent from regular slides, the external
+  presenter, and PDF output.
 - The **canvas renderer** owns the compact navigation controls, shape editing,
   the slide list, and current position. **More controls > Shape editing**
   toggles the same placement mode as `edit_architecture`. For Markdown loaded
@@ -95,8 +96,10 @@ The themed slide is displayed and updates automatically
   DSL objects as native PowerPoint content. Architecture nodes, groups, and
   connector-label pills are visible AutoShapes with integrated text; icons use a
   transparent foreground picture layer. Mermaid and unsupported styling stay
-  visible as background artwork and are listed in the export report. AI may call
-  `export_pptx` with another workspace-confined `.pptx` path.
+  visible as background artwork and are listed in the export report. Speaker
+  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.
 - 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
@@ -945,7 +948,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, raster images, and Architecture DSL objects remain native. 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, raster images, and Architecture DSL objects remain native. 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. |
 | `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/renderer.js

@@ -7,6 +7,8 @@ import {
 } from "./theme.mjs";
 import {
   extractSpeakerNotes,
+  speakerNotesToPlainText,
+  splitSpeakerNotes,
   stripSpeakerNotes,
 } from "./speaker-notes.mjs";
 import { splitImportPath } from "./import-path.mjs";
@@ -604,7 +606,8 @@ function createSlide(markdown, fallbackTheme, themeLocked = deckThemeLocked) {
   const md = placeholder ? PLACEHOLDER : markdown;
   const { meta, body: rawBody } = splitFrontMatter(md);
   const directive = extractSlideSizeDirective(rawBody);
-  const body = stripSpeakerNotes(directive.body);
+  const speakerNotes = splitSpeakerNotes(directive.body);
+  const body = speakerNotes.markdown;
 
   const layout = (meta.layout || "").toLowerCase();
   const titleSlide = layout === "title";
@@ -771,6 +774,7 @@ function createSlide(markdown, fallbackTheme, themeLocked = deckThemeLocked) {
     sectionSlide,
     centerSlide,
     backcoverSlide,
+    speakerNotes: speakerNotes.notes,
     title: meta.title || meta.deck || "Slide",
   };
 }
@@ -1583,6 +1587,9 @@ async function collectPptxSlide(slide, index) {
         : undefined,
     });
     if (!paragraph.runs.some((run) => run.text.trim())) continue;
+    const disableTextWrap =
+      element.classList.contains("kicker") ||
+      (element.matches("h1, h2, .slide-title") && renderedTextLineCount(element) === 1);
     elements.push({
       type: "text",
       path: elementPath(element, deck),
@@ -1591,9 +1598,7 @@ async function collectPptxSlide(slide, index) {
         : relativeBounds(element, deck)),
       paragraphs: [paragraph],
       opacity: Number(getComputedStyle(element).opacity) || 1,
-      ...(element.matches("h1, h2, .slide-title") && renderedTextLineCount(element) === 1
-        ? { textWrap: "none" }
-        : {}),
+      ...(disableTextWrap ? { textWrap: "none" } : {}),
     });
     element.setAttribute("data-pptx-native", "text");
   }
@@ -1749,6 +1754,7 @@ async function collectPptxSlide(slide, index) {
           ? "backcover"
           : "standard";
   const visibleTitle = deck.querySelector("h1, h2")?.textContent?.trim();
+  const notes = speakerNotesToPlainText(slide.speakerNotes, window.marked, document);
   return {
     index,
     layout,
@@ -1756,6 +1762,7 @@ async function collectPptxSlide(slide, index) {
     title: visibleTitle || slide.title,
     width: OUTPUT_WIDTH,
     height: OUTPUT_HEIGHT,
+    ...(notes ? { notes } : {}),
     elements,
     fallbacks,
   };

package/shared/renderer/speaker-notes.mjs

@@ -18,6 +18,253 @@ function normalizeNote(text) {
   return lines.map((line) => line.slice(indent)).join("\n").trim();
 }
 
+function isXmlCodePoint(codePoint) {
+  return (
+    codePoint === 0x9 ||
+    codePoint === 0xa ||
+    codePoint === 0xd ||
+    (codePoint >= 0x20 && codePoint <= 0xd7ff) ||
+    (codePoint >= 0xe000 && codePoint <= 0xfffd) ||
+    (codePoint >= 0x10000 && codePoint <= 0x10ffff)
+  );
+}
+
+function xmlSafeText(text) {
+  return [...text]
+    .map((character) => (isXmlCodePoint(character.codePointAt(0)) ? character : "\uFFFD"))
+    .join("");
+}
+
+function decodeEntities(text) {
+  const named = new Map([
+    ["amp", "&"],
+    ["apos", "'"],
+    ["gt", ">"],
+    ["lt", "<"],
+    ["nbsp", " "],
+    ["quot", '"'],
+  ]);
+  return text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (entity, value) => {
+    if (value[0] !== "#") return named.get(value.toLowerCase()) ?? entity;
+    const codePoint =
+      value[1]?.toLowerCase() === "x"
+        ? Number.parseInt(value.slice(2), 16)
+        : Number.parseInt(value.slice(1), 10);
+    if (!Number.isSafeInteger(codePoint) || codePoint < 0 || codePoint > 0x10ffff) {
+      return entity;
+    }
+    return isXmlCodePoint(codePoint) ? String.fromCodePoint(codePoint) : "\uFFFD";
+  });
+}
+
+function htmlEntityDecoder(documentRef) {
+  if (!documentRef || typeof documentRef.createElement !== "function") {
+    return decodeEntities;
+  }
+  const textarea = documentRef.createElement("textarea");
+  return (text) => {
+    textarea.innerHTML = text;
+    return textarea.value;
+  };
+}
+
+function htmlTagEnd(value, start) {
+  let quote = "";
+  for (let index = start + 1; index < value.length; index += 1) {
+    const character = value[index];
+    if (quote) {
+      if (character === quote) quote = "";
+    } else if (character === '"' || character === "'") {
+      quote = character;
+    } else if (character === ">") {
+      return index;
+    }
+  }
+  return -1;
+}
+
+function htmlTokenText(value, decodeHtml) {
+  const blockTags = new Set([
+    "address",
+    "article",
+    "aside",
+    "blockquote",
+    "div",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "li",
+    "p",
+    "pre",
+    "section",
+    "tr",
+  ]);
+  let output = "";
+  let cursor = 0;
+  while (cursor < value.length) {
+    const start = value.indexOf("<", cursor);
+    if (start < 0) {
+      output += value.slice(cursor);
+      break;
+    }
+    output += value.slice(cursor, start);
+    if (value.startsWith("<!--", start)) {
+      const end = value.indexOf("-->", start + 4);
+      cursor = end < 0 ? value.length : end + 3;
+      continue;
+    }
+    const end = htmlTagEnd(value, start);
+    if (end < 0) {
+      output += value.slice(start);
+      break;
+    }
+    const source = value.slice(start + 1, end).trim();
+    const closing = source.startsWith("/");
+    const name = /^\/?\s*([a-z][a-z0-9-]*)/i.exec(source)?.[1]?.toLowerCase();
+    if (!name) {
+      output += value.slice(start, end + 1);
+    } else if (name === "br") {
+      output += "\n";
+    } else if (!closing && name === "li") {
+      output += "• ";
+    } else if (closing && blockTags.has(name)) {
+      output += "\n";
+    }
+    cursor = end + 1;
+  }
+  return decodeHtml(output);
+}
+
+function inlineTokensText(tokens, decodeHtml) {
+  return (Array.isArray(tokens) ? tokens : [])
+    .map((token) => {
+      if (!token || typeof token !== "object") return "";
+      if (token.type === "br") return "\n";
+      if (token.type === "codespan" || token.type === "escape") {
+        return decodeHtml(token.text || "");
+      }
+      if (token.type === "image") return decodeHtml(token.text || "");
+      if (token.type === "html") {
+        return htmlTokenText(token.text || token.raw || "", decodeHtml);
+      }
+      if (token.type === "link") {
+        const label =
+          inlineTokensText(token.tokens, decodeHtml) ||
+          decodeHtml(token.text || token.href || "");
+        const href = decodeHtml(token.href || "");
+        if (!href || href === label || href === `mailto:${label}`) return label;
+        return `${label} (${href})`;
+      }
+      if (Array.isArray(token.tokens)) return inlineTokensText(token.tokens, decodeHtml);
+      return decodeHtml(token.text || "");
+    })
+    .join("");
+}
+
+function listTokenText(token, depth, decodeHtml) {
+  const orderedStart = Number.isInteger(Number(token.start)) ? Number(token.start) : 1;
+  return token.items
+    .map((item, itemIndex) => {
+      const marker = item.task
+        ? item.checked
+          ? "☒ "
+          : "☐ "
+        : token.ordered
+          ? `${orderedStart + itemIndex}. `
+          : "• ";
+      const indent = "  ".repeat(depth);
+      const continuation = `${indent}${" ".repeat(marker.length)}`;
+      const lines = [];
+      let started = false;
+      for (const child of item.tokens || []) {
+        if (child.type === "space") continue;
+        if (child.type === "list") {
+          lines.push(listTokenText(child, depth + 1, decodeHtml));
+          continue;
+        }
+        const text = blockTokenText(child, depth, decodeHtml).trim();
+        if (!text) continue;
+        const childLines = text.split("\n");
+        if (!started) {
+          lines.push(`${indent}${marker}${childLines.shift() || ""}`);
+          started = true;
+        }
+        lines.push(...childLines.map((line) => continuation + line));
+        if (started && child.type === "paragraph" && lines.length > 1) {
+          lines.push("");
+        }
+      }
+      if (lines.at(-1) === "") lines.pop();
+      return lines.join("\n");
+    })
+    .join("\n");
+}
+
+function tableTokenText(token, decodeHtml) {
+  const rows = [
+    token.header || [],
+    ...(Array.isArray(token.rows) ? token.rows : []),
+  ];
+  return rows
+    .map((row) =>
+      row.map((cell) => inlineTokensText(cell.tokens, decodeHtml)).join(" | "),
+    )
+    .join("\n");
+}
+
+function blockTokenText(token, listDepth, decodeHtml) {
+  if (!token || typeof token !== "object") return "";
+  if (["heading", "paragraph", "text"].includes(token.type)) {
+    return inlineTokensText(token.tokens, decodeHtml) || decodeHtml(token.text || "");
+  }
+  if (token.type === "code") return token.text || "";
+  if (token.type === "blockquote") {
+    return blockTokensText(token.tokens, listDepth, decodeHtml);
+  }
+  if (token.type === "list") return listTokenText(token, listDepth, decodeHtml);
+  if (token.type === "table") return tableTokenText(token, decodeHtml);
+  if (token.type === "html") {
+    return htmlTokenText(token.text || token.raw || "", decodeHtml);
+  }
+  if (Array.isArray(token.tokens)) {
+    return blockTokensText(token.tokens, listDepth, decodeHtml);
+  }
+  return token.type === "space" || token.type === "hr"
+    ? ""
+    : decodeHtml(token.text || "");
+}
+
+function blockTokensText(tokens, listDepth, decodeHtml) {
+  return (Array.isArray(tokens) ? tokens : [])
+    .map((token) => blockTokenText(token, listDepth, decodeHtml).trimEnd())
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+/**
+ * Convert speaker-note Markdown into readable plain text for PowerPoint notes.
+ *
+ * Paragraphs, list indentation, code contents, link destinations, and table
+ * columns remain readable while presentation-only Markdown markers are removed.
+ */
+export function speakerNotesToPlainText(
+  markdown,
+  markedApi = globalThis.marked,
+  documentRef = globalThis.document,
+) {
+  if (!markedApi || typeof markedApi.lexer !== "function") {
+    throw new TypeError("A Marked lexer is required to convert speaker notes.");
+  }
+  const tokens = markedApi.lexer(normalizeText(markdown), { gfm: true });
+  const decodeHtml = htmlEntityDecoder(documentRef);
+  return xmlSafeText(blockTokensText(tokens, 0, decodeHtml))
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
 function closesFence(line, fence) {
   const indentation = line.match(/^[ \t]*/)?.[0].length ?? 0;
   if (indentation > 3) return false;
@@ -104,3 +351,8 @@ export function extractSpeakerNotes(markdown) {
 export function stripSpeakerNotes(markdown) {
   return parseSpeakerNotes(markdown).markdown;
 }
+
+/** Return visible Markdown and speaker notes from one parser pass. */
+export function splitSpeakerNotes(markdown) {
+  return parseSpeakerNotes(markdown);
+}

package/shared/runtime/output.mjs

@@ -173,6 +173,9 @@ export async function preparePptxPackageModel(
     if (!sourceSlide || !Array.isArray(sourceSlide.elements)) {
       throw new Error(`PowerPoint slide ${slideIndex + 1} has an invalid element list.`);
     }
+    if (sourceSlide.notes !== undefined && typeof sourceSlide.notes !== "string") {
+      throw new Error(`PowerPoint slide ${slideIndex + 1} has invalid speaker notes.`);
+    }
     const elements = [];
     for (const sourceElement of sourceSlide.elements) {
       if (sourceElement?.type !== "image") {
@@ -210,6 +213,7 @@ export async function preparePptxPackageModel(
     }
     slides.push({
       backgroundAssetId: `markdstage-background-${slideIndex + 1}`,
+      ...(sourceSlide.notes ? { notes: sourceSlide.notes } : {}),
       elements,
     });
   }
@@ -594,9 +598,13 @@ export async function exportPptx(
         ...packageModel,
       });
       const packageSummary = inspectPackage(buffer);
+      const expectedNotes = model.slides.filter(
+        (slide) => typeof slide.notes === "string" && slide.notes.trim(),
+      ).length;
       if (
         !packageSummary.valid ||
         packageSummary.slideCount !== snapshot.slides.length ||
+        packageSummary.notesCount !== expectedNotes ||
         packageSummary.dimensions.widthEmu !== PPTX_DIMENSIONS.widthEmu ||
         packageSummary.dimensions.heightEmu !== PPTX_DIMENSIONS.heightEmu
       ) {

package/shared/runtime/pptx-package.mjs

@@ -17,6 +17,7 @@ const NS_R =
 const NS_REL =
   "http://schemas.openxmlformats.org/package/2006/relationships";
 const JAPANESE_FONT_FACE = "Yu Gothic";
+const HUNDREDTH_POINTS_PER_PIXEL = 75;
 
 const REL = {
   officeDocument: `${NS_R}/officeDocument`,
@@ -28,6 +29,8 @@ const REL = {
   theme: `${NS_R}/theme`,
   image: `${NS_R}/image`,
   hyperlink: `${NS_R}/hyperlink`,
+  notesSlide: `${NS_R}/notesSlide`,
+  notesMaster: `${NS_R}/notesMaster`,
 };
 
 const CONTENT_TYPES = {
@@ -50,8 +53,21 @@ function fail(message) {
   throw new TypeError(`Invalid PowerPoint model: ${message}`);
 }
 
+function isXmlCodePoint(codePoint) {
+  return (
+    codePoint === 0x9 ||
+    codePoint === 0xa ||
+    codePoint === 0xd ||
+    (codePoint >= 0x20 && codePoint <= 0xd7ff) ||
+    (codePoint >= 0xe000 && codePoint <= 0xfffd) ||
+    (codePoint >= 0x10000 && codePoint <= 0x10ffff)
+  );
+}
+
 function xmlEscape(value) {
-  return String(value)
+  return [...String(value)]
+    .map((character) => (isXmlCodePoint(character.codePointAt(0)) ? character : "\uFFFD"))
+    .join("")
     .replaceAll("&", "&amp;")
     .replaceAll("<", "&lt;")
     .replaceAll(">", "&gt;")
@@ -334,7 +350,26 @@ function normalizeText(value, path) {
   return value;
 }
 
-function paragraphXml(paragraph, path, relationships) {
+function bulletTextOffsetPx(paragraph, path) {
+  if (
+    !paragraph ||
+    typeof paragraph !== "object" ||
+    Array.isArray(paragraph) ||
+    !paragraph.bullet ||
+    !Array.isArray(paragraph.runs) ||
+    paragraph.runs.length === 0
+  ) {
+    return 0;
+  }
+  const largestRunSize = Math.max(
+    ...paragraph.runs.map((run, index) =>
+      fontSizeOf(run, `${path}.runs[${index}]`),
+    ),
+  );
+  return largestRunSize / HUNDREDTH_POINTS_PER_PIXEL;
+}
+
+function paragraphXml(paragraph, path, relationships, leftMarginPx = 0) {
   if (!paragraph || typeof paragraph !== "object" || Array.isArray(paragraph)) {
     fail(`${path} must be an object`);
   }
@@ -360,12 +395,21 @@ function paragraphXml(paragraph, path, relationships) {
         : paragraph.bullet.character || "•";
     bullet = `<a:buChar char="${xmlEscape(character)}"/>`;
   }
+  const bulletOffsetPx = bulletTextOffsetPx(paragraph, path);
+  const paragraphMarginPx = Math.max(leftMarginPx, bulletOffsetPx);
+  const indentation = [
+    paragraphMarginPx > 0 ? `marL="${emu(paragraphMarginPx)}"` : "",
+    bulletOffsetPx > 0 ? `indent="-${emu(bulletOffsetPx)}"` : "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+  const indentationAttributes = indentation ? ` ${indentation}` : "";
   const runs = paragraph.runs
     .map((run, index) =>
       runXml(run, `${path}.runs[${index}]`, relationships),
     )
     .join("");
-  return `<a:p><a:pPr algn="${align}" lvl="${level}">${bullet}</a:pPr>${runs}<a:endParaRPr lang="en-US"><a:ea typeface="${JAPANESE_FONT_FACE}"/></a:endParaRPr></a:p>`;
+  return `<a:p><a:pPr algn="${align}" lvl="${level}"${indentationAttributes}>${bullet}</a:pPr>${runs}<a:endParaRPr lang="en-US" noProof="1"><a:ea typeface="${JAPANESE_FONT_FACE}"/></a:endParaRPr></a:p>`;
 }
 
 function runXml(run, path, relationships) {
@@ -376,6 +420,7 @@ function runXml(run, path, relationships) {
   const size = fontSizeOf(run, path);
   const attributes = [
     'lang="en-US"',
+    'noProof="1"',
     `sz="${size}"`,
     run.bold ? 'b="1"' : "",
     run.italic ? 'i="1"' : "",
@@ -448,11 +493,17 @@ function textBodyXml(
   tag = "p:txBody",
   bodyOptions = {},
   bodyPath = path,
+  leftMarginPx = 0,
 ) {
   const text = normalizeText(value, path);
   const paragraphs = text.paragraphs
     .map((paragraph, index) =>
-      paragraphXml(paragraph, `${path}.paragraphs[${index}]`, relationships),
+      paragraphXml(
+        paragraph,
+        `${path}.paragraphs[${index}]`,
+        relationships,
+        leftMarginPx,
+      ),
     )
     .join("");
   return `<${tag}>${textBodyPropertiesXml(bodyOptions, bodyPath)}<a:lstStyle/>${paragraphs}</${tag}>`;
@@ -465,12 +516,35 @@ function shapeBase(id, name, bounds, properties, text = "") {
 function textShapeXml(element, path, id, relationships) {
   const bounds = boundsOf(element, path);
   const text = { paragraphs: element.paragraphs };
+  const paragraphs = Array.isArray(text.paragraphs) ? text.paragraphs : [];
+  const bulletInsetPx = Math.max(
+    0,
+    ...paragraphs.map((paragraph, index) =>
+      bulletTextOffsetPx(paragraph, `${path}.paragraphs[${index}]`),
+    ),
+  );
+  const adjustedBounds =
+    bulletInsetPx > 0
+      ? {
+          ...bounds,
+          x: bounds.x - bulletInsetPx,
+          width: bounds.width + bulletInsetPx,
+        }
+      : bounds;
   return shapeBase(
     id,
     `Text ${id}`,
-    bounds,
+    adjustedBounds,
     '<a:prstGeom prst="rect"><a:avLst/></a:prstGeom><a:noFill/><a:ln><a:noFill/></a:ln>',
-    textBodyXml(text, `${path}`, relationships, "p:txBody", element),
+    textBodyXml(
+      text,
+      `${path}`,
+      relationships,
+      "p:txBody",
+      element,
+      path,
+      bulletInsetPx,
+    ),
   );
 }
 
@@ -665,7 +739,7 @@ function connectorXml(element, path, nextId, relationships) {
   return shapes.join("");
 }
 
-function relationshipRegistry() {
+function relationshipRegistry(notesSlideNumber = null) {
   const entries = [
     {
       id: "rId1",
@@ -674,6 +748,14 @@ function relationshipRegistry() {
       external: false,
     },
   ];
+  if (notesSlideNumber !== null) {
+    entries.push({
+      id: `rId${entries.length + 1}`,
+      type: REL.notesSlide,
+      target: `../notesSlides/notesSlide${notesSlideNumber}.xml`,
+      external: false,
+    });
+  }
   const images = new Map();
   const hyperlinks = new Map();
   const add = (type, target, external) => {
@@ -707,13 +789,13 @@ function baseShapeTree() {
   return '<p:nvGrpSpPr><p:cNvPr id="1" name=""/><p:cNvGrpSpPr/><p:nvPr/></p:nvGrpSpPr><p:grpSpPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="0" cy="0"/><a:chOff x="0" y="0"/><a:chExt cx="0" cy="0"/></a:xfrm></p:grpSpPr>';
 }
 
-function buildSlide(slide, slideIndex, assets) {
+function buildSlide(slide, slideIndex, assets, notesSlideNumber = null) {
   const path = `slides[${slideIndex}]`;
   if (!slide || typeof slide !== "object" || Array.isArray(slide)) {
     fail(`${path} must be an object`);
   }
   if (!Array.isArray(slide.elements)) fail(`${path}.elements must be an array`);
-  const relationships = relationshipRegistry();
+  const relationships = relationshipRegistry(notesSlideNumber);
   let shapeId = 2;
   const nextId = () => shapeId++;
   const shapes = [];
@@ -787,7 +869,7 @@ function relationshipsXml(entries) {
     .join("")}</Relationships>`;
 }
 
-function contentTypesXml(slideCount, assets) {
+function contentTypesXml(slideCount, assets, notesCount) {
   const imageTypes = new Map();
   for (const asset of assets.values()) {
     imageTypes.set(asset.extension, asset.contentType);
@@ -803,19 +885,36 @@ function contentTypesXml(slideCount, assets) {
     (_, index) =>
       `<Override PartName="/ppt/slides/slide${index + 1}.xml" ContentType="application/vnd.openxmlformats-officedocument.presentationml.slide+xml"/>`,
   ).join("");
-  return `${XML}<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/>${defaults}<Override PartName="/docProps/core.xml" ContentType="application/vnd.openxmlformats-package.core-properties+xml"/><Override PartName="/docProps/app.xml" ContentType="application/vnd.openxmlformats-officedocument.extended-properties+xml"/><Override PartName="/ppt/presentation.xml" ContentType="application/vnd.openxmlformats-officedocument.presentationml.presentation.main+xml"/><Override PartName="/ppt/slideMasters/slideMaster1.xml" ContentType="application/vnd.openxmlformats-officedocument.presentationml.slideMaster+xml"/><Override PartName="/ppt/slideLayouts/slideLayout1.xml" ContentType="application/vnd.openxmlformats-officedocument.presentationml.slideLayout+xml"/><Override PartName="/ppt/theme/theme1.xml" ContentType="application/vnd.openxmlformats-officedocument.theme+xml"/>${slides}</Types>`;
+  const notes = Array.from(
+    { length: notesCount },
+    (_, index) =>
+      `<Override PartName="/ppt/notesSlides/notesSlide${index + 1}.xml" ContentType="application/vnd.openxmlformats-officedocument.presentationml.notesSlide+xml"/>`,
+  ).join("");
+  const notesMaster =
+    notesCount > 0
+      ? '<Override PartName="/ppt/notesMasters/notesMaster1.xml" ContentType="application/vnd.openxmlformats-officedocument.presentationml.notesMaster+xml"/>'
+      : "";
+  const notesTheme =
+    notesCount > 0
+      ? '<Override PartName="/ppt/theme/theme2.xml" ContentType="application/vnd.openxmlformats-officedocument.theme+xml"/>'
+      : "";
+  return `${XML}<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/>${defaults}<Override PartName="/docProps/core.xml" ContentType="application/vnd.openxmlformats-package.core-properties+xml"/><Override PartName="/docProps/app.xml" ContentType="application/vnd.openxmlformats-officedocument.extended-properties+xml"/><Override PartName="/ppt/presentation.xml" ContentType="application/vnd.openxmlformats-officedocument.presentationml.presentation.main+xml"/><Override PartName="/ppt/slideMasters/slideMaster1.xml" ContentType="application/vnd.openxmlformats-officedocument.presentationml.slideMaster+xml"/><Override PartName="/ppt/slideLayouts/slideLayout1.xml" ContentType="application/vnd.openxmlformats-officedocument.presentationml.slideLayout+xml"/><Override PartName="/ppt/theme/theme1.xml" ContentType="application/vnd.openxmlformats-officedocument.theme+xml"/>${notesTheme}${slides}${notesMaster}${notes}</Types>`;
 }
 
-function presentationXml(slideCount) {
+function presentationXml(slideCount, notesCount) {
   const slides = Array.from(
     { length: slideCount },
     (_, index) =>
       `<p:sldId id="${256 + index}" r:id="rId${index + 2}"/>`,
   ).join("");
-  return `${XML}<p:presentation xmlns:a="${NS_A}" xmlns:r="${NS_R}" xmlns:p="${NS_P}"><p:sldMasterIdLst><p:sldMasterId id="2147483648" r:id="rId1"/></p:sldMasterIdLst><p:sldIdLst>${slides}</p:sldIdLst><p:sldSz cx="${PPTX_DIMENSIONS.widthEmu}" cy="${PPTX_DIMENSIONS.heightEmu}" type="screen16x9"/><p:notesSz cx="6858000" cy="9144000"/><p:defaultTextStyle/></p:presentation>`;
+  const notesMaster =
+    notesCount > 0
+      ? `<p:notesMasterIdLst><p:notesMasterId r:id="rId${slideCount + 2}"/></p:notesMasterIdLst>`
+      : "";
+  return `${XML}<p:presentation xmlns:a="${NS_A}" xmlns:r="${NS_R}" xmlns:p="${NS_P}"><p:sldMasterIdLst><p:sldMasterId id="2147483648" r:id="rId1"/></p:sldMasterIdLst>${notesMaster}<p:sldIdLst>${slides}</p:sldIdLst><p:sldSz cx="${PPTX_DIMENSIONS.widthEmu}" cy="${PPTX_DIMENSIONS.heightEmu}" type="screen16x9"/><p:notesSz cx="6858000" cy="9144000"/><p:defaultTextStyle/></p:presentation>`;
 }
 
-function presentationRelsXml(slideCount) {
+function presentationRelsXml(slideCount, notesCount) {
   const entries = [
     {
       id: "rId1",
@@ -828,6 +927,13 @@ function presentationRelsXml(slideCount) {
       target: `slides/slide${index + 1}.xml`,
     })),
   ];
+  if (notesCount > 0) {
+    entries.push({
+      id: `rId${slideCount + 2}`,
+      type: REL.notesMaster,
+      target: "notesMasters/notesMaster1.xml",
+    });
+  }
   return relationshipsXml(entries);
 }
 
@@ -835,8 +941,8 @@ function coreXml(title) {
   return `${XML}<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:dcmitype="http://purl.org/dc/dcmitype/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><dc:title>${xmlEscape(title)}</dc:title><dc:creator>MarkdStage</dc:creator><cp:lastModifiedBy>MarkdStage</cp:lastModifiedBy></cp:coreProperties>`;
 }
 
-function appXml(slideCount) {
-  return `${XML}<Properties xmlns="http://schemas.openxmlformats.org/officeDocument/2006/extended-properties" xmlns:vt="http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes"><Application>MarkdStage</Application><PresentationFormat>On-screen Show (16:9)</PresentationFormat><Slides>${slideCount}</Slides><Notes>0</Notes><HiddenSlides>0</HiddenSlides><MMClips>0</MMClips><ScaleCrop>false</ScaleCrop><Company/><LinksUpToDate>false</LinksUpToDate><SharedDoc>false</SharedDoc><HyperlinksChanged>false</HyperlinksChanged><AppVersion>1.0</AppVersion></Properties>`;
+function appXml(slideCount, notesCount) {
+  return `${XML}<Properties xmlns="http://schemas.openxmlformats.org/officeDocument/2006/extended-properties" xmlns:vt="http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes"><Application>MarkdStage</Application><PresentationFormat>On-screen Show (16:9)</PresentationFormat><Slides>${slideCount}</Slides><Notes>${notesCount}</Notes><HiddenSlides>0</HiddenSlides><MMClips>0</MMClips><ScaleCrop>false</ScaleCrop><Company/><LinksUpToDate>false</LinksUpToDate><SharedDoc>false</SharedDoc><HyperlinksChanged>false</HyperlinksChanged><AppVersion>1.0</AppVersion></Properties>`;
 }
 
 function themeXml() {
@@ -851,6 +957,97 @@ function slideLayoutXml() {
   return `${XML}<p:sldLayout xmlns:a="${NS_A}" xmlns:r="${NS_R}" xmlns:p="${NS_P}" type="blank" preserve="1"><p:cSld name="Blank"><p:spTree>${baseShapeTree()}</p:spTree></p:cSld><p:clrMapOvr><a:masterClrMapping/></p:clrMapOvr></p:sldLayout>`;
 }
 
+function notesPlaceholderXml({ id, name, type, idx, x, y, cx, cy, paragraphs = "" }) {
+  return `<p:sp><p:nvSpPr><p:cNvPr id="${id}" name="${xmlEscape(name)}"/><p:cNvSpPr txBox="1"/><p:nvPr><p:ph type="${type}" idx="${idx}"/></p:nvPr></p:nvSpPr><p:spPr><a:xfrm><a:off x="${x}" y="${y}"/><a:ext cx="${cx}" cy="${cy}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom><a:noFill/><a:ln><a:noFill/></a:ln></p:spPr><p:txBody><a:bodyPr/><a:lstStyle/>${paragraphs || "<a:p/>"}</p:txBody></p:sp>`;
+}
+
+function notesParagraphsXml(notes) {
+  return notes
+    .split("\n")
+    .map((line) => {
+      if (!line) {
+        return `<a:p><a:endParaRPr lang="en-US"><a:ea typeface="${JAPANESE_FONT_FACE}"/></a:endParaRPr></a:p>`;
+      }
+      const preserve = /^\s|\s$|\s{2}/.test(line) ? ' xml:space="preserve"' : "";
+      return `<a:p><a:r><a:rPr lang="en-US" dirty="0"><a:ea typeface="${JAPANESE_FONT_FACE}"/></a:rPr><a:t${preserve}>${xmlEscape(line)}</a:t></a:r><a:endParaRPr lang="en-US"><a:ea typeface="${JAPANESE_FONT_FACE}"/></a:endParaRPr></a:p>`;
+    })
+    .join("");
+}
+
+function notesMasterXml() {
+  const slideImage = notesPlaceholderXml({
+    id: 2,
+    name: "Slide Image Placeholder 1",
+    type: "sldImg",
+    idx: 1,
+    x: 1143000,
+    y: 685800,
+    cx: 4572000,
+    cy: 3429000,
+  });
+  const body = notesPlaceholderXml({
+    id: 3,
+    name: "Notes Placeholder 2",
+    type: "body",
+    idx: 2,
+    x: 685800,
+    y: 4343400,
+    cx: 5486400,
+    cy: 4114800,
+  });
+  return `${XML}<p:notesMaster xmlns:a="${NS_A}" xmlns:r="${NS_R}" xmlns:p="${NS_P}"><p:cSld name="Notes Master"><p:spTree>${baseShapeTree()}${slideImage}${body}</p:spTree></p:cSld><p:clrMap accent1="accent1" accent2="accent2" accent3="accent3" accent4="accent4" accent5="accent5" accent6="accent6" bg1="lt1" bg2="lt2" folHlink="folHlink" hlink="hlink" tx1="dk1" tx2="dk2"/><p:notesStyle><a:lvl1pPr marL="0" algn="l"><a:defRPr sz="1200"><a:latin typeface="Aptos"/><a:ea typeface="${JAPANESE_FONT_FACE}"/></a:defRPr></a:lvl1pPr></p:notesStyle></p:notesMaster>`;
+}
+
+function notesSlideXml(notes) {
+  const slideImage = notesPlaceholderXml({
+    id: 2,
+    name: "Slide Image Placeholder 1",
+    type: "sldImg",
+    idx: 1,
+    x: 1143000,
+    y: 685800,
+    cx: 4572000,
+    cy: 3429000,
+  });
+  const body = notesPlaceholderXml({
+    id: 3,
+    name: "Notes Placeholder 2",
+    type: "body",
+    idx: 2,
+    x: 685800,
+    y: 4343400,
+    cx: 5486400,
+    cy: 4114800,
+    paragraphs: notesParagraphsXml(notes),
+  });
+  return `${XML}<p:notes xmlns:a="${NS_A}" xmlns:r="${NS_R}" xmlns:p="${NS_P}"><p:cSld><p:spTree>${baseShapeTree()}${slideImage}${body}</p:spTree></p:cSld><p:clrMapOvr><a:masterClrMapping/></p:clrMapOvr></p:notes>`;
+}
+
+function notesSlideRelsXml(slideIndex) {
+  return relationshipsXml([
+    {
+      id: "rId1",
+      type: REL.notesMaster,
+      target: "../notesMasters/notesMaster1.xml",
+    },
+    {
+      id: "rId2",
+      type: REL.slide,
+      target: `../slides/slide${slideIndex + 1}.xml`,
+    },
+  ]);
+}
+
+function normalizedNotes(slide, slideIndex) {
+  const path = `slides[${slideIndex}]`;
+  if (!slide || typeof slide !== "object" || Array.isArray(slide)) {
+    fail(`${path} must be an object`);
+  }
+  if (slide.notes === undefined || slide.notes === null || slide.notes === "") return "";
+  if (typeof slide.notes !== "string") fail(`${path}.notes must be a string`);
+  return slide.notes.replace(/\r\n?/g, "\n").trim();
+}
+
 function crc32(data) {
   let crc = 0xffffffff;
   for (const byte of data) crc = CRC_TABLE[(crc ^ byte) & 0xff] ^ (crc >>> 8);
@@ -995,11 +1192,25 @@ export function buildPptxPackage({ title = "Presentation", slides, assets = [] }
   }
   if (slides.length > 0x7ffffeff) fail("slides contains too many items");
   const normalizedAssets = normalizeAssets(assets);
-  const builtSlides = slides.map((slide, index) =>
-    buildSlide(slide, index, normalizedAssets),
-  );
+  const notesSlides = [];
+  const builtSlides = slides.map((slide, index) => {
+    const notes = normalizedNotes(slide, index);
+    const notesSlideNumber = notes ? notesSlides.length + 1 : null;
+    const built = buildSlide(slide, index, normalizedAssets, notesSlideNumber);
+    if (notes) {
+      notesSlides.push({
+        notes,
+        slideIndex: index,
+        number: notesSlideNumber,
+      });
+    }
+    return built;
+  });
   const entries = [
-    { name: "[Content_Types].xml", data: contentTypesXml(slides.length, normalizedAssets) },
+    {
+      name: "[Content_Types].xml",
+      data: contentTypesXml(slides.length, normalizedAssets, notesSlides.length),
+    },
     {
       name: "_rels/.rels",
       data: relationshipsXml([
@@ -1009,11 +1220,14 @@ export function buildPptxPackage({ title = "Presentation", slides, assets = [] }
       ]),
     },
     { name: "docProps/core.xml", data: coreXml(title) },
-    { name: "docProps/app.xml", data: appXml(slides.length) },
-    { name: "ppt/presentation.xml", data: presentationXml(slides.length) },
+    { name: "docProps/app.xml", data: appXml(slides.length, notesSlides.length) },
+    {
+      name: "ppt/presentation.xml",
+      data: presentationXml(slides.length, notesSlides.length),
+    },
     {
       name: "ppt/_rels/presentation.xml.rels",
-      data: presentationRelsXml(slides.length),
+      data: presentationRelsXml(slides.length, notesSlides.length),
     },
     { name: "ppt/theme/theme1.xml", data: themeXml() },
     { name: "ppt/slideMasters/slideMaster1.xml", data: slideMasterXml() },
@@ -1039,6 +1253,18 @@ export function buildPptxPackage({ title = "Presentation", slides, assets = [] }
         },
       ]),
     },
+    ...(notesSlides.length
+      ? [
+          { name: "ppt/theme/theme2.xml", data: themeXml() },
+          { name: "ppt/notesMasters/notesMaster1.xml", data: notesMasterXml() },
+          {
+            name: "ppt/notesMasters/_rels/notesMaster1.xml.rels",
+            data: relationshipsXml([
+              { id: "rId1", type: REL.theme, target: "../theme/theme2.xml" },
+            ]),
+          },
+        ]
+      : []),
     ...builtSlides.flatMap((slide, index) => [
       { name: `ppt/slides/slide${index + 1}.xml`, data: slide.xml },
       {
@@ -1046,6 +1272,16 @@ export function buildPptxPackage({ title = "Presentation", slides, assets = [] }
         data: slide.rels,
       },
     ]),
+    ...notesSlides.flatMap((notesSlide) => [
+      {
+        name: `ppt/notesSlides/notesSlide${notesSlide.number}.xml`,
+        data: notesSlideXml(notesSlide.notes),
+      },
+      {
+        name: `ppt/notesSlides/_rels/notesSlide${notesSlide.number}.xml.rels`,
+        data: notesSlideRelsXml(notesSlide.slideIndex),
+      },
+    ]),
     ...[...normalizedAssets.values()].map((asset) => ({
       name: asset.mediaPath,
       data: asset.data,
@@ -1068,6 +1304,9 @@ export function inspectPptxPackage(buffer) {
       const number = (name) => Number(/\d+/.exec(name)[0]);
       return number(left) - number(right);
     });
+  const notesNames = [...files.keys()].filter((name) =>
+    /^ppt\/notesSlides\/notesSlide\d+\.xml$/.test(name),
+  );
   const core = files.get("docProps/core.xml")?.data.toString("utf8") || "";
   const title = /<dc:title>([\s\S]*?)<\/dc:title>/.exec(core);
   return {
@@ -1079,6 +1318,7 @@ export function inspectPptxPackage(buffer) {
       crc32: entry.crc32,
     })),
     slideCount: slideNames.length,
+    notesCount: notesNames.length,
     mediaCount: [...files.keys()].filter((name) => name.startsWith("ppt/media/"))
       .length,
     dimensions: {

package/src/cli.mjs

@@ -149,6 +149,7 @@ function usage(command) {
       "Usage: markdstage export <file.md> [--output slides.pdf|slides.pptx]",
       "",
       "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.",
     ],
     guide: [