@markdstage/markdstage 2.6.0 → 3.0.0

package/README.md

@@ -16,8 +16,8 @@ exported PDF, or hybrid editable PowerPoint deck.
 ## Install
 
 ```console
-npx @markdstage/markdstage presentation slides.md
 npx @markdstage/markdstage present slides.md
+npx @markdstage/markdstage preview slides.md
 npm install --global @markdstage/markdstage
 ```
 
@@ -31,8 +31,8 @@ npm install --global .\markdstage-markdstage-<version>.tgz
 ## Commands
 
 ```console
-markdstage presentation slides.md
-markdstage present slides.md --watch
+markdstage present slides.md
+markdstage preview slides.md --watch
 markdstage validate slides.md --json
 markdstage inspect slides.md --json
 markdstage capture slides.md --pages 2,4
@@ -45,8 +45,8 @@ markdstage skill install --target claude
 
 | Command | Description |
 | --- | --- |
-| `presentation` | Opens the presenter view with the current slide, next-slide preview, speaker notes, and navigation. Select **Start presentation** to open the synchronized audience-facing window; select **End presentation** to close it. `--watch` reloads on save, and `--no-open` serves the presenter URL without launching a browser. |
-| `present` | Serves the deck on loopback and opens the MarkdStage presenter window: navigation, presenter view, next-slide preview, speaker notes, overview, custom themes, Mermaid, Architecture DSL, and local assets. `--watch` reloads on save while preserving the current slide, keeps the last valid deck when a save is broken, and enables Architecture editing. Without `--watch`, the source is read-only. `--no-open` serves the deck only. |
+| `present` | Opens the presenter view with the current slide, next-slide preview, speaker notes, and navigation. Select **Start presentation** to open the synchronized audience-facing window; select **End presentation** to close it. `--watch` reloads on save, and `--no-open` serves the presenter URL without launching a browser. |
+| `preview` | Serves the deck on loopback and opens the MarkdStage preview: navigation, presenter view, next-slide preview, speaker notes, overview, custom themes, Mermaid, Architecture DSL, and local assets. `--watch` reloads on save while preserving the current slide, keeps the last valid deck when a save is broken, and enables Architecture editing. Without `--watch`, the source is read-only. `--no-open` serves the deck only. |
 | `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. |
@@ -60,7 +60,7 @@ Global options: `--workspace <dir>`, `--theme <name>`, `--theme-file <path>`,
 
 ## Architecture editing
 
-Run `markdstage present slides.md --watch` for the live authoring workflow. The
+Run `markdstage preview slides.md --watch` for the live authoring workflow. The
 browser starts in viewing mode. Select the pencil control to move Architecture
 elements; those placement changes are saved atomically to the matching
 `architecture` fence. Select **Advanced edit** to add, update, duplicate,

package/package.json

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

@@ -207,10 +207,31 @@ When the extension detects a presentation-related prompt, it adds a short hint
 to use `markdstage_guide` at most once per session. No hint is added after the
 tool has already been called, and session-end cleanup removes the state.
 
-### Slide fragment format
+### Markdown file syntax
 
-Each element in open / `load_deck` `slides` is one Markdown string. It may start
-with front matter delimited by `---`, followed by GFM-compatible content.
+A Markdown file represents the complete deck. At the top level, a line containing
+only `---` after a blank line separates slides. A leading `---` block is file
+front matter, and `---` inside a fenced code block is not a separator.
+
+Use only the top-level `---` syntax for slide boundaries. Custom markers such as
+`<!-- slide -->` are not slide separators and must not be used.
+
+Do not place a top-level HTML comment immediately before a slide separator. End
+the comment, leave a blank line, and then write `---`; without the blank line,
+the separator may not be recognized as a slide boundary.
+
+To have MarkdStage read and split a workspace Markdown file, use **More controls >
+Open Markdown**. This file-loading workflow is separate from the Canvas API.
+
+### Canvas API `slides` array
+
+For canvas `open` and `load_deck`, each element of the `slides` array is exactly
+one slide. The caller must read, split, or generate the deck before invoking the
+Canvas API. Do not pass a complete multi-slide Markdown file as one array element
+and expect its `---` lines to be split.
+
+Each array element is one Markdown string. It may start with front matter
+delimited by `---`, followed by GFM-compatible content.
 
 | Front matter | Purpose |
 | --- | --- |
