@markdstage/markdstage 0.1.1

package/shared/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,19 @@
+# Third-Party Notices
+
+This extension bundles the following open-source software under `vendor/`. Use each package
+in accordance with its license terms, copyright notices, and disclaimers. Consult each
+project's distribution and linked source for the latest license and complete copyright notices.
+
+| Open-source software | License | Bundled file | Source |
+| --- | --- | --- | --- |
+| marked | MIT License | `vendor/marked.min.js` | <https://github.com/markedjs/marked> |
+| DOMPurify | Apache-2.0 / MPL-2.0 | `vendor/purify.min.js` | <https://github.com/cure53/DOMPurify> |
+| highlight.js | MIT License | `vendor/highlight.min.js` | <https://github.com/highlightjs/highlight.js> |
+| Mermaid | MIT License | `vendor/mermaid.min.js` | <https://github.com/mermaid-js/mermaid> |
+
+The highlight.js license text is also bundled in
+[`vendor/highlight.LICENSE`](./vendor/highlight.LICENSE). Because DOMPurify's upstream
+distribution terms provide multiple license options, users should review the upstream LICENSE.
+
+Include this file in this repository's extension distribution. Do not remove copyright notices
+or license links for bundled open-source software from release ZIP files or other distributions.

package/shared/deck-state.mjs

