@markdstage/markdstage 2.6.0 → 3.1.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.1.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

@@ -93,11 +93,18 @@ The themed slide is displayed and updates automatically
   produces a 16:9 PDF with backgrounds, images, highlighted code, and Mermaid.
 - **Hybrid editable PowerPoint export is available from More controls > Export
   PowerPoint.** It
-  preserves supported text, lists, links, tables, raster images, and Architecture
-  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. Speaker
+  preserves supported text, lists, links, tables, fenced code blocks, raster
+  images, and Architecture DSL objects as native PowerPoint content. Code blocks
+  retain editable syntax-colored runs, whitespace, monospace typography, and
+  block decoration; unsupported effects such as shadows remain cropped fallback
+  pictures. Architecture nodes, groups, and connector-label pills are visible
+  AutoShapes with integrated text; icons use a transparent foreground picture
+  layer. Supported SVG files remain individual pictures. Mermaid, shadows, and
+  other unsupported styling stay visible as cropped, positioned fallback
+  pictures and are listed in the export report. Each theme used in the deck gets
+  its own slide master with named `title`, `default`, `center`, `section`, and
+  `backcover` layouts. Common backgrounds and top bars are stored in layout
+  artwork; supported cover logos are separate layout pictures. 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.
@@ -207,10 +214,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 +273,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 +307,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 +779,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 +871,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
@@ -968,7 +1002,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. 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, 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. |
 | `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/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":