@jpeakai/mermaidjs-lint 0.4.2 → 0.6.0

package/README.md

@@ -28,7 +28,7 @@ Installed as a dev dependency, the command is `mermaidjs-lint`, and `--help` lis
 
 Three tenets are guarantees about every diagram the tool passes, and the fourth is a commitment about the tool.
 
-- **Readable in light and dark.** Declared fills, label colours and borders are scored as the host draws them, on nodes, erDiagram rows and edge labels, in both themes.
+- **Readable in light and dark.** Declared fills, label colours and borders are scored as the host draws them, on nodes, erDiagram rows, edge labels and sequence diagrams, in both themes.
 - **Renders.** Every diagram parses with the mermaid parsers this package ships, and every mermaid fence is closed.
 - **Simple enough to follow.** Node count and visual complexity are scored against a density preset, so an oversized diagram is flagged to be split.
 - **Extensible.** A plugin adds rules of your own, which run through the same config, fix engine and verification as the built-ins.
@@ -54,7 +54,7 @@ It does not compare edge endpoints, edge labels or node text, so review the diff
 ## Requirements and compatibility
 
 - **Runtime:** Bun, or Node `>=20` as the `engines` field of `package.json` states.
-- **Mermaid:** the parse rules use the `mermaid` package, at `^11.14.0`, and `@mermaid-js/parser`, both installed with this package.
+- **Mermaid:** the parse and contrast rules use the `mermaid` package at exactly `11.17.2`, and `@mermaid-js/parser`, both installed with this package. The pin holds sequence diagram colours, which change between mermaid releases.
 - **Your host's mermaid may differ.** GitHub and other hosts draw diagrams with their own mermaid version. A diagram type newer than the host's may parse here and still fail to draw there.
 
 `npm ls mermaid` in your project prints the mermaid version a run uses.

package/dist/bin.js

@@ -9,7 +9,7 @@ import { parseArgs } from "node:util";
 // package.json
 var package_default = {
   name: "@jpeakai/mermaidjs-lint",
-  version: "0.4.2",
+  version: "0.6.0",
   type: "module",
   description: "Deterministic lint gates and verified fixers for Mermaid diagrams in markdown",
   license: "MIT",
@@ -67,7 +67,7 @@ var package_default = {
     "mdast-util-from-markdown": "^2.0.3",
     "mdast-util-frontmatter": "^2.0.1",
     "mdast-util-gfm": "^3.1.0",
-    mermaid: "^11.14.0",
+    mermaid: "11.17.2",
     "micromark-extension-frontmatter": "^2.0.0",
     "micromark-extension-gfm": "^3.0.0"
   },
@@ -179,6 +179,14 @@ class RuleOptionError extends UsageError {
   }
 }
 
