@alfacapital-tech/c4builder 0.9.0-rc.2 → 0.9.0-rc.3

package/dist/core/render/diagrams.js

@@ -13,6 +13,8 @@ import { httpGetBuffer } from "../../util/http.js";
 import { renderD2, foldD2Imports } from "./d2renderer.js";
 // BPMN-бэкенд: пакеты движка грузятся лениво внутри renderBpmn.
 import { renderBpmn, BPMN_CACHE_PACKAGES } from "./bpmnrenderer.js";
+// Mermaid-бэкенд: пакет движка грузится лениво внутри renderMermaid.
+import { renderMermaid, MERMAID_PACKAGE } from "./mermaidrenderer.js";
 import { resolveJava } from "./jre.js";
 // PNG-выход: SVG обоих движков растеризуется resvg (ленивая загрузка внутри модуля).
 import { rasterizeSvgToPng } from "./pngraster.js";
@@ -65,7 +67,7 @@ const runPool = async (tasks, concurrency) => {
     if (firstError !== undefined)
         throw firstError;
 };
-// Версии пакетов движков (D2, BPMN) для чексуммы кэша (апгрейд движка → перерендер).
+// Версии пакетов движков (D2, BPMN, mermaid) для чексуммы кэша (апгрейд движка → перерендер).
 // Читаем package.json лениво и один раз: pure-PlantUML сборки их не трогают.
 const versionCache = new Map();
 const pkgVersion = (name) => {
@@ -100,7 +102,9 @@ export const renderKey = (diagram, options, outFormat) => (diagram.engine === 'd
     ? `d2\0${pkgVersion('@terrastruct/d2')}\0layout=${options.D2_LAYOUT}\0fmt=${outFormat}`
     : diagram.engine === 'bpmn'
         ? `bpmn\0${BPMN_CACHE_PACKAGES.map(pkgVersion).join('\0')}\0fmt=${outFormat}`
-        : `puml\0${VENDORED_JAR.version}\0charset=${options.CHARSET}\0fmt=${outFormat}\0ditaa=${diagram.isDitaa}`) +
+        : diagram.engine === 'mermaid'
+            ? `mermaid\0${pkgVersion(MERMAID_PACKAGE)}\0fmt=${outFormat}`
+            : `puml\0${VENDORED_JAR.version}\0charset=${options.CHARSET}\0fmt=${outFormat}\0ditaa=${diagram.isDitaa}`) +
     `\0font=${fontCacheTag(options)}`;
 export const getMime = (format) => {
     if (format === 'svg')
@@ -279,19 +283,22 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
     // BPMN рендерится в общем окне jsdom главного потока — параллельность ничего не даёт,
     // а последовательная очередь исключает гонки на общем состоянии бандла bpmn-js.
     const bpmnTasks = [];
+    // Mermaid — так же: своё окно jsdom, глобальный конфиг и подмены на время рендера.
+    const mermaidTasks = [];
     const otherTasks = [];
     for (const item of tree) {
         for (const diagram of item.diagrams) {
             // Чексумма = контент диаграммы + свёрнутый граф её зависимостей, чтобы
             // правка включаемого/импортируемого файла инвалидировала кэш: PlantUML —
-            // !include-граф (.iuml и пр.), D2 — граф @/...@-импортов. У BPMN зависимостей нет.
+            // !include-граф (.iuml и пр.), D2 — граф @/...@-импортов. У BPMN и mermaid их нет.
             const body = `${diagram.content || ''}`;
             const entryPath = path.join(item.dir, diagram.dir);
             const isD2 = diagram.engine === 'd2';
             const isBpmn = diagram.engine === 'bpmn';
+            const isMermaid = diagram.engine === 'mermaid';
             const includes = isD2
                 ? foldD2Imports(entryPath, body)
-                : isBpmn
+                : isBpmn || isMermaid
                     ? ''
                     : foldIncludes(body, item.dir, item.dir, new Set());
             const outFormat = diagramOutputFormat(diagram, options);
@@ -340,12 +347,16 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
                 // Для растеризации PlantUML не-ditaa рендерим в svg (не -tpng), затем resvg.
                 let rendered;
                 try {
+                    // Путь для сообщений движка; у блоков в markdown — их страница.
+                    const file = source ?? path.relative(process.cwd(), entryPath).split(path.sep).join('/');
                     if (isD2) {
                         rendered = await renderD2(entryPath, { layout: options.D2_LAYOUT, seed: body });
                     }
                     else if (isBpmn) {
-                        // Путь для сообщений валидации; у виртуальных страниц — их источник.
-                        rendered = await renderBpmn(body, source ?? path.relative(process.cwd(), entryPath).split(path.sep).join('/'));
+                        rendered = await renderBpmn(body, file);
+                    }
+                    else if (isMermaid) {
+                        rendered = await renderMermaid(body, file);
                     }
                     else {
                         // Резолв JRE отложен до первого реального PlantUML-рендера (эта
@@ -380,18 +391,19 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
                     await writeFile(filePath, outFormat === 'png' ? await rasterizeSvgToPng(svg, options.USE_SYSTEM_FONTS) : svg);
                 }
             });
-            (isD2 ? d2Tasks : isBpmn ? bpmnTasks : otherTasks).push(task);
+            (isD2 ? d2Tasks : isBpmn ? bpmnTasks : isMermaid ? mermaidTasks : otherTasks).push(task);
         }
     }