@@ -0,0 +1,105 @@
+const DEFAULT_BACKCOVER = ["---", "layout: backcover", "---", ""].join("\n");
+
+export const OPEN_INPUT_REQUIRES_SLIDES_MESSAGE =
+  "Non-empty open input must include slides (a non-empty array of strings). " +
+  "To refocus the current canvas, call open_canvas with no input. " +
+  "To replace the registered snapshot, pass slides or call load_deck. " +
+  "sourceName is metadata for asset/theme resolution and output naming; it never reads or watches a Markdown file.";
+
+function readLayout(markdown) {
+  if (typeof markdown !== "string") return "";
+  const text = markdown
+    .replace(/\r\n/g, "\n")
+    .replace(/\r/g, "\n")
+    .replace(/^[\n \t\uFEFF]+/, "");
+  if (!text.startsWith("---\n")) return "";
+  const lines = text.split("\n");
+  for (let i = 1; i < lines.length; i += 1) {
+    if (lines[i].trim() === "---") break;
+    const separator = lines[i].indexOf(":");
+    if (separator <= 0) continue;
+    if (lines[i].slice(0, separator).trim().toLowerCase() !== "layout") continue;
+    return lines[i]
+      .slice(separator + 1)
+      .trim()
+      .replace(/^["']+|["']+$/g, "")
+      .toLowerCase();
+  }
+  return "";
+}
+
+export function ensureBackCover(slides) {
+  if (!slides.length) return slides;
+  if (readLayout(slides[slides.length - 1]) === "backcover") return slides;
+  return [...slides, DEFAULT_BACKCOVER];
+}
+
+function sameSlides(left, right) {
+  return left.length === right.length && left.every((slide, index) => slide === right[index]);
+}
+
+function clampIndex(value, total) {
+  const index = Number(value);
+  if (!Number.isFinite(index) || total <= 0) return 0;
+  return Math.max(0, Math.min(Math.trunc(index), total - 1));
+}
+
+export function classifyOpenInput(input) {
+  if (input === undefined || input === null) return { kind: "refocus" };
+  if (typeof input !== "object" || Array.isArray(input)) {
+    return {
+      kind: "invalid",
+      message: "MarkdStage open input must be an object when provided.",
+    };
+  }
+  if (Object.keys(input).length === 0) return { kind: "refocus" };
+  if (!Object.prototype.hasOwnProperty.call(input, "slides")) {
+    return { kind: "invalid", message: OPEN_INPUT_REQUIRES_SLIDES_MESSAGE };
+  }
+  const slides = input.slides;
+  if (
+    !Array.isArray(slides) ||
+    slides.length === 0 ||
+    !slides.every((slide) => typeof slide === "string")
+  ) {
+    return {
+      kind: "invalid",
+      message: "slides must be a non-empty array of strings when provided to open",
+    };
+  }
+  return { kind: "deck", slides };
+}
+
+export function planDeckOpen(
+  currentSlides,
+  incomingSlides,
+  { hasThemeInput = false, hasSourceInput = false } = {},
+) {
+  const normalizedCurrent = ensureBackCover(currentSlides.slice());
+  const normalizedIncoming = ensureBackCover(incomingSlides.slice());
+  const sameDeck = sameSlides(normalizedCurrent, normalizedIncoming);
+  return {
+    sameDeck,
+    shouldApply:
+      currentSlides.length === 0 || !sameDeck || hasThemeInput || hasSourceInput,
+    preserveCurrentIndex: sameDeck,
+  };
+}
+
+export function getExportSlides(inst) {
+  if (inst.slides.length) {
+    const slides = [...inst.slides];
+    if (inst.mode === "adhoc" && typeof inst.markdown === "string") {
+      slides[clampIndex(inst.index, slides.length)] = inst.markdown;
+    }
+    return slides;
+  }
+  if (inst.mode === "adhoc" && typeof inst.markdown === "string") {
+    return [inst.markdown];
+  }
+  return [];
+}
+
+export function getOutputSnapshotSlides(inst) {
+  return ensureBackCover(getExportSlides(inst));
+}

package/shared/docs/custom-theme-authoring.md

@@ -0,0 +1,208 @@
+# Custom theme authoring guide
+
+This guide is a reference for people who create `custom` themes for the
+MarkdStage canvas and for AI systems that generate themes.
+
+## Minimum setup
+
+Themes can be managed by folder. Put only custom properties in the CSS, and
+define optional cover and back-cover assets in `theme.json` in the same folder.
+
+```markdown
+---
+theme: custom
+theme-file: themes/brand/theme.css
+---
+```
+
+A minimal theme folder has the following structure. `theme.json` is optional;
+without it, the theme works as a traditional CSS-only theme.
+
+```text
+themes/brand/
+  theme.css
+  theme.json
+  assets/
+    cover.svg
+    logo.svg
+```
+
+`theme-file` resolves the same relative path in this order:
+
+1. The same folder as the source Markdown
+2. The workspace root
+
+For example, place `themes/brand/theme.css` at the workspace root as a shared
+theme for every deck. To override only `decks/quarterly/slides.md`, add
+`decks/quarterly/themes/brand/theme.css`. Both Markdown files can specify
+`theme-file: themes/brand/theme.css`; the file beside the Markdown takes
+precedence. When AI registers a deck with `open` / `load_deck`, it passes the
+source Markdown's workspace-relative path as `sourceName` for relative resolution.
+
+```css
+--bg: #101820;
+--fg: #ffffff;
+--body: #d7e3ef;
+--accent: #00a4ef;
+--surface: #182b3a;
+--border: #31536b;
+```
+
+You may also wrap declarations in `:root { ... }`.
+
+```css
+:root {
+  --bg: #101820;
+  --accent: #00a4ef;
+}
+```
+
+## Available properties
+
+### Base slide colors
+
+| Property | Purpose |
+| --- | --- |
+| `--bg` | Standard slide background |
+| `--fg` | Headings and primary text |
+| `--muted` | Secondary text |
+| `--body` | Body text |
+| `--accent` | Primary accent |
+| `--accent-strong` | Strong accent |
+| `--accent-soft` | Subtle accent background |
+| `--accent-line` | Accent line |
+| `--surface` | Cards and surfaces |
+| `--code` | Code block background |
+| `--code-fg` | Code block text |
+| `--border` | Borders |
+
+### Code syntax
+
+`--syntax-comment`, `--syntax-keyword`, `--syntax-string`,
+`--syntax-number`, `--syntax-title`, `--syntax-type`,
+`--syntax-meta`, and `--syntax-variable` color corresponding code elements.
+
+For diff rendering, use `--syntax-addition`, `--syntax-addition-bg`,
+`--syntax-deletion`, and `--syntax-deletion-bg`.
+
+### Decoration and covers
+
+| Property | Purpose |
+| --- | --- |
+| `--glow-1` / `--glow-2` | Background glows |
+| `--topbar` | Top bar background |
+| `--kicker-mark` | Kicker mark |
+| `--cover-bg` | Cover background |
+| `--cover-topbar` | Top bar background used only on the cover |
+| `--cover-text-align` | Cover body text alignment |
+| `--cover-content-align` | Horizontal alignment within the cover body |
+| `--cover-content-self` | Cover body area alignment |
+| `--cover-content-width` | Cover body area width |
+| `--cover-logo-width` | Cover logo width |
+| `--section-bg` | Section-divider background |
+| `--backcover-bg` | Back-cover background |
+| `--backcover-logo-width` | Back-cover logo width |
+| `--print-slide-bg` | Standard PDF page background |
+| `--print-cover-bg` | PDF cover background |
+| `--print-section-bg` | PDF section-divider background |
+| `--ms-font` | Font for Microsoft-style themes |
+
+`--ms-red`, `--ms-green`, `--ms-blue`, and `--ms-yellow` are also available as
+supporting brand colors.
+
+`--section-bg` and `--print-section-bg` are used as CSS `background` values.
+They support solid colors and multiple comma-separated gradients. Theme-file
+security restrictions prohibit `url()`. Section dividers have no image, logo,
+or icon settings in `theme.json`.
+
+## theme.json
+
+A `theme.json` file in the CSS folder is loaded automatically. Specify image
+paths relative to `theme.json` using the `assets/...` form.
+
+```json
+{
+  "$schema": "../../.github/extensions/markdstage/schema/theme-metadata-v1.schema.json",
+  "version": 1,
+  "cover": {
+    "background": { "image": "assets/cover.svg" },
+    "logo": { "image": "assets/logo.svg", "alt": "Example" }
+  },
+  "backcover": {
+    "logo": { "image": "assets/logo-light.svg", "alt": "Example" },
+    "copyright": "Copyright Example"
+  }
+}
+```
+
+- `cover.background` is decorative, so `alt` is optional.
+- Logo `alt` text is required.
+- Supported formats are SVG / PNG / WebP / JPEG, with a 2 MiB limit per file.
+- Absolute paths, external URLs, `..`, and symbolic links outside the theme
+  folder are rejected.
+- If an existing `theme.json` is invalid, loading returns an error rather than
+  silently falling back to CSS only.
+- Slide-front-matter `logo` / `copyright` values override back-cover metadata.
+
+### Sizing and spacing
+
+You may change `--deck-pad-y`, `--deck-pad-x`, `--slide-h1-size`,
+`--slide-h2-size`, `--slide-h3-size`, `--slide-body-size`, and
+`--slide-code-size`.
+
+Values may use CSS units and functions such as `px`, `rem`, and `clamp(...)`.
+
+## Authoring considerations
+
+- Runtime accepts arbitrary custom properties beginning with `--`, but only the
+  names documented here are used by standard layouts.
+- Values cannot be empty.
+- Selectors, `@import`, `url(...)`, `javascript:`, and `expression(...)` are prohibited.
+- Do not put arbitrary CSS rules or JavaScript in a theme file.
+- Keep theme files in the workspace and use relative paths that resolve safely
+  from the Markdown or workspace root.
+- The maximum theme file size is 64 KiB.
+- The maximum `theme.json` size is 64 KiB.
+- When a property appears more than once, the final value wins.
+- Gradients are supported in addition to solid colors. Verify contrast for body
+  and secondary text.
+- The same theme applies to PDF output.
+
+## Example
+
+```css
+:root {
+  --bg: #0b1320;
+  --fg: #f7fbff;
+  --muted: #9bb0c6;
+  --body: #d9e7f2;
+  --accent: #42d3ff;
+  --accent-strong: #a6f36b;
+  --accent-soft: rgb(66 211 255 / 14%);
+  --accent-line: rgb(66 211 255 / 45%);
+  --surface: #14263a;
+  --code: #101e2e;
+  --code-fg: #c6e6ff;
+  --border: #2d4d68;
+  --topbar: linear-gradient(90deg, #42d3ff, #a6f36b);
+  --kicker-mark: linear-gradient(135deg, #42d3ff, #a6f36b);
+  --cover-bg: linear-gradient(145deg, #102b48, #101729);
+  --cover-text-align: left;
+  --cover-content-align: flex-start;
+  --cover-content-width: 62%;
+  --section-bg:
+    linear-gradient(55deg, transparent 76%, #42d3ff 77%, transparent 78%),
+    radial-gradient(110% 55% at 60% 115%, #42d3ff, #315b32 42%, transparent 72%),
+    #0b1320;
+  --print-section-bg: var(--section-bg);
+  --backcover-bg: linear-gradient(145deg, #0d6b91, #315b32);
+}
+```
+
+## Guidance for AI theme selection
+
+- When explicit brand colors are requested, use `custom` with `theme-file`.
+- When built-in themes satisfy a request such as "bright" or "dark," use
+  `light` or `dark` rather than creating a custom theme.
+- Before creating a custom theme, retrieve `theme-schema` from
+  `markdstage_guide` and verify property names.

package/shared/markdown-deck.mjs

@@ -0,0 +1,220 @@
+// Split one Markdown file into an array of Markdown fragments, one per slide.
+//
+// Splitting was previously the skill's (generative AI's) responsibility. The
+// extension now also provides deterministic splitting so the canvas can import
+// Markdown directly. It does not summarize prose or decide how to adapt content
+// for slides; it only splits content and combines front matter.
+//
+// Keep this free of runtime npm dependencies because the extension is distributed as a ZIP.
+
+// Opening fence: three or more ` or ~ characters, as in marked; inspect only one info word.
+const FENCE_OPEN = /^([ \t]{0,3})(`{3,}|~{3,})[ \t]*([^\s`~]*)[ \t]*$/;
+
+// Slide separator: a line containing only `---` (three or more hyphens).
+// Do not treat `***` / `___` horizontal rules as separators; only the front-matter marker qualifies.
+const SEPARATOR = /^[ \t]{0,3}-{3,}[ \t]*$/;
+
+// One front-matter line: `key: value`. The value may be empty.
+const META_LINE = /^([A-Za-z][\w-]*)[ \t]*:(.*)$/;
+
+// Comment syntax allowed in front matter.
+const META_COMMENT = /^[ \t]*#/;
+
+// Keys not inherited by each slide from deck front matter.
+// - layout: Inheritance would make every page a cover or back cover. The leading
+//   front matter is also the first slide's front matter, so it still applies there.
+// - page: Sequence numbers are slide-specific; a deck-wide value has no meaning.
+const NON_INHERITED_KEYS = new Set(["layout", "page"]);
+
+// Layouts that do not receive automatic page numbers (cover, section divider, and back cover).
+const UNNUMBERED_LAYOUTS = new Set(["title", "section", "backcover"]);
+
+function normalizeText(text) {
+  return String(text).replace(/\r\n?/g, "\n").replace(/^\uFEFF/, "");
+}
+
+/**
+ * Read one front-matter block (`---` through `---`).
+ *
+ * Treat lines[start] as front matter only when it is `---` and all content up to
+ * the closing `---` consists of `key: value`, blank lines, or comments. Otherwise
+ * return null so the caller treats it as a normal separator or body content.
+ *
+ * Inspecting the contents before deciding prevents per-slide front matter
+ * immediately after a `---` slide separator from becoming an extra slide.
+ */
+function readFrontMatterAt(lines, start) {
+  if (!SEPARATOR.test(lines[start] ?? "")) return null;
+  const entries = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (SEPARATOR.test(line)) {
+      // Do not treat empty `---` `---` as front matter; it is indistinguishable from two rules.
+      if (!entries.length) return null;
+      return { meta: entriesToMeta(entries), end: i };
+    }
+    if (line.trim() === "" || META_COMMENT.test(line)) continue;
+    const matched = META_LINE.exec(line);
+    if (!matched) return null;
+    entries.push([matched[1], matched[2].trim()]);
+  }
+  return null;
+}
+
+function entriesToMeta(entries) {
+  const meta = new Map();
+  for (const [key, value] of entries) meta.set(key.toLowerCase(), { key, value });
+  return meta;
+}
+
+function metaLayout(meta) {
+  return (meta.get("layout")?.value || "").toLowerCase();
+}
+
+/** Convert a front-matter Map back to text enclosed by `---`. */
+function formatFrontMatter(meta) {
+  if (!meta.size) return "";
+  const lines = ["---"];
+  for (const { key, value } of meta.values()) {
+    lines.push(value === "" ? `${key}:` : `${key}: ${value}`);
+  }
+  lines.push("---");
+  return lines.join("\n");
+}
+
+/**
+ * Split a complete Markdown file into shared deck front matter and individual slides.
+ *
+ * The returned slides value is an array of `{ meta, body }`, where meta maps
+ * lowercase keys to `{ key, value }`.
+ *
+ * Splitting rules:
+ * - Do not use `---` inside code fences as a separator.
+ * - Extract leading file front matter as shared deck settings.
+ * - Associate front matter immediately after a separator (or at the beginning
+ *   of an otherwise empty body) with that slide.
+ * - Treat `---` after a nonblank line as a setext heading (H2), not a separator.
+ */
+export function splitMarkdownDeck(text) {
+  const lines = normalizeText(text).split("\n");
+  let cursor = 0;
+
+  // Skip leading blank lines, then read shared deck front matter.
+  while (cursor < lines.length && lines[cursor].trim() === "") cursor += 1;
+  let deckMeta = new Map();
+  const deckFrontMatter = readFrontMatterAt(lines, cursor);
+  if (deckFrontMatter) {
+    deckMeta = deckFrontMatter.meta;
+    cursor = deckFrontMatter.end + 1;
+  }
+
+  const slides = [];
+  let meta = new Map();
+  let body = [];
+  let sawContent = false;
+  let fence = null;
+
+  const flush = () => {
+    const text = body.join("\n").trim();
+    if (text || meta.size) slides.push({ meta, body: text });
+    meta = new Map();
+    body = [];
+    sawContent = false;
+  };
+
+  for (let i = cursor; i < lines.length; i += 1) {
+    const line = lines[i];
+
+    if (fence) {
+      body.push(line);
+      if (new RegExp(`^[ \\t]{0,3}[${fence[0]}]{${fence.length},}[ \\t]*$`).test(line)) {
+        fence = null;
+      }
+      continue;
+    }
+
+    const open = FENCE_OPEN.exec(line);
+    if (open) {
+      fence = open[2];
+      body.push(line);
+      sawContent = true;
+      continue;
+    }
+
+    if (SEPARATOR.test(line)) {
+      // `---` after a nonblank line is a setext heading (H2), not a separator.
+      // Check this before front matter so a `key: value`-like paragraph after a
+      // heading is not misidentified as front matter.
+      const previous = i > 0 ? lines[i - 1] : "";
+      if (sawContent && previous.trim() !== "") {
+        body.push(line);
+        continue;
+      }
+      // A separator `---` may also open the next slide's front matter
+      // (`---` / `key: value` / `---`). Include it only after validating the
+      // content as front matter, avoiding an extra blank slide.
+      const front = readFrontMatterAt(lines, i);
+      if (front) {
+        // If nothing has accumulated, this is the current slide's own front matter.
+        if (sawContent || meta.size) flush();
+        meta = front.meta;
+        i = front.end;
+        continue;
+      }
+      flush();
+      continue;
+    }
+
+    body.push(line);
+    if (line.trim() !== "") sawContent = true;
+  }
+  flush();
+
+  return { deckMeta, slides };
+}
+
+/**
+ * Convert a Markdown file to slide fragments the extension can render directly.
+ *
+ * - Inherit shared deck front matter on each slide; slide-level values take precedence.
+ * - Do not inherit `layout`. Leading file front matter also belongs to the first
+ *   slide, so it still applies there (for example, `layout: title`).
+ * - Add `page` / `total` automatically only when neither the deck nor slide
+ *   specifies them. Do not display numbers on covers, section dividers, or back
+ *   covers, although they still participate in sequence numbering.
+ */
+export function buildDeckSlides(text) {
+  const { deckMeta, slides } = splitMarkdownDeck(text);
+  if (!slides.length) return [];
+
+  const merged = slides.map((slide, i) => {
+    const meta = new Map();
+    for (const [key, entry] of deckMeta) {
+      // Leading file front matter also belongs to the first slide, so include its layout.
+      if (NON_INHERITED_KEYS.has(key) && !(i === 0 && key === "layout")) continue;
+      meta.set(key, entry);
+    }
+    for (const [key, entry] of slide.meta) meta.set(key, entry);
+    return { meta, body: slide.body };
+  });
+
+  const total = String(merged.filter((slide) => metaLayout(slide.meta) !== "backcover").length);
+
+  let ordinal = 0;
+  return merged.map((slide) => {
+    const layout = metaLayout(slide.meta);
+    if (layout !== "backcover") ordinal += 1;
+    if (!UNNUMBERED_LAYOUTS.has(layout)) {
+      if (!slide.meta.has("page")) {
+        slide.meta.set("page", { key: "page", value: String(ordinal) });
+      }
+      if (!slide.meta.has("total")) {
+        slide.meta.set("total", { key: "total", value: total });
+      }
+    }
+
+    const front = formatFrontMatter(slide.meta);
+    if (!front) return slide.body;
+    return slide.body ? `${front}\n${slide.body}` : front;
+  });
+}