@markdstage/markdstage 0.1.3 → 2.4.0

package/src/commands/present.mjs

@@ -1,6 +1,6 @@
 // markdstage present — serve the deck on loopback and open it in a browser.
 
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { tmpdir } from "node:os";
 import { spawn } from "node:child_process";
@@ -19,73 +19,162 @@ async function createWatcher(session, server, { onStatus }) {
   const { createMarkdownWatcher } = await import(
     pathToFileURL(sharedPath("scripts", "markdown-watcher.mjs")).href
   );
-  return createMarkdownWatcher({
+  const setWatchState = (status, error = "") => {
+    const changed = session.watchStatus !== status || session.watchError !== error;
+    session.watchStatus = status;
+    session.watchError = error;
+    if (changed) server.broadcast();
+  };
+  const watcher = createMarkdownWatcher({
     path: session.file,
     onChange: async () => {
       try {
+        if ((await readFile(session.file, "utf8")) === session.sourceMarkdown) {
+          setWatchState("watching");
+          return;
+        }
         // Keep the current slide, and keep the last valid deck when the file is
         // saved in a broken intermediate state.
         await session.load({ preserveIndex: true });
+        setWatchState("watching");
         server.broadcast();
         onStatus(`reloaded ${session.sourceName} (${session.slides.length} slides)`);
       } catch (error) {
+        setWatchState("error", error?.code || "source_reload_failed");
         onStatus(`reload failed, keeping the last valid deck: ${error?.message || error}`, true);
       }
     },
-    onError: (error) => onStatus(`watch error: ${error?.message || error}`, true),
+    onError: (error) => {
+      setWatchState("error", "watch_failed");
+      onStatus(`watch error: ${error?.message || error}`, true);
+    },
   });
+  setWatchState("watching");
+  return watcher;
 }
 
 export async function presentCommand(options, io) {
-  return withDeckServer(options, async (session, server) => {
-    const watcher = options.watch ? await createWatcher(session, server, {
-      onStatus: (message, isError) => io.status(message, isError),
-    }) : null;
+  let audienceProcess = null;
+  let audienceProfileDir = "";
+  let audienceUrl = "";
 
-    let browserProcess = null;
-    let profileDir = "";
-    if (options.open) {
-      const browser = findChromiumBrowser();
-      if (!browser) {
-        throw new MarkdStageError(
-          "presenter_browser_not_found",
-          "Presenting requires Microsoft Edge, Google Chrome, or Chromium. Re-run with --no-open to serve the deck only.",
-        );
-      }
-      profileDir = await mkdtemp(join(tmpdir(), "markdstage-presenter-window-"));
-      browserProcess = spawn(
-        browser,
-        buildPresenterBrowserArgs({ profileDir, presenterUrl: server.url }),
-        { windowsHide: false, stdio: "ignore" },
-      );
-      browserProcess.once("error", (error) => {
-        io.status(`browser failed to start: ${error?.message || error}`, true);
-      });
+  const closeAudience = async () => {
+    const process = audienceProcess;
+    audienceProcess = null;
+    if (isProcessRunning(process)) await terminateProcessTree(process);
+    if (audienceProfileDir) {
+      await rm(audienceProfileDir, { recursive: true, force: true }).catch(() => {});
+      audienceProfileDir = "";
     }
+    return { stopped: Boolean(process) };
+  };
 
-    io.print(`MarkdStage is presenting ${session.sourceName || session.file}`);
-    io.print(`  slides:    ${session.slides.length}`);
-    io.print(`  theme:     ${session.theme}`);
-    io.print(`  workspace: ${resolve(session.workspaceRoot)}`);
-    io.print(`  url:       ${server.url}`);
-    if (options.watch) io.print("  watching:  on (the deck reloads when the file is saved)");
-    io.print("Press Ctrl+C to stop.");
+  const audience = options.presenterView
+    ? {
+        isRunning: () => isProcessRunning(audienceProcess),
+        open: async () => {
+          if (isProcessRunning(audienceProcess)) return { alreadyRunning: true };
+          await closeAudience();
+          const browser = findChromiumBrowser();
+          if (!browser) {
+            throw new MarkdStageError(
+              "presenter_browser_not_found",
+              "Opening the audience view requires Microsoft Edge, Google Chrome, or Chromium.",
+            );
+          }
+          audienceProfileDir = await mkdtemp(join(tmpdir(), "markdstage-audience-window-"));
+          audienceProcess = spawn(
+            browser,
+            buildPresenterBrowserArgs({
+              profileDir: audienceProfileDir,
+              presenterUrl: audienceUrl,
+            }),
+            { windowsHide: false, stdio: "ignore" },
+          );
+          await new Promise((ready, reject) => {
+            audienceProcess.once("spawn", ready);
+            audienceProcess.once("error", reject);
+          });
+          return { alreadyRunning: false };
+        },
+        close: closeAudience,
+      }
+    : null;
 
-    await new Promise((done) => {
-      const stop = () => {
-        process.off("SIGINT", stop);
-        process.off("SIGTERM", stop);
-        done();
-      };
-      process.once("SIGINT", stop);
-      process.once("SIGTERM", stop);
-      if (browserProcess) browserProcess.once("close", stop);
-      if (options.until) options.until.then(stop, stop);
-    });
+  try {
+    return await withDeckServer({ ...options, presenter: audience }, async (session, server) => {
+      if (audience) {
+        const url = new URL(server.url);
+        url.searchParams.set("present", "1");
+        audienceUrl = url.href;
+      }
+      const watcher = options.watch
+        ? await createWatcher(session, server, {
+            onStatus: (message, isError) => io.status(message, isError),
+          })
+        : null;
 
-    watcher?.close();
-    if (isProcessRunning(browserProcess)) await terminateProcessTree(browserProcess);
-    if (profileDir) await rm(profileDir, { recursive: true, force: true }).catch(() => {});
-    return { ok: true, url: server.url, total: session.slides.length, theme: session.theme };
-  });
+      let browserProcess = null;
+      let profileDir = "";
+      const browserUrl = new URL(server.url);
+      if (options.presenterView) browserUrl.searchParams.set("presenter", "1");
+      try {
+        if (options.open) {
+          const browser = findChromiumBrowser();
+          if (!browser) {
+            throw new MarkdStageError(
+              "presenter_browser_not_found",
+              "Presenting requires Microsoft Edge, Google Chrome, or Chromium. Re-run with --no-open to serve the deck only.",
+            );
+          }
+          profileDir = await mkdtemp(join(tmpdir(), "markdstage-presenter-window-"));
+          browserProcess = spawn(
+            browser,
+            buildPresenterBrowserArgs({ profileDir, presenterUrl: browserUrl.href }),
+            { windowsHide: false, stdio: "ignore" },
+          );
+          await new Promise((ready, reject) => {
+            browserProcess.once("spawn", ready);
+            browserProcess.once("error", reject);
+          });
+        }
+
+        io.print(`MarkdStage is presenting ${session.sourceName || session.file}`);
+        io.print(`  slides:    ${session.slides.length}`);
+        io.print(`  theme:     ${session.theme}`);
+        io.print(`  workspace: ${resolve(session.workspaceRoot)}`);
+        io.print(`  url:       ${browserUrl.href}`);
+        if (options.watch) {
+          io.print("  watching:  on (live reload and Architecture editing are enabled)");
+        }
+        io.print("Press Ctrl+C to stop.");
+
+        await new Promise((done) => {
+          const stop = () => {
+            process.off("SIGINT", stop);
+            process.off("SIGTERM", stop);
+            done();
+          };
+          process.once("SIGINT", stop);
+          process.once("SIGTERM", stop);
+          if (browserProcess) browserProcess.once("close", stop);
+          if (options.until) options.until.then(stop, stop);
+        });
+
+        return {
+          ok: true,
+          url: browserUrl.href,
+          total: session.slides.length,
+          theme: session.theme,
+        };
+      } finally {
+        watcher?.close();
+        await closeAudience();
+        if (isProcessRunning(browserProcess)) await terminateProcessTree(browserProcess);
+        if (profileDir) await rm(profileDir, { recursive: true, force: true }).catch(() => {});
+      }
+    });
+  } finally {
+    await closeAudience();
+  }
 }

package/src/deck.mjs

@@ -23,6 +23,8 @@ export async function withDeckServer(options, run) {
   const server = await startPresentationServer(session, {
     token,
     onLog: options.log,
+    editable: options.watch === true,
+    presenter: options.presenter,
   });
   try {
     return await run(session, server);

package/src/runtime.mjs

@@ -64,9 +64,15 @@ export const { MarkdStageError } = errors;
 export const { createDeckSession, readDeckSlides, resolveDeckFile, resolveDeckTheme } =
   deckSession;
 export const { createUrlToken, startPresentationServer } = presentationServer;
-export const { captureSlides, exportPdf, inspectLayout, MAX_CAPTURE_SLIDES } = output;
+export const {
+  captureSlides,
+  exportPdf,
+  exportPptx,
+  inspectLayout,
+  MAX_CAPTURE_SLIDES,
+} = output;
 export const { findChromiumBrowser, terminateProcessTree, isProcessRunning } = browser;
-export const { captureDirectoryName, pdfNameForSource } = outputPaths;
+export const { captureDirectoryName, pdfNameForSource, pptxNameForSource } = outputPaths;
 export const {
   architectureValidationErrors,
   deckValidationFeedback,

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 in a browser, validating Architecture DSL and " +
-  "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,26 +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\`.
+## 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 present <file> [--watch]\` | Serve the deck on loopback and open it in a browser window. \`--watch\` reloads on save and keeps the current slide. |
+| \`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