@jpeakai/mermaidjs-lint 0.4.2 → 0.6.0

package/src/check.ts

@@ -6,7 +6,7 @@
 
 import { FlagError } from "./errors.ts";
 import { buildDocModel, type DocModel, documentKind } from "./model.ts";
-import { PROFILES } from "./parse/contrast.ts";
+import { type CanvasSetting, canvasColourProblem, PROFILES, THEMES, type Theme } from "./parse/contrast.ts";
 import { canonicalPreset, PRESET_NAMES } from "./parse/metrics.ts";
 import { BUILTIN, HELPERS, type Registry } from "./rules/registry.ts";
 import type { Finding, Rule, RuleOptions } from "./rules/types.ts";
@@ -16,13 +16,36 @@ import type { Finding, Rule, RuleOptions } from "./rules/types.ts";
 export interface RunFlags {
   preset?: string;
   profile?: string;
+  // The page canvas under the github profile, either side or both. A side
+  // left out keeps the configured canvas, or GitHub's.
+  canvas?: CanvasSetting;
 }
 
-// A preset or profile that no rule can take fails as a usage error, with the
-// code the command gives a bad flag, so a library caller can branch on it. The
-// command passes "--" as the prefix, so the message names its own flag.
+// The name a canvas side goes by: the command's flag, or the RunFlags field.
+const canvasName = (side: Theme, prefix: string): string => (prefix ? `${prefix}canvas-${side}` : `canvas.${side}`);
+
+// A preset, profile or canvas that no rule can take fails as a usage error,
+// with the code the command gives a bad flag, so a library caller can branch on
+// it. The command passes "--" as the prefix, so the message names its own flag.
 export const checkRunFlags = (flags: RunFlags, prefix = ""): void => {
-  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`,
@@ -44,6 +67,18 @@ export const optionsFor = (rule: Rule, configured: RuleOptions | undefined, flag
     if (value !== undefined && rule.options?.[name]) options[name] = value;
   }
   if (typeof options.preset === "string") options.preset = canonicalPreset(options.preset) ?? options.preset;
+  // A canvas flag sets one side over the configured canvas, so --canvas-dark
+  // alone keeps a configured light side.
+  const canvas = flags.canvas;
+  if (canvas && THEMES.some((side) => canvas[side] !== undefined) && rule.options?.canvas === "canvas") {
+    const configured = typeof options.canvas === "object" && options.canvas !== null ? options.canvas : {};
+    const merged: Record<string, string> = { ...(configured as Record<string, string>) };
+    for (const side of THEMES) {
+      const value = canvas[side];
+      if (value !== undefined) merged[side] = value;
+    }
+    options.canvas = merged;
+  }
   return options;
 };
 

package/src/cli.ts

@@ -21,7 +21,7 @@ import { CATEGORIES, type Finding, type Rule } from "./rules/types.ts";
 // The invocation forms, printed alone after a usage error so the error is not
 // buried, and first in --help.
 const 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`;
@@ -52,6 +52,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.
@@ -75,6 +79,8 @@ interface Parsed {
     help?: boolean;
     preset?: string;
     profile?: string;
+    "canvas-light"?: string;
+    "canvas-dark"?: string;
     config?: string;
     "no-plugins"?: boolean;
     "lenient-plugins"?: boolean;
@@ -94,6 +100,8 @@ const parse = (argv: string[]): Parsed =>
       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 },
@@ -221,7 +229,16 @@ const run = async (argv: string[], cwd: string): Promise<number> => {
   }
   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: RunFlags = {
+    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");
   }
@@ -268,7 +285,6 @@ const run = async (argv: string[], cwd: string): Promise<number> => {
   // rule that reads the path sees one form, and the auto profile is found
   // from the file's own folder whatever the process's working directory. The
   // report shows the path relative to cwd.
-  const flags: RunFlags = { preset: values.preset, profile: values.profile };
   const perFile = await Promise.all(
     files.map(async (file) => {
       let src = await readFile(file, "utf8");

package/src/errors.ts

@@ -130,6 +130,21 @@ export class RuleOptionError extends UsageError {
   }
 }
 
+// A canvas was set for a file scored under mkdocs-material, whose page is
+// Material's own, so the canvas would change nothing. Ignoring it would report
+// a pass the caller did not ask for, so the run stops instead.
+export class CanvasProfileError extends UsageError {
+  readonly file: string;
+
+  constructor(file: string) {
+    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;
+  }
+}
+
 // --fix would write through a symbolic link whose target sits outside the
 // project root, so the run stops before any file is written.
 export class FixOutsideRootError extends UsageError {

package/src/index.ts

@@ -8,6 +8,7 @@ export { type Collected, collectFiles } from "./files.ts";
 export { type FixReport, fixSource, fixSourceReport } from "./fix/engine.ts";
 export { buildDocModel, DIAGRAM_EXTS, type Diagram, type DocModel, documentKind } from "./model.ts";
 export type { ContrastAssessment, StyleDirective, ValueSpan } from "./parse/color.ts";
+export { type Canvas, type CanvasSetting, GITHUB_CANVAS } from "./parse/contrast.ts";
 export { PRESETS, type Preset, type ThresholdConfig, thresholdsFrom } from "./parse/metrics.ts";
 export { type DiagramStats, detectKeyword, extractStats } from "./parse/stats.ts";
 export type { Plugin, PluginEdit, PluginFinding, PluginMeta, PluginRule } from "./plugins/contract.ts";

package/src/parse/contrast.ts

@@ -8,7 +8,9 @@
 // color: is edge label text, scored on Mermaid's own label box under github.
 //
 // Profiles, by who controls the label text:
-//   github           the author does, so the declared pairs are scored as written
+//   github           the author does, so the declared pairs are scored as written,
+//                    and anything page-backed is scored on GitHub's canvas or
+//                    on the canvas the caller sets for its own host
 //   mkdocs-material  the host theme forces the text and ignores color:, so each
 //                    fill is composited over both theme backgrounds and the
 //                    host text is scored in light and dark
@@ -16,6 +18,7 @@
 import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { alphaOf, type ContrastAssessment, compositeOver, type StyleDirective, wcagAssess } from "./color.ts";
+import { getMermaidCore, type MermaidCore } from "./stats.ts";
 
 export type Profile = "github" | "mkdocs-material";
 export type Theme = "light" | "dark";
@@ -30,12 +33,38 @@ const MKDOCS_MATERIAL = {
   dark: { bg: "#1e2129", text: "hsl(225 18% 86% / 0.82)" },
 } as const;
 
-// GitHub's page canvas, which a translucent fill composites against. The dark
-// value is measured from a rendered diagram: the Mermaid container paints no
-// surface of its own, so the canvas is the true backdrop.
-const GITHUB = { light: { bg: "#ffffff" }, dark: { bg: "#0d1117" } } as const;
+// The page canvas in each theme: the colour behind everything the diagram does
+// not box. A translucent fill composites against it, and page-backed text, such
+// as an edge label's box or a sequence message, is scored on it.
+export type Canvas = Readonly<Record<Theme, string>>;
 
-const THEMES: Theme[] = ["light", "dark"];
+// A canvas as a caller sets it: either side, or both. A side left out keeps
+// GitHub's.
+export type CanvasSetting = Readonly<Partial<Record<Theme, string>>>;
+
+// GitHub's page canvas, the default under the github profile. The dark value is
+// measured from a rendered diagram: the Mermaid container paints no surface of
+// its own, so the canvas is the true backdrop. A host that draws its own page,
+// such as a documentation viewer with its own theme, sets its own canvas.
+export const GITHUB_CANVAS: Canvas = { light: "#ffffff", dark: "#0d1117" };
+
+export const THEMES: readonly Theme[] = ["light", "dark"];
+
+// Why a canvas colour cannot be used, or null when it can. A canvas is a page,
+// so it must be an opaque colour: nothing shows through it to composite onto.
+export const canvasColourProblem = (value: unknown): string | null => {
+  if (typeof value !== "string") return "is not a colour string";
+  let alpha: number;
+  try {
+    alpha = alphaOf(value);
+  } catch {
+    return "is not a CSS colour";
+  }
+  return alpha < 1 ? "is translucent, and a page canvas must be opaque" : null;
+};
+
+// The canvas a setting resolves to, with GitHub's for any side it leaves out.
+export const resolveCanvas = (setting: CanvasSetting | undefined): Canvas => ({ ...GITHUB_CANVAS, ...setting });
 
 // The box an edge label is drawn on, read off Mermaid 11's theme sources. A
 // linkStyle color: becomes an inline `color: ... !important` on the label's
@@ -46,7 +75,7 @@ const THEMES: Theme[] = ["light", "dark"];
 // and lighten(#181818, 25) = #585858 in dark, opaque. GitHub draws the default
 // theme in light mode and the dark theme in dark mode, the same assumption the
 // erDiagram rows make, so the stack is composited over the matching canvas:
-// #e8e8e8 in light and #585858 in dark. No one colour clears 4.5:1 on both, so
+// #e8e8e8 in light and #585858 in dark on GitHub's. No one colour clears 4.5:1 on both, so
 // a fixed edge label colour always fails one theme. Under mkdocs-material the
 // host sets `.edgeLabel p { color: var(--md-mermaid-edge-color) }` on the p
 // itself, which beats the colour the p would inherit, so color: is ignored
@@ -56,9 +85,9 @@ const MERMAID_EDGE_LABEL = {
   dark: { box: "#585858", backing: "rgba(88,88,88,0.5)" },
 } as const;
 
-export const edgeLabelBackground = (theme: Theme): string => {
+export const edgeLabelBackground = (theme: Theme, canvas: Canvas = GITHUB_CANVAS): string => {
   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])));
 };
 
 // Mermaid's own erDiagram row surfaces under its default and dark themes. A
@@ -73,10 +102,14 @@ const MERMAID_ER = {
 const AA_NORMAL = 4.5;
 const AA_NON_TEXT = 3.0;
 
+// What a pair was scored from: a style directive, or, in a sequence diagram,
+// a theme variable, which has no directive and no value span to rewrite.
+export type ContrastSource = StyleDirective | (Omit<StyleDirective, "kind"> & { kind: "themeVariables" });
+
 export interface ContrastPair {
   kind: PairKind;
   selector: string;
-  directive: StyleDirective;
+  directive: ContrastSource;
   foreground: string;
   background: string;
   line: number; // line within the diagram text
@@ -105,7 +138,7 @@ export interface ContrastResult {
   skipped: SkippedDirective[];
 }
 
-const scorePair = (kind: PairKind, d: StyleDirective, fg: string, bg: string): ContrastPair => {
+const scorePair = (kind: PairKind, d: ContrastSource, fg: string, bg: string): ContrastPair => {
   const assessment = wcagAssess(fg, bg);
   return {
     kind,
@@ -123,11 +156,16 @@ const message = (err: unknown): string => (err instanceof Error ? err.message :
 
 // A linkStyle color: is edge label text, scored on the label box in both themes.
 // A linkStyle without one styles only the line, which has no label pair.
-const scoreEdgeLabel = (d: StyleDirective, pairs: ContrastPair[], skipped: SkippedDirective[]): void => {
+const scoreEdgeLabel = (
+  d: StyleDirective,
+  canvas: Canvas,
+  pairs: ContrastPair[],
+  skipped: SkippedDirective[],
+): void => {
   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,
@@ -138,11 +176,11 @@ const scoreEdgeLabel = (d: StyleDirective, pairs: ContrastPair[], skipped: Skipp
   }
 };
 
-export const scoreGithub = (directives: StyleDirective[]): ContrastResult => {
+export const scoreGithub = (directives: StyleDirective[], canvas: Canvas = GITHUB_CANVAS): ContrastResult => {
   const pairs: ContrastPair[] = [];
   const skipped: SkippedDirective[] = [];
   for (const d of directives) {
-    if (d.kind === "linkStyle") scoreEdgeLabel(d, pairs, skipped);
+    if (d.kind === "linkStyle") scoreEdgeLabel(d, canvas, pairs, skipped);
     if (d.kind !== "classDef" && d.kind !== "style") continue;
     const { fill, color, stroke } = d.properties;
     const note = (reason: string, blocking?: boolean): void => {
@@ -165,10 +203,10 @@ export const scoreGithub = (directives: StyleDirective[]): ContrastResult => {
       note("fill is fully transparent, so there is no box to anchor contrast");
       continue;
     }
-    // A translucent fill is scored on both GitHub canvases and the worse result
-    // gates. An opaque fill resolves the same on both and keeps one pair.
+    // A translucent fill is scored on both canvases and the worse result gates.
+    // An opaque fill resolves the same on both and keeps one pair.
     const boxes: Array<[string, Theme | undefined]> =
-      alpha < 1 ? THEMES.map((t): [string, Theme] => [compositeOver(fill, GITHUB[t].bg), t]) : [[fill, undefined]];
+      alpha < 1 ? THEMES.map((t): [string, Theme] => [compositeOver(fill, canvas[t]), t]) : [[fill, undefined]];
     if (!color) {
       note(
         "no color: declared beside fill:, and the github profile requires one " +
@@ -196,7 +234,7 @@ export const scoreGithub = (directives: StyleDirective[]): ContrastResult => {
   return { pairs, skipped };
 };
 
-const scoreHostPair = (kind: PairKind, d: StyleDirective, theme: Theme, fgRaw: string, box: string): ContrastPair => {
+const scoreHostPair = (kind: PairKind, d: ContrastSource, theme: Theme, fgRaw: string, box: string): ContrastPair => {
   // The foreground may itself be translucent, so it composites onto the box.
   const fg = compositeOver(fgRaw, box);
   const assessment = wcagAssess(fg, box);
@@ -311,15 +349,246 @@ export const scoreEr = (directives: StyleDirective[]): ContrastResult => {
   return { pairs, skipped };
 };
 
+// The canvas applies under github only. Material draws its own page, so the
+// rules refuse a canvas under mkdocs-material before scoring (see shared.ts).
+// An erDiagram's rows are Mermaid's own opaque surfaces, so no canvas shows.
 export const scoreForProfile = (
   directives: StyleDirective[],
   profile: Profile,
   keyword: string | null,
+  canvas: Canvas = GITHUB_CANVAS,
 ): ContrastResult => {
   if (profile === "mkdocs-material") return scoreMkdocs(directives);
-  return keyword === "erDiagram" ? scoreEr(directives) : scoreGithub(directives);
+  return keyword === "erDiagram" ? scoreEr(directives) : scoreGithub(directives, canvas);
 };
 
+// ─── Sequence diagrams ───────────────────────────────────────────────────────
+//
+// A sequence diagram has no style directives. Its colours are theme variables:
+// some set in YAML frontmatter or an %%{init}%% directive, the rest derived by
+// Mermaid's own theme calculation. So the config is read with mermaid.parse,
+// which merges both the way the renderer does, and every variable is resolved
+// by Mermaid's theme engine, never by a copy of its palettes. The features a
+// diagram uses (human actors, notes, loops, activations, numbering, rect
+// backgrounds) are read from the parsed sequence DB. The variables changed
+// between Mermaid releases, so package.json pins the exact version.
+//
+// The SVG is transparent: message text, arrows, lifelines and loop text sit on
+// the host page, and themeVariables.background paints nothing behind them.
+//
+// github: the default theme in light and the dark theme in dark, as GitHub
+// draws them, unless the config pins a theme, which then applies to both.
+//
+// mkdocs-material: Material renders with Mermaid's default theme in both of its
+// schemes and appends its own themeCSS, which wins over Mermaid's styles. That
+// CSS sets every sequence label, box, actor, message line, note, loop frame,
+// rect and number from its own --md-mermaid-* variables, so no text pair is
+// the author's. Three surfaces escape it and keep the diagram's variables, as
+// measured in a browser on Material 9.7 with Mermaid 11.17: lifelines
+// (.actor-line beats Material's bare `line`), arrowheads (Material targets
+// #arrowhead, but Mermaid 11 names it <id>-arrowhead) and activation bars.
+// Each is a border, so under this profile, as for every other diagram, it is
+// scored but advisory.
+
+// The themes Mermaid resolves without per-actor colour arrays or a look of its own.
+const SEQUENCE_THEMES = ["base", "default", "dark", "forest", "neutral"];
+
+// The sequence DB's message types, from Mermaid's LINETYPE table.
+const LINE = { NOTE: 2, ACTIVE_START: 17, RECT_START: 22, AUTONUMBER: 26 } as const;
+// loop, alt, opt, par, critical, break and par over each open a frame.
+const FRAME_STARTS = new Set([10, 12, 15, 19, 27, 30, 32]);
+
+interface SequenceDb {
+  getActors: () => Map<string, { type: string }>;
+  getMessages: () => Array<{ type: number; message: unknown }>;
+}
+
+// What a sequence diagram draws that brings its own colour pairs.
+export interface SequenceFeatures {
+  humanActor: boolean;
+  note: boolean;
+  frame: boolean;
+  activation: boolean;
+  numbered: boolean;
+  rects: string[];
+}
+
+export const sequenceFeatures = (db: SequenceDb): SequenceFeatures => {
+  const messages = db.getMessages();
+  const has = (type: number): boolean => 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 as { visible?: boolean } | null)?.visible !== false,
+    ),
+    rects: messages.filter((m) => m.type === LINE.RECT_START).map((m) => String(m.message)),
+  };
+};
+
+type Variables = Record<string, unknown>;
+
+// Mermaid's theme variables for a config in each theme, as its own engine
+// resolves them. The site config is restored inside the same synchronous
+// block, so a parse elsewhere never sees it changed. The site config is read
+// rather than getConfig(), which mixes in the last parsed diagram's directives.
+const resolveVariables = (
+  mermaid: MermaidCore,
+  config: Variables,
+  themes: Record<Theme, string>,
+): Record<Theme, Variables> => {
+  const prior = mermaid.mermaidAPI.getSiteConfig();
+  try {
+    const out = {} as Record<Theme, Variables>;
+    for (const t of THEMES) {
+      mermaid.initialize({ ...structuredClone(config), theme: themes[t] });
+      out[t] = { ...(mermaid.mermaidAPI.getSiteConfig().themeVariables as Variables) };
+    }
+    return out;
+  } finally {
+    mermaid.initialize(prior);
+  }
+};
+
+const themeVariable = (selector: string, line: number): ContrastSource => ({
+  kind: "themeVariables",
+  selector,
+  properties: {},
+  spans: {},
+  line,
+});
+
+export const scoreSequence = async (
+  source: string,
+  profile: Profile,
+  canvas: Canvas = GITHUB_CANVAS,
+): Promise<ContrastResult> => {
+  const pairs: ContrastPair[] = [];
+  const skipped: SkippedDirective[] = [];
+  const lines = source.split("\n");
+  const keywordLine = lines.findIndex((l) => /^\s*sequenceDiagram\b/.test(l)) + 1;
+  // The line that sets a variable, or the keyword line when it is inherited.
+  const lineOf = (key: string): number => {
+    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: Variables;
+  let db: SequenceDb;
+  try {
+    config = (await mermaid.parse(source)).config;
+    db = (await mermaid.mermaidAPI.getDiagramFromText(source)).db as SequenceDb;
+  } catch {
+    // parse-diagram-unparseable reports it. As for complexity, a diagram the
+    // parser cannot read has no colours to trust.
+    return { pairs, skipped };
+  }
+
+  const block = (selector: string, reason: string): ContrastResult => {
+    skipped.push({ selector, line: lineOf(selector), reason, blocking: true });
+    return { pairs, skipped };
+  };
+  // Under mkdocs-material a diagram's themeCSS replaces Material's own, so
+  // neither profile can say what it draws.
+  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: string): string => (pinned === undefined ? fallback : String(pinned));
+  let variables: Record<Theme, Variables>;
+  try {
+    variables = resolveVariables(mermaid, config, { light: theme("default"), dark: theme(host ? "default" : "dark") });
+  } catch (err) {
+    // A colour the theme derives others from, such as actorBorder, fails here.
+    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: string): string => {
+      const value = vars[key];
+      if (typeof value !== "string") throw new Error(`${key} is not a resolved colour`);
+      return value;
+    };
+    // fgKey drawn on a background: a variable, or a colour such as the page.
+    const pair = (
+      kind: PairKind,
+      fgKey: string,
+      bg: { key: string } | { colour: string },
+      suffix = "",
+      at?: number,
+    ) => {
+      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" });
+    // A human actor's name and stick figure sit outside the box fill.
+    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" });
+    // Messages and frame text inside a rect sit on its colour, not the page.
+    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 };
+};
+
+// Scores a diagram by its keyword: a sequence diagram by its theme variables,
+// any other by its style directives.
+export const scoreDiagram = (
+  source: string,
+  directives: StyleDirective[],
+  profile: Profile,
+  keyword: string | null,
+  canvas: Canvas = GITHUB_CANVAS,
+): Promise<ContrastResult> =>
+  keyword === "sequenceDiagram"
+    ? scoreSequence(source, profile, canvas)
+    : Promise.resolve(scoreForProfile(directives, profile, keyword, canvas));
+
 // An ancestor mkdocs.yml or mkdocs.yaml, searched up to 20 levels, means the
 // diagram is read through Material.
 export const detectProfile = (filePath: string): Profile => {

package/src/parse/stats.ts

@@ -32,6 +32,20 @@ const getMermaid = async (): Promise<typeof import("mermaid").default> => {
   return mermaidCore;
 };
 
+// The slice of mermaid core the contrast scorer reads: the config a diagram
+// declares, its parsed DB, and the theme engine. Typed here without mermaid's
+// own types, so the published declarations never need them.
+export interface MermaidCore {
+  parse: (text: string) => Promise<{ config: Record<string, unknown> }>;
+  initialize: (config: Record<string, unknown>) => void;
+  mermaidAPI: {
+    getSiteConfig: () => Record<string, unknown>;
+    getDiagramFromText: (text: string) => Promise<{ db: unknown }>;
+  };
+}
+
+export const getMermaidCore = async (): Promise<MermaidCore> => (await getMermaid()) as unknown as MermaidCore;
+
 export interface DiagramStats {
   nodes: number;
   edges: number;

package/src/plugins/load.ts

@@ -47,7 +47,7 @@ const importModule = async (source: PluginSource, runtime?: RuntimeInfo): Promis
   }
 };
 
-const OPTION_TYPES = new Set<OptionType>(["number", "string", "boolean", "string[]"]);
+const OPTION_TYPES = new Set<OptionType>(["number", "string", "boolean", "string[]", "canvas"]);
 
 // Option names every rule shares with the built-ins. See checkRule.
 const RESERVED_OPTIONS = ["preset", "profile"] as const;
@@ -81,7 +81,10 @@ const checkRule = (spec: string, key: string, raw: unknown, own: ReadonlySet<str
   if (options !== undefined) {
     const valid = isRecord(options) && Object.values(options).every((t) => OPTION_TYPES.has(t as OptionType));
     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`,
+      );
     }
     // preset and profile keep their built-in meaning for every rule: the
     // config checks the value against the built-in names, and --preset and

package/src/plugins/runtime.ts

@@ -1,5 +1,6 @@
 // What the running JavaScript can import. Bun runs TypeScript directly, and Node
-// strips types from 22.18 (earlier with a flag, and not at all before 22.6). A
+// strips types from 22.18 and from 23.6 (earlier with a flag, and not at all
+// before 22.6). A
 // local rule written in TypeScript therefore works under `bunx --bun` or a recent
 // Node, and anywhere else it fails with a message that says how to fix it.
 
@@ -12,4 +13,4 @@ export const canImportTypeScript = (runtime: RuntimeInfo = process as unknown as
   typeof runtime.versions.bun === "string" || Boolean(runtime.features.typescript);
 
 export const 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";
+  "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";