@markdstage/markdstage 0.1.3 → 2.4.0

package/shared/runtime/presentation-server.mjs

@@ -18,7 +18,10 @@ import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { randomBytes } from "node:crypto";
 import { resolveAssetFile } from "../scripts/asset-paths.mjs";
+import { importedArchitectureBlockIndex } from "../scripts/markdown-blocks.mjs";
 import { isMarkdownPath, listMarkdownFiles } from "../scripts/markdown-files.mjs";
+import { startArchitectureEditorServer } from "./architecture-editor-server.mjs";
+import { saveArchitectureSource } from "./architecture-source.mjs";
 import { isPathInside } from "./output-paths.mjs";
 import { safeJoin, sendChunkedVendorAsset, sendFile } from "./static-files.mjs";
 
@@ -27,6 +30,7 @@ const EXT_DIR = resolve(RUNTIME_DIR, "..");
 const VENDOR_DIR = join(EXT_DIR, "vendor");
 const VENDOR_MANIFEST = join(VENDOR_DIR, "vendor-assets.lock.json");
 const MAX_BODY_BYTES = 4096;
+const MAX_EDIT_BODY_BYTES = 256 * 1024;
 
 export function createUrlToken() {
   return randomBytes(24).toString("base64url");
@@ -87,8 +91,13 @@ function broadcast(session) {
  * Returns `{ url, token, port, close, broadcast }`. `session.url` is set to the
  * token-scoped base URL so the shared output runtime can render from it.
  */
-export async function startPresentationServer(session, { onLog, token = createUrlToken() } = {}) {
+export async function startPresentationServer(
+  session,
+  { editable = false, onLog, presenter, token = createUrlToken() } = {},
+) {
   const base = `/${token}`;
+  const architectureEditors = new Map();
+  const editingAvailable = editable === true;
   let port = 0;
 
   const server = createServer(async (req, res) => {
@@ -149,13 +158,21 @@ export async function startPresentationServer(session, { onLog, token = createUr
         customThemeCss: session.customThemeCss,
         customThemeMeta: session.customThemeMeta,
         mode: session.mode,
-        sourceBacked: false,
-        sourceMode: "snapshot",
+        sourceBacked: editingAvailable,
+        sourceModeAvailable: false,
+        sourceMode: editingAvailable ? "live" : "snapshot",
         sourceWatchStatus: session.watchStatus || "inactive",
         sourceWatchError: session.watchError || "",
-        presenterRunning: false,
-        architectureEdit: false,
-        architectureDetailedEdit: false,
+        presenterRunning: Boolean(presenter?.isRunning?.()),
+        presenterWindowAvailable: Boolean(presenter),
+        presenterViewAvailable: Boolean(presenter),
+        pdfExportAvailable: false,
+        pptxExportAvailable: false,
+        markdownImportAvailable: false,
+        architectureEditAvailable: editingAvailable,
+        architectureEdit: editingAvailable && Boolean(session.architectureEdit),
+        architectureDetailedEdit: editingAvailable,
+        architectureDetailedEditTarget: editingAvailable ? "window" : "",
       });
       return;
     }
@@ -371,8 +388,241 @@ export async function startPresentationServer(session, { onLog, token = createUr
       return;
     }
 
-    // Canvas-only routes. The CLI keeps them explicit so the browser reports an
-    // actionable message instead of a bare 404.
+    if (editingAvailable && route === "/edit-mode") {
+      if (req.method !== "POST") {
+        res.setHeader("Allow", "POST");
+        json(res, 405, { ok: false, error: "method_not_allowed" });
+        return;
+      }
+      if (!sameOrigin()) {
+        json(res, 403, { ok: false, error: "origin_not_allowed" });
+        return;
+      }
+      let body;
+      try {
+        body = await readJsonBody(req);
+      } catch (error) {
+        res.setHeader("Connection", "close");
+        json(res, error?.message === "payload_too_large" ? 413 : 400, {
+          ok: false,
+          error: error?.message || "bad_request",
+        });
+        return;
+      }
+      if (typeof body.enabled !== "boolean") {
+        json(res, 400, { ok: false, error: "enabled (boolean) is required" });
+        return;
+      }
+      const changed = Boolean(session.architectureEdit) !== body.enabled;
+      session.architectureEdit = body.enabled;
+      json(res, 200, {
+        ok: true,
+        changed,
+        architectureEdit: session.architectureEdit,
+      });
+      return;
+    }
+
+    if (editingAvailable && route === "/edit") {
+      if (req.method !== "POST") {
+        res.setHeader("Allow", "POST");
+        json(res, 405, { ok: false, error: "method_not_allowed" });
+        return;
+      }
+      if (!sameOrigin()) {
+        json(res, 403, { ok: false, error: "origin_not_allowed" });
+        return;
+      }
+      let body;
+      try {
+        body = await readJsonBody(req, MAX_EDIT_BODY_BYTES);
+      } catch (error) {
+        res.setHeader("Connection", "close");
+        json(res, error?.message === "payload_too_large" ? 413 : 400, {
+          ok: false,
+          error: error?.message || "bad_request",
+        });
+        return;
+      }
+      if (!session.architectureEdit) {
+        json(res, 409, { ok: false, error: "edit_mode_disabled" });
+        return;
+      }
+      if (typeof body.source !== "string" || !body.source.trim()) {
+        json(res, 400, { ok: false, error: "source (string) is required" });
+        return;
+      }
+      const index = Number.isInteger(body.index) ? body.index : session.index;
+      const block = Number.isInteger(body.block) ? body.block : 0;
+      const deckVersion = Number.isInteger(body.deckVersion)
+        ? body.deckVersion
+        : session.deckVersion;
+      if (index < 0 || index >= session.slides.length) {
+        json(res, 400, { ok: false, error: "index_out_of_range" });
+        return;
+      }
+      if (deckVersion !== session.deckVersion) {
+        json(res, 409, { ok: false, error: "deck_changed" });
+        return;
+      }
+      const globalBlock = importedArchitectureBlockIndex(session.slides, index, block);
+      if (globalBlock === null) {
+        json(res, 404, { ok: false, error: "block_not_found" });
+        return;
+      }
+      const result = await saveArchitectureSource({
+        workspaceRoot: session.workspaceRoot,
+        sourcePath: session.sourceName,
+        sourceFile: session.file,
+        blockIndex: globalBlock,
+        source: body.source,
+        expectedMarkdown: session.sourceMarkdown,
+      });
+      if (!result.ok) {
+        const status =
+          result.error === "source_changed"
+            ? 409
+            : result.error === "block_not_found"
+              ? 404
+              : result.error === "source_file_too_large"
+                ? 413
+                : result.error === "source_write_failed"
+                  ? 500
+                  : 422;
+        json(res, status, result);
+        return;
+      }
+      try {
+        await session.load({ preserveIndex: true });
+      } catch (error) {
+        json(res, 500, {
+          ok: false,
+          error: "source_reload_failed",
+          message: error?.message || "The saved deck could not be reloaded.",
+        });
+        return;
+      }
+      broadcast(session);
+      json(res, 200, {
+        ok: true,
+        version: session.version,
+        deckVersion: session.deckVersion,
+        index,
+        block,
+        markdown: session.markdown,
+        fileSaved: true,
+      });
+      return;
+    }
+
+    if (editingAvailable && route === "/architecture-editor/open") {
+      if (req.method !== "POST") {
+        res.setHeader("Allow", "POST");
+        json(res, 405, { ok: false, error: "method_not_allowed" });
+        return;
+      }
+      if (!sameOrigin()) {
+        json(res, 403, { ok: false, error: "origin_not_allowed" });
+        return;
+      }
+      let body;
+      try {
+        body = await readJsonBody(req);
+      } catch (error) {
+        json(res, error?.message === "payload_too_large" ? 413 : 400, {
+          ok: false,
+          error: error?.message || "bad_request",
+        });
+        return;
+      }
+      const slideIndex = Number.isInteger(body.index) ? body.index : session.index;
+      const blockIndex = Number.isInteger(body.block) ? body.block : 0;
+      const globalBlock = importedArchitectureBlockIndex(
+        session.slides,
+        slideIndex,
+        blockIndex,
+      );
+      if (globalBlock === null) {
+        json(res, 404, { ok: false, error: "block_not_found" });
+        return;
+      }
+      const key = `${session.file}\0${globalBlock}`;
+      let entry = architectureEditors.get(key);
+      const refreshExisting = Boolean(entry?.editor);
+      if (!entry) {
+        entry = { editor: null };
+        entry.promise = startArchitectureEditorServer({
+          extensionDirectory: EXT_DIR,
+          workspaceRoot: session.workspaceRoot,
+          sourcePath: session.sourceName,
+          blockIndex: globalBlock,
+          theme: session.theme,
+          logger: onLog,
+          onMarkdownSaved: async ({ sourcePath }) => {
+            if (resolve(session.workspaceRoot, sourcePath) !== resolve(session.file)) {
+              return;
+            }
+            await session.load({ preserveIndex: true });
+            broadcast(session);
+          },
+        });
+        architectureEditors.set(key, entry);
+      }
+      try {
+        const editor = entry.editor ?? (await entry.promise);
+        entry.editor = editor;
+        if (refreshExisting && !editor.dirty) {
+          await editor.reload(
+            {
+              sourcePath: session.sourceName,
+              blockIndex: globalBlock,
+              theme: session.theme,
+            },
+            { discard: true },
+          );
+        } else {
+          editor.setTheme(session.theme);
+        }
+        json(res, 200, { ok: true, url: editor.url });
+      } catch (error) {
+        if (!entry.editor && architectureEditors.get(key) === entry) {
+          architectureEditors.delete(key);
+        }
+        json(res, error?.code === "block_not_found" ? 404 : 409, {
+          ok: false,
+          error: error?.code || "editor_open_failed",
+          message: error?.message || "Architecture Editor could not be opened.",
+        });
+        return;
+      }
+      return;
+    }
+
+    if (presenter && route === "/present") {
+      if (req.method !== "POST" && req.method !== "DELETE") {
+        res.setHeader("Allow", "POST, DELETE");
+        json(res, 405, { ok: false, error: "method_not_allowed" });
+        return;
+      }
+      if (!sameOrigin()) {
+        json(res, 403, { ok: false, error: "origin_not_allowed" });
+        return;
+      }
+      try {
+        const result = req.method === "POST" ? await presenter.open() : await presenter.close();
+        json(res, 200, { ok: true, ...result });
+      } catch (error) {
+        json(res, 500, {
+          ok: false,
+          error: error?.code || "presenter_launch_failed",
+          message: error?.message || "The audience view could not be updated.",
+        });
+      }
+      return;
+    }
+
+    // Routes that are unavailable in this CLI server mode stay explicit so the
+    // browser reports an actionable message instead of a bare 404.
     if (
       route === "/present" ||
       route === "/export" ||
@@ -487,8 +737,14 @@ export async function startPresentationServer(session, { onLog, token = createUr
     token,
     port,
     broadcast: () => broadcast(session),
-    close: () =>
-      new Promise((done) => {
+    close: async () => {
+      await Promise.all(
+        [...architectureEditors.values()].map(async (entry) =>
+          (entry.editor ?? (await entry.promise.catch(() => null)))?.close().catch(() => {}),
+        ),
+      );
+      architectureEditors.clear();
+      await new Promise((done) => {
         for (const client of [...session.clients]) {
           try {
             client.end();
@@ -499,7 +755,7 @@ export async function startPresentationServer(session, { onLog, token = createUr
         session.clients.clear();
         server.close(() => done());
         server.closeAllConnections?.();
-      }),
+      });
+    },
   };
 }
-

package/src/cli.mjs

@@ -36,11 +36,12 @@ import {
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
 const COMMANDS = [
+  ["presentation", "Open presenter view and launch the audience view from it."],
   ["present", "Serve a deck on loopback and open it in a browser window."],
   ["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."],
-  ["export", "Export the deck as a 16:9 PDF."],
+  ["export", "Export the deck as PDF or editable PowerPoint."],
   ["guide", "Print the canonical MarkdStage authoring guide."],
   ["skill", "Install or check the portable MarkdStage Agent Skills."],
   ["help", "Show help for MarkdStage or for one command."],
@@ -58,6 +59,7 @@ const GLOBAL_OPTIONS = {
 };
 
 const COMMAND_OPTIONS = {
+  presentation: { watch: { type: "boolean" }, "no-open": { type: "boolean" } },
   present: { watch: { type: "boolean" }, "no-open": { type: "boolean" } },
   validate: {},
   inspect: { slide: { type: "string" }, all: { type: "boolean" }, "fail-on-issues": { type: "boolean" } },
@@ -101,12 +103,26 @@ function usage(command) {
     return lines.join("\n");
   }
   const help = {
+    presentation: [
+      "Usage: markdstage presentation <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.",
+      "",
+      "  --watch     Reload on save.",
+      "  --no-open   Serve the presenter view without launching a browser.",
+      "",
+      "Presentation requires an installed Microsoft Edge, Google Chrome, or Chromium.",
+    ],
     present: [
       "Usage: markdstage present <file.md> [options]",
       "",
-      "  --watch     Reload the deck when the Markdown file is saved.",
+      "  --watch     Reload on save and enable Architecture editing.",
       "  --no-open   Serve the deck without launching a browser.",
       "",
+      "Without --watch, presentation is read-only. Watch mode starts in normal viewing mode;",
+      "use the pencil control to edit Architecture diagrams and open the detailed designer.",
+      "",
       "Presenting requires an installed Microsoft Edge, Google Chrome, or Chromium.",
     ],
     validate: [
@@ -130,9 +146,10 @@ function usage(command) {
       "Without --pages only the slides reported as clipped are captured.",
     ],
     export: [
-      "Usage: markdstage export <file.md> [--output slides.pdf]",
+      "Usage: markdstage export <file.md> [--output slides.pdf|slides.pptx]",
       "",
-      "Produces the same 16:9 PDF as the MarkdStage canvas.",
+      "Produces the same 16:9 PDF or hybrid editable PowerPoint as the MarkdStage canvas.",
+      "The output extension selects the format; omitting --output keeps PDF as the default.",
     ],
     guide: [
       "Usage: markdstage guide [topic] [--json]",
@@ -259,6 +276,27 @@ export async function run(argv, io = {}) {
         if (values.json) json(report);
         return EXIT_OK;
       }
+      case "presentation": {
+        const file = requireFile(positionals, "presentation");
+        const report = await presentCommand(
+          {
+            ...deckOptions(file, values),
+            watch: values.watch,
+            open: !values["no-open"],
+            presenterView: true,
+            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;
+      }
       case "validate": {
         const file = requireFile(positionals, "validate");
         const report = await validateCommand(deckOptions(file, values));

package/src/commands/export.mjs

@@ -1,18 +1,38 @@
-// markdstage export — produce the same 16:9 PDF as the Canvas Extension.
+// markdstage export — produce the same PDF or editable PowerPoint as the Canvas Extension.
 
-import { exportPdf, pdfNameForSource } from "../runtime.mjs";
+import { extname } from "node:path";
+
+import {
+  exportPdf,
+  exportPptx,
+  pdfNameForSource,
+  pptxNameForSource,
+} from "../runtime.mjs";
 import { withDeckServer } from "../deck.mjs";
 
-export async function exportCommand(options) {
-  return withDeckServer(options, async (session) =>
-    exportPdf(
-      session,
-      options.output || pdfNameForSource(session.sourceName),
-      options.theme,
-    ),
-  );
+export async function exportCommand(
+  options,
+  exporters = { pdf: exportPdf, pptx: exportPptx },
+) {
+  return withDeckServer(options, async (session) => {
+    const requested = options.output || pdfNameForSource(session.sourceName);
+    const extension = extname(requested).toLowerCase();
+    if (extension === ".pptx") {
+      return exporters.pptx(
+        session,
+        options.output || pptxNameForSource(session.sourceName),
+        options.theme,
+      );
+    }
+    return exporters.pdf(session, requested, options.theme);
+  });
 }
 
 export function formatExportReport(report) {
-  return `Exported ${report.total} slide(s) to ${report.path} (${report.bytes} bytes, theme ${report.theme}).`;
+  const format = report.format === "pptx" ? "PowerPoint" : "PDF";
+  const fallback =
+    report.format === "pptx" && report.fallbackCount
+      ? `, ${report.fallbackCount} fallback item(s)`
+      : "";
+  return `Exported ${report.total} slide(s) to ${report.path} (${report.bytes} bytes, ${format}, theme ${report.theme}${fallback}).`;
 }