@@ -245,14 +266,6 @@ First explain the **prerequisites**.
 -->
 ```
 
-Write local images as `![Alternative text](/assets/foo.png)` and pass the source
-Markdown's workspace-relative path as `sourceName`. Lookup tries adjacent
-`assets/` before workspace-root `assets/`. Architecture `icon` and `image.src`
-use `assets/foo.svg` without a leading slash and follow the same lookup order.
-`sourceName` supplies this resolution base only; it does not read or watch the
-Markdown file.
-Specifically, lookup checks `assets/` beside the Markdown before `assets/` at the workspace root.
-
 On a standard slide, the first H1/H2 is fixed in the top title area, so its
 position does not move with body length. Later headings remain in the body.
 Specialized `title`, `section`, and `backcover` layouts retain their own
@@ -287,6 +300,20 @@ layout: section
 ## Key GitHub Copilot features
 ```
 
+### `sourceName` role
+
+`sourceName` is workspace-relative metadata used to resolve adjacent themes and
+images and to derive output filenames. It does not read, parse, split, or watch
+Markdown content. Passing `sourceName` does not load a deck; non-empty canvas
+input must still include the complete `slides` array.
+
+To have MarkdStage load a Markdown file, use **More controls > Open Markdown**.
+
+Write local images as `![Alternative text](/assets/foo.png)`. With `sourceName`,
+lookup tries `assets/` beside the Markdown before workspace-root `assets/`.
+Architecture `icon` and `image.src` use `assets/foo.svg` without a leading slash
+and follow the same lookup order.
+
 ### Choosing a theme
 
 Set the deck-wide `theme`; use `dark` when omitted.
@@ -745,8 +772,8 @@ Architecture diagrams can be moved directly over the rendered result. For decks
 imported through **More controls > Open Markdown**, edits write back to the source `architecture` fence and
 survive re-import. Decks supplied directly through open / `load_deck` cannot be
 reversibly mapped to a source file, so they save only to canvas deck state.
-In the standalone CLI, `markdstage present slides.md --watch` enables the same
-source-backed editing workflow; `present` without `--watch` is read-only.
+In the standalone CLI, `markdstage preview slides.md --watch` enables the same
+source-backed editing workflow; `preview` without `--watch` is read-only.
 
 **Placement editing is a stable part of Architecture DSL v1.**
 
@@ -837,7 +864,7 @@ blocks.
 For a source-backed deck imported through **More controls > Open Markdown**,
 **Shape editing** opens this editor directly. If the slide contains multiple
 Architecture blocks, select one from the accessible picker first. CLI
-`present --watch` opens the same editor in a browser window. Agents can open
+`preview --watch` opens the same editor in a browser window. Agents can open
 the editor canvas directly:
 
 ```json

package/shared/markdstage-guide.mjs

@@ -110,12 +110,18 @@ export async function readGuide(topic = "overview") {
         section(readme, "## How it works"),
         "",
         "Users can load workspace Markdown directly with **More controls > Open Markdown** (deterministic splitting without AI; natural-language summarization remains the AI's responsibility). The workspace root is the Git repository root when available, otherwise the folder opened for the current session.",
-        "Use **More controls > Shape editing** to adjust the placement of an existing Architecture diagram. In the CLI, run `markdstage present slides.md --watch`; it starts in viewing mode and enables the same placement editor plus the detailed Architecture designer. CLI `present` without `--watch` is read-only. Comprehensive edits affect the source Markdown only when explicitly saved.",
+        "Use **More controls > Shape editing** to adjust the placement of an existing Architecture diagram. In the CLI, run `markdstage preview slides.md --watch`; it starts in viewing mode and enables the same placement editor plus the detailed Architecture designer. CLI `preview` without `--watch` is read-only. Comprehensive edits affect the source Markdown only when explicitly saved.",
         "",
         "For details, request `slide-format`, `themes`, `custom-themes`, `theme-schema`, `architecture-dsl`, or `architecture-schema`.",
       ].join("\n");
     case "slide-format":
-      return section(readme, "### Slide fragment format");
+      return [
+        section(readme, "### Markdown file syntax"),
+        "",
+        section(readme, "### Canvas API `slides` array"),
+        "",
+        section(readme, "### `sourceName` role"),
+      ].join("\n");
     case "themes":
       return section(readme, "### Choosing a theme");
     case "custom-themes":

package/shared/renderer/renderer.js

@@ -2148,6 +2148,7 @@ let currentVersion = -1;
 let knownDeckVersion = -1;
 let deckSlides = [];
 let deckTitles = [];
+let deckLayouts = [];
 let navIndex = 0;
 let navTotal = 0;
 let navMode = "deck";
@@ -2189,6 +2190,11 @@ function deriveTitle(md) {
   return fallback ? trimTitle(fallback) : "(Untitled)";
 }
 
+function deriveLayout(md) {
+  const { meta } = splitFrontMatter(typeof md === "string" ? md : "");
+  return typeof meta.layout === "string" ? meta.layout.trim().toLowerCase() : "";
+}
+
 function trimTitle(text) {
   const stripped = text
     .replace(/[*_`>#~]/g, "")
