@markdstage/markdstage 0.1.1

package/shared/schema/examples/web-app.architecture.json

@@ -0,0 +1,119 @@
+{
+  "$schema": "../architecture-v1.schema.json",
+  "version": 1,
+  "canvas": { "width": 1600, "height": 900 },
+  "title": "Web application overview",
+  "description": "A three-tier web application: clients, the application platform, and stored state.",
+  "elements": [
+    {
+      "type": "group",
+      "id": "clients",
+      "title": "Clients",
+      "x": 80,
+      "y": 220,
+      "width": 360,
+      "height": 420,
+      "layout": { "type": "column", "gap": 36, "padding": 54 },
+      "children": [
+        {
+          "type": "node",
+          "id": "browser",
+          "shape": "rounded-rect",
+          "icon": "user",
+          "text": "Browser"
+        },
+        {
+          "type": "node",
+          "id": "mobile",
+          "shape": "rounded-rect",
+          "icon": "user",
+          "text": "Mobile app"
+        }
+      ]
+    },
+    {
+      "type": "group",
+      "id": "platform",
+      "title": "Application platform",
+      "x": 560,
+      "y": 180,
+      "width": 480,
+      "height": 500,
+      "layout": { "type": "column", "gap": 36, "padding": 54 },
+      "style": { "stroke": "accentLine" },
+      "children": [
+        {
+          "type": "node",
+          "id": "gateway",
+          "shape": "rounded-rect",
+          "icon": "api",
+          "text": "API gateway"
+        },
+        {
+          "type": "node",
+          "id": "service",
+          "shape": "rounded-rect",
+          "icon": "server",
+          "text": "Order service"
+        },
+        {
+          "type": "node",
+          "id": "worker",
+          "shape": "rounded-rect",
+          "icon": "cloud",
+          "text": "Background worker"
+        }
+      ]
+    },
+    {
+      "type": "node",
+      "id": "database",
+      "shape": "rounded-rect",
+      "icon": "database",
+      "text": "Managed database",
+      "ariaLabel": "Managed relational database",
+      "x": 1160,
+      "y": 300,
+      "width": 320,
+      "height": 160,
+      "style": { "fill": "accentSoft" }
+    },
+    {
+      "type": "connector",
+      "from": "browser",
+      "to": "gateway",
+      "label": "HTTPS",
+      "routing": "orthogonal"
+    },
+    {
+      "type": "connector",
+      "from": "mobile",
+      "to": "gateway",
+      "label": "HTTPS",
+      "routing": "orthogonal",
+      "lane": 1
+    },
+    {
+      "type": "connector",
+      "from": "gateway",
+      "to": "service",
+      "routing": "straight"
+    },
+    {
+      "type": "connector",
+      "from": "service",
+      "to": "database",
+      "label": "SQL",
+      "routing": "orthogonal"
+    },
+    {
+      "type": "connector",
+      "from": "worker",
+      "to": "database",
+      "label": "batch",
+      "routing": "orthogonal",
+      "lane": -1,
+      "style": { "dash": "8 6" }
+    }
+  ]
+}

