@markdstage/markdstage 3.3.0 → 3.8.0

package/README.md

@@ -16,8 +16,8 @@ exported PDF, or hybrid editable PowerPoint deck.
 ## Install
 
 ```console
-npx @markdstage/markdstage present slides.md
-npx @markdstage/markdstage preview slides.md
+npx @markdstage/markdstage
+npx @markdstage/markdstage slides.md
 npm install --global @markdstage/markdstage
 ```
 
@@ -31,6 +31,8 @@ npm install --global .\markdstage-markdstage-<version>.tgz
 ## Commands
 
 ```console
+markdstage
+markdstage slides.md
 markdstage present slides.md
 markdstage preview slides.md --watch
 markdstage validate slides.md --json
@@ -38,36 +40,46 @@ markdstage inspect slides.md --json
 markdstage capture slides.md --pages 2,4
 markdstage export slides.md --output slides.pdf
 markdstage export slides.md --output slides.pptx
+markdstage export slides.md --output slides.pptx --mermaid-image-fallback
 markdstage guide architecture-dsl
 markdstage skill install --target codex
 markdstage skill install --target claude
 ```
 
+`markdstage` opens an empty Canvas-equivalent UI for the current workspace.
+Choose **Open Markdown** to load a deck. `markdstage slides.md` opens the same UI
+in slide view with automatic refresh enabled.
+
 | Command | Description |
 | --- | --- |
-| `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. |
+| `present` | Opens the full MarkdStage UI in presenter view. Open Markdown, automatic refresh, editing, export, and audience controls remain available. `--watch` starts in live mode, and `--no-open` serves the UI without launching a browser. |
+| `preview` | Opens the same full UI in slide view. It is a compatibility/convenience entry point; `--watch` starts in live mode, and `--no-open` serves the UI without launching a browser. |
 | `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. PowerPoint output includes speaker-note Markdown as readable plain text notes. 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. Use `--mermaid-image-fallback` with an explicit `.pptx` output to place each Mermaid diagram as one image instead of editable PowerPoint shapes, equivalent to choosing **Images** in the UI export dialog. |
 | `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`. |
 
-Global options: `--workspace <dir>`, `--theme <name>`, `--theme-file <path>`,
-`--json`, `--help`, `--version`.
+Application options: `--workspace <dir>`, `--theme <name>`,
+`--theme-file <path>`, `--no-open`, and `--json`. Use `--help` and `--version`
+for global information.
 
 ## Architecture editing
 
-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,
-reparent, or delete elements in the detailed designer, then select **Save**.
+Run `markdstage slides.md` for the live authoring workflow. The browser starts
+in the fixed 16:9 output preview and remains in viewing mode.
+Select **Output preview** to switch to the retained responsive layout. Select
+the pencil control to move Architecture elements; editing automatically switches
+to the responsive layout, and those placement changes are saved atomically to
+the matching `architecture` fence. Select **Advanced edit** to add, update,
+duplicate, reparent, or delete elements in the detailed designer, then select
+**Save**.
 
 The server rejects a save if the Markdown changed outside the editor. Successful