@@ -2205,6 +2211,7 @@ async function fetchDeck() {
     if (Array.isArray(data.slides)) {
       deckSlides = data.slides;
       deckTitles = deckSlides.map(deriveTitle);
+      deckLayouts = deckSlides.map(deriveLayout);
     }
     if (typeof data.deckVersion === "number") knownDeckVersion = data.deckVersion;
     buildOverview();
@@ -3032,24 +3039,51 @@ function buildOverview() {
   const list = document.getElementById("overviewList");
   if (!list) return;
   list.replaceChildren();
+  let insideSection = false;
   deckTitles.forEach((title, i) => {
+    const layout = deckLayouts[i] || "";
+    if (layout === "title" || layout === "backcover") insideSection = false;
+    const sectionChild =
+      insideSection && layout !== "title" && layout !== "section" && layout !== "backcover";
+
     const li = document.createElement("li");
     li.className = "overview-item";
+    if (layout === "title" || layout === "section") {
+      li.classList.add(`overview-item-${layout}`);
+    }
+    if (sectionChild) li.classList.add("overview-item-section-child");
     li.dataset.index = String(i);
+    if (layout) li.dataset.layout = layout;
+
     const btn = document.createElement("button");
     btn.type = "button";
     btn.className = "overview-link";
+    btn.setAttribute(
+      "aria-label",
+      `${i + 1} ${title}${layout === "title" || layout === "section" ? `, ${layout} slide` : ""}`,
+    );
+
     const num = document.createElement("span");
     num.className = "overview-num";
     num.textContent = String(i + 1);
     const label = document.createElement("span");
     label.className = "overview-label";
     label.textContent = title;
+
     btn.appendChild(num);
+    if (layout === "title" || layout === "section") {
+      const kind = document.createElement("span");
+      kind.className = "overview-kind";
+      kind.textContent = layout === "title" ? "Title" : "Section";
+      kind.setAttribute("aria-hidden", "true");
+      btn.appendChild(kind);
+    }
     btn.appendChild(label);
     btn.addEventListener("click", () => goToIndex(i));
     li.appendChild(btn);
     list.appendChild(li);
+
+    if (layout === "section") insideSection = true;
   });
   highlightOverview();
 }
@@ -3478,13 +3512,9 @@ function init() {
     return;
   }
   if (params.get("print") === "1") {
-    // Print mode never reaches editing-mode branches. Removing this return would
-    // bake the editing UI into PDFs, so a regression test protects it.
-    //
-    // This early return is also **the primary fix for the #12 hang**. Only print
-    // mode avoids connectEvents() (an unclosed SSE) and the two-second setInterval,
-    // allowing the page to become idle and --print-to-pdf to complete.
-    // Removing the return makes printing hang forever.
+    // Print mode renders one immutable output snapshot and never reaches editing,
+    // SSE, or polling branches. The output runtime waits for its ready report
+    // before asking Chromium to create the PDF.
     initPrint(params).catch(reportPrintBootstrapFailure);
     return;
   }

package/shared/renderer/slides.css

@@ -547,8 +547,22 @@ body.presenter-view-mode .layout-warning{display:none;}
      align-items:center;justify-content:center;border-radius:6px;
      font-size:.82em;font-weight:700;font-variant-numeric:tabular-nums;
      color:var(--muted);background:var(--code);border:1px solid var(--border);}