package/shared/schema/theme-metadata-v1.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/runceel/markdstage/schema/theme-metadata-v1.schema.json",
+  "title": "Presentation custom theme metadata v1",
+  "description": "Optional theme.json manifest stored beside a custom theme CSS file.",
+  "type": "object",
+  "required": ["version"],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "version": {
+      "const": 1
+    },
+    "cover": {
+      "type": "object",
+      "properties": {
+        "background": {
+          "$ref": "#/$defs/decorativeImage"
+        },
+        "logo": {
+          "$ref": "#/$defs/meaningfulImage"
+        }
+      },
+      "additionalProperties": false
+    },
+    "backcover": {
+      "type": "object",
+      "properties": {
+        "logo": {
+          "$ref": "#/$defs/meaningfulImage"
+        },
+        "copyright": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "assetPath": {
+      "type": "string",
+      "maxLength": 200,
+      "pattern": "^assets/(?:[A-Za-z0-9][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_-]+)*/)*[A-Za-z0-9][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_-]+)*\\.(?:svg|png|webp|jpg|jpeg)$"
+    },
+    "decorativeImage": {
+      "type": "object",
+      "required": ["image"],
+      "properties": {
+        "image": {
+          "$ref": "#/$defs/assetPath"
+        },
+        "alt": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "meaningfulImage": {
+      "type": "object",
+      "required": ["image", "alt"],
+      "properties": {
+        "image": {
+          "$ref": "#/$defs/assetPath"
+        },
+        "alt": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/shared/schema/theme-v1.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/runceel/markdstage/schema/theme-v1.json",
+  "title": "MarkdStage custom theme v1",
+  "description": "Machine-readable catalog for CSS custom properties supported by the MarkdStage canvas custom theme. Optional cover/backcover assets live in a sibling theme.json manifest.",
+  "type": "object",
+  "required": [
+    "version",
+    "variables"
+  ],
+  "properties": {
+    "version": {
+      "const": 1
+    },
+    "variables": {
+      "type": "object",
+      "description": "CSS custom property declarations. The runtime accepts any name matching the pattern.",
+      "properties": {
+        "--bg": { "type": "string", "description": "Standard slide background" },
+        "--fg": { "type": "string", "description": "Headings and primary text" },
+        "--muted": { "type": "string", "description": "Secondary text" },
+        "--body": { "type": "string", "description": "Body text" },
+        "--accent": { "type": "string", "description": "Primary accent" },
+        "--accent-strong": { "type": "string", "description": "Strong accent" },
+        "--accent-soft": { "type": "string", "description": "Subtle accent background" },
+        "--accent-line": { "type": "string", "description": "Accent line" },
+        "--surface": { "type": "string", "description": "Cards and surfaces" },
+        "--code": { "type": "string", "description": "Code block background" },
+        "--code-fg": { "type": "string", "description": "Code block text" },
+        "--border": { "type": "string", "description": "Border" },
+        "--syntax-comment": { "type": "string", "description": "Code comments" },
+        "--syntax-keyword": { "type": "string", "description": "Code keywords" },
+        "--syntax-string": { "type": "string", "description": "Code strings" },
+        "--syntax-number": { "type": "string", "description": "Code numbers" },
+        "--syntax-title": { "type": "string", "description": "Code titles" },
+        "--syntax-type": { "type": "string", "description": "Code types" },
+        "--syntax-meta": { "type": "string", "description": "Code metadata" },
+        "--syntax-variable": { "type": "string", "description": "Code variables" },
+        "--syntax-addition": { "type": "string", "description": "Added-line text color" },
+        "--syntax-addition-bg": { "type": "string", "description": "Added-line background" },
+        "--syntax-deletion": { "type": "string", "description": "Deleted-line text color" },
+        "--syntax-deletion-bg": { "type": "string", "description": "Deleted-line background" },
+        "--glow-1": { "type": "string", "description": "Background glow 1" },
+        "--glow-2": { "type": "string", "description": "Background glow 2" },
+        "--topbar": { "type": "string", "description": "Top bar background" },
+        "--kicker-mark": { "type": "string", "description": "Kicker mark" },
+        "--cover-bg": { "type": "string", "description": "Cover background" },
+        "--cover-topbar": { "type": "string", "description": "Top bar background used only on the cover" },
+        "--cover-text-align": { "type": "string", "description": "Cover body text alignment" },
+        "--cover-content-align": { "type": "string", "description": "Horizontal alignment within the cover body" },
+        "--cover-content-self": { "type": "string", "description": "Cover body area alignment" },
+        "--cover-content-width": { "type": "string", "description": "Cover body area width" },
+        "--cover-logo-width": { "type": "string", "description": "Cover logo width" },
+        "--section-bg": { "type": "string", "description": "Section-divider background" },
+        "--backcover-bg": { "type": "string", "description": "Back-cover background" },
+        "--backcover-logo-width": { "type": "string", "description": "Back-cover logo width" },
+        "--print-slide-bg": { "type": "string", "description": "Standard PDF page background" },
+        "--print-cover-bg": { "type": "string", "description": "PDF cover background" },
+        "--print-section-bg": { "type": "string", "description": "PDF section-divider background" },
+        "--ms-font": { "type": "string", "description": "Font for Microsoft-style themes" },
+        "--ms-red": { "type": "string", "description": "Microsoft red" },
+        "--ms-green": { "type": "string", "description": "Microsoft green" },
+        "--ms-blue": { "type": "string", "description": "Microsoft blue" },
+        "--ms-yellow": { "type": "string", "description": "Microsoft yellow" },
+        "--deck-pad-y": { "type": "string", "description": "Vertical slide padding" },
+        "--deck-pad-x": { "type": "string", "description": "Horizontal slide padding" },
+        "--slide-h1-size": { "type": "string", "description": "H1 size" },
+        "--slide-h2-size": { "type": "string", "description": "H2 size" },
+        "--slide-h3-size": { "type": "string", "description": "H3 size" },
+        "--slide-body-size": { "type": "string", "description": "Body text size" },
+        "--slide-code-size": { "type": "string", "description": "Code text size" }
+      },
+      "patternProperties": {
+        "^--[A-Za-z0-9_-]+$": { "type": "string" }
+      },
+      "additionalProperties": false,
+      "minProperties": 1
+    }
+  },
+  "additionalProperties": false,
+  "x-theme-file-format": "CSS custom property declarations, optionally wrapped in one :root block.",
+  "x-value-syntax": "Any non-empty CSS value except selectors, @import, url(), javascript:, expression(), and style tags.",
+  "x-theme-metadata": "When present, theme.json beside the CSS file must conform to theme-metadata-v1.schema.json."
+}

package/shared/scripts/architecture-assets.mjs

@@ -0,0 +1,226 @@
+import { open, mkdir, readdir, realpath, stat, unlink } from "node:fs/promises";
+import { extname, join, relative, resolve, sep } from "node:path";
+
+import {
+  ASSET_EXTENSIONS,
+  ASSET_PATH_PATTERN,
+} from "../renderer/architecture.mjs";
+import {
+  assetRootCandidates,
+  isPathInside,
+} from "./asset-paths.mjs";
+
+export const ARCHITECTURE_ASSET_MAX_BYTES = 10 * 1024 * 1024;
+export const ARCHITECTURE_ASSET_LIST_MAX = 1_000;
+
+const CONTENT_TYPES = Object.freeze({
+  svg: new Set(["image/svg+xml", "text/xml", "application/xml"]),
+  png: new Set(["image/png"]),
+  webp: new Set(["image/webp"]),
+  jpg: new Set(["image/jpeg"]),
+  jpeg: new Set(["image/jpeg"]),
+});
+
+function fail(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  throw error;
+}
+
+async function canonicalAssetRoot(
+  workspaceRoot,
+  { create = false, requestedAssets = "" } = {},
+) {
+  let canonicalWorkspace;
+  try {
+    canonicalWorkspace = await realpath(resolve(workspaceRoot));
+  } catch (_) {
+    fail("workspace_not_found", "The workspace root is unavailable.");
+  }
+  const assetsPath = requestedAssets || join(canonicalWorkspace, "assets");
+  if (create) await mkdir(assetsPath, { recursive: true });
+  let canonicalAssets;
+  try {
+    canonicalAssets = await realpath(assetsPath);
+  } catch (error) {
+    if (!create && error?.code === "ENOENT") {
+      return { workspace: canonicalWorkspace, assets: null };
+    }
+    fail("asset_root_unavailable", "The workspace assets folder is unavailable.");
+  }
+  if (!isPathInside(canonicalWorkspace, canonicalAssets)) {
+    fail(
+      "asset_root_outside_workspace",
+      "The assets folder must resolve inside the workspace.",
+    );
+  }
+  const info = await stat(canonicalAssets);
+  if (!info.isDirectory()) {
+    fail("asset_root_unavailable", "The workspace assets path is not a directory.");
+  }
+  return { workspace: canonicalWorkspace, assets: canonicalAssets };
+}
+
+function supportedExtension(filename) {
+  const extension = extname(filename).slice(1).toLowerCase();
+  return ASSET_EXTENSIONS.includes(extension) ? extension : "";
+}
+
+function assertContentType(extension, contentType) {
+  const normalized = String(contentType || "")
+    .split(";", 1)[0]
+    .trim()
+    .toLowerCase();
+  if (!normalized || normalized === "application/octet-stream") return;
+  if (!CONTENT_TYPES[extension]?.has(normalized)) {
+    fail(
+      "asset_content_type_mismatch",
+      `The ${normalized} content type does not match .${extension}.`,
+    );
+  }
+}
+
+function hasSupportedSignature(content, extension) {
+  if (extension === "png") {
+    return (
+      content.length >= 8 &&
+      content.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))
+    );
+  }
+  if (extension === "jpg" || extension === "jpeg") {
+    return (
+      content.length >= 3 &&
+      content[0] === 0xff &&
+      content[1] === 0xd8 &&
+      content[2] === 0xff
+    );
+  }
+  if (extension === "webp") {
+    return (
+      content.length >= 12 &&
+      content.subarray(0, 4).toString("ascii") === "RIFF" &&
+      content.subarray(8, 12).toString("ascii") === "WEBP"
+    );
+  }
+  if (extension === "svg") {
+    const source = content.subarray(0, Math.min(content.length, 16 * 1024)).toString("utf8");
+    if (/<!doctype/i.test(source)) return false;
+    return /^\uFEFF?\s*(?:<\?xml[^>]*>\s*)?(?:<!--[\s\S]*?-->\s*)*<svg(?:\s|>)/i.test(
+      source,
+    );
+  }
+  return false;
+}
+
+export function normalizeArchitectureAssetName(filename) {
+  const extension = supportedExtension(filename);
+  if (!extension) {
+    fail(
+      "unsupported_asset_type",
+      "Only SVG, PNG, WebP, JPG, and JPEG images can be imported.",
+    );
+  }
+  const rawStem = String(filename || "").slice(0, -extname(filename).length);
+  const stem =
+    rawStem
+      .normalize("NFKD")
+      .replace(/[\u0300-\u036f]/g, "")
+      .replace(/[^A-Za-z0-9._-]+/g, "-")
+      .replace(/^[^A-Za-z0-9]+/, "")
+      .replace(/[-_.]+$/, "")
+      .slice(0, 160) || "image";
+  return { stem, extension };
+}
+
+export async function listArchitectureAssets(workspaceRoot, sourcePath = "") {
+  const assets = [];
+  const seen = new Set();
+
+  const walk = async (root, directory, relativeDirectory = "") => {
+    if (assets.length >= ARCHITECTURE_ASSET_LIST_MAX) return;
+    let entries = await readdir(directory, { withFileTypes: true });
+    entries = entries.sort((left, right) => left.name.localeCompare(right.name, "en"));
+    for (const entry of entries) {
+      if (assets.length >= ARCHITECTURE_ASSET_LIST_MAX) break;
+      if (entry.isSymbolicLink()) continue;
+      const relativePath = relativeDirectory
+        ? `${relativeDirectory}/${entry.name}`
+        : entry.name;
+      const candidate = join(directory, entry.name);
+      if (entry.isDirectory()) {
+        await walk(root, candidate, relativePath);
+        continue;
+      }
+      if (!entry.isFile() || !supportedExtension(entry.name)) continue;
+      const assetPath = `assets/${relativePath.split(sep).join("/")}`;
+      if (!ASSET_PATH_PATTERN.test(assetPath)) continue;
+      let canonicalFile;
+      try {
+        canonicalFile = await realpath(candidate);
+      } catch (_) {
+        continue;
+      }
+      if (!isPathInside(root.workspace, canonicalFile) || !isPathInside(root.assets, canonicalFile)) {
+        continue;
+      }
+      const info = await stat(canonicalFile);
+      if (!info.isFile() || info.size > ARCHITECTURE_ASSET_MAX_BYTES) continue;
+      const assetKey = process.platform === "win32" ? assetPath.toLowerCase() : assetPath;
+      if (seen.has(assetKey)) continue;
+      seen.add(assetKey);
+      assets.push({ path: assetPath, size: info.size });
+    }
+  };
+
+  for (const requestedAssets of assetRootCandidates(workspaceRoot, sourcePath)) {
+    const root = await canonicalAssetRoot(workspaceRoot, { requestedAssets });
+    if (root.assets) await walk(root, root.assets);
+  }
+  return assets;
+}
+
+export async function importArchitectureAsset(
+  workspaceRoot,
+  { filename, contentType, content },
+) {
+  if (!Buffer.isBuffer(content) || content.length === 0) {
+    fail("empty_asset", "Choose a non-empty image file.");
+  }
+  if (content.length > ARCHITECTURE_ASSET_MAX_BYTES) {
+    fail("asset_too_large", "Images must be 10 MB or smaller.");
+  }
+  const { stem, extension } = normalizeArchitectureAssetName(filename);
+  assertContentType(extension, contentType);
+  if (!hasSupportedSignature(content, extension)) {
+    fail(
+      "asset_signature_mismatch",
+      `The file contents do not match the .${extension} image format.`,
+    );
+  }
+  const root = await canonicalAssetRoot(workspaceRoot, { create: true });
+  for (let index = 1; index < 10_000; index += 1) {
+    const suffix = index === 1 ? "" : `-${index}`;
+    const name = `${stem}${suffix}.${extension}`;
+    const assetPath = `assets/${name}`;
+    if (!ASSET_PATH_PATTERN.test(assetPath)) {
+      fail("invalid_asset_name", "The imported image name is not safe for Architecture DSL.");
+    }
+    const target = join(root.assets, name);
+    let handle;
+    try {
+      handle = await open(target, "wx");
+      await handle.writeFile(content);
+      await handle.sync();
+      await handle.close();
+      return { path: assetPath, size: content.length };
+    } catch (error) {
+      if (handle) {
+        await handle.close().catch(() => {});
+        await unlink(target).catch(() => {});
+      }
+      if (error?.code === "EEXIST") continue;
+      fail("asset_write_failed", error?.message || "The image could not be imported.");
+    }
+  }
+  fail("asset_name_exhausted", "A unique filename could not be allocated.");
+}

package/shared/scripts/asset-paths.mjs

@@ -0,0 +1,92 @@
+import { realpath, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+
+function fail(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  throw error;
+}
+
+export function isPathInside(root, candidate) {
+  const rel = relative(resolve(root), resolve(candidate));
+  return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
+function pathKey(path) {
+  const normalized = normalize(resolve(path));
+  return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+export function assetRootCandidates(workspaceRoot, sourcePath = "") {
+  const workspace = resolve(workspaceRoot);
+  const roots = [];
+  const seen = new Set();
+  const add = (path) => {
+    const key = pathKey(path);
+    if (seen.has(key)) return;
+    seen.add(key);
+    roots.push(resolve(path));
+  };
+
+  if (typeof sourcePath === "string" && sourcePath.trim()) {
+    const source = resolve(workspace, sourcePath.trim());
+    if (!isPathInside(workspace, source)) {
+      fail("asset_source_outside_workspace", "The asset source must stay inside the workspace.");
+    }
+    add(join(dirname(source), "assets"));
+  }
+  add(join(workspace, "assets"));
+  return roots;
+}
+
+function safeJoin(rootDir, rel) {
+  if (typeof rel !== "string" || !rel || isAbsolute(rel) || rel.includes("\0")) return null;
+  const root = resolve(rootDir);
+  const candidate = normalize(join(root, rel));
+  return isPathInside(root, candidate) ? candidate : null;
+}
+
+export async function resolveAssetFile(workspaceRoot, sourcePath, assetPath) {
+  const requestedRoots = assetRootCandidates(workspaceRoot, sourcePath);
+  let canonicalWorkspace;
+  try {
+    canonicalWorkspace = await realpath(resolve(workspaceRoot));
+  } catch (_) {
+    fail("workspace_not_found", "The workspace root is unavailable.");
+  }
+
+  for (const requestedRoot of requestedRoots) {
+    const candidate = safeJoin(requestedRoot, assetPath);
+    if (!candidate) {
+      fail("invalid_asset_path", "The asset path must stay inside an assets folder.");
+    }
+
+    let canonicalRoot;
+    try {
+      canonicalRoot = await realpath(requestedRoot);
+    } catch (error) {
+      if (error?.code === "ENOENT") continue;
+      fail("asset_root_unavailable", "An assets folder is unavailable.");
+    }
+    if (!isPathInside(canonicalWorkspace, canonicalRoot)) {
+      fail("asset_root_outside_workspace", "Assets folders must resolve inside the workspace.");
+    }
+
+    let canonicalAsset;
+    try {
+      canonicalAsset = await realpath(candidate);
+    } catch (error) {
+      if (error?.code === "ENOENT") continue;
+      fail("asset_unavailable", "The requested asset is unavailable.");
+    }
+    if (
+      !isPathInside(canonicalWorkspace, canonicalAsset) ||
+      !isPathInside(canonicalRoot, canonicalAsset)
+    ) {
+      fail("asset_outside_workspace", "The requested asset must resolve inside its assets folder.");
+    }
+    const info = await stat(canonicalAsset);
+    if (info.isFile()) return canonicalAsset;
+  }
+  return null;
+}

package/shared/scripts/atomic-markdown-replace.mjs

@@ -0,0 +1,46 @@
+import { randomUUID } from "node:crypto";
+import { open, readFile, rename, rm, stat } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+
+function sourceChangedError() {
+  const error = new Error("source_changed");
+  error.code = "SOURCE_CHANGED";
+  return error;
+}
+
+export async function atomicReplaceMarkdown({
+  path,
+  markdown,
+  expectedMarkdown,
+  mode,
+  revalidate,
+}) {
+  const temporary = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+  let handle = null;
+  try {
+    const expectedInfo = await stat(path);
+    handle = await open(temporary, "wx", mode);
+    await handle.writeFile(markdown, "utf8");
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    await revalidate();
+    const currentInfo = await stat(path);
+    if (
+      currentInfo.dev !== expectedInfo.dev ||
+      currentInfo.ino !== expectedInfo.ino ||
+      currentInfo.size !== expectedInfo.size ||
+      currentInfo.mtimeMs !== expectedInfo.mtimeMs ||
+      currentInfo.ctimeMs !== expectedInfo.ctimeMs
+    ) {
+      throw sourceChangedError();
+    }
+    if ((await readFile(path, "utf8")) !== expectedMarkdown) {
+      throw sourceChangedError();
+    }
+    await rename(temporary, path);
+  } finally {
+    await handle?.close().catch(() => {});
+    await rm(temporary, { force: true }).catch(() => {});
+  }
+}