@markdstage/markdstage 2.3.0 → 2.4.0

package/package.json

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

@@ -27,8 +27,8 @@ Canvas iframe (renderer/)
   | highlights language-tagged code fences with highlight.js
   | converts ```mermaid blocks with mermaid.run
   | converts validated ```architecture JSON DSL into a safe SVG DOM
-  | provides ◀ ▶, ✎, 16:9 PDF preview, margin clicks, arrow keys, and the ☰ slide list
-  | opens a synchronized external window with ⛶
+  | keeps ◀ page ▶, ☰, and ⋯ visible in a compact control bar
+  | groups editing, presentation, preview, import, refresh, and export under ⋯
   v
 The themed slide is displayed and updates automatically
 ```
@@ -75,26 +75,30 @@ The themed slide is displayed and updates automatically
 - 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.
-- The **canvas renderer** owns navigation controls, ✎ editing, the slide list,
-  and current position. ✎ toggles the same placement mode as
-  `edit_architecture`. For Markdown loaded with 📂, **Advanced editing** opens
+- 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
+  with **More controls > Open Markdown**, **Advanced editing** opens
   the dedicated `architecture-editor` canvas. The agent only opens the deck and
   does not run an `ask_user` loop. Margin clicks are installed only in normal
   canvas and presenter modes, never print mode. `goto_slide` remains available
   for an explicit page request from chat.
-- **PDF Export is available from the printer icon.** When `sourceName` is passed
+- **PDF Export is available from More controls > Export PDF.** When
+  `sourceName` is passed
   to open / `load_deck`, the printer saves `<source-name>.pdf` in the workspace.
   It does not load or watch that file. AI may call `export_pdf` with another
   `outputPath`. Hidden print mode renders every page, then headless Edge/Chrome
   produces a 16:9 PDF with backgrounds, images, highlighted code, and Mermaid.
-- **Hybrid editable PowerPoint export is available from the P control.** It
+- **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. AI may call
   `export_pptx` with another workspace-confined `.pptx` path.
-- Use the **16:9 control** to letterbox the current slide inside the canvas with
+- 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
@@ -109,7 +113,8 @@ The themed slide is displayed and updates automatically
   element hints. Call `capture_slides` only when visual inspection is needed;
   PNGs are fixed 1280×720 files and the action returns paths instead of inline
   image data.
-- Open the **external presenter** with ⛶ or `open_presenter`. Edge / Chrome /
+- Open the **external presenter** with **More controls > External window** or
+  `open_presenter`. Edge / Chrome /
   Chromium starts in a dedicated temporary profile as a movable, resizable
   1280×720 app-mode window. It shares `/state`, `/navigate`, and SSE with the
   canvas, so keyboard and Surface Pen position remain synchronized. Move it to
@@ -124,12 +129,13 @@ The themed slide is displayed and updates automatically
 - Add language names such as `csharp`, `json`, or `diff` to code fences for
   highlight.js syntax highlighting.
 
-## Markdown import (📂)
+## Markdown import
 
-Users can load Markdown directly from the canvas without AI. Press 📂 or `I` to
-open a filtered list of workspace `*.md` / `*.markdown` files. Selecting one
-loads it, splits it into slides, and replaces the deck. Import also works from
-the initial waiting view. The control is not shown in presenter or print mode.
+Users can load Markdown directly from the canvas without AI. Select **More
+controls > Open Markdown** or press `I` to open a filtered list of workspace
+`*.md` / `*.markdown` files. Selecting one loads it, splits it into slides, and
+replaces the deck. Import also works from the initial waiting view. The control
+is not shown in presenter or print mode.
 The workspace root is the Git repository root when available, otherwise the
 folder opened for the current session.
 
@@ -728,7 +734,7 @@ should determine placement without writing every coordinate.
 ### Placement editing
 
 Architecture diagrams can be moved directly over the rendered result. For decks
-imported through 📂, edits write back to the source `architecture` fence and
+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
@@ -808,7 +814,7 @@ blocks.
 - Saving reloads any MarkdStage canvas or watched CLI presentation showing the
   same Markdown while preserving the current page and theme.
 
-Source-backed decks imported through 📂 and CLI `present --watch` enable
+Source-backed decks imported through **More controls > Open Markdown** and CLI `present --watch` enable
 **Advanced editing**. Agents can open the editor canvas directly:
 
 ```json