+.overview-kind{flex:0 0 auto;padding:.18em .48em;border-radius:999px;
+     color:var(--accent-strong);background:var(--surface);border:1px solid var(--accent);
+     font-size:.66em;font-weight:750;letter-spacing:.06em;text-transform:uppercase;}
 .overview-label{flex:1 1 auto;font-size:.96em;line-height:1.35;
      overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
+.overview-item-title{margin-bottom:.45em;}
+.overview-item-title .overview-link{background:color-mix(in srgb,var(--accent-soft) 74%,transparent);
+     border:1px solid color-mix(in srgb,var(--accent) 48%,var(--border));}
+.overview-item-title .overview-label{color:var(--fg);font-weight:700;}
+.overview-item-section{margin-top:.65em;padding-top:.55em;border-top:1px solid var(--border);}
+.overview-item-section .overview-link{padding-block:.65em;background:var(--accent-soft);
+     border-left:4px solid var(--accent);}
+.overview-item-section .overview-num{color:var(--fg);border-color:var(--accent);}
+.overview-item-section .overview-label{color:var(--fg);font-weight:700;}
+.overview-item-section-child .overview-link{width:calc(100% - 1.2em);margin-left:1.2em;
+     border-left:1px solid color-mix(in srgb,var(--accent) 42%,var(--border));border-radius:0 8px 8px 0;}
 .overview-item.current .overview-link{background:var(--accent-soft);}
 .overview-item.current .overview-num{color:var(--fg);background:var(--accent);
      border-color:var(--accent);}

package/shared/runtime/browser.mjs

@@ -6,7 +6,7 @@
 // because the Extension is distributed as a folder ZIP.
 
 import { existsSync } from "node:fs";
-import { readFile, open, rm, stat } from "node:fs/promises";
+import { readFile, open, rm, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { execFileSync, spawn } from "node:child_process";
 
@@ -173,84 +173,6 @@ export function delay(milliseconds) {
   return new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds));
 }
 