+class CanvasProfileError extends UsageError {
+  file;
+  constructor(file) {
+    super(`${file}: a canvas applies under the github profile only, and this file is scored under mkdocs-material, whose page is Material's own; drop the canvas for it, or pass --profile github`, "canvas-profile");
+    this.file = file;
+  }
+}
+
 class FixOutsideRootError extends UsageError {
   file;
   target;
@@ -395,6 +403,7 @@ var getMermaid = async () => {
   mermaidCore = (await import("mermaid")).default;
   return mermaidCore;
 };
+var getMermaidCore = async () => await getMermaid();
 var LANGIUM_TYPES = {
   "architecture-beta": "architecture",
   architecture: "architecture",
@@ -1040,15 +1049,27 @@ var MKDOCS_MATERIAL = {
   light: { bg: "#ffffff", text: "#36464e" },
   dark: { bg: "#1e2129", text: "hsl(225 18% 86% / 0.82)" }
 };
-var GITHUB = { light: { bg: "#ffffff" }, dark: { bg: "#0d1117" } };
+var GITHUB_CANVAS = { light: "#ffffff", dark: "#0d1117" };
 var THEMES = ["light", "dark"];
+var canvasColourProblem = (value) => {
+  if (typeof value !== "string")
+    return "is not a colour string";
+  let alpha;
+  try {
+    alpha = alphaOf(value);
+  } catch {
+    return "is not a CSS colour";
+  }
+  return alpha < 1 ? "is translucent, and a page canvas must be opaque" : null;
+};
+var resolveCanvas = (setting) => ({ ...GITHUB_CANVAS, ...setting });
 var MERMAID_EDGE_LABEL = {
   light: { box: "rgba(232,232,232,0.8)", backing: "rgba(232,232,232,0.5)" },
   dark: { box: "#585858", backing: "rgba(88,88,88,0.5)" }
 };
-var edgeLabelBackground = (theme) => {
+var edgeLabelBackground = (theme, canvas = GITHUB_CANVAS) => {
   const { box, backing } = MERMAID_EDGE_LABEL[theme];
-  return compositeOver(box, compositeOver(box, compositeOver(backing, GITHUB[theme].bg)));
+  return compositeOver(box, compositeOver(box, compositeOver(backing, canvas[theme])));
 };
 var MERMAID_ER = {
   light: { odd: "#ffffff", even: "#f1f1ff", label: "#333333" },
@@ -1070,12 +1091,12 @@ var scorePair = (kind, d, fg, bg) => {
   };
 };
 var message = (err) => err instanceof Error ? err.message : String(err);
-var scoreEdgeLabel = (d, pairs, skipped) => {
+var scoreEdgeLabel = (d, canvas, pairs, skipped) => {
   const { color } = d.properties;
   if (!color)
     return;
   try {
-    pairs.push(...THEMES.map((t) => scoreHostPair("text", d, t, color, edgeLabelBackground(t))));
+    pairs.push(...THEMES.map((t) => scoreHostPair("text", d, t, color, edgeLabelBackground(t, canvas))));
   } catch (err) {
     skipped.push({
       selector: d.selector,
@@ -1085,12 +1106,12 @@ var scoreEdgeLabel = (d, pairs, skipped) => {
     });
   }
 };
-var scoreGithub = (directives) => {
+var scoreGithub = (directives, canvas = GITHUB_CANVAS) => {
   const pairs = [];
   const skipped = [];
   for (const d of directives) {
     if (d.kind === "linkStyle")
-      scoreEdgeLabel(d, pairs, skipped);
+      scoreEdgeLabel(d, canvas, pairs, skipped);
     if (d.kind !== "classDef" && d.kind !== "style")
       continue;
     const { fill, color, stroke } = d.properties;
@@ -1112,7 +1133,7 @@ var scoreGithub = (directives) => {
       note("fill is fully transparent, so there is no box to anchor contrast");
       continue;
     }
-    const boxes = alpha < 1 ? THEMES.map((t) => [compositeOver(fill, GITHUB[t].bg), t]) : [[fill, undefined]];
+    const boxes = alpha < 1 ? THEMES.map((t) => [compositeOver(fill, canvas[t]), t]) : [[fill, undefined]];
     if (!color) {
       note("no color: declared beside fill:, and the github profile requires one " + "(if the host forces label text, use the mkdocs-material profile)", true);
     }
@@ -1245,11 +1266,144 @@ var scoreEr = (directives) => {
   }
   return { pairs, skipped };
 };
-var scoreForProfile = (directives, profile, keyword) => {
+var scoreForProfile = (directives, profile, keyword, canvas = GITHUB_CANVAS) => {
   if (profile === "mkdocs-material")
     return scoreMkdocs(directives);
-  return keyword === "erDiagram" ? scoreEr(directives) : scoreGithub(directives);
+  return keyword === "erDiagram" ? scoreEr(directives) : scoreGithub(directives, canvas);
+};
+var SEQUENCE_THEMES = ["base", "default", "dark", "forest", "neutral"];
+var LINE = { NOTE: 2, ACTIVE_START: 17, RECT_START: 22, AUTONUMBER: 26 };
+var FRAME_STARTS = new Set([10, 12, 15, 19, 27, 30, 32]);
+var sequenceFeatures = (db) => {
+  const messages = db.getMessages();
+  const has = (type) => messages.some((m) => m.type === type);
+  return {
+    humanActor: [...db.getActors().values()].some((a) => a.type === "actor"),
+    note: has(LINE.NOTE),
+    frame: messages.some((m) => FRAME_STARTS.has(m.type)),
+    activation: has(LINE.ACTIVE_START),
+    numbered: messages.some((m) => m.type === LINE.AUTONUMBER && m.message?.visible !== false),
+    rects: messages.filter((m) => m.type === LINE.RECT_START).map((m) => String(m.message))
+  };
 };
+var resolveVariables = (mermaid, config, themes) => {
+  const prior = mermaid.mermaidAPI.getSiteConfig();
+  try {
+    const out = {};
+    for (const t of THEMES) {
+      mermaid.initialize({ ...structuredClone(config), theme: themes[t] });
+      out[t] = { ...mermaid.mermaidAPI.getSiteConfig().themeVariables };
+    }
+    return out;
+  } finally {
+    mermaid.initialize(prior);
+  }
+};
+var themeVariable = (selector, line) => ({
+  kind: "themeVariables",
+  selector,
+  properties: {},
+  spans: {},
+  line
+});
+var scoreSequence = async (source, profile, canvas = GITHUB_CANVAS) => {
+  const pairs = [];
+  const skipped = [];
+  const lines = source.split(`
+`);
+  const keywordLine = lines.findIndex((l) => /^\s*sequenceDiagram\b/.test(l)) + 1;
+  const lineOf = (key) => {
+    const found = lines.findLastIndex((l) => new RegExp(`\\b${key}["']?\\s*:`).test(l));
+    return found < 0 ? keywordLine : found + 1;
+  };
+  const rectLines = lines.flatMap((l, i) => /^\s*rect\s/.test(l) ? [i + 1] : []);
+  const mermaid = await getMermaidCore();
+  let config;
+  let db;
+  try {
+    config = (await mermaid.parse(source)).config;
+    db = (await mermaid.mermaidAPI.getDiagramFromText(source)).db;
+  } catch {
+    return { pairs, skipped };
+  }
+  const block = (selector, reason) => {
+    skipped.push({ selector, line: lineOf(selector), reason, blocking: true });
+    return { pairs, skipped };
+  };
+  if (config.themeCSS !== undefined)
+    return block("themeCSS", "themeCSS restyles the diagram with CSS the audit cannot model");
+  const pinned = config.theme;
+  if (pinned !== undefined && !SEQUENCE_THEMES.includes(String(pinned))) {
+    return block("theme", `the ${String(pinned)} theme is not modelled, only ${SEQUENCE_THEMES.join(", ")}`);
+  }
+  const features = sequenceFeatures(db);
+  const host = profile === "mkdocs-material";
+  const theme = (fallback) => pinned === undefined ? fallback : String(pinned);
+  let variables;
+  try {
+    variables = resolveVariables(mermaid, config, { light: theme("default"), dark: theme(host ? "default" : "dark") });
+  } catch (err) {
+    return block("themeVariables", `Mermaid could not resolve the theme: ${message(err)}`);
+  }
+  for (const t of THEMES) {
+    const page = host ? MKDOCS_MATERIAL[t].bg : canvas[t];
+    const vars = variables[t];
+    const color = (key) => {
+      const value = vars[key];
+      if (typeof value !== "string")
+        throw new Error(`${key} is not a resolved colour`);
+      return value;
+    };
+    const pair = (kind, fgKey, bg, suffix = "", at) => {
+      const selector = fgKey + suffix;
+      const line = at ?? lineOf(fgKey);
+      try {
+        const box = compositeOver("key" in bg ? color(bg.key) : bg.colour, page);
+        pairs.push({ ...scoreHostPair(kind, themeVariable(selector, line), t, color(fgKey), box), advisory: host });
+      } catch (err) {
+        skipped.push({ selector, line, reason: `${t} sequence pair unparseable: ${message(err)}`, blocking: true });
+      }
+    };
+    const onPage = { colour: page };
+    if (host) {
+      pair("border", "actorLineColor", onPage);
+      pair("border", "signalColor", onPage, " (arrowhead)");
+      if (features.activation)
+        pair("border", "activationBorderColor", { key: "activationBkgColor" });
+      continue;
+    }
+    pair("text", "actorTextColor", { key: "actorBkg" });
+    pair("border", "actorBorder", { key: "actorBkg" });
+    if (features.humanActor) {
+      pair("text", "actorTextColor", onPage, " (human actor label)");
+      pair("border", "actorBorder", onPage, " (human actor glyph)");
+    }
+    pair("border", "actorLineColor", onPage);
+    pair("text", "signalTextColor", onPage);
+    pair("border", "signalColor", onPage);
+    if (features.note)
+      pair("text", "noteTextColor", { key: "noteBkgColor" });
+    if (features.frame) {
+      pair("text", "labelTextColor", { key: "labelBoxBkgColor" });
+      pair("text", "loopTextColor", onPage);
+      pair("border", "labelBoxBorderColor", onPage, " (loop frame)");
+    }
+    if (features.activation)
+      pair("border", "activationBorderColor", { key: "activationBkgColor" });
+    if (features.numbered)
+      pair("text", "sequenceNumberColor", { key: "signalColor" });
+    for (const [i, rect] of features.rects.entries()) {
+      const fill = { colour: rect };
+      const at = rectLines[i];
+      pair("text", "signalTextColor", fill, " (rect)", at);
+      pair("border", "signalColor", fill, " (rect)", at);
+      if (features.frame)
+        pair("text", "loopTextColor", fill, " (rect)", at);
+    }
+  }
+  return { pairs, skipped };
+};
+var scoreDiagram = (source, directives, profile, keyword, canvas = GITHUB_CANVAS) => keyword === "sequenceDiagram" ? scoreSequence(source, profile, canvas) : Promise.resolve(scoreForProfile(directives, profile, keyword, canvas));
 var detectProfile = (filePath) => {
   let dir = dirname(resolve(filePath));
   for (let i = 0;i < 20; i++) {
@@ -1413,7 +1567,7 @@ var COMPLEXITY_OPTIONS = {
   subgraphWeight: "number",
   depthWeight: "number"
 };
-var CONTRAST_OPTIONS = { profile: "string" };
+var CONTRAST_OPTIONS = { profile: "string", canvas: "canvas" };
 var measure = async (diagram, config) => {
   const stats = await diagram.stats();
   if (parseFailed(diagram.source, stats))
@@ -1443,17 +1597,35 @@ var profileOf = (ctx) => {
   }
   return wanted === "auto" ? detectProfile(ctx.file) : wanted;
 };
-var scored = new WeakMap;
-var contrastOf = (diagram, profile) => {
-  let byProfile = scored.get(diagram);
-  if (!byProfile) {
-    byProfile = new Map;
-    scored.set(diagram, byProfile);
+var settingsOf = (ctx) => {
+  const profile = profileOf(ctx);
+  const setting = ctx.options.canvas;
+  if (setting === undefined)
+    return { profile, canvas: GITHUB_CANVAS };
+  for (const side of THEMES) {
+    if (!(side in setting))
+      continue;
+    const problem = canvasColourProblem(setting[side]);
+    if (problem)
+      throw new Error(`canvas.${side} ${problem}: ${JSON.stringify(setting[side])}`);
   }
-  let result = byProfile.get(profile);
+  if (profile === "mkdocs-material")
+    throw new CanvasProfileError(ctx.file);
+  return { profile, canvas: resolveCanvas(setting) };
+};
+var scored = new WeakMap;
+var contrastOf = (diagram, settings) => {
+  const { profile, canvas } = settings;
+  const key = `${profile}\x00${canvas.light}\x00${canvas.dark}`;
+  let bySettings = scored.get(diagram);
+  if (!bySettings) {
+    bySettings = new Map;
+    scored.set(diagram, bySettings);
+  }
+  let result = bySettings.get(key);
   if (!result) {
-    result = scoreForProfile(diagram.directives, profile, diagram.keyword);
-    byProfile.set(profile, result);
+    result = scoreDiagram(diagram.source, diagram.directives, profile, diagram.keyword, canvas);
+    bySettings.set(key, result);
   }
   return result;
 };
@@ -1565,11 +1737,11 @@ var contrastBorderBelowUiMinimum = {
   category: "contrast",
   summary: "a border below 3:1 against its fill",
   options: CONTRAST_OPTIONS,
-  check: (ctx) => {
-    const profile = profileOf(ctx);
+  check: async (ctx) => {
+    const settings = settingsOf(ctx);
     const found = [];
     for (const diagram of ctx.doc.diagrams) {
-      for (const p of contrastOf(diagram, profile).pairs) {
+      for (const p of (await contrastOf(diagram, settings)).pairs) {
         if (p.kind !== "border" || p.passes || p.advisory)
           continue;
         const line = fileLine(diagram, p.line);
@@ -1579,7 +1751,7 @@ var contrastBorderBelowUiMinimum = {
           endLine: line,
           rule: RULE.BORDER,
           message: `${p.directive.kind} ${p.selector}: border ${p.assessment.ratio.toFixed(2)}:1 < ${AA_NON_TEXT2} ` + `(${p.foreground} on ${p.background}${p.theme ? `, ${p.theme}` : ""})`,
-          remediation: "Darken the stroke or lighten the fill until the ratio reaches 3:1."
+          remediation: p.directive.kind === "themeVariables" ? "Set the theme variable to a colour that reaches 3:1 on its background in both themes, or remove it and let the theme set it." : "Darken the stroke or lighten the fill until the ratio reaches 3:1."
         });
       }
     }
@@ -1593,11 +1765,11 @@ var contrastDirectiveUnauditable = {
   category: "contrast",
   summary: "a style directive whose contrast cannot be audited",
   options: CONTRAST_OPTIONS,
-  check: (ctx) => {
-    const profile = profileOf(ctx);
+  check: async (ctx) => {
+    const settings = settingsOf(ctx);
     const found = [];
     for (const diagram of ctx.doc.diagrams) {
-      for (const s of contrastOf(diagram, profile).skipped) {
+      for (const s of (await contrastOf(diagram, settings)).skipped) {
         if (!s.blocking)
           continue;
         const line = fileLine(diagram, s.line);
@@ -1607,7 +1779,7 @@ var contrastDirectiveUnauditable = {
           endLine: line,
           rule: RULE.UNAUDITABLE,
           message: `${s.selector}: unaudited, ${s.reason}`,
-          remediation: "Declare the missing property or fix the colour so the pair can be scored."
+          remediation: "Declare the missing property, fix the colour, or remove the config the audit cannot model, so the pair can be scored."
         });
       }
     }
@@ -1624,11 +1796,11 @@ var contrastTextBelowAa = {
   category: "contrast",
   summary: "label text below 4.5:1 against its fill",
   options: CONTRAST_OPTIONS,
-  check: (ctx) => {
-    const profile = profileOf(ctx);
+  check: async (ctx) => {
+    const settings = settingsOf(ctx);
     const found = [];
     for (const diagram of ctx.doc.diagrams) {
-      for (const p of contrastOf(diagram, profile).pairs) {
+      for (const p of (await contrastOf(diagram, settings)).pairs) {
         if (p.kind !== "text" || p.passes)
           continue;
         const where = [p.theme, p.row].filter(Boolean).join("/");
@@ -1639,19 +1811,19 @@ var contrastTextBelowAa = {
           endLine: line,
           rule: RULE.TEXT,
           message: `${p.directive.kind} ${p.selector}: text ${p.assessment.ratio.toFixed(2)}:1 < ${AA_NORMAL2} ` + `(${p.foreground} on ${p.background}${where ? `, ${where}` : ""})`,
-          remediation: profile === "mkdocs-material" ? "The host theme forces the label text, so change the fill until the host text reads on it in both themes." : p.directive.kind === "linkStyle" ? "An edge label sits on Mermaid's own label box, light in one theme and grey in the other, and no one colour reads on both, so drop color: from the linkStyle and let the theme set the label text." : "Darken or lighten the fill, or change color:, until the ratio reaches 4.5:1 in every theme."
+          remediation: settings.profile === "mkdocs-material" ? "The host theme forces the label text, so change the fill until the host text reads on it in both themes." : p.directive.kind === "themeVariables" ? "A sequence diagram colour is a theme variable, and text with no box of its own sits on the page, so set the variable to a colour that reads on its background in both themes, or remove it and let the theme set it." : p.directive.kind === "linkStyle" ? "An edge label sits on Mermaid's own label box, light in one theme and grey in the other, and no one colour reads on both, so drop color: from the linkStyle and let the theme set the label text." : "Darken or lighten the fill, or change color:, until the ratio reaches 4.5:1 in every theme."
         });
       }
     }
     return found;
   },
-  fix: (ctx) => {
-    const profile = profileOf(ctx);
-    if (profile === "mkdocs-material")
+  fix: async (ctx) => {
+    const settings = settingsOf(ctx);
+    if (settings.profile === "mkdocs-material")
       return [];
     const edits = [];
     for (const diagram of ctx.doc.diagrams) {
-      const { pairs } = contrastOf(diagram, profile);
+      const { pairs } = await contrastOf(diagram, settings);
       const failing = new Set(pairs.filter((p) => p.kind === "text" && !p.passes).map((p) => p.directive));
       for (const directive of failing) {
         const span = directive.spans.color;
@@ -1771,8 +1943,27 @@ var typeOf = (value) => {
     return "boolean";
   if (Array.isArray(value) && value.every((v) => typeof v === "string"))
     return "string[]";
+  if (isCanvasShape(value))
+    return "canvas";
   return null;
 };
+var isCanvasShape = (value) => {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    return false;
+  const keys = Object.keys(value);
+  return keys.length > 0 && keys.every((k) => THEMES.includes(k));
+};
+var describeType = (want) => want === "canvas" ? 'an object such as { "light": "#ffffff", "dark": "#0d1117" }' : `a ${want}`;
+var checkCanvas = (where, rule, name, value) => {
+  for (const side of THEMES) {
+    if (!(side in value))
+      continue;
+    const problem = canvasColourProblem(value[side]);
+    if (problem) {
+      throw new RuleOptionError(where, rule.id, name, `option "${name}.${side}" of "${rule.id}" ${problem}: ${JSON.stringify(value[side])}`);
+    }
+  }
+};
 var checkOptions = (where, rule, options) => {
   const accepted = Object.keys(rule.options ?? {});
   for (const [name, value] of Object.entries(options)) {
@@ -1782,8 +1973,13 @@ var checkOptions = (where, rule, options) => {
       throw new RuleOptionError(where, rule.id, name, `rule "${rule.id}" has no option "${name}"; ${list}`);
     }
     if (typeOf(value) !== want) {
-      throw new RuleOptionError(where, rule.id, name, `option "${name}" of "${rule.id}" must be a ${want}`);
+      throw new RuleOptionError(where, rule.id, name, `option "${name}" of "${rule.id}" must be ${describeType(want)}`);
     }
+    if (want === "canvas")
+      checkCanvas(where, rule, name, value);
+  }
+  if (options.profile === "mkdocs-material" && options.canvas !== undefined && rule.options?.canvas === "canvas") {
+    throw new RuleOptionError(where, rule.id, "canvas", `option "canvas" of "${rule.id}" applies under the github profile only, and this rule sets profile mkdocs-material, whose page is Material's own`);
   }
   if (typeof options.preset === "string" && canonicalPreset(options.preset) === null) {
     throw new RuleOptionError(where, rule.id, "preset", `option "preset" of "${rule.id}" is not a known preset`);
@@ -1827,8 +2023,24 @@ var buildRegistry = (input) => {
 var BUILTIN = buildRegistry({ rules: RULES, fixOrder: FIX_ORDER, categories: BUILTIN_CATEGORIES });
 
 // src/check.ts
+var canvasName = (side, prefix) => prefix ? `${prefix}canvas-${side}` : `canvas.${side}`;
 var checkRunFlags = (flags, prefix = "") => {
-  const { preset, profile } = flags;
+  const { preset, profile, canvas } = flags;
+  for (const side of THEMES) {
+    if (canvas?.[side] === undefined)
+      continue;
+    const problem = canvasColourProblem(canvas[side]);
+    if (problem) {
+      const name = canvasName(side, prefix);
+      throw new FlagError(name, `${name} ${problem}: "${canvas[side]}"; give an opaque CSS colour, such as #ffffff`);
+    }
+  }
+  const sides = THEMES.filter((side) => canvas?.[side] !== undefined);
+  const first = sides[0];
+  if (profile === "mkdocs-material" && first !== undefined) {
+    const name = canvasName(first, prefix);
+    throw new FlagError(name, `${name} applies under the github profile only; mkdocs-material scores Material's own page colours`);
+  }
   if (preset !== undefined && canonicalPreset(preset) === null) {
     throw new FlagError(`${prefix}preset`, `${prefix}preset must be one of ${PRESET_NAMES.join(", ")}, not "${preset}"`);
   }
@@ -1845,6 +2057,17 @@ var optionsFor = (rule, configured, flags) => {
   }
   if (typeof options.preset === "string")
     options.preset = canonicalPreset(options.preset) ?? options.preset;
+  const canvas = flags.canvas;
+  if (canvas && THEMES.some((side) => canvas[side] !== undefined) && rule.options?.canvas === "canvas") {
+    const configured2 = typeof options.canvas === "object" && options.canvas !== null ? options.canvas : {};
+    const merged = { ...configured2 };
+    for (const side of THEMES) {
+      const value = canvas[side];
+      if (value !== undefined)
+        merged[side] = value;
+    }
+    options.canvas = merged;
+  }
   return options;
 };
 var checkModel = async (doc, file, flags = {}, registry = BUILTIN) => {
@@ -2269,7 +2492,7 @@ var RULE_KEY = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 
 // src/plugins/runtime.ts
 var canImportTypeScript = (runtime = process) => typeof runtime.versions.bun === "string" || Boolean(runtime.features.typescript);
-var TYPESCRIPT_HELP = "TypeScript cannot be imported by this runtime. Run with Bun (bunx --bun @jpeakai/mermaidjs-lint), use Node 22.18 or newer, or write a .js or .mjs file";
+var TYPESCRIPT_HELP = "TypeScript cannot be imported by this runtime. Run with Bun (bunx --bun @jpeakai/mermaidjs-lint), use Node 22.18 or newer (23.6 or newer on Node 23), or write a .js or .mjs file";
 
 // src/plugins/load.ts
 var isRecord3 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
@@ -2291,7 +2514,7 @@ var importModule = async (source, runtime) => {
     throw new PluginImportError(source.spec, message2(err));
   }
 };
-var OPTION_TYPES = new Set(["number", "string", "boolean", "string[]"]);
+var OPTION_TYPES = new Set(["number", "string", "boolean", "string[]", "canvas"]);
 var RESERVED_OPTIONS = ["preset", "profile"];
 var checkRule = (spec, key, raw, own) => {
   const where = `rule "${key}"`;
@@ -2320,7 +2543,7 @@ var checkRule = (spec, key, raw, own) => {
   if (options !== undefined) {
     const valid = isRecord3(options) && Object.values(options).every((t) => OPTION_TYPES.has(t));
     if (!valid) {
-      throw new PluginContractError(spec, `${where} options must map names to number, string, boolean or string[]`);
+      throw new PluginContractError(spec, `${where} options must map names to number, string, boolean, string[] or canvas`);
     }
     for (const name of RESERVED_OPTIONS) {
       if (name in options && options[name] !== "string") {
@@ -2587,7 +2810,7 @@ var setUp = async ({
 
 // src/cli.ts
 var SYNOPSIS = `usage: mermaidjs-lint <path...> [--fix] [--json] [--preset NAME] [--profile NAME] [--config FILE]
-                     [--no-plugins | --lenient-plugins]
+                     [--canvas-light COLOUR] [--canvas-dark COLOUR] [--no-plugins | --lenient-plugins]
        mermaidjs-lint --list-rules
        mermaidjs-lint --validate-plugins [--json] [--config FILE]
        mermaidjs-lint --version | -h, --help`;
@@ -2613,6 +2836,10 @@ Examples of every rule, with fixes: https://jpeakai.github.io/jpai-mermaidjs-lin
   numeric threshold set in the config overrides both.
 --profile NAME sets how contrast is read: ${PROFILES.join(", ")}. It overrides a profile set in the config.
   auto reads mkdocs-material when any parent folder holds mkdocs.yml or mkdocs.yaml, else github.
+--canvas-light COLOUR and --canvas-dark COLOUR set the page a host draws in each theme, under the github
+  profile only. A translucent fill, an edge label box and a sequence diagram's page-backed text are scored
+  on it. Each is an opaque CSS colour such as #faf8f9, and a side not given keeps the config's, or GitHub's
+  (#ffffff light, #0d1117 dark). A file scored under mkdocs-material refuses a canvas with a usage error.
 --json prints one JSON object instead of text lines.
 --fix applies every fix it can prove safe, then reports what remains.
 A fixer that is unsure leaves the text alone and the finding stays.
@@ -2636,6 +2863,8 @@ var parse2 = (argv) => parseArgs({
     help: { type: "boolean", short: "h", default: false },
     preset: { type: "string", short: "p" },
     profile: { type: "string" },
+    "canvas-light": { type: "string" },
+    "canvas-dark": { type: "string" },
     config: { type: "string" },
     "no-plugins": { type: "boolean", default: false },
     "lenient-plugins": { type: "boolean", default: false },
@@ -2741,7 +2970,16 @@ var run = async (argv, cwd) => {
   }
   const listing = values["list-rules"];
   const validating = values["validate-plugins"];
-  checkRunFlags({ preset: values.preset, profile: values.profile }, "--");
+  const canvas = {
+    ...values["canvas-light"] !== undefined && { light: values["canvas-light"] },
+    ...values["canvas-dark"] !== undefined && { dark: values["canvas-dark"] }
+  };
+  const flags = {
+    preset: values.preset,
+    profile: values.profile,
+    ...Object.keys(canvas).length > 0 && { canvas }
+  };
+  checkRunFlags(flags, "--");
   if (values["no-plugins"] && values["lenient-plugins"]) {
     throw new FlagError("--lenient-plugins", "--no-plugins and --lenient-plugins contradict each other");
   }
@@ -2787,7 +3025,6 @@ var run = async (argv, cwd) => {
     throw new FlagError("files", "no matching files");
   if (values.fix)
     await refuseOutsideLinks(files, root, cwd);
-  const flags = { preset: values.preset, profile: values.profile };
   const perFile = await Promise.all(files.map(async (file) => {
     let src = await readFile3(file, "utf8");
     if (values.fix) {