@@ -907,7 +913,8 @@ special layout and are never auto-enlarged.
 | Long press | `Win+F18` | Previous slide |
 
 `Win+F19` double press and pen connection/removal/docking do not launch
-MarkdStage. Start the presenter through ⛶ or explicit `open_presenter`.
+MarkdStage. Start the presenter through **More controls > External window** or
+explicit `open_presenter`.
 
 The Windows setting that lets apps override shortcut-button behavior may remain
 enabled. This implementation listens directly for Windows pen shortcuts rather
@@ -956,14 +963,14 @@ fails with `invalid_input`; pass the complete `slides` array or call
 | `GET /export-data` | Return the token-bound deck snapshot to print, inspection, capture, or PowerPoint mode. |
 | `POST /export-status` | Let headless output modes report rendering status and fixed-layout diagnostics. |
 | `POST /navigate` | Accept absolute `{ index }` or relative `{ delta }`, update position, and notify all clients through SSE. |
-| `POST /present` | Start the presenter from ⛶; accepts same-origin POST only. |
-| `POST /export` | Start source-named PDF export from the printer icon; accepts same-origin POST only. |
-| `POST /export-pptx` | Start source-named hybrid PowerPoint export from the P control; accepts same-origin POST only. |
+| `POST /present` | Start the presenter from **More controls > External window**; accepts same-origin POST only. |
+| `POST /export` | Start source-named PDF export from **More controls > Export PDF**; accepts same-origin POST only. |
+| `POST /export-pptx` | Start source-named hybrid PowerPoint export from **More controls > Export PowerPoint**; accepts same-origin POST only. |
 | `POST /edit` | Write an edited fence with `{ index, block, source }`; returns `409 edit_mode_disabled` when editing is off. |
 | `POST /edit-mode` | Set `{ enabled }`, including for `?architectureEdit=1`; same-origin POST only. |
 | `POST /architecture-editor/open` | Convert source-backed slide/block indexes to a file-wide block index and open Architecture Editor. |
 | `GET /events` | SSE nudge for low-latency `version` changes. |
-| `GET /markdown-files` | Return bounded workspace-relative `*.md` / `*.markdown` paths for 📂, excluding `.git`, `node_modules`, and dot-prefixed entries. |
+| `GET /markdown-files` | Return bounded workspace-relative `*.md` / `*.markdown` paths for **Open Markdown**, excluding `.git`, `node_modules`, and dot-prefixed entries. |
 | `POST /import` | Load and split `{ path, sourceMode?: "snapshot" | "live" }`; reject paths outside workspace, wrong extensions, and oversized files. Same-origin POST only. |
 | `POST /source-mode` | Switch a source-backed deck with `{ mode: "snapshot" | "live" }`; entering live mode loads the latest source. |
 
@@ -978,7 +985,7 @@ fails with `invalid_input`; pass the complete `slides` array or call
     editor.css               # Workspace, tree, and inspector styles
     editor.js                # Diagram commands, draft, and explicit-save UI
   copilot-extension.json     # Manifest for Gist sharing
-  markdown-deck.mjs         # Raw Markdown splitting for 📂 import
+  markdown-deck.mjs         # Raw Markdown splitting for canvas import
   scripts/
     markdown-blocks.mjs     # Scan and replace architecture fences
     markdown-files.mjs      # Scan workspace Markdown

package/shared/markdstage-guide.mjs

