@markdstage/markdstage 3.3.0 → 3.4.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
@@ -43,10 +45,14 @@ 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. |
@@ -55,19 +61,24 @@ markdstage skill install --target claude
 | `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.4.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

@@ -118,12 +118,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`.

package/shared/renderer/renderer.js

@@ -426,13 +426,14 @@ function collectDeckLayout(rendered) {
 function updateFixedPreviewWarning() {
   const warning = document.getElementById("layoutWarning");
   const button = document.getElementById("navFixedPreview");
-  if (!fixedPreviewMode || !layoutTarget) {
+  const empty = document.body.classList.contains("markdstage-empty");
+  if (!fixedPreviewMode || !layoutTarget || empty) {
     document.body.classList.remove("fixed-preview-overflow");
     if (warning) {
       warning.hidden = true;
       warning.textContent = "";
     }
-    if (button) button.dataset.state = fixedPreviewMode ? "active" : "";
+    if (button) button.dataset.state = fixedPreviewMode && !empty ? "active" : "";
     syncMoreControls();
     return;
   }
@@ -3020,6 +3021,7 @@ async function fetchDeck() {
 function setArchitectureEditMode(enabled) {
   const next = Boolean(enabled) && architectureEditAvailable && !presenterMode;
   if (next === architectureEditMode) return false;
+  if (next && fixedPreviewMode) setFixedPreviewMode(false);
   architectureEditMode = next;
   document.body.classList.toggle("architecture-edit-mode", next);
   updateArchitectureEditButton(next);
@@ -4352,6 +4354,17 @@ function init() {
     requestArchitectureEditMode(true);
   }
 
+  // Canvas and CLI preview start on the fixed 16:9 output surface. Presenter
+  // views keep their purpose-built layouts, and the control still lets users
+  // switch back to the responsive canvas layout.
+  if (
+    !presenterMode &&
+    !presenterViewRequested &&
+    params.get("responsive") !== "1"
+  ) {
+    setFixedPreviewMode(true);
+  }
+
   updateArchitectureEditButton();
   if (!previewMode) wireControls();
   else if (navigationEnabled) {

package/shared/runtime/deck-session.mjs

@@ -112,14 +112,25 @@ export async function createDeckSession({
   // An explicit --workspace wins; otherwise confine the deck to its Git
   // repository root (or the folder holding the Markdown file).
   const deckDirectory = file ? resolve(file, "..") : process.cwd();
-  const root = workspaceRoot
+  const requestedRoot = workspaceRoot
     ? resolve(workspaceRoot)
     : resolveWorkspaceRoot(deckDirectory, deckDirectory);
-  const resolved = await resolveDeckFile(file, root);
+  let root;
+  try {
+    root = await realpath(requestedRoot);
+  } catch (_) {
+    throw new MarkdStageError(
+      "workspace_not_found",
+      `Could not read workspace directory: ${requestedRoot}`,
+    );
+  }
+  const resolved = file ? await resolveDeckFile(file, root) : null;
   const session = {
-    file: resolved.path,
-    workspaceRoot: resolved.workspaceRoot,
-    sourceName: workspaceRelative(resolved.workspaceRoot, resolved.path),
+    file: resolved?.path ?? "",
+    workspaceRoot: resolved?.workspaceRoot ?? root,
+    sourceName: resolved
+      ? workspaceRelative(resolved.workspaceRoot, resolved.path)
+      : "",
     url: "",
     version: 0,
     deckVersion: 0,
@@ -145,6 +156,9 @@ export async function createDeckSession({
   };
 
   session.load = async ({ preserveIndex = false } = {}) => {
+    if (!session.file) {
+      throw new MarkdStageError("no_deck", "Open a Markdown file first.");
+    }
     const { markdown, slides } = await readDeckSlides(session.file);
     const selection = resolveDeckTheme({
       slides,
@@ -176,6 +190,23 @@ export async function createDeckSession({
     return session.slides.length;
   };
 
+  session.openFile = async (nextFile, { preserveIndex = false } = {}) => {
+    const next = await resolveDeckFile(nextFile, session.workspaceRoot);
+    const previous = {
+      file: session.file,
+      sourceName: session.sourceName,
+    };
+    session.file = next.path;
+    session.sourceName = workspaceRelative(next.workspaceRoot, next.path);
+    try {
+      return await session.load({ preserveIndex });
+    } catch (error) {
+      session.file = previous.file;
+      session.sourceName = previous.sourceName;
+      throw error;
+    }
+  };
+
   session.navigate = (target) => {
     const next = clampIndex(target, session.slides.length);
     if (next === session.index) return false;
@@ -185,6 +216,6 @@ export async function createDeckSession({
     return true;
   };
 
-  await session.load();
+  if (session.file) await session.load();
   return session;
 }