@markdstage/markdstage 3.3.0 → 3.4.0

package/src/cli.mjs

@@ -21,7 +21,7 @@ import {
   exitCodeFor,
 } from "./exit.mjs";
 import { parsePageList } from "./deck.mjs";
-import { presentCommand } from "./commands/present.mjs";
+import { applicationCommand } from "./commands/present.mjs";
 import { validateCommand, formatValidateReport } from "./commands/validate.mjs";
 import { inspectCommand, formatInspectReport } from "./commands/inspect.mjs";
 import { captureCommand, formatCaptureReport } from "./commands/capture.mjs";
@@ -36,8 +36,8 @@ import {
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
 const COMMANDS = [
-  ["present", "Open presenter view and launch the audience view from it."],
-  ["preview", "Serve a deck on loopback and open it in a browser window."],
+  ["present", "Open the MarkdStage UI in presenter view."],
+  ["preview", "Open the MarkdStage UI in slide view."],
   ["validate", "Check deck structure, Architecture DSL blocks, and themes."],
   ["inspect", "Report 1280x720 clipping diagnostics for a deck."],
   ["capture", "Write 1280x720 PNG files for selected or clipped slides."],
@@ -78,7 +78,14 @@ function usage(command) {
     const lines = [
       "MarkdStage — turn Markdown into 16:9 slides.",
       "",
-      "Usage: markdstage <command> [options]",
+      "Usage:",
+      "  markdstage [options]",
+      "  markdstage <file.md> [options]",
+      "  markdstage <command> [options]",
+      "",
+      "Application:",
+      "  With no file, open an empty UI and choose Markdown from the workspace.",
+      "  With a Markdown file, open it in live slide view and refresh it on save.",
       "",
       "Commands:",
     ];
@@ -91,6 +98,7 @@ function usage(command) {
       "  --workspace <dir>   Confine every read and write to this directory.",
       "  --theme <name>      Override the deck theme.",
       "  --theme-file <path> Use a custom theme metadata file.",
+      "  --no-open           Serve the UI without launching a browser.",
       "  --json              Print machine-readable JSON.",
       "  -h, --help          Show help for a command.",
       "  -v, --version       Print the CLI version.",
@@ -106,10 +114,10 @@ function usage(command) {
     present: [
       "Usage: markdstage present <file.md> [options]",
       "",
-      "Opens presenter view with the current slide, next-slide preview, and speaker notes.",
-      "Use Start presentation in that view to open the synchronized audience window.",
+      "Opens the full MarkdStage UI in presenter view.",
+      "Open Markdown, automatic refresh, editing, export, and audience controls remain available.",
       "",
-      "  --watch     Reload on save.",
+      "  --watch     Start with automatic refresh enabled.",
       "  --no-open   Serve the presenter view without launching a browser.",
       "",
       "Presentation requires an installed Microsoft Edge, Google Chrome, or Chromium.",
@@ -117,11 +125,13 @@ function usage(command) {
     preview: [
       "Usage: markdstage preview <file.md> [options]",
       "",
-      "  --watch     Reload on save and enable Architecture editing.",
-      "  --no-open   Serve the deck without launching a browser.",
+      "Opens the full MarkdStage UI in slide view.",
+      "",
+      "  --watch     Start with automatic refresh enabled.",
+      "  --no-open   Serve the UI without launching a browser.",
       "",
-      "Without --watch, preview is read-only. Watch mode starts in normal viewing mode;",
-      "use the pencil control to edit Architecture diagrams and open the detailed designer.",
+      "Preview starts on the fixed 16:9 output surface. Use Output preview to switch",
+      "to the responsive layout. Architecture editing and export remain available.",
       "",
       "Preview requires an installed Microsoft Edge, Google Chrome, or Chromium.",
     ],
@@ -201,6 +211,10 @@ function deckOptions(file, values) {
   };
 }
 
+function isMarkdownArgument(value) {
+  return typeof value === "string" && /\.(?:md|markdown)$/i.test(value);
+}
+
 export async function run(argv, io = {}) {
   const out = io.out ?? ((text) => console.log(text));
   const err = io.err ?? ((text) => console.error(text));
@@ -208,7 +222,7 @@ export async function run(argv, io = {}) {
 
   const command = argv[0];
   const rest = argv.slice(1);
-  if (command === "--help" || command === "-h" || command === undefined) {
+  if (command === "--help" || command === "-h") {
     out(usage());
     return EXIT_OK;
   }
@@ -229,9 +243,63 @@ export async function run(argv, io = {}) {
     out(await packageVersion());
     return EXIT_OK;
   }
-  if (command.startsWith("-")) {
-    err(`Unknown option: ${command}\n\n${usage()}`);
-    return EXIT_USAGE;
+  if (command === undefined || isMarkdownArgument(command) || command.startsWith("-")) {
+    let values;
+    let positionals;
+    try {
+      ({ values, positionals } = parseArgs({
+        args: argv,
+        options: {
+          ...GLOBAL_OPTIONS,
+          "no-open": { type: "boolean" },
+        },
+        allowPositionals: true,
+      }));
+    } catch (error) {
+      err(`${error.message}\n\n${usage()}`);
+      return EXIT_USAGE;
+    }
+    if (values.help) {
+      out(usage());
+      return EXIT_OK;
+    }
+    if (values.version) {
+      out(await packageVersion());
+      return EXIT_OK;
+    }
+    if (positionals.length > 1) {
+      err(`Application mode accepts at most one Markdown file.\n\n${usage()}`);
+      return EXIT_USAGE;
+    }
+    const file = positionals[0];
+    if (file && !isMarkdownArgument(file)) {
+      err(`Unknown command: ${file}\n\n${usage()}`);
+      return EXIT_USAGE;
+    }
+    try {
+      const report = await applicationCommand(
+        {
+          ...deckOptions(file, values),
+          live: Boolean(file),
+          open: io.open ?? !values["no-open"],
+          until: io.until,
+        },
+        {
+          print: values.json ? () => {} : (message) => out(message),
+          status: (message, isError) => {
+            if (isError) err(message);
+            else if (!values.json) out(message);
+          },
+        },
+      );
+      if (values.json) json(report);
+      return EXIT_OK;
+    } catch (error) {
+      const code = exitCodeFor(error);
+      if (values.json) json(errorPayload(error));
+      else err(error?.message || String(error));
+      return code || EXIT_FAILURE;
+    }
   }
   if (!COMMAND_OPTIONS[command]) {
     err(`Unknown command: ${command}\n\n${usage()}`);
@@ -264,8 +332,13 @@ export async function run(argv, io = {}) {
     switch (command) {
       case "preview": {
         const file = requireFile(positionals, "preview");
-        const report = await presentCommand(
-          { ...deckOptions(file, values), watch: values.watch, open: !values["no-open"], until: io.until },
+        const report = await applicationCommand(
+          {
+            ...deckOptions(file, values),
+            watch: values.watch,
+            open: io.open ?? !values["no-open"],
+            until: io.until,
+          },
           {
             print: values.json ? () => {} : (message) => out(message),
             status: (message, isError) => {
@@ -279,11 +352,11 @@ export async function run(argv, io = {}) {
       }
       case "present": {
         const file = requireFile(positionals, "present");
-        const report = await presentCommand(
+        const report = await applicationCommand(
           {
             ...deckOptions(file, values),
             watch: values.watch,
-            open: !values["no-open"],
+            open: io.open ?? !values["no-open"],
             presenterView: true,
             until: io.until,
           },

package/src/commands/present.mjs

@@ -1,181 +1,171 @@
-// Shared server for the markdstage preview and present commands.
+// Shared browser application for the top-level, preview, and present commands.
 
-import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { mkdtemp, rm } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { tmpdir } from "node:os";
 import { spawn } from "node:child_process";
-import { pathToFileURL } from "node:url";
 import {
   MarkdStageError,
   buildPresenterBrowserArgs,
   findChromiumBrowser,
   isProcessRunning,
-  sharedPath,
   terminateProcessTree,
 } from "../runtime.mjs";
 import { withDeckServer } from "../deck.mjs";
 
-async function createWatcher(session, server, { onStatus }) {
-  const { createMarkdownWatcher } = await import(
-    pathToFileURL(sharedPath("scripts", "markdown-watcher.mjs")).href
-  );
-  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) => {
-      setWatchState("error", "watch_failed");
-      onStatus(`watch error: ${error?.message || error}`, true);
-    },
-  });
-  setWatchState("watching");
-  return watcher;
-}
-
-export async function presentCommand(options, io) {
+export async function applicationCommand(options, io, dependencies = {}) {
+  const createTempDirectory = dependencies.mkdtemp ?? mkdtemp;
+  const findBrowser = dependencies.findChromiumBrowser ?? findChromiumBrowser;
+  const processIsRunning = dependencies.isProcessRunning ?? isProcessRunning;
+  const remove = dependencies.rm ?? rm;
+  const spawnBrowser = dependencies.spawn ?? spawn;
+  const terminate = dependencies.terminateProcessTree ?? terminateProcessTree;
   let audienceProcess = null;
   let audienceProfileDir = "";
   let audienceUrl = "";
+  let audienceOperation = Promise.resolve();
+
+  const runAudienceOperation = (operation) => {
+    const result = audienceOperation.then(operation, operation);
+    audienceOperation = result.catch(() => {});
+    return result;
+  };
 
-  const closeAudience = async () => {
+  const closeAudienceNow = async () => {
     const process = audienceProcess;
+    const profileDir = audienceProfileDir;
     audienceProcess = null;
-    if (isProcessRunning(process)) await terminateProcessTree(process);
-    if (audienceProfileDir) {
-      await rm(audienceProfileDir, { recursive: true, force: true }).catch(() => {});
-      audienceProfileDir = "";
+    audienceProfileDir = "";
+    if (processIsRunning(process)) await terminate(process);
+    if (profileDir) {
+      await remove(profileDir, { recursive: true, force: true }).catch(() => {});
     }
     return { stopped: Boolean(process) };
   };
 
-  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,
+  const closeAudience = () => runAudienceOperation(closeAudienceNow);
+
+  const audience = {
+    isRunning: () => processIsRunning(audienceProcess),
+    open: () => runAudienceOperation(async () => {
+      if (processIsRunning(audienceProcess)) return { alreadyRunning: true };
+      await closeAudienceNow();
+      const browser = findBrowser();
+      if (!browser) {
+        throw new MarkdStageError(
+          "presenter_browser_not_found",
+          "Opening the audience view requires Microsoft Edge, Google Chrome, or Chromium.",
+        );
       }
-    : null;
+      const profileDir = await createTempDirectory(
+        join(tmpdir(), "markdstage-audience-window-"),
+      );
+      const process = spawnBrowser(
+        browser,
+        buildPresenterBrowserArgs({
+          profileDir,
+          presenterUrl: audienceUrl,
+        }),
+        { windowsHide: false, stdio: "ignore" },
+      );
+      try {
+        await new Promise((ready, reject) => {
+          process.once("spawn", ready);
+          process.once("error", reject);
+        });
+      } catch (error) {
+        if (processIsRunning(process)) await terminate(process);
+        await remove(profileDir, { recursive: true, force: true }).catch(() => {});
+        throw error;
+      }
+      audienceProcess = process;
+      audienceProfileDir = profileDir;
+      return { alreadyRunning: false };
+    }),
+    close: closeAudience,
+  };
 
   try {
-    return await withDeckServer({ ...options, presenter: audience }, async (session, server) => {
-      if (audience) {
+    return await withDeckServer(
+      {
+        ...options,
+        application: true,
+        initialSourceMode: options.live || options.watch ? "live" : "snapshot",
+        presenter: audience,
+      },
+      async (session, server) => {
         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;
 
-      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.",
+        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 = findBrowser();
+            if (!browser) {
+              throw new MarkdStageError(
+                "presenter_browser_not_found",
+                "Opening MarkdStage requires Microsoft Edge, Google Chrome, or Chromium. Re-run with --no-open to serve the UI only.",
+              );
+            }
+            profileDir = await createTempDirectory(join(tmpdir(), "markdstage-app-window-"));
+            browserProcess = spawnBrowser(
+              browser,
+              buildPresenterBrowserArgs({ profileDir, presenterUrl: browserUrl.href }),
+              { windowsHide: false, stdio: "ignore" },
             );
+            await new Promise((ready, reject) => {
+              browserProcess.once("spawn", ready);
+              browserProcess.once("error", reject);
+            });
           }
-          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 ${options.presenterView ? "presenting" : "previewing"} ${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.");
+          const operation = options.presenterView
+            ? "presenting"
+            : session.file
+              ? "previewing"
+              : "ready in";
+          io.print(`MarkdStage is ${operation} ${session.sourceName || "the workspace"}`);
+          io.print(`  slides:    ${session.slides.length}`);
+          io.print(`  theme:     ${session.theme}`);
+          io.print(`  workspace: ${resolve(session.workspaceRoot)}`);
+          io.print(`  url:       ${browserUrl.href}`);
+          if ((options.live || options.watch) && session.file) {
+            io.print("  watching:  on (live reload is 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);
-        });
+          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(() => {});
-      }
-    });
+          return {
+            ok: true,
+            url: browserUrl.href,
+            total: session.slides.length,
+            theme: session.theme,
+            sourceMode: server.sourceMode,
+          };
+        } finally {
+          await closeAudience();
+          if (processIsRunning(browserProcess)) await terminate(browserProcess);
+          if (profileDir) {
+            await remove(profileDir, { recursive: true, force: true }).catch(() => {});
+          }
+        }
+      },
+    );
   } finally {
     await closeAudience();
   }

package/src/deck.mjs

@@ -21,10 +21,14 @@ export async function withDeckServer(options, run) {
     log: options.log,
   });
   const server = await startPresentationServer(session, {
+    application: options.application,
+    exporters: options.exporters,
+    initialSourceMode: options.initialSourceMode,
     token,
     onLog: options.log,
     editable: options.watch === true,
     presenter: options.presenter,
+    watcherFactory: options.watcherFactory,
   });
   try {
     return await run(session, server);

package/src/skills.mjs

@@ -82,7 +82,7 @@ what the MarkdStage canvas and MarkdStage Desktop render.
    \`markdstage validate slides.md --json\`. Review diagnostic codes, JSON Pointers,
    and completeness, fix independent issues together, and preserve the same
    validated content when presenting. Suggestions are never automatic repairs.
-5. Use \`markdstage preview slides.md --watch\` for live source-backed authoring.
+5. Use \`markdstage slides.md\` 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
@@ -96,11 +96,13 @@ what the MarkdStage canvas and MarkdStage Desktop render.
    \`markdstage export slides.md --output slides.pdf\`, or
    \`markdstage export slides.md --output slides.pptx\`.
 
-The browser in \`preview --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**. \`preview\` without
-\`--watch\` is read-only.
+The browser in \`markdstage slides.md\` starts in viewing mode on the fixed 16:9
+output surface. **Output preview** switches to the retained responsive layout.
+The user can activate the pencil control to switch to the responsive layout and
+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**. Automatic refresh can be toggled from the
+same UI without disabling Architecture editing.
 
 Never hand-write HTML or CSS for a slide. Fix layout problems by shortening the
 content or by changing the layout in front matter. Prefer structured validation
@@ -110,8 +112,10 @@ and layout diagnostics over capturing every slide.
 
 | Command | Purpose |
 | --- | --- |
-| \`markdstage present <file> [--watch]\` | Open presenter view with the current slide, next-slide preview, speaker notes, and controls for a synchronized audience window. |
-| \`markdstage preview <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\` | Open an empty Canvas-equivalent UI and choose Markdown from the workspace. |
+| \`markdstage <file>\` | Open the full UI in live slide view with automatic refresh, editing, presenting, and UI export. |
+| \`markdstage present <file> [--watch]\` | Open the same full UI in presenter view; \`--watch\` enables automatic refresh initially. |
+| \`markdstage preview <file> [--watch]\` | Open the same full UI in slide view; \`--watch\` enables automatic refresh initially. |
 | \`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; use \`--fail-on-issues\` for quality gates. |
 | \`markdstage capture <file> [--pages 2,4]\` | Write 1280x720 PNG files; without \`--pages\` only clipped slides are captured. |