@@ -109,8 +109,8 @@ export async function readGuide(topic = "overview") {
       return [
         section(readme, "## How it works"),
         "",
-        "Users can load workspace Markdown directly with the canvas 📂 button (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 MarkdStage's ✎ control 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.",
+        "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.",
         "",
         "For details, request `slide-format`, `themes`, `custom-themes`, `theme-schema`, `architecture-dsl`, or `architecture-schema`.",
       ].join("\n");

package/shared/renderer/index.html

@@ -19,18 +19,58 @@
 
   <!-- In-canvas navigation controls (persist across slide re-renders). -->
   <nav id="nav" class="nav" hidden aria-label="Slide controls">
-    <button id="navPrev" class="nav-btn" type="button" title="Previous (←)" aria-label="Previous slide">&#9664;</button>
-    <span id="navCounter" class="nav-counter" aria-live="polite"></span>
-    <button id="navNext" class="nav-btn" type="button" title="Next (→)" aria-label="Next slide">&#9654;</button>
-    <button id="navEdit" class="nav-btn" type="button" title="Shape editing mode" aria-label="Shape editing mode" hidden>&#x270E;</button>
-    <button id="navPresent" class="nav-btn" type="button" title="Open in external window (F11 for full screen)" aria-label="Open in external window" hidden>&#x26F6;</button>
-    <button id="navPresenterView" class="nav-btn" type="button" title="Presenter view" aria-label="Presenter view" hidden>&#128100;</button>
-    <button id="navFixedPreview" class="nav-btn nav-fixed-preview" type="button" title="Preview PDF layout at 16:9" aria-label="Preview PDF layout at 16:9" aria-pressed="false">16:9</button>
-    <button id="navExport" class="nav-btn" type="button" title="Save as PDF" aria-label="Save as PDF" hidden>&#128438;</button>
-    <button id="navExportPptx" class="nav-btn" type="button" title="Save as editable PowerPoint" aria-label="Save as editable PowerPoint" hidden>P</button>
-    <button id="navImport" class="nav-btn" type="button" title="Load Markdown (I)" aria-label="Load Markdown" hidden>&#128193;</button>
-    <button id="navSourceMode" class="nav-btn" type="button" title="Automatically refresh when Markdown is saved" aria-label="Automatically refresh when Markdown is saved" hidden>&#8635;</button>
-    <button id="navList" class="nav-btn" type="button" title="Slide list (O)" aria-label="Slide list">&#9776;</button>
+    <div class="nav-main" role="group" aria-label="Slide navigation">
+      <button id="navPrev" class="nav-btn" type="button" title="Previous (←)" aria-label="Previous slide">&#9664;</button>
+      <span id="navCounter" class="nav-counter" aria-live="polite"></span>
+      <button id="navNext" class="nav-btn" type="button" title="Next (→)" aria-label="Next slide">&#9654;</button>
+      <button id="navList" class="nav-btn" type="button" title="Slide list (O)" aria-label="Slide list">&#9776;</button>
+    </div>
+    <div id="navTools" class="nav-tools">
+      <button id="navMore" class="nav-btn nav-more-toggle" type="button" title="More controls" aria-label="More controls" aria-expanded="false" aria-controls="navMorePanel">&#8943;</button>
+    </div>
+    <div id="navMorePanel" class="nav-more-panel" role="group" aria-label="More slide controls" hidden>
+      <section class="nav-more-group" data-nav-group="present" aria-labelledby="navMorePresentLabel">
+        <span id="navMorePresentLabel" class="nav-more-title">Present</span>
+        <button id="navPresent" class="nav-more-item" type="button" title="Open in external window (F11 for full screen)" aria-label="Open in external window" hidden>
+          <span class="nav-more-icon" aria-hidden="true">&#x26F6;</span>
+          <span class="nav-more-label">External window</span>
+        </button>
+        <button id="navPresenterView" class="nav-more-item" type="button" title="Presenter view" aria-label="Presenter view" hidden>
+          <span class="nav-more-icon" aria-hidden="true">&#128100;</span>
+          <span class="nav-more-label">Presenter view</span>
+        </button>
+      </section>
+      <section class="nav-more-group" data-nav-group="view" aria-labelledby="navMoreViewLabel">
+        <span id="navMoreViewLabel" class="nav-more-title">View &amp; edit</span>
+        <button id="navEdit" class="nav-more-item" type="button" title="Shape editing mode" aria-label="Shape editing mode" hidden>
+          <span class="nav-more-icon" aria-hidden="true">&#x270E;</span>
+          <span class="nav-more-label">Shape editing</span>
+        </button>
+        <button id="navFixedPreview" class="nav-more-item" type="button" title="Preview PDF layout at 16:9" aria-label="Preview PDF layout at 16:9" aria-pressed="false">
+          <span class="nav-more-icon nav-fixed-preview" aria-hidden="true">16:9</span>
+          <span class="nav-more-label">Output preview</span>
+        </button>
+      </section>
+      <section class="nav-more-group" data-nav-group="file" aria-labelledby="navMoreFileLabel">
+        <span id="navMoreFileLabel" class="nav-more-title">File</span>
+        <button id="navImport" class="nav-more-item" type="button" title="Open Markdown (I)" aria-label="Open Markdown" hidden>
+          <span class="nav-more-icon" aria-hidden="true">&#128193;</span>
+          <span class="nav-more-label">Open Markdown</span>
+        </button>
+        <button id="navSourceMode" class="nav-more-item" type="button" title="Automatically refresh when Markdown is saved" aria-label="Automatically refresh when Markdown is saved" hidden>
+          <span class="nav-more-icon" aria-hidden="true">&#8635;</span>
+          <span class="nav-more-label">Automatic refresh</span>
+        </button>
+        <button id="navExport" class="nav-more-item" type="button" title="Save as PDF" aria-label="Save as PDF" hidden>
+          <span class="nav-more-icon" aria-hidden="true">&#128438;</span>
+          <span class="nav-more-label">Export PDF</span>
+        </button>
+        <button id="navExportPptx" class="nav-more-item" type="button" title="Save as editable PowerPoint" aria-label="Save as editable PowerPoint" hidden>
+          <span class="nav-more-icon" aria-hidden="true">P</span>
+          <span class="nav-more-label">Export PowerPoint</span>
+        </button>
+      </section>
+    </div>
     <span id="presentStatus" class="sr-only" aria-live="polite"></span>
     <span id="exportStatus" class="sr-only" aria-live="polite"></span>
     <span id="sourceStatus" class="sr-only" aria-live="polite"></span>

package/shared/renderer/renderer.js

@@ -98,6 +98,7 @@ let previewMode = false;
 let previewOffset = 0;
 let navigationEnabled = true;
 let fixedPreviewMode = false;
+let moreControlsOpen = false;
 // Markdown for the most recently rendered slide, retained for editing-mode rerenders.
 let lastMarkdown = "";
 // Editing UI attached to the rendered slide; destroyed on every rerender.
@@ -427,12 +428,14 @@ function updateFixedPreviewWarning() {
       warning.textContent = "";
     }
     if (button) button.dataset.state = fixedPreviewMode ? "active" : "";
+    syncMoreControls();
     return;
   }
 
   const diagnostic = collectSlideLayout(layoutTarget, navIndex);
   document.body.classList.toggle("fixed-preview-overflow", diagnostic.pdfClipped);
   if (button) button.dataset.state = diagnostic.pdfClipped ? "error" : "active";