-/**
- * Run a headless browser once with `--print-to-pdf`.
- *
- * ⚠️ **`pageUrl` must include `?print=1&token=...` (#12).**
- *
- * `--print-to-pdf` completes only when the page becomes idle. In renderer `init()`,
- * only print mode returns early. Normal and presenter views keep an unclosed SSE
- * (`new EventSource("./events")`) and a two-second `setInterval` running.
- * Passing a URL without `?print=1` therefore means **the browser never exits**.
- *
- * Observed results, using Chrome arguments byte-for-byte identical to this function:
- *
- * | URL                        | Result                                  |
- * | -------------------------- | --------------------------------------- |
- * | `/?print=1&token=<valid>`  | exit 0 @ 2.4s (valid PDF)               |
- * | `/?print=1&token=` (empty) | exit 0 @ 1.9s (blank; renderer reports failure) |
- * | `/` (normal view)          | **HANG** (still running after 120 seconds) |
- * | `/?present=1`              | **HANG**                                |
- * | `/nope-404` (no renderer)  | exit 0 @ 3.0s                           |
- *
- * ⚠️ **`--virtual-time-budget` is effectively ignored by `--headless=new`.**
- * The `--virtual-time-budget=12000` argument below does not stop this hang.
- * Adding `--timeout=8000` is also ineffective, as verified empirically.
- * The argument is harmless and remains in place, but **do not treat it as a
- * wall-clock timeout**. Only Node's `PDF_RENDER_TIMEOUT_MS` and
- * `terminateProcessTree` enforce a limit, and failure may take up to 60 seconds.
- */
-export async function runHeadlessBrowser(browser, args, failureLabel) {
-  await new Promise((resolvePromise, rejectPromise) => {
-    const child = spawn(browser, args, {
-      detached: process.platform !== "win32",
-      windowsHide: true,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    let diagnostics = "";
-    let settled = false;
-    let timedOut = false;
-    const appendDiagnostics = (chunk) => {
-      diagnostics = `${diagnostics}${chunk.toString()}`.slice(-12_000);
-    };
-    child.stdout.on("data", appendDiagnostics);
-    child.stderr.on("data", appendDiagnostics);
-
-    const settle = (error) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      if (error) rejectPromise(error);
-      else resolvePromise();
-    };
-    const timer = setTimeout(async () => {
-      if (settled) return;
-      timedOut = true;
-      await terminateProcessTree(child);
-      settle(new Error(`${failureLabel} timed out after ${PDF_RENDER_TIMEOUT_MS / 1000}s.`));
-    }, PDF_RENDER_TIMEOUT_MS);
-
-    child.once("error", (error) => {
-      if (!timedOut) settle(error);
-    });
-    child.once("exit", (code, signal) => {
-      if (timedOut) return;
-      if (code === 0) {
-        settle();
-        return;
-      }
-      const detail = diagnostics.trim();
-      settle(
-        new Error(
-          `${failureLabel} failed (${signal ? `signal ${signal}` : `exit ${code}`})${
-            detail ? `: ${detail}` : "."
-          }`,
-        ),
-      );
-    });
-  });
-}
-
 function withSandboxFallback(args) {
   if (
     process.platform !== "win32" &&
@@ -262,35 +184,38 @@ function withSandboxFallback(args) {
   return args;
 }
 
-export async function runPdfBrowser(browser, pageUrl, outputPath, profileDir) {
-  // Enforce the contract at runtime. Otherwise it silently waits 60 seconds
-  // before timing out, obscuring the cause; fail immediately with an explanation.
+export async function runPdfBrowser(browser, pageUrl, outputPath, profileDir, job) {
   if (new URL(pageUrl).searchParams.get("print") !== "1") {
     throw new Error(
-      `Refusing to run --print-to-pdf against a non-print URL (${pageUrl}): only ?print=1 stops the renderer's SSE and polling loops, so any other page hangs the browser forever.`,
+      `Refusing to render PDF from a non-print URL (${pageUrl}).`,
     );
   }
-  const args = withSandboxFallback([
-    "--headless=new",
-    "--disable-gpu",
-    "--disable-background-networking",
-    "--disable-component-update",
-    "--disable-default-apps",
-    "--disable-extensions",
-    "--force-color-profile=srgb",
-    "--hide-scrollbars",
-    "--no-first-run",
-    "--no-pdf-header-footer",
-    "--print-to-pdf-no-header",
-    "--run-all-compositor-stages-before-draw",
-    // Ineffective (#12): --headless=new ignores it. See the JSDoc above.
-    // The actual safeguards are PDF_RENDER_TIMEOUT_MS + terminateProcessTree.
-    "--virtual-time-budget=12000",
-    `--user-data-dir=${profileDir}`,
-    `--print-to-pdf=${outputPath}`,
-    pageUrl,
-  ]);
-  await runHeadlessBrowser(browser, args, "Browser PDF rendering");
+  if (!job || typeof job !== "object") {
+    throw new Error("PDF rendering requires an output job.");
+  }
+
+  const { cdp, child } = await openCdpOutputPage(browser, pageUrl, profileDir, job);
+  try {
+    // The renderer reports ready only after Mermaid, images, fonts, and layout
+    // have settled. Give Chromium two compositor frames before printing.
+    await cdp.send("Runtime.evaluate", {
+      expression:
+        "new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))",
+      awaitPromise: true,
+    });
+    const pdf = await cdp.send("Page.printToPDF", {
+      displayHeaderFooter: false,
+      printBackground: true,
+      preferCSSPageSize: true,
+      transferMode: "ReturnAsBase64",
+    });
+    if (typeof pdf.data !== "string" || pdf.data.length === 0) {
+      throw new Error("Chromium DevTools did not return PDF data.");
+    }
+    await writeFile(outputPath, Buffer.from(pdf.data, "base64"));
+  } finally {
+    await closeCdpOutputPage(cdp, child);
+  }
 }
 
 async function waitForDevToolsPort(profileDir, child, diagnostics) {

package/shared/runtime/output.mjs

@@ -497,14 +497,14 @@ export async function exportPdf(inst, requestedPath, requestedTheme) {
     profileDir = await mkdtemp(join(tmpdir(), "markdstage-pdf-"));
     const outputBase = basename(outputPath, extname(outputPath)) || "markdstage";
     temporaryOutputPath = join(outputParent, `.${outputBase}.${token}.tmp.pdf`);
-    inst.exportJobs.set(token, createOutputJob(snapshot, "pdf"));
+    const exportJob = createOutputJob(snapshot, "pdf");
+    inst.exportJobs.set(token, exportJob);
 
     const pageUrl = pageUrlFor(inst, { print: 1, token });
-    await runPdfBrowser(browser, pageUrl, temporaryOutputPath, profileDir);
-    const exportJob = inst.exportJobs.get(token);
-    if (exportJob?.status !== "ready") {
+    await runPdfBrowser(browser, pageUrl, temporaryOutputPath, profileDir, exportJob);
+    if (exportJob.status !== "ready") {
       throw new Error(
-        exportJob?.error || "The print renderer did not finish before the browser exited.",
+        exportJob.error || "The print renderer did not finish before PDF generation.",
       );
     }
     const bytes = await verifyPdf(temporaryOutputPath);

package/src/cli.mjs

@@ -36,8 +36,8 @@ import {
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
 const COMMANDS = [
-  ["presentation", "Open presenter view and launch the audience view from it."],
-  ["present", "Serve a deck on loopback and open it in a browser window."],
+  ["present", "Open presenter view and launch the audience view from it."],
+  ["preview", "Serve a deck on loopback and open it in a browser window."],
   ["validate", "Check deck structure, Architecture DSL blocks, and themes."],
   ["inspect", "Report 1280x720 clipping diagnostics for a deck."],
   ["capture", "Write 1280x720 PNG files for selected or clipped slides."],
@@ -59,8 +59,8 @@ const GLOBAL_OPTIONS = {
 };
 
 const COMMAND_OPTIONS = {
-  presentation: { watch: { type: "boolean" }, "no-open": { type: "boolean" } },
   present: { watch: { type: "boolean" }, "no-open": { type: "boolean" } },
+  preview: { watch: { type: "boolean" }, "no-open": { type: "boolean" } },
   validate: {},
   inspect: { slide: { type: "string" }, all: { type: "boolean" }, "fail-on-issues": { type: "boolean" } },
   capture: { pages: { type: "string" }, output: { type: "string" } },
@@ -103,8 +103,8 @@ function usage(command) {
     return lines.join("\n");
   }
   const help = {
-    presentation: [
-      "Usage: markdstage presentation <file.md> [options]",
+    present: [
+      "Usage: markdstage present <file.md> [options]",
       "",
       "Opens presenter view with the current slide, next-slide preview, and speaker notes.",
       "Use Start presentation in that view to open the synchronized audience window.",
@@ -114,16 +114,16 @@ function usage(command) {
       "",
       "Presentation requires an installed Microsoft Edge, Google Chrome, or Chromium.",
     ],
-    present: [
-      "Usage: markdstage present <file.md> [options]",
+    preview: [
+      "Usage: markdstage preview <file.md> [options]",
       "",
       "  --watch     Reload on save and enable Architecture editing.",
       "  --no-open   Serve the deck without launching a browser.",
       "",
-      "Without --watch, presentation is read-only. Watch mode starts in normal viewing mode;",
+      "Without --watch, preview is read-only. Watch mode starts in normal viewing mode;",
       "use the pencil control to edit Architecture diagrams and open the detailed designer.",
       "",
-      "Presenting requires an installed Microsoft Edge, Google Chrome, or Chromium.",
+      "Preview requires an installed Microsoft Edge, Google Chrome, or Chromium.",
     ],
     validate: [
       "Usage: markdstage validate <file.md> [--json]",
@@ -262,8 +262,8 @@ export async function run(argv, io = {}) {
 
   try {
     switch (command) {
-      case "present": {
-        const file = requireFile(positionals, "present");
+      case "preview": {
+        const file = requireFile(positionals, "preview");
         const report = await presentCommand(
           { ...deckOptions(file, values), watch: values.watch, open: !values["no-open"], until: io.until },
           {
@@ -277,8 +277,8 @@ export async function run(argv, io = {}) {
         if (values.json) json(report);
         return EXIT_OK;
       }
-      case "presentation": {
-        const file = requireFile(positionals, "presentation");
+      case "present": {
+        const file = requireFile(positionals, "present");
         const report = await presentCommand(
           {
             ...deckOptions(file, values),

package/src/commands/present.mjs

@@ -1,4 +1,4 @@
-// markdstage present — serve the deck on loopback and open it in a browser.
+// Shared server for the markdstage preview and present commands.
 
 import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { join, resolve } from "node:path";
@@ -139,7 +139,9 @@ export async function presentCommand(options, io) {
           });
         }
 
-        io.print(`MarkdStage is presenting ${session.sourceName || session.file}`);
+        io.print(
+          `MarkdStage is ${options.presenterView ? "presenting" : "previewing"} ${session.sourceName || session.file}`,
+        );
         io.print(`  slides:    ${session.slides.length}`);
         io.print(`  theme:     ${session.theme}`);
         io.print(`  workspace: ${resolve(session.workspaceRoot)}`);

package/src/skills.mjs

@@ -78,7 +78,7 @@ what the MarkdStage canvas and MarkdStage Desktop render.
    \`references/slide-format.md\`).
 4. Validate structure, themes, and Architecture DSL before visual review:
    \`markdstage validate slides.md --json\`.
-5. Use \`markdstage present slides.md --watch\` for live source-backed authoring.
+5. Use \`markdstage preview slides.md --watch\` for live source-backed authoring.
    It reloads on save without losing the current slide and keeps the last valid
    deck while a save is incomplete.
 6. Check fixed 16:9 output with \`markdstage inspect slides.md --json\`. Use
@@ -88,14 +88,14 @@ what the MarkdStage canvas and MarkdStage Desktop render.
    whose balance, spacing, or diagrams need visual judgment.
 8. Revise Markdown and repeat validation plus targeted inspection until the deck
    is valid, unclipped, concise, and visually balanced.
-9. Deliver from the same source with \`markdstage presentation slides.md\`,
+9. Deliver from the same source with \`markdstage present slides.md\`,
    \`markdstage export slides.md --output slides.pdf\`, or
    \`markdstage export slides.md --output slides.pptx\`.
 
-The browser in \`present --watch\` starts in viewing mode. The user can activate
+The browser in \`preview --watch\` starts in viewing mode. The user can activate
 the pencil control to move Architecture elements, then choose **Advanced edit**
 for the detailed designer. Placement changes save immediately, while the
-detailed designer saves only when the user selects **Save**. \`present\` without
+detailed designer saves only when the user selects **Save**. \`preview\` without
 \`--watch\` is read-only.
 
 Never hand-write HTML or CSS for a slide. Fix layout problems by shortening the
@@ -106,8 +106,8 @@ and layout diagnostics over capturing every slide.
 
 | Command | Purpose |
 | --- | --- |
-| \`markdstage presentation <file> [--watch]\` | Open presenter view with the current slide, next-slide preview, speaker notes, and controls for a synchronized audience window. |
-| \`markdstage present <file> [--watch]\` | Serve the deck on loopback and open it in a browser window. \`--watch\` reloads on save, keeps the current slide, and enables Architecture placement and detailed editing. Without it, the source is read-only. |
+| \`markdstage present <file> [--watch]\` | Open presenter view with the current slide, next-slide preview, speaker notes, and controls for a synchronized audience window. |
+| \`markdstage preview <file> [--watch]\` | Serve the deck on loopback and open it in a browser window. \`--watch\` reloads on save, keeps the current slide, and enables Architecture placement and detailed editing. Without it, the source is read-only. |
 | \`markdstage validate <file> [--json]\` | Check deck structure, Architecture DSL blocks, and themes. |
 | \`markdstage inspect <file> [--json]\` | Report 1280x720 clipping diagnostics for the deck or one slide; use \`--fail-on-issues\` for quality gates. |
 | \`markdstage capture <file> [--pages 2,4]\` | Write 1280x720 PNG files; without \`--pages\` only clipped slides are captured. |