-    // PlantUML-пул, D2- и BPMN-очереди работают независимо (процессы java, WASM-worker,
-    // главный поток) и параллельно друг другу. allSettled — чтобы падение одной очереди не
+    // PlantUML-пул, D2-, BPMN- и mermaid-очереди работают независимо (процессы java,
+    // WASM-worker, главный поток) и параллельно друг другу. allSettled — чтобы падение одной очереди не
     // оставляло другие как floating promise с висящими JVM: все доосушаются, затем бросаем первую
     // ошибку (приоритет — PlantUML-пул, порядок между очередями не значим).
     try {
         const results = await Promise.allSettled([
             runPool(otherTasks, renderConcurrency()),
             runPool(d2Tasks, 1),
-            runPool(bpmnTasks, 1)
+            runPool(bpmnTasks, 1),
+            runPool(mermaidTasks, 1)
         ]);
         const failed = results.find((r) => r.status === 'rejected');
         if (failed && failed.status === 'rejected')

package/dist/core/render/mermaidrenderer.js

@@ -0,0 +1,495 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import crypto from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import vm from 'node:vm';
+import { DEFAULT_FONT_NAME } from "./fonts.js";
+import { getResvg, resvgFontOptions } from "./pngraster.js";
+import { ASCENT, DESCENT, X_HEIGHT, clearTextWidths, textWidth } from "./textmetrics.js";
+// Четвёртый бэкенд рендера: настоящий mermaid (официальная однофайловая сборка
+// @mermaid-js/tiny) в окне jsdom → SVG. Геометрию, которой у jsdom нет (getBBox), считает
+// resvg по вендорному шрифту. Пакет — optionalDependency, грузится лениво при первой
+// mermaid-диаграмме: проекты без mermaid его не трогают (как D2 и BPMN).
+// Версия пакета идёт в ключ кэша (render/diagrams): апгрейд mermaid обязан перерисовать.
+export const MERMAID_PACKAGE = '@mermaid-js/tiny';
+// problems — строка без пути файла (check печатает `✗ <file>: <problem>`), message — с путём.
+export class MermaidError extends Error {
+    problems;
+    constructor(file, problem) {
+        super(`${file}: ${problem}`);
+        this.problems = [problem];
+    }
+}
+// Конфигурация фиксирована (design §4): подписи — SVG <text> (foreignObject resvg не
+// рисует), классический вид без фильтров neo, ширина gantt вместо нулевой ширины контейнера
+// jsdom. Ключи, ломающие офлайн-рендер, закреплены через secure — %%{init}%% и frontmatter
+// их не переопределят; остальное (тема, flowchart.curve…) mermaid применяет сам.
+const CONFIG = {
+    startOnLoad: false,
+    securityLevel: 'strict',
+    look: 'classic',
+    theme: 'default',
+    // Метрики считаются по Nimbus Sans; он метрически совместим с Helvetica/Arial — в
+    // браузере без него SVG показывается ими с теми же размерами.
+    fontFamily: `"${DEFAULT_FONT_NAME}", Helvetica, Arial, sans-serif`,
+    htmlLabels: false,
+    flowchart: { htmlLabels: false },
+    journey: { textPlacement: 'tspan' },
+    gantt: { useWidth: 800 },
+    deterministicIds: true,
+    suppressErrorRendering: true,
+    secure: [
+        'secure',
+        'securityLevel',
+        'startOnLoad',
+        'maxTextSize',
+        'suppressErrorRendering',
+        'maxEdges',
+        'look',
+        'htmlLabels',
+        'fontFamily',
+        'themeCSS'
+    ]
+};
+const SVG_NS = 'http://www.w3.org/2000/svg';
+const FONT_SIZE = 16;
+// Мини-каскад CSS для раскладки текста: getComputedStyle в jsdom не применяет стили mermaid
+// к SVG (отдаёт начальные значения), а от text-anchor, кегля и baseline зависят все размеры.
+const TEXT_PROPS = ['font-size', 'font-weight', 'text-anchor', 'dominant-baseline', 'alignment-baseline'];
+const declarations = (css) => {
+    const out = {};
+    for (const [, name, value] of css.matchAll(/([\w-]+)\s*:\s*([^;]+)/g))
+        if (TEXT_PROPS.includes(name.toLowerCase()))
+            out[name.toLowerCase()] = value.replace(/!important/, '').trim();
+    return out;
+};
+const specificity = (selector) => (selector.match(/#[\w-]+/g)?.length ?? 0) * 10_000 +
+    (selector.match(/\.[\w-]+|\[[^\]]*\]|:(?!:)[\w-]+/g)?.length ?? 0) * 100 +
+    (selector.replace(/#[\w-]+|\.[\w-]+|\[[^\]]*\]|::?[\w-]+(\([^)]*\))?/g, ' ').match(/[a-z][\w-]*/gi)
+        ?.length ?? 0);
+// Правила одного <style>, отсортированные по специфичности и порядку — побеждает последнее
+// совпавшее. Кэш по элементу: mermaid пишет стили диаграммы один раз.
+const rulesMemo = new WeakMap();
+const styleRules = (style) => {
+    let rules = rulesMemo.get(style);
+    if (!rules) {
+        const ranked = [];
+        for (const [, selectors, body] of (style.textContent ?? '').matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
+            const decls = declarations(body);
+            if (!Object.keys(decls).length)
+                continue;
+            for (const selector of selectors.split(/,(?![^(]*\))/))
+                ranked.push({
+                    selector: selector.trim(),
+                    decls,
+                    rank: specificity(selector) * 1e4 + ranked.length
+                });
+        }
+        rules = ranked.sort((a, b) => a.rank - b.rank);
+        rulesMemo.set(style, rules);
+    }
+    return rules;
+};
+// Стили mermaid — прямые дети корневого <svg>; обход всего дерева на каждый замер давал
+// минуту на диаграмму в тысячи узлов.
+const cssRules = (el) => {
+    const svg = el.closest('svg');
+    return svg ? [...svg.children].filter((c) => c.localName === 'style').flatMap(styleRules) : [];
+};
+const matches = (el, selector) => {
+    try {
+        return el.matches(selector);
+    }
+    catch {
+        return false; // селектор, который nwsapi не разбирает, браузерный и здесь не нужен
+    }
+};
+// Значения на время одного замера: getBBox группы раскладывает все её тексты с общими
+// предками. Между замерами mermaid меняет DOM — там кэш не живёт.
+let valueMemo;
+const measure = (fn) => {
+    if (valueMemo)
+        return fn();
+    valueMemo = new Map();
+    try {
+        return fn();
+    }
+    finally {
+        valueMemo = undefined;
+    }
+};
+// Значение у самого элемента: inline style > CSS > атрибут представления.
+const ownValue = (el, name) => {
+    const memo = valueMemo?.get(el);
+    const cached = memo?.get(name);
+    if (cached !== undefined)
+        return cached;
+    let value = declarations(el.getAttribute('style') ?? '')[name] ?? '';
+    if (!value) {
+        for (const rule of cssRules(el))
+            if (rule.decls[name] && matches(el, rule.selector))
+                value = rule.decls[name];
+        value ||= el.getAttribute(name) ?? '';
+    }
+    if (valueMemo)
+        valueMemo.set(el, (memo ?? new Map()).set(name, value));
+    return value;
+};
+const inherited = (el, name) => {
+    for (let e = el; e; e = e.parentElement) {
+        const value = ownValue(e, name);
+        if (value)
+            return value;
+    }
+    return '';
+};
+const fontSize = (el) => {
+    for (let e = el; e; e = e.parentElement) {
+        const value = ownValue(e, 'font-size');
+        const n = Number.parseFloat(value);
+        if (Number.isNaN(n))
+            continue;
+        if (value.endsWith('%'))
+            return (n / 100) * fontSize(e.parentElement);
+        return value.endsWith('em') ? n * fontSize(e.parentElement) : n;
+    }
+    return FONT_SIZE;
+};
+const isBold = (el) => {
+    const weight = inherited(el, 'font-weight');
+    return weight === 'bold' || weight === 'bolder' || Number(weight) >= 600;
+};
+const length = (value, size) => {
+    const n = Number.parseFloat(value ?? '');
+    if (Number.isNaN(n))
+        return 0;
+    return value?.trim().endsWith('em') ? n * size : n;
+};
+const EMPTY = { x: 0, y: 0, width: 0, height: 0 };
+// Округление гасит f32-шум resvg между платформами: из bbox считаются координаты SVG.
+const round2 = (v) => Math.round(v * 100) / 100;
+// Bbox <text>, как у браузера: advance-ширина строк и em-box по ascent/descent шрифта,
+// округлённым до пикселя (так делает Chrome; mermaid центрирует подписи по этой высоте).
+// Строка — фрагмент от элемента с абсолютными x/y (так mermaid раскладывает переносы).
+// ponytail: tspan только с dy без x продолжает строку по x в браузере, здесь — нет; у mermaid
+// таких нет.
+const textBox = (text) => {
+    const lines = [];
+    let x = 0;
+    let y = 0;
+    let line;
+    const walk = (node) => {
+        if (node.nodeType === node.TEXT_NODE) {
+            const el = node.parentElement;
+            const value = (node.nodeValue ?? '').replace(/\s+/g, ' ');
+            if (!el || (!line && !value.trim()))
+                return;
+            if (!line) {
+                line = { x, y, el, runs: [] };
+                lines.push(line);
+            }
+            line.runs.push({ text: value, size: fontSize(el), bold: isBold(el) });
+            return;
+        }
+        if (node.nodeType !== node.ELEMENT_NODE)
+            return;
+        const el = node;
+        const size = fontSize(el);
+        const ax = el.getAttribute('x');
+        const ay = el.getAttribute('y');
+        if (ax !== null)
+            x = length(ax, size);
+        if (ay !== null)
+            y = length(ay, size);
+        x += length(el.getAttribute('dx'), size);
+        y += length(el.getAttribute('dy'), size);
+        if (ax !== null || ay !== null)
+            line = undefined;
+        for (const child of el.childNodes)
+            walk(child);
+    };
+    walk(text);
+    let box;
+    for (const l of lines) {
+        // Пробелы по краям строки браузер схлопывает.
+        const runs = l.runs.map((r, i) => ({
+            ...r,
+            text: i === 0 ? r.text.trimStart() : r.text
+        }));
+        const last = runs[runs.length - 1];
+        last.text = last.text.trimEnd();
+        const width = runs.reduce((sum, r) => sum + textWidth(r.text, r.size, r.bold), 0);
+        if (width <= 0)
+            continue;
+        const size = runs[0].size;
+        const anchor = inherited(l.el, 'text-anchor');
+        const x0 = l.x - (anchor === 'middle' ? width / 2 : anchor === 'end' ? width : 0);
+        const ascent = Math.round(ASCENT * size);
+        const descent = Math.round(DESCENT * size);
+        const baseline = inherited(l.el, 'dominant-baseline') || inherited(l.el, 'alignment-baseline');
+        const shift = baseline === 'central'
+            ? (ascent - descent) / 2
+            : baseline === 'middle'
+                ? (X_HEIGHT * size) / 2
+                : 0;
+        const b = { x0, y0: l.y + shift - ascent, x1: x0 + width, y1: l.y + shift + descent };
+        box = box
+            ? {
+                x0: Math.min(box.x0, b.x0),
+                y0: Math.min(box.y0, b.y0),
+                x1: Math.max(box.x1, b.x1),
+                y1: Math.max(box.y1, b.y1)
+            }
+            : b;
+    }
+    return box
+        ? {
+            x: round2(box.x0),
+            y: round2(box.y0),
+            width: round2(box.x1 - box.x0),
+            height: round2(box.y1 - box.y0)
+        }
+        : EMPTY;
+};
+// Атрибуты оформления, которых нет в getBBox браузера (обводки, маркеры, фильтры);
+// классы и стили mermaid в изолированном поддереве всё равно не применяются.
+const PAINT_ATTRS = /\s(?:fill|stroke|stroke-width|stroke-dasharray|marker-start|marker-mid|marker-end|filter|opacity|fill-opacity|stroke-opacity|style|class)="[^"]*"/g;
+// Bbox поддерева (design §3): тексты заменяются прямоугольниками своей раскладки, остальную
+// геометрию в координатах элемента (без его transform) считает resvg. Тонкая обводка
+// оставляет в bbox и линии без заливки.
+const subtreeBox = (window, el) => {
+    const tag = el.localName;
+    if (tag === 'text' || tag === 'tspan')
+        return textBox(el);
+    const live = [...el.querySelectorAll('text')];
+    const clone = el.cloneNode(true);
+    clone.removeAttribute('transform');
+    for (const [i, t] of [...clone.querySelectorAll('text')].entries()) {
+        const rect = window.document.createElementNS(SVG_NS, 'rect');
+        for (const [k, v] of Object.entries(textBox(live[i])))
+            rect.setAttribute(k, String(v));
+        const transform = t.getAttribute('transform');
+        if (transform)
+            rect.setAttribute('transform', transform);
+        t.replaceWith(rect);
+    }
+    for (const style of clone.querySelectorAll('style'))
+        style.remove();
+    const serializer = new window.XMLSerializer();
+    const inner = (tag === 'svg' ? [...clone.childNodes] : [clone])
+        .map((n) => serializer.serializeToString(n))
+        .join('')
+        .replace(PAINT_ATTRS, '');
+    const { Resvg } = getResvg();
+    const b = new Resvg(`<svg xmlns="${SVG_NS}" fill="black" stroke="black" stroke-width="0.001">${inner}</svg>`, { font: resvgFontOptions(false) }).getBBox();
+    return b ? { x: round2(b.x), y: round2(b.y), width: round2(b.width), height: round2(b.height) } : EMPTY;
+};
+// Полифилы окна: ровно то, что mermaid зовёт при раскладке. getBoundingClientRect нужен pie
+// (ширина легенды); позиция без CTM — mermaid берёт от него только размеры.
+const installPolyfills = (window) => {
+    Object.assign(window.SVGElement.prototype, {
+        getBBox() {
+            return measure(() => subtreeBox(window, this));
+        },
+        getComputedTextLength() {
+            return measure(() => textBox(this).width);
+        },
+        getBoundingClientRect() {
+            const b = measure(() => subtreeBox(window, this));
+            return { ...b, left: b.x, top: b.y, right: b.x + b.width, bottom: b.y + b.height };
+        }
+    });
+    window.structuredClone = structuredClone;
+};
+// Имя пакета переменной: у jsdom нет типов, а import() по литералу потребовал бы их.
+const load = (name) => import(__rewriteRelativeImportExtension(name));
+let enginePromise = null;
+const getEngine = () => {
+    enginePromise ??= (async () => {
+        let JSDOM;
+        let VirtualConsole;
+        let bundle;
+        try {
+            ({ JSDOM, VirtualConsole } = await load('jsdom'));
+            // import.meta.resolve, а не require.resolve: на Node 22 только он проходит через
+            // хуки резолва module.registerHooks (тесты «пакет не установлен»).
+            bundle = readFileSync(new URL(import.meta.resolve(MERMAID_PACKAGE)), 'utf8');
+        }
+        catch (err) {
+            enginePromise = null; // провал импорта не кешируем — даём повторить
+            throw new Error(`Rendering mermaid diagrams requires the optional packages ${MERMAID_PACKAGE} and jsdom.\n` +
+                'Reinstall without --omit=optional: npm i -g @alfacapital-tech/c4builder\n' +
+                `Original error: ${err.message || err}`);
+        }
+        // Консоль окна глушим: mermaid пишет туда отладку, ошибки мы берём из исключений.
+        const dom = new JSDOM('<!DOCTYPE html><html><body></body></html>', {
+            runScripts: 'outside-only',
+            virtualConsole: new VirtualConsole()
+        });
+        installPolyfills(dom.window);
+        // Бандл исполняется в VM-контексте окна: глобальные объекты процесса Node не трогаются.
+        // Не window.eval: бандл в strict-режиме, и его var в strict-eval не попал бы в window.
+        vm.runInContext(bundle, dom.getInternalVMContext());
+        dom.window.mermaid.initialize(CONFIG);
+        return { window: dom.window };
+    })();
+    return enginePromise;
+};
+// Окно jsdom одно на процесс; закрывается после одиночной сборки и в check (как у BPMN),
+// чтобы CLI завершался. Не бросает — иначе затёр бы исходную причину падения.
+export const teardownMermaid = async () => {
+    if (!enginePromise)
+        return;
+    const pending = enginePromise;
+    enginePromise = null;
+    clearTextWidths();
+    try {
+        (await pending).window.close();
+    }
+    catch {
+        // движок не поднялся — закрывать нечего
+    }
+};
+// mulberry32: детерминированная замена Math.random на время рендера.
+const prng = (seed) => {
+    let state = seed;
+    return () => {
+        state = (state + 0x6d2b79f5) | 0;
+        let t = Math.imul(state ^ (state >>> 15), 1 | state);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+};
+// Детерминизм (design §5): Math.random (кривые связей ER и др.) — от seed источника,
+// «сегодня» (маркер текущего дня gantt) — эпоха 0, иначе SVG менялся бы от сборки к сборке.
+// Глобальный конфиг mermaid и подмены на параллельность не рассчитаны: рендеры строго
+// последовательные (очередь mermaid в render/diagrams, check — по файлу).
+const renderSvg = async (window, id, seed, source) => {
+    const { Math: math, Date: RealDate } = window;
+    const random = math.random;
+    math.random = prng(seed);
+    window.Date = new Proxy(RealDate, {
+        construct: (target, args) => Reflect.construct(target, args.length ? args : [0]),
+        get: (target, key) => (key === 'now' ? () => 0 : Reflect.get(target, key))
+    });
+    try {
+        return (await window.mermaid.render(id, source)).svg;
+    }
+    finally {
+        math.random = random;
+        window.Date = RealDate;
+    }
+};
+// Строки источника, которые разбирает mermaid, — по номерам файла: mermaid вырезает
+// frontmatter, директивы %%{…}%%, комментарии %% (вместе с пустыми строками перед ними) и
+// пустые строки в начале, а номера строк в ошибках считает от остатка.
+// ponytail: многострочная директива в середине диаграммы сдвинет номера — такие не встречались.
+const FRONTMATTER = /^-{3}\s*[\n\r](.*?)[\n\r]-{3}\s*[\n\r]+/s;
+const parsedLines = (source) => {
+    const fm = FRONTMATTER.exec(source)?.[0] ?? '';
+    const offset = fm.split('\n').length - 1;
+    const body = source
+        .slice(fm.length)
+        .replace(/%%\{[\s\S]*?\}%%/g, (d) => '\n'.repeat(d.split('\n').length - 1));
+    const kept = [];
+    let blanks = [];
+    for (const [i, line] of body.split(/\r?\n/).entries()) {
+        if (/^\s*%%(?!\{)./.test(line))
+            blanks = [];
+        else if (!line.trim())
+            blanks.push(offset + i + 1);
+        else {
+            if (kept.length)
+                kept.push(...blanks);
+            blanks = [];
+            kept.push(offset + i + 1);
+        }
+    }
+    return kept;
+};
+const UNSUPPORTED = /^(mindmap|architecture[\w-]*)$/;
+const oneLine = (s) => s.replace(/\s*\n\s*/g, '; ').trim();
+// Ошибка движка → `line N: …` с номером строки файла (design §7). Ошибки из окна — объекты
+// другого realm, instanceof Error для них ложен.
+const problemOf = (err, lines, type) => {
+    const raw = String(err?.message ?? err);
+    const toFile = (n) => lines[Number(n) - 1] ?? Number(n);
+    if (/No diagram type detected/.test(raw))
+        return `line ${lines[0] ?? 1}: unknown mermaid diagram type '${type || '(empty)'}'`;
+    // jison: «Parse error on line N:», фрагмент, строка-указатель «---^», ожидаемые токены.
+    const jison = /^Parse error on line (\d+):\n([\s\S]*)$/.exec(raw);
+    if (jison)
+        return `line ${toFile(jison[1])}: ${oneLine(jison[2]
+            .split('\n')
+            .filter((l) => !/^-*\^$/.test(l.trim()))
+            .join('\n'))}`;
+    const at = /\bline (\d+)/.exec(raw);
+    const message = oneLine(raw.replace(/\bline (\d+)/g, (_, n) => `line ${toFile(n)}`));
+    return at ? `line ${toFile(at[1])}: ${message}` : message;
+};
+// Постобработка SVG: id внутри документа — по порядку появления от корня (счётчики mermaid
+// растут между рендерами в одном окне), ссылки url(#…) без кавычек (в кавычках resvg их
+// игнорирует), без фильтров (resvg не рисует узел с невалидным фильтром).
+const finalizeSvg = (svg, root) => {
+    const ids = new Map();
+    for (const [, id] of svg.matchAll(/\sid="([^"]+)"/g))
+        if (id !== root && !ids.has(id))
+            ids.set(id, `${root}-${ids.size}`);
+    const rename = (id) => ids.get(id) ?? id;
+    return svg
+        .replace(/<filter\b[\s\S]*?<\/filter>|<filter\b[^>]*\/>/g, '')
+        .replace(/\sfilter="[^"]*"/g, '')
+        .replace(/(\sid=")([^"]+)"/g, (_, attr, id) => `${attr}${rename(id)}"`)
+        .replace(/url\((['"]?)#([^)'"]+)\1\)/g, (_, _q, id) => `url(#${rename(id)})`)
+        .replace(/(\s(?:xlink:)?href="#)([^"]+)"/g, (_, attr, id) => `${attr}${rename(id)}"`)
+        .replace(/(\saria-(?:labelledby|describedby)=")([^"]+)"/g, (_, attr, list) => `${attr}${list.split(' ').map(rename).join(' ')}"`)
+        .replace(/<style>([\s\S]*?)<\/style>/g, (_, css) => `<style>${resvgCss(css)}</style>`)
+        .replace(/rgba?\(([\d.\s,]+)\)/g, (whole, args) => whole.replace(args, args
+        .split(',')
+        .map((a, i) => (i < 3 ? String(Math.round(Number.parseFloat(a))) : a.trim()))
+        .join(', ')));
+};
+// CSS под resvg: правило со списком селекторов, где хоть один ему непонятен
+// ([id$=…]), выбрасывается целиком — разносим список по правилам. Дробные каналы rgba()
+// resvg не разбирает и красит чёрным — округляем (выше, для всего SVG).
+const resvgCss = (css) => css
+    .replace(/filter:[^;}]*;?/g, '')
+    .replace(/([^{}]+)\{([^{}]*)\}/g, (whole, selectors, body) => {
+    const list = selectors.split(/,(?![^(]*\))/);
+    return list.length > 1 ? list.map((s) => `${s.trim()}{${body}}`).join('') : whole;
+});
+const lineOf = (source, index) => source.slice(0, index).split('\n').length;
+// Полный конвейер одного источника — общий для сборки и `c4builder check`. file — путь для
+// сообщений (у блока в markdown — его страница).
+export const renderMermaid = async (source, file) => {
+    const text = source.replace(/^/, '');
+    const lines = parsedLines(text);
+    const type = /^[\w-]+/.exec(text.split(/\r?\n/)[(lines[0] ?? 1) - 1]?.trim() ?? '')?.[0] ?? '';
+    // tiny-сборка не включает эти типы и KaTeX: без проверки — невнятное «No diagram type
+    // detected» или формула сырым текстом на картинке.
+    if (UNSUPPORTED.test(type))
+        throw new MermaidError(file, `line ${lines[0]}: unsupported mermaid diagram type '${type}'`);
+    const math = /\$\$[\s\S]+?\$\$/.exec(text);
+    if (math)
+        throw new MermaidError(file, `line ${lineOf(text, math.index)}: unsupported mermaid feature 'KaTeX math' ($$...$$)`);
+    const { window } = await getEngine();
+    const hash = crypto.createHash('sha1').update(text).digest('hex');
+    const id = `m${hash.slice(0, 8)}`;
+    let svg;
+    try {
+        svg = await renderSvg(window, id, Number.parseInt(hash.slice(8, 16), 16), text);
+    }
+    catch (err) {
+        throw new MermaidError(file, problemOf(err, lines, type));
+    }
+    // Тип, который игнорирует htmlLabels, дал бы в PNG пустые подписи.
+    if (svg.includes('<foreignObject'))
+        throw new MermaidError(file, `diagram type '${type}' uses HTML labels, which cannot be rendered offline`);
+    return Buffer.from(finalizeSvg(svg, id), 'utf8');
+};

package/dist/core/render/textmetrics.js

@@ -0,0 +1,36 @@
+import { DEFAULT_FONT_NAME } from "./fonts.js";
+import { getResvg, resvgFontOptions } from "./pngraster.js";
+// Метрики вендорного Nimbus Sans для движков, которые в jsdom раскладывают текст сами
+// (BPMN, mermaid): jsdom не умеет ни canvas.measureText, ни getBBox. Меряем тем же resvg,
+// что растрирует PNG. Режим системных шрифтов на них не влияет (как и на D2): детерминизм
+// важнее.
+// hhea и OS/2 Nimbus Sans Regular на 1000 единиц (vendor/fonts): ascender 729,
+// descender −271, sxHeight 516.
+export const ASCENT = 0.729;
+export const DESCENT = 0.271;
+export const X_HEIGHT = 0.516;
+const widthMemo = new Map();
+export const escapeXml = (s) => s.replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' })[c]);
+const inkWidth = (text, size, bold) => {
+    const { Resvg } = getResvg();
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"><text y="${size}" ` +
+        `font-family="${DEFAULT_FONT_NAME}" font-size="${size}"${bold ? ' font-weight="bold"' : ''} ` +
+        `xml:space="preserve">${escapeXml(text)}</text></svg>`;
+    return new Resvg(svg, { font: resvgFontOptions(false) }).getBBox()?.width ?? 0;
+};
+// Advance-ширина строки, как у браузера: bbox «|текст|» минус bbox «||» — с пробелами по
+// краям, а не ширина чернил.
+export const textWidth = (text, size, bold = false) => {
+    if (!text)
+        return 0;
+    const key = `${size}\0${bold}\0${text}`;
+    let width = widthMemo.get(key);
+    if (width === undefined) {
+        // Округление гасит f32-шум resvg между платформами: координаты текста в SVG
+        // считаются из этой ширины и должны совпадать побайтно.
+        width = Math.round((inkWidth(`|${text}|`, size, bold) - inkWidth('||', size, bold)) * 100) / 100;
+        widthMemo.set(key, width);
+    }
+    return width;
+};
+export const clearTextWidths = () => widthMemo.clear();

package/dist/core/scan/fences.js

@@ -7,7 +7,7 @@ import crypto from 'node:crypto';
 // списке), инфо-строка, тело (может быть пустым), закрывающая того же вида не короче
 // открывающей. Тело захватывается вместе с завершающим переводом строки.
 const FENCE_RE = /^([ \t]*)(`{3,}|~{3,})[ \t]*([^\n]*)\n([\s\S]*?)^[ \t]*\2[`~]*[ \t]*$/gm;
-const ENGINE_EXT = { plantuml: '.puml', puml: '.puml', d2: '.d2' };
+const ENGINE_EXT = { plantuml: '.puml', puml: '.puml', d2: '.d2', mermaid: '.mmd' };
 /** Применить fn к тексту вне fenced-блоков (сами блоки — без изменений). */
 export const mapOutsideFences = (md, fn) => {
     let out = '';
@@ -20,7 +20,7 @@ export const mapOutsideFences = (md, fn) => {
 };
 /**
  * Экстрактор диаграмм одной страницы; извлекаются только блоки языков `langs` (из
- * plantuml/puml/d2), остальные остаются кодом. Имя файла — `<base>-<sha1 контента>`: не
+ * plantuml/puml/d2/mermaid), остальные остаются кодом. Имя файла — `<base>-<sha1 контента>`: не
  * зависит от позиции fence, поэтому вставка/удаление соседнего блока не сдвигает имена и
  * не подсовывает картинку соседа из кэша; одинаковые блоки дают одну диаграмму.
  */