+  syncMoreControls();
   if (!warning) return;
   if (!diagnostic.pdfClipped) {
     warning.hidden = true;
@@ -2141,6 +2144,7 @@ function updateArchitectureEditButton(enabled = architectureEditMode) {
   button.dataset.state = enabled && !presenterMode ? "active" : "";
   button.title = enabled ? "Exit shape editing mode" : "Shape editing mode";
   button.setAttribute("aria-label", button.title);
+  syncMoreControls();
 }
 
 function sourceWatchErrorMessage(code) {
@@ -2160,6 +2164,7 @@ function updateSourceModeButton() {
   if (!sourceBacked) {
     button.dataset.state = "";
     if (status) status.textContent = "";
+    syncMoreControls();
     return;
   }
   if (sourceMode === "live" && sourceWatchStatus === "error") {
@@ -2168,6 +2173,7 @@ function updateSourceModeButton() {
     button.title = `${message}. Click to pin the display to the loaded snapshot`;
     button.setAttribute("aria-label", button.title);
     if (status) status.textContent = message;
+    syncMoreControls();
     return;
   }
   const live = sourceMode === "live";
@@ -2181,6 +2187,7 @@ function updateSourceModeButton() {
       ? "Slides refresh automatically when Markdown is saved"
       : "Markdown retains the display from the loaded snapshot";
   }
+  syncMoreControls();
 }
 
 async function requestSourceMode(mode) {
@@ -2508,6 +2515,7 @@ async function setPresenterRunning(running) {
       button.dataset.state = "error";
       button.title = message;
     }
+    syncMoreControls();
   } finally {
     presenterRequestPending = false;
     if (button) button.disabled = false;
@@ -2522,6 +2530,64 @@ function togglePresenterWindow() {
   return setPresenterRunning(!presenterRunning);
 }
 
+function visibleMoreControlButtons() {
+  const panel = document.getElementById("navMorePanel");
+  if (!panel) return [];
+  return [...panel.querySelectorAll(".nav-more-item")].filter((button) => !button.hidden);
+}
+
+function setMoreControlsOpen(enabled, { focusFirst = false, restoreFocus = false } = {}) {
+  const nav = document.getElementById("nav");
+  const trigger = document.getElementById("navMore");
+  const panel = document.getElementById("navMorePanel");
+  if (!nav || !trigger || !panel) return;
+
+  const next = Boolean(enabled) && !nav.classList.contains("nav-empty") && !trigger.hidden;
+  moreControlsOpen = next;
+  trigger.setAttribute("aria-expanded", next ? "true" : "false");
+  panel.hidden = nav.classList.contains("nav-empty") ? !markdownImportAvailable : !next;
+
+  if (next && focusFirst) {
+    requestAnimationFrame(() => visibleMoreControlButtons()[0]?.focus());
+  } else if (!next && restoreFocus) {
+    trigger.focus();
+  }
+}
+
+function toggleMoreControls() {
+  setMoreControlsOpen(!moreControlsOpen, { focusFirst: !moreControlsOpen });
+}
+
+function syncMoreControls() {
+  const nav = document.getElementById("nav");
+  const trigger = document.getElementById("navMore");
+  const panel = document.getElementById("navMorePanel");
+  if (!nav || !trigger || !panel) return;
+
+  panel.querySelectorAll(".nav-more-group").forEach((group) => {
+    group.hidden = ![...group.querySelectorAll(".nav-more-item")].some(
+      (button) => !button.hidden,
+    );
+  });
+
+  const buttons = visibleMoreControlButtons();
+  const hasError = buttons.some((button) => button.dataset.state === "error");
+  const hasActive = buttons.some((button) => button.dataset.state === "active");
+  trigger.dataset.state = hasError ? "error" : hasActive ? "active" : "";
+  trigger.title = hasError
+    ? "More controls (attention required)"
+    : hasActive
+      ? "More controls (an option is active)"
+      : "More controls";
+  trigger.setAttribute("aria-label", trigger.title);
+
+  const empty = nav.classList.contains("nav-empty");
+  trigger.hidden = empty || buttons.length === 0;
+  if (trigger.hidden) moreControlsOpen = false;
+  trigger.setAttribute("aria-expanded", moreControlsOpen ? "true" : "false");
+  panel.hidden = empty ? !markdownImportAvailable : !moreControlsOpen;
+}
+
 function updateHostActionButtons() {
   const present = document.getElementById("navPresent");
   if (present) present.hidden = presenterMode || !presenterWindowAvailable;
@@ -2537,6 +2603,7 @@ function updateHostActionButtons() {
   if (importButton) importButton.hidden = presenterMode || !markdownImportAvailable;
   if (!presenterViewAvailable && presenterViewOpen) closePresenterView();
   if (!markdownImportAvailable && importOpen) closeImportPicker();
+  syncMoreControls();
 }
 
 function updatePresenterButton(running, message = "") {
@@ -2553,6 +2620,7 @@ function updatePresenterButton(running, message = "") {
     toggle.textContent = running ? "End presentation" : "Start presentation";
     toggle.dataset.state = running ? "active" : "";
   }
+  syncMoreControls();
 }
 
 async function exportPdfFromCanvas() {
@@ -2582,6 +2650,7 @@ async function exportPdfFromCanvas() {
       button.dataset.state = "active";
       button.title = message;
     }
+    syncMoreControls();
   } catch (error) {
     const message = error?.message || "Could not save the PDF.";
     console.error("PDF export failed", error);
@@ -2590,6 +2659,7 @@ async function exportPdfFromCanvas() {
       button.dataset.state = "error";
       button.title = message;
     }
+    syncMoreControls();
   } finally {
     pdfExportPending = false;
     if (button) button.disabled = false;
@@ -2626,6 +2696,7 @@ async function exportPptxFromCanvas() {
       button.dataset.state = "active";
       button.title = message;
     }
+    syncMoreControls();
   } catch (error) {
     const message = error?.message || "Could not save the PowerPoint presentation.";
     console.error("PowerPoint export failed", error);
@@ -2634,6 +2705,7 @@ async function exportPptxFromCanvas() {
       button.dataset.state = "error";
       button.title = message;
     }
+    syncMoreControls();
   } finally {
     pptxExportPending = false;
     if (button) button.disabled = false;
@@ -2653,6 +2725,7 @@ function setFixedPreviewMode(enabled) {
       ? "Return to responsive canvas layout"
       : "Preview PDF layout at 16:9";
   }
+  syncMoreControls();
   if (fixedPreviewMode) {
     updateFixedPreviewScale();
   } else {
@@ -2687,6 +2760,7 @@ function updateNav() {
   if (next) next.disabled = navMode === "deck" && navIndex >= navTotal - 1;
   highlightOverview();
   updatePresenterView();
+  syncMoreControls();
 }
 
 function openPresenterView() {
@@ -2711,7 +2785,7 @@ function closePresenterView() {
   document.body.classList.remove("presenter-view-mode");
   const view = document.getElementById("presenterView");
   if (view) view.hidden = true;
-  document.getElementById("navPresenterView")?.focus();
+  document.getElementById("navMore")?.focus();
 }
 
 function updatePresenterView() {
@@ -3035,10 +3109,11 @@ function wirePreviewKeyboardNavigation() {
 }
 
 function wireControls() {
-  const bind = (id, fn) => {
+  const bind = (id, fn, { closeMore = false } = {}) => {
     const el = document.getElementById(id);
     if (!el) return;
     el.addEventListener("click", () => {
+      if (closeMore) setMoreControlsOpen(false);
       fn();
       // Drop focus so a follow-up Space/Enter doesn't re-trigger the button on
       // top of the global keyboard handler.
@@ -3047,15 +3122,16 @@ function wireControls() {
   };
   bind("navPrev", goPrev);
   bind("navNext", goNext);
-  bind("navEdit", toggleArchitectureEditMode);
-  bind("navPresent", openPresenterWindow);
-  bind("navPresenterView", openPresenterView);
-  bind("navFixedPreview", toggleFixedPreviewMode);
-  bind("navExport", exportPdfFromCanvas);
-  bind("navExportPptx", exportPptxFromCanvas);
-  bind("navImport", toggleImportPicker);
-  bind("navSourceMode", toggleSourceMode);
   bind("navList", toggleOverview);
+  bind("navMore", toggleMoreControls);
+  bind("navEdit", toggleArchitectureEditMode, { closeMore: true });
+  bind("navPresent", openPresenterWindow, { closeMore: true });
+  bind("navPresenterView", openPresenterView, { closeMore: true });
+  bind("navFixedPreview", toggleFixedPreviewMode, { closeMore: true });
+  bind("navExport", exportPdfFromCanvas, { closeMore: true });
+  bind("navExportPptx", exportPptxFromCanvas, { closeMore: true });
+  bind("navImport", toggleImportPicker, { closeMore: true });
+  bind("navSourceMode", toggleSourceMode, { closeMore: true });
   bind("overviewClose", closeOverview);
   bind("importClose", closeImportPicker);
   bind("presenterPrevButton", goPrev);
@@ -3083,6 +3159,14 @@ function wireControls() {
     });
   }
 
+  document.addEventListener("pointerdown", (e) => {
+    if (!moreControlsOpen) return;
+    const tools = document.getElementById("navTools");
+    const panel = document.getElementById("navMorePanel");
+    if (tools?.contains(e.target) || panel?.contains(e.target)) return;
+    setMoreControlsOpen(false);
+  });
+
   wirePointerNavigation();
 
   // The iframe must be focused to receive key events; grab focus up front and
@@ -3105,16 +3189,23 @@ function wireControls() {
       e.preventDefault();
       return;
     }
+    if (e.key === "Escape" && moreControlsOpen) {
+      setMoreControlsOpen(false, { restoreFocus: true });
+      e.preventDefault();
+      return;
+    }
     if (handleSlideNavigationKey(e)) return;
     if (t && (t.tagName === "INPUT" || t.tagName === "TEXTAREA" || t.isContentEditable)) return;
     switch (e.key) {
       case "o":
       case "O":
+        setMoreControlsOpen(false);
         toggleOverview();
         e.preventDefault();
         break;
       case "i":
       case "I":
+        setMoreControlsOpen(false);
         toggleImportPicker();
         e.preventDefault();
         break;

package/shared/renderer/slides.css

@@ -389,6 +389,8 @@ footer .page{color:var(--accent-strong);font-weight:600;background:var(--accent-
      opacity:.45;transition:opacity .2s ease;}
 .nav:hover,.nav:focus-within{opacity:1;}
 @media (prefers-reduced-motion:reduce){.nav{transition:none;}}
+.nav-main{display:flex;align-items:center;gap:.4em;}
+.nav-tools{position:relative;display:flex;align-items:center;}
 .nav-btn{display:inline-flex;align-items:center;justify-content:center;
      min-width:2em;height:2em;padding:0 .55em;
      font-size:clamp(13px,1.9vh,17px);line-height:1;cursor:pointer;
@@ -400,10 +402,37 @@ footer .page{color:var(--accent-strong);font-weight:600;background:var(--accent-
 .nav-btn:disabled{opacity:.32;cursor:default;}
 .nav-btn[data-state="active"]{color:var(--accent-strong);background:var(--accent-soft);}
 .nav-btn[data-state="error"]{color:#d13438;}
-.nav-fixed-preview{min-width:3.25em;font-size:clamp(11px,1.55vh,14px);font-weight:700;}
+.nav-more-toggle{position:relative;}
+.nav-more-toggle[data-state]::after{content:"";position:absolute;right:.22em;top:.22em;
+     width:.38em;height:.38em;border-radius:50%;background:transparent;}
+.nav-more-toggle[data-state="active"]::after{background:var(--accent-strong);}
+.nav-more-toggle[data-state="error"]::after{background:#d13438;}
 .nav-counter{min-width:4.2em;text-align:center;font-variant-numeric:tabular-nums;
      font-weight:600;color:var(--accent-strong);font-size:clamp(12px,1.7vh,16px);
      padding:0 .3em;user-select:none;}
+.nav-more-panel[hidden],.nav-more-group[hidden]{display:none;}
+.nav-more-panel{position:absolute;left:50%;bottom:calc(100% + .65em);transform:translateX(-50%);
+     width:min(20em,calc(100vw - 24px));max-height:min(70vh,32em);overflow:auto;
+     display:grid;gap:.7em;padding:.7em;border:1px solid var(--border);border-radius:12px;
+     color:var(--fg);background:color-mix(in srgb,var(--surface) 96%,transparent);
+     box-shadow:0 12px 34px rgba(0,0,0,.3);}
+.nav-more-group{display:grid;gap:.18em;}
+.nav-more-title{padding:.2em .65em;color:var(--muted);font-size:.72em;font-weight:750;
+     letter-spacing:.06em;text-transform:uppercase;}
+.nav-more-item{display:grid;grid-template-columns:2.8em minmax(0,1fr);align-items:center;
+     width:100%;min-height:2.55em;padding:.42em .65em;border:1px solid transparent;
+     border-radius:8px;color:var(--fg);background:transparent;font:inherit;text-align:left;
+     cursor:pointer;}
+.nav-more-item[hidden]{display:none;}
+.nav-more-item:hover:not(:disabled){background:var(--accent-soft);color:var(--accent-strong);}
+.nav-more-item:focus-visible{outline:2px solid var(--accent);outline-offset:1px;}
+.nav-more-item:disabled{opacity:.4;cursor:default;}
+.nav-more-item[data-state="active"]{color:var(--accent-strong);background:var(--accent-soft);}
+.nav-more-item[data-state="error"]{color:#d13438;}
+.nav-more-icon{display:inline-flex;align-items:center;justify-content:center;min-width:2.2em;
+     font-size:.95em;font-weight:700;}
+.nav-more-icon.nav-fixed-preview{font-size:.72em;}
+.nav-more-label{min-width:0;font-size:.88em;font-weight:600;line-height:1.25;}
 .layout-warning{position:fixed;top:14px;right:14px;z-index:55;
      max-width:min(420px,calc(100vw - 28px));padding:.55em .8em;border-radius:8px;
      color:#fff;background:#a4262c;border:1px solid #f1aeb5;
@@ -418,14 +447,20 @@ body.presenter-mode #navImport{display:none;}
 body.presenter-mode #navSourceMode{display:none;}
 body.preview-mode .nav,body.preview-mode .overview{display:none!important;}
 /* When no deck is loaded, leave only the load button as the available action. */
-.nav.nav-empty > :not(#navImport){display:none;}
+.nav.nav-empty .nav-main,.nav.nav-empty #navMore{display:none;}
+.nav.nav-empty .nav-more-panel{position:static;display:block;width:auto;max-height:none;
+     overflow:visible;padding:0;border:0;border-radius:0;transform:none;background:transparent;
+     box-shadow:none;}
+.nav.nav-empty .nav-more-group,.nav.nav-empty .nav-more-title,
+.nav.nav-empty .nav-more-item{display:none;}
+.nav.nav-empty .nav-more-group[data-nav-group="file"]{display:block;}
+.nav.nav-empty #navImport{display:inline-flex;gap:.55em;width:auto;min-width:2.5em;height:2.5em;
+     padding:0 1em;}
 body.markdstage-empty .nav{
        opacity:1;padding:.42em;border-color:#3b4562;background:#151b2f;
        box-shadow:0 10px 30px rgba(0,0,0,.36);}
 body.markdstage-empty #navImport{
-       width:auto;min-width:2.5em;height:2.5em;padding:0 1em;
        border-color:#ffb547;background:#ffb547;color:#0b1020;font-weight:750;}
-body.markdstage-empty #navImport::after{content:"  Open Markdown";}
 body.markdstage-empty #navImport:hover{background:#ffd77a;color:#0b1020;}
 
 /* ===== Presenter view ===== */

package/src/skills.mjs

@@ -24,11 +24,12 @@ export const SKILL_TARGETS = {
 };
 
 const DESCRIPTION =
-  "Turn Markdown into 16:9 slides with the MarkdStage CLI. Use when the user " +
-  'asks to present, preview, validate, screenshot, or export a Markdown deck ("present slides.md", ' +
-  '"turn this file into slides", "export the deck to PDF", "check whether my slides fit"). ' +
-  "Provides deterministic commands for presenting and visually editing Architecture DSL in a " +
-  "browser, validating themes, inspecting 1280x720 clipping, capturing PNGs, and exporting PDF.";
+  "Turn Markdown into 16:9 slides with the MarkdStage CLI. Use when the user asks to create, " +
+  "refine, present, preview, validate, inspect, screenshot, or export a Markdown deck " +
+  '("present slides.md", "turn this file into slides", "export the deck to PDF or PowerPoint", ' +
+  '"check whether my slides fit"). Provides a deterministic create-review-deliver workflow, ' +
+  "browser-based Architecture DSL editing, theme validation, 1280x720 clipping diagnostics, " +
+  "targeted PNG capture, and PDF/PowerPoint export.";
 
 function frontMatter(fields) {
   const lines = ["---"];
@@ -66,32 +67,51 @@ what the MarkdStage canvas and MarkdStage Desktop render.
 - An installed Microsoft Edge, Google Chrome, or Chromium (never downloaded automatically).
 - The CLI: \`npx @markdstage/markdstage <command>\` or \`npm install --global @markdstage/markdstage\`.
 
-## Workflow
-
-1. Write or edit the deck as one Markdown file (see \`references/slide-format.md\`).
-2. Validate it: \`markdstage validate slides.md --json\`.
-3. Check the fixed 16:9 layout: \`markdstage inspect slides.md --json\`.
-4. Capture clipped slides for review: \`markdstage capture slides.md\`.
-5. Present or export: \`markdstage present slides.md --watch\` / \`markdstage export slides.md\`.
-
-Use \`present --watch\` for live authoring. It 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
+## Recommended authoring workflow
+
+1. Establish the source material, audience, objective, approximate length, theme,
+   required diagrams, and output format.
+2. Read only the relevant guidance. Start with
+   \`markdstage guide slide-format\`, then retrieve \`themes\`,
+   \`custom-themes\`, or \`architecture-dsl\` when needed.
+3. Create the complete deck as one Markdown source file (see
+   \`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.
+   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
+   \`--slide <n>\` after localized changes and \`--fail-on-issues\` in CI.
+7. Run \`markdstage capture slides.md\` only after inspection. Without
+   \`--pages\`, it captures only clipped slides; use \`--pages 2,4\` for pages
+   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\`,
+   \`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 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
 \`--watch\` is read-only.
 
 Never hand-write HTML or CSS for a slide. Fix layout problems by shortening the
-content or by changing the layout in front matter.
+content or by changing the layout in front matter. Prefer structured validation
+and layout diagnostics over capturing every slide.
 
 ## Commands
 
 | 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 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. |
+| \`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. |
-| \`markdstage export <file> [--output slides.pdf]\` | Produce the 16:9 PDF. |
+| \`markdstage export <file> [--output slides.pdf|slides.pptx]\` | Produce a 16:9 PDF or hybrid editable PowerPoint. |
 | \`markdstage guide <topic>\` | Print the canonical MarkdStage authoring guide. |
 
 Exit codes: \`0\` success, \`1\` usage error, \`2\` deck or input error, \`3\` no