-saves reload the watched deck without changing the current slide. Presenter,
+saves reload the watched deck without changing the current slide. Automatic
+refresh can be toggled without disabling Architecture editing. Presenter,
 capture, inspect, and export views contain no editing UI.
 
 ```console

package/package.json

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

@@ -60,8 +60,9 @@ The themed slide is displayed and updates automatically
   Theme-file lookup tries the source Markdown folder before the repository
   root, allowing a deck-local file to override a shared file with the same
   path. Files outside the workspace and arbitrary selectors are rejected.
-  A sibling `theme.json` may define cover background, cover/back-cover logos,
-  and copyright. **Every theme automatically receives a final
+  A sibling `theme.json` may define common and default/center backgrounds, cover
+  background, cover/back-cover logos, and copyright. Per-slide `background-image`
+  overrides all themes and layouts. **Every theme automatically receives a final
   `layout: backcover` slide** unless one already exists. Logo and copyright
   appear only when supplied by metadata or front matter.
 - See [`docs/custom-theme-authoring.md`](docs/custom-theme-authoring.md) for
@@ -108,6 +109,11 @@ 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.
+- **PowerPoint export offers Mermaid output options when the deck contains diagrams.**
+  Choose **Editable shapes** or **Images** in the export dialog, then **Export**.
+  Each opening defaults to editable shapes. **Cancel** or **Esc** closes without
+  exporting; decks without Mermaid export immediately. This choice is not saved
+  in the deck. The CLI equivalent is `--mermaid-image-fallback` for image output.
 - **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
@@ -118,12 +124,13 @@ The themed slide is displayed and updates automatically
   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
-  by PDF output. This preview is local to the canvas and does not change deck
-  state. A visible and accessible warning identifies content that would be
-  clipped.
+- The canvas starts in **More controls > Output preview**, letterboxing the
+  current slide with the same fixed 1280×720 typography, spacing, diagram
+  limits, and clipping used by PDF output. Select **Output preview** to return
+  to the retained responsive canvas layout. This preview is local to the canvas
+  and does not change deck state. A visible and accessible warning identifies
+  content that would be clipped. Entering lightweight Architecture editing also
+  returns to the responsive layout so its placement controls remain available.
 - AI should call **`inspect_layout` before exporting a non-scrolling deck**. It
   renders the currently registered in-memory output snapshot in headless
   Chromium; it does not read or validate the source file named by `sourceName`.
@@ -181,7 +188,8 @@ slides remains the AI's responsibility.
 - **Initial front matter is deck configuration** inherited by all slides
   (`theme`, `theme-file`, `deck`, `kicker`, `size`, `logo`, `copyright`, and
   related keys). It is also slide one's own front matter, so
-  `layout: title` affects slide one only.
+  `layout: title` affects slide one only. `background-image` is also per-slide
+  and is never inherited by later slides.
 - **Each page may have front matter.** When the block after the separator
   contains only `key: value` entries and is closed by `---`, it is treated as
   that page's front matter; the separator line also opens the block.
@@ -294,6 +302,7 @@ delimited by `---`, followed by GFM-compatible content.
 | `size` | `auto` (default), `normal`, `large`, or `xlarge` |
 | `theme` | Per-slide override; normally use the deck theme |
 | `theme-file` | CSS for `custom`, resolved beside the Markdown before workspace root |
+| `background-image` | Per-slide decorative image, e.g. `/assets/background.png`; overrides every layout and theme |
 | `logo` / `copyright` | Override `backcover` metadata |
 
 Make the first slide a `layout: title` cover. The extension appends a final
@@ -342,7 +351,8 @@ total: 8
 
 For an intermediate chapter divider, use `layout: section`, normally with one
 H1/H2. Add `kicker` or footer data only when needed. The background follows the
-theme and contains no image, logo, or icon.
+theme and contains no image, logo, or icon unless a per-slide `background-image`
+is supplied.
 
 ```markdown
 ---
@@ -352,6 +362,23 @@ layout: section
 ## Key GitHub Copilot features
 ```
 
+Use `background-image: /assets/background.png` (or the `assets/background.png`
+alias without the leading slash) in a slide's front matter to
+override its background, including `title`, `section`, and `backcover`, under
+`dark`, `light`, `microsoft`, or `custom`. It applies only to that slide, even
+when specified in the initial file front matter. Lookup tries `assets/` beside
+the Markdown, then workspace-root `assets/`; without `sourceName`, it uses the
+workspace root. Accepted extensions are `.svg`, `.png`, `.webp`, `.jpg`, and
+`.jpeg`, at most 2 MiB per image. Remote and `data:` URLs are rejected.
+
+Images are centered and cropped to fill the slide (`object-fit: cover`) behind
+content and logos, preserving the existing background underneath. A custom
+theme uses `layouts.default.background` or `layouts.center.background` before
+its common root `background`; that common fallback applies to default/center
+only. Without a per-slide override, `title` still uses `cover.background` and
+section/back-cover colors and logos are unchanged. Only absent settings trigger
+fallback: invalid paths, missing files, and oversized images fail explicitly.
+
 ### `sourceName` role
 
 `sourceName` is workspace-relative metadata used to resolve adjacent themes and
@@ -382,6 +409,16 @@ workspace-relative source path as `sourceName`.
 | `microsoft` | Microsoft, Fluent, Office, or the Microsoft four-color style |
 | `custom` | Reproduce brand colors or an organizational template with CSS custom properties |
 
+Custom `theme.json` may specify a common `background` and individual
+`layouts.default.background` / `layouts.center.background` entries, each using
+`{ "image": "assets/background.png", "alt": "Optional description" }`.
+These theme-local images use the existing safe `assets/` grammar and 2 MiB
+limit. For default/center, precedence is per-slide `background-image`, then
+layout image, then common image, then the existing background. Common images
+never replace `cover.background` on title slides or section/back-cover
+backgrounds. Per-slide overrides work across all layouts and built-in themes.
+See [Custom theme authoring](docs/custom-theme-authoring.md) for the full contract.
+
 ## Architecture DSL v1
 
 An `architecture` code fence renders a position-stable JSON DSL as SVG. Canvas

package/shared/architecture-editor/editor.css

@@ -107,11 +107,8 @@ body[data-inspector-open="false"] .inspector-panel{display:none;}
 .tree-item[aria-selected="true"] .tree-icon{color:inherit;}
 .tree-icon{width:18px;text-align:center;color:var(--editor-muted);}
 .tree-label{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
-.editor-viewport{position:relative;min-width:0;min-height:0;overflow:auto;cursor:grab;
-  background-color:#101217;
-  background-image:linear-gradient(var(--editor-grid) 1px,transparent 1px),
-    linear-gradient(90deg,var(--editor-grid) 1px,transparent 1px);
-  background-size:20px 20px;}
+.editor-viewport{position:relative;min-width:0;min-height:0;overflow:auto;cursor:default;
+  background-color:#101217;touch-action:none;}
 :root[data-theme="light"] .editor-viewport,:root[data-theme="microsoft"] .editor-viewport{
   background-color:#e9edf3;}
 .canvas-surface{display:flex;align-items:flex-start;justify-content:center;width:max-content;min-width:100%;min-height:100%;
@@ -130,6 +127,13 @@ body[data-inspector-open="false"] .inspector-panel{display:none;}
 .canvas-surface [data-editor-ref]{cursor:pointer;outline:none;}
 .canvas-surface [data-editor-ref][data-editor-movable="true"]{cursor:grab;}
 .editor-viewport.is-panning{cursor:grabbing;user-select:none;}
+.editor-viewport.is-panning [data-editor-ref]{cursor:grabbing;}
+.editor-viewport.is-selecting{cursor:crosshair;user-select:none;}
+.editor-grid,.editor-marquee{pointer-events:none;}
+.editor-marquee{fill:var(--editor-accent);fill-opacity:.18;stroke:var(--editor-accent);stroke-width:1;
+  vector-effect:non-scaling-stroke;}
+.visually-hidden{position:absolute;width:1px;height:1px;padding:0;overflow:hidden;
+  clip-path:inset(50%);white-space:nowrap;}
 .editor-viewport.is-dragging [data-editor-ref]{pointer-events:none;}
 .canvas-surface [data-editor-ref],.canvas-surface .editor-resize-handle{will-change:transform;}
 .canvas-surface .editor-drag-target{filter:drop-shadow(0 12px 16px rgba(0,0,0,.28));opacity:.92;}