@markdstage/markdstage 2.5.1 → 3.0.0

package/shared/renderer/slides.css

@@ -250,12 +250,15 @@ body.mermaid-loading .mermaid{visibility:hidden;}
 .architecture-editor [data-architecture-movable="false"]{cursor:not-allowed;outline:none;}
 .architecture-editor [data-architecture-type]:focus-visible>rect,
 .architecture-editor [data-architecture-type]:focus-visible>ellipse,
+.architecture-editor [data-architecture-type]:focus-visible>polygon,
 .architecture-editor .architecture-selected>rect,
-.architecture-editor .architecture-selected>ellipse{
+.architecture-editor .architecture-selected>ellipse,
+.architecture-editor .architecture-selected>polygon{
      stroke:var(--accent-strong);stroke-width:7;filter:drop-shadow(0 0 8px var(--accent-line));}
 /* Layout-managed elements cannot move. Show a dashed explanation only when selected. */
 .architecture-editor [data-architecture-movable="false"].architecture-selected>rect,
-.architecture-editor [data-architecture-movable="false"].architecture-selected>ellipse{
+.architecture-editor [data-architecture-movable="false"].architecture-selected>ellipse,
+.architecture-editor [data-architecture-movable="false"].architecture-selected>polygon{
      stroke-dasharray:10 8;}
 .architecture-error{display:flex;flex-direction:column;gap:.35em;margin:.5em 0;
      padding:.8em 1em;border:2px solid #d13438;border-radius:8px;
@@ -544,8 +547,22 @@ body.presenter-view-mode .layout-warning{display:none;}
      align-items:center;justify-content:center;border-radius:6px;
      font-size:.82em;font-weight:700;font-variant-numeric:tabular-nums;
      color:var(--muted);background:var(--code);border:1px solid var(--border);}
+.overview-kind{flex:0 0 auto;padding:.18em .48em;border-radius:999px;
+     color:var(--accent-strong);background:var(--surface);border:1px solid var(--accent);
+     font-size:.66em;font-weight:750;letter-spacing:.06em;text-transform:uppercase;}
 .overview-label{flex:1 1 auto;font-size:.96em;line-height:1.35;
      overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
+.overview-item-title{margin-bottom:.45em;}
+.overview-item-title .overview-link{background:color-mix(in srgb,var(--accent-soft) 74%,transparent);
+     border:1px solid color-mix(in srgb,var(--accent) 48%,var(--border));}
+.overview-item-title .overview-label{color:var(--fg);font-weight:700;}
+.overview-item-section{margin-top:.65em;padding-top:.55em;border-top:1px solid var(--border);}
+.overview-item-section .overview-link{padding-block:.65em;background:var(--accent-soft);
+     border-left:4px solid var(--accent);}
+.overview-item-section .overview-num{color:var(--fg);border-color:var(--accent);}
+.overview-item-section .overview-label{color:var(--fg);font-weight:700;}
+.overview-item-section-child .overview-link{width:calc(100% - 1.2em);margin-left:1.2em;
+     border-left:1px solid color-mix(in srgb,var(--accent) 42%,var(--border));border-radius:0 8px 8px 0;}
 .overview-item.current .overview-link{background:var(--accent-soft);}
 .overview-item.current .overview-num{color:var(--fg);background:var(--accent);
      border-color:var(--accent);}

package/shared/runtime/browser.mjs

@@ -6,7 +6,7 @@
 // because the Extension is distributed as a folder ZIP.
 
 import { existsSync } from "node:fs";
-import { readFile, open, rm, stat } from "node:fs/promises";
+import { readFile, open, rm, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { execFileSync, spawn } from "node:child_process";
 
@@ -173,84 +173,6 @@ export function delay(milliseconds) {
   return new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds));
 }
 
-/**
- * Run a headless browser once with `--print-to-pdf`.
- *
- * ⚠️ **`pageUrl` must include `?print=1&token=...` (#12).**
- *
- * `--print-to-pdf` completes only when the page becomes idle. In renderer `init()`,
- * only print mode returns early. Normal and presenter views keep an unclosed SSE
- * (`new EventSource("./events")`) and a two-second `setInterval` running.
- * Passing a URL without `?print=1` therefore means **the browser never exits**.
- *
- * Observed results, using Chrome arguments byte-for-byte identical to this function:
- *
- * | URL                        | Result                                  |
- * | -------------------------- | --------------------------------------- |
- * | `/?print=1&token=<valid>`  | exit 0 @ 2.4s (valid PDF)               |
- * | `/?print=1&token=` (empty) | exit 0 @ 1.9s (blank; renderer reports failure) |
- * | `/` (normal view)          | **HANG** (still running after 120 seconds) |
- * | `/?present=1`              | **HANG**                                |
- * | `/nope-404` (no renderer)  | exit 0 @ 3.0s                           |
- *
- * ⚠️ **`--virtual-time-budget` is effectively ignored by `--headless=new`.**
- * The `--virtual-time-budget=12000` argument below does not stop this hang.
- * Adding `--timeout=8000` is also ineffective, as verified empirically.
- * The argument is harmless and remains in place, but **do not treat it as a
- * wall-clock timeout**. Only Node's `PDF_RENDER_TIMEOUT_MS` and
- * `terminateProcessTree` enforce a limit, and failure may take up to 60 seconds.
- */
-export async function runHeadlessBrowser(browser, args, failureLabel) {
-  await new Promise((resolvePromise, rejectPromise) => {
-    const child = spawn(browser, args, {
-      detached: process.platform !== "win32",
-      windowsHide: true,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-    let diagnostics = "";
-    let settled = false;
-    let timedOut = false;
-    const appendDiagnostics = (chunk) => {
-      diagnostics = `${diagnostics}${chunk.toString()}`.slice(-12_000);
-    };
-    child.stdout.on("data", appendDiagnostics);
-    child.stderr.on("data", appendDiagnostics);
-
-    const settle = (error) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      if (error) rejectPromise(error);
-      else resolvePromise();
-    };
-    const timer = setTimeout(async () => {
-      if (settled) return;
-      timedOut = true;
-      await terminateProcessTree(child);
-      settle(new Error(`${failureLabel} timed out after ${PDF_RENDER_TIMEOUT_MS / 1000}s.`));
-    }, PDF_RENDER_TIMEOUT_MS);
-
-    child.once("error", (error) => {
-      if (!timedOut) settle(error);
-    });
-    child.once("exit", (code, signal) => {
-      if (timedOut) return;
-      if (code === 0) {
-        settle();
-        return;
-      }
-      const detail = diagnostics.trim();
-      settle(
-        new Error(
-          `${failureLabel} failed (${signal ? `signal ${signal}` : `exit ${code}`})${
-            detail ? `: ${detail}` : "."
-          }`,
-        ),
-      );
-    });
-  });
-}
-
 function withSandboxFallback(args) {
   if (
     process.platform !== "win32" &&
@@ -262,35 +184,38 @@ function withSandboxFallback(args) {
   return args;
 }
 
-export async function runPdfBrowser(browser, pageUrl, outputPath, profileDir) {
-  // Enforce the contract at runtime. Otherwise it silently waits 60 seconds
-  // before timing out, obscuring the cause; fail immediately with an explanation.
+export async function runPdfBrowser(browser, pageUrl, outputPath, profileDir, job) {
   if (new URL(pageUrl).searchParams.get("print") !== "1") {
     throw new Error(
-      `Refusing to run --print-to-pdf against a non-print URL (${pageUrl}): only ?print=1 stops the renderer's SSE and polling loops, so any other page hangs the browser forever.`,
+      `Refusing to render PDF from a non-print URL (${pageUrl}).`,
     );
   }
-  const args = withSandboxFallback([
-    "--headless=new",
-    "--disable-gpu",
-    "--disable-background-networking",
-    "--disable-component-update",
-    "--disable-default-apps",
-    "--disable-extensions",
-    "--force-color-profile=srgb",
-    "--hide-scrollbars",
-    "--no-first-run",
-    "--no-pdf-header-footer",
-    "--print-to-pdf-no-header",
-    "--run-all-compositor-stages-before-draw",
-    // Ineffective (#12): --headless=new ignores it. See the JSDoc above.
-    // The actual safeguards are PDF_RENDER_TIMEOUT_MS + terminateProcessTree.
-    "--virtual-time-budget=12000",
-    `--user-data-dir=${profileDir}`,
-    `--print-to-pdf=${outputPath}`,
-    pageUrl,
-  ]);
-  await runHeadlessBrowser(browser, args, "Browser PDF rendering");
+  if (!job || typeof job !== "object") {
+    throw new Error("PDF rendering requires an output job.");
+  }
+
+  const { cdp, child } = await openCdpOutputPage(browser, pageUrl, profileDir, job);
+  try {
+    // The renderer reports ready only after Mermaid, images, fonts, and layout
+    // have settled. Give Chromium two compositor frames before printing.
+    await cdp.send("Runtime.evaluate", {
+      expression:
+        "new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)))",
+      awaitPromise: true,
+    });
+    const pdf = await cdp.send("Page.printToPDF", {
+      displayHeaderFooter: false,
+      printBackground: true,
+      preferCSSPageSize: true,
+      transferMode: "ReturnAsBase64",
+    });
+    if (typeof pdf.data !== "string" || pdf.data.length === 0) {
+      throw new Error("Chromium DevTools did not return PDF data.");
+    }
+    await writeFile(outputPath, Buffer.from(pdf.data, "base64"));
+  } finally {
+    await closeCdpOutputPage(cdp, child);
+  }
 }
 
 async function waitForDevToolsPort(profileDir, child, diagnostics) {

package/shared/runtime/output.mjs

@@ -497,14 +497,14 @@ export async function exportPdf(inst, requestedPath, requestedTheme) {
     profileDir = await mkdtemp(join(tmpdir(), "markdstage-pdf-"));
     const outputBase = basename(outputPath, extname(outputPath)) || "markdstage";
     temporaryOutputPath = join(outputParent, `.${outputBase}.${token}.tmp.pdf`);
-    inst.exportJobs.set(token, createOutputJob(snapshot, "pdf"));
+    const exportJob = createOutputJob(snapshot, "pdf");
+    inst.exportJobs.set(token, exportJob);
 
     const pageUrl = pageUrlFor(inst, { print: 1, token });
-    await runPdfBrowser(browser, pageUrl, temporaryOutputPath, profileDir);
-    const exportJob = inst.exportJobs.get(token);
-    if (exportJob?.status !== "ready") {
+    await runPdfBrowser(browser, pageUrl, temporaryOutputPath, profileDir, exportJob);
+    if (exportJob.status !== "ready") {
       throw new Error(
-        exportJob?.error || "The print renderer did not finish before the browser exited.",
+        exportJob.error || "The print renderer did not finish before PDF generation.",
       );
     }
     const bytes = await verifyPdf(temporaryOutputPath);

package/shared/runtime/pptx-package.mjs

@@ -569,8 +569,16 @@ function nativeShapeXml(element, path, id, relationships) {
     rect: "rect",
     roundedRect: "roundRect",
     ellipse: "ellipse",
+    diamond: "diamond",
+    triangle: "triangle",
+    hexagon: "hexagon",
+    parallelogram: "parallelogram",
   }[element.shape];
-  if (!preset) fail(`${path}.shape must be rect, roundedRect, or ellipse`);
+  if (!preset) {
+    fail(
+      `${path}.shape must be rect, roundedRect, ellipse, diamond, triangle, hexagon, or parallelogram`,
+    );
+  }
   const opacity = optionalUnitInterval(element.opacity, `${path}.opacity`);
   const properties = `${xfrmXml(bounds)}<a:prstGeom prst="${preset}"><a:avLst/></a:prstGeom>${colorXml(
     element.fill,

package/shared/schema/architecture-v1.schema.json

@@ -204,7 +204,17 @@
       "properties": {
         "type": { "const": "node" },
         "id": { "$ref": "#/$defs/identifier" },
-        "shape": { "enum": ["rect", "rounded-rect", "ellipse"] },
+        "shape": {
+          "enum": [
+            "rect",
+            "rounded-rect",
+            "ellipse",
+            "diamond",
+            "triangle",
+            "hexagon",
+            "parallelogram"
+          ]
+        },
         "x": { "$ref": "#/$defs/coordinate" },
         "y": { "$ref": "#/$defs/coordinate" },
         "width": { "$ref": "#/$defs/extent" },

package/src/cli.mjs

@@ -36,8 +36,8 @@ 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."],
+  ["present", "Open presenter view and launch the audience view from it."],
+  ["preview", "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."],
@@ -59,8 +59,8 @@ const GLOBAL_OPTIONS = {
 };
 
 const COMMAND_OPTIONS = {
-  presentation: { watch: { type: "boolean" }, "no-open": { type: "boolean" } },
   present: { watch: { type: "boolean" }, "no-open": { type: "boolean" } },
+  preview: { watch: { type: "boolean" }, "no-open": { type: "boolean" } },
   validate: {},
   inspect: { slide: { type: "string" }, all: { type: "boolean" }, "fail-on-issues": { type: "boolean" } },
   capture: { pages: { type: "string" }, output: { type: "string" } },
@@ -103,8 +103,8 @@ function usage(command) {
     return lines.join("\n");
   }
   const help = {
-    presentation: [
-      "Usage: markdstage presentation <file.md> [options]",
+    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.",
@@ -114,16 +114,16 @@ function usage(command) {
       "",
       "Presentation requires an installed Microsoft Edge, Google Chrome, or Chromium.",
     ],
-    present: [
-      "Usage: markdstage present <file.md> [options]",
+    preview: [
+      "Usage: markdstage preview <file.md> [options]",
       "",
       "  --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;",
+      "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.",
       "",
-      "Presenting requires an installed Microsoft Edge, Google Chrome, or Chromium.",
+      "Preview requires an installed Microsoft Edge, Google Chrome, or Chromium.",
     ],
     validate: [
       "Usage: markdstage validate <file.md> [--json]",
@@ -262,8 +262,8 @@ export async function run(argv, io = {}) {
 
   try {
     switch (command) {
-      case "present": {
-        const file = requireFile(positionals, "present");
+      case "preview": {
+        const file = requireFile(positionals, "preview");
         const report = await presentCommand(
           { ...deckOptions(file, values), watch: values.watch, open: !values["no-open"], until: io.until },
           {
@@ -277,8 +277,8 @@ export async function run(argv, io = {}) {
         if (values.json) json(report);
         return EXIT_OK;
       }
-      case "presentation": {
-        const file = requireFile(positionals, "presentation");
+      case "present": {
+        const file = requireFile(positionals, "present");
         const report = await presentCommand(
           {
             ...deckOptions(file, values),

package/src/commands/present.mjs

@@ -1,4 +1,4 @@
-// markdstage present — serve the deck on loopback and open it in a browser.
+// Shared server for the markdstage preview and present commands.
 
 import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { join, resolve } from "node:path";
@@ -139,7 +139,9 @@ export async function presentCommand(options, io) {
           });
         }
 
-        io.print(`MarkdStage is presenting ${session.sourceName || session.file}`);
+        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)}`);

package/src/skills.mjs

@@ -78,7 +78,7 @@ what the MarkdStage canvas and MarkdStage Desktop render.
    \`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.
+5. Use \`markdstage preview 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
@@ -88,14 +88,14 @@ what the MarkdStage canvas and MarkdStage Desktop render.
    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\`,
+9. Deliver from the same source with \`markdstage present 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 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**. \`present\` without
+detailed designer saves only when the user selects **Save**. \`preview\` without
 \`--watch\` is read-only.
 
 Never hand-write HTML or CSS for a slide. Fix layout problems by shortening the
@@ -106,8 +106,8 @@ and layout diagnostics over capturing every slide.
 
 | 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 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 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. |