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

package/dist/cli/commands/site.js

@@ -1,17 +1,21 @@
 import chalk from 'chalk';
+import { createHash, randomUUID } from 'node:crypto';
 import path from 'node:path';
 import fs from 'node:fs';
 import express from 'express';
 import open from 'open';
+import { batchSchema, formatBatch } from "../../core/feedback.js";
 import { deleteQuestion, formatQuestion, pickSource, writeQuestion } from "../../core/questions.js";
 import { packageJson as pkg } from "../../util/paths.js";
 import { pendingUpdate } from "../update.js";
-import { COMMENTS_PATH, commentsSnippet } from "./site.comments.js";
+import { COMMENTS_PATH, commentsSnippet, FEEDBACK_HEADER, FEEDBACK_PATH } from "./site.comments.js";
 const COMMENT_MAX = 2000;
 const LIVERELOAD_PATH = '/__livereload';
 // Восстановление скролла после reload: docsify рендерит контент асинхронно после fetch md,
 // высота страницы доступна не сразу — поллим до достижения нужной y или таймаута.
 // Комментарии держим здесь, а не в сниппете: он уходит в браузер пользователя.
+// События агента (design D4) идут по тому же потоку и пересылаются сниппету комментариев
+// DOM-событиями `c4builder:*` — второй EventSource странице не нужен.
 const LIVERELOAD_SNIPPET = `
 <script>
 (function () {
@@ -48,6 +52,13 @@ const LIVERELOAD_SNIPPET = `
             es.close();
             location.reload();
         });
+        ['agent', 'delivered'].forEach(function (name) {
+            es.addEventListener(name, function (e) {
+                try {
+                    window.dispatchEvent(new CustomEvent('c4builder:' + name, { detail: JSON.parse(e.data) }));
+                } catch (err) {}
+            });
+        });
         es.onerror = function () {
             es.close();
             setTimeout(connect, delay);
@@ -88,12 +99,24 @@ pages = () => new Map()) => {
     const port = program.port || currentConfiguration.WEB_PORT;
     const distFolder = path.resolve(currentConfiguration.DIST_FOLDER);
     const liveReloadEnabled = !!(program.watch && reloadEmitter);
+    const agent = { ...(program.agent ?? { on: false, name: '', explicit: false }) };
     // Кеш index.html — отдаём его из памяти, если на диске его временно нет
     // (в окне build.js → emptyDir(DIST_FOLDER) перед записью).
     let lastIndexHtml = null;
     // reloadEmitter в условии — сужает тип до EventEmitter внутри блока (liveReloadEnabled
     // истинно ⟺ reloadEmitter задан), поэтому дальше без non-null assertions.
     if (liveReloadEnabled && reloadEmitter) {
+        // Состояние слушателя `c4builder feedback` (design D4): подключён, пока открыт long-poll
+        // или с конца последнего прошло меньше idleMs — зазор между повторами команды.
+        let listening = false;
+        const agentState = () => ({ on: agent.on, listening });
+        const setAgent = (on, listen) => {
+            if (on === agent.on && listen === listening)
+                return;
+            agent.on = on;
+            listening = listen;
+            reloadEmitter.emit('agent', agentState());
+        };
         app.get(LIVERELOAD_PATH, (req, res) => {
             res.set({
                 'Content-Type': 'text/event-stream',
@@ -104,21 +127,36 @@ pages = () => new Map()) => {
             res.flushHeaders();
             res.write('retry: 1000\n\n');
             const onReload = () => res.write('event: reload\ndata: {}\n\n');
+            const onAgent = (data) => res.write(`event: agent\ndata: ${JSON.stringify(data)}\n\n`);
+            const onDelivered = (data) => res.write(`event: delivered\ndata: ${JSON.stringify(data)}\n\n`);
             const heartbeat = setInterval(() => res.write(': ping\n\n'), 15000);
             reloadEmitter.on('reload', onReload); // liveReloadEnabled ⇒ reloadEmitter задан
+            reloadEmitter.on('agent', onAgent);
+            reloadEmitter.on('delivered', onDelivered);
+            onAgent(agentState());
             console.log(chalk.gray(`livereload: client connected (${reloadEmitter.listenerCount('reload')} total)`));
             req.on('close', () => {
                 clearInterval(heartbeat);
                 reloadEmitter.off('reload', onReload);
+                reloadEmitter.off('agent', onAgent);
+                reloadEmitter.off('delivered', onDelivered);
                 console.log(chalk.gray(`livereload: client disconnected (${reloadEmitter.listenerCount('reload')} left)`));
             });
         });
+        // Ключ черновиков review в localStorage (design D5): страницы разных проектов на одном
+        // localhost:<port> не должны видеть чужой черновик.
+        const projectKey = createHash('sha1').update(process.cwd()).digest('hex').slice(0, 8);
         // Кэш проверки обновлений читается на каждую страницу: результат фоновой проверки,
         // запущенной этим же `site -w`, виден со следующей перезагрузки без рестарта сервера.
         const inject = (html) => {
             const next = pendingUpdate();
             const snippet = LIVERELOAD_SNIPPET +
-                commentsSnippet(currentConfiguration.QUESTIONS_HEADING) +
+                commentsSnippet(currentConfiguration.QUESTIONS_HEADING, {
+                    agent: agent.on,
+                    listening,
+                    project: projectKey,
+                    language: currentConfiguration.UI_LANGUAGE
+                }) +
                 (next ? updateBanner(next) : '');
             if (html.includes('</body>'))
                 return html.replace('</body>', `${snippet}</body>`);
@@ -129,15 +167,21 @@ pages = () => new Map()) => {
         // любого сайта в браузере может слать POST на localhost — требуем Origin самого сайта.
         const str = (v) => (typeof v === 'string' ? v : '');
         const heading = currentConfiguration.QUESTIONS_HEADING;
+        // Host — только локальный: при DNS rebinding чужой домен резолвится в 127.0.0.1 и
+        // присылает согласованные Host и Origin, сверка Origin с одним Host это пропускает.
+        const localHost = (req) => {
+            const host = req.get('host');
+            const local = [`127.0.0.1:${req.socket.localPort}`, `localhost:${req.socket.localPort}`];
+            return host && local.includes(host) ? host : undefined;
+        };
+        const fromSite = (req) => {
+            const host = localHost(req);
+            return !!host && req.get('origin') === `http://${host}`;
+        };
         // Общая часть POST/DELETE: проверка Origin и исходный файл страницы из тела запроса.
         // Ошибка уже отправлена клиенту, когда возвращается undefined.
         const resolveTarget = (req, res) => {
-            const origin = req.get('origin');
-            const host = req.get('host');
-            // Host — только локальный: при DNS rebinding чужой домен резолвится в 127.0.0.1 и
-            // присылает согласованные Host и Origin, сверка Origin с одним Host это пропускает.
-            const local = [`127.0.0.1:${req.socket.localPort}`, `localhost:${req.socket.localPort}`];
-            if (!origin || !host || !local.includes(host) || origin !== `http://${host}`) {
+            if (!fromSite(req)) {
                 res.status(403).json({ error: 'comments are accepted only from the site itself' });
                 return undefined;
             }
@@ -214,6 +258,104 @@ pages = () => new Map()) => {
                 res.status(500).json({ error: `could not remove the comment: ${e.message}` });
             }
         });
+        // Замечания агенту (change site-agent-feedback): FIFO пачек в памяти (design D3), страница
+        // шлёт POST, `c4builder feedback` забирает long-poll'ом (D1). Пачка снимается с очереди,
+        // когда ответ записан; обрыв до этого возвращает её в голову очереди.
+        const { pollMs = 25_000, idleMs = 30_000 } = program;
+        const queue = [];
+        const waiters = [];
+        let polls = 0;
+        let idleTimer;
+        const disabled = () => agent.explicit && !agent.on;
+        const drop = (res) => {
+            const i = waiters.indexOf(res);
+            if (i >= 0)
+                waiters.splice(i, 1);
+        };
+        const pump = () => {
+            while (queue.length && waiters.length) {
+                const res = waiters.shift();
+                const item = queue.shift();
+                if (res && item)
+                    deliver(res, item);
+            }
+        };
+        const deliver = (res, item) => {
+            res.on('close', () => {
+                if (!res.writableFinished) {
+                    queue.unshift(item);
+                    pump();
+                    return;
+                }
+                console.log(chalk.gray(`feedback: batch delivered to the agent (${item.batch.decision})`));
+                reloadEmitter.emit('delivered', { id: item.id });
+            });
+            res.type('text/markdown').send(formatBatch(item.batch, pages(), process.cwd()));
+        };
+        app.post(FEEDBACK_PATH, express.json({ limit: '4mb' }), (req, res) => {
+            if (!fromSite(req)) {
+                res.status(403).json({ error: 'feedback is accepted only from the site itself' });
+                return;
+            }
+            if (disabled()) {
+                res.status(404).json({ error: 'agent feedback is disabled (--no-agent)' });
+                return;
+            }
+            const parsed = batchSchema.safeParse(req.body);
+            if (!parsed.success) {
+                const issue = parsed.error.issues[0];
+                res.status(400).json({
+                    error: `invalid feedback: ${issue?.path.join('.')} ${issue?.message}`
+                });
+                return;
+            }
+            const batch = parsed.data;
+            if (batch.decision === 'submitted' && !batch.comments.length && !batch.general) {
+                res.status(400).json({ error: 'nothing to send' });
+                return;
+            }
+            const id = randomUUID();
+            const queued = !waiters.length;
+            queue.push({ id, batch });
+            pump();
+            console.log(chalk.gray(`feedback: ${batch.decision}, ${batch.comments.length} comment(s)${queued ? ' — queued, no agent listening' : ''}`));
+            res.json({ id, queued });
+        });
+        // Нестандартный заголовок вынуждает браузер к preflight, на который сервер не отвечает:
+        // чужая страница не может ни прочитать, ни «съесть» очередь простым запросом (design D6).
+        app.get(`${FEEDBACK_PATH}/next`, (req, res) => {
+            if (!localHost(req) || req.get('origin') || req.get(FEEDBACK_HEADER) !== '1') {
+                res.status(403).json({ error: 'feedback is served only to the c4builder feedback command' });
+                return;
+            }
+            if (disabled()) {
+                res.status(404).json({ error: 'agent feedback is disabled (--no-agent)' });
+                return;
+            }
+            if (!agent.on)
+                console.log(chalk.gray('agent mode on: "c4builder feedback" connected'));
+            polls++;
+            clearTimeout(idleTimer);
+            setAgent(true, true);
+            let timer;
+            res.on('close', () => {
+                clearTimeout(timer);
+                drop(res);
+                if (--polls === 0)
+                    idleTimer = setTimeout(() => setAgent(agent.on, false), idleMs);
+            });
+            waiters.push(res);
+            pump();
+            if (!waiters.includes(res))
+                return;
+            timer = setTimeout(() => {
+                // Пачку успели отдать этому запросу — ответ уже пишется, 204 не нужен.
+                if (!waiters.includes(res))
+                    return;
+                drop(res);
+                res.status(204).end();
+            }, req.query.wait === '0' ? 0 : pollMs);
+        });
         app.use((req, res, next) => {
             if (req.method !== 'GET')
                 return next();
@@ -264,6 +406,8 @@ pages = () => new Map()) => {
             console.log(`go to ${chalk.green(url)}`);
             if (liveReloadEnabled)
                 console.log(chalk.gray('livereload enabled (browser auto-reload on rebuild)'));
+            if (liveReloadEnabled && agent.on)
+                console.log(`agent mode (${agent.name}): page feedback goes to "c4builder feedback --wait${program.port ? ` -p ${port}` : ''}" — run it in the background and again after each batch`);
             // --open: открываем браузер один раз при старте; BROWSER=none отключает (CI/headless)
             if (program.open && process.env.BROWSER !== 'none')
                 open(url).catch(() => console.log(chalk.gray('could not open the browser automatically')));

package/dist/cli/dispatch.js

@@ -9,6 +9,8 @@ import cmdJre from "./commands/jre.js";
 import cmdCheck from "./commands/check.js";
 import cmdList from "./commands/list.js";
 import cmdSite from "./commands/site.js";
+import cmdFeedback from "./commands/feedback.js";
+import { detectAgent } from "./agent.js";
 import { cmdUpdate, pendingUpdate, startUpdateCheck } from "./update.js";
 import cmdCollect from "./wizard/collect.js";
 import { build } from "../core/build.js";
@@ -23,11 +25,12 @@ import { acquireBuildLock, BuildLockHeldError, waitBuildLock } from "../util/loc
 // больше не будет (одиночный запуск).
 import { teardownD2 } from "../core/render/d2renderer.js";
 import { teardownBpmn } from "../core/render/bpmnrenderer.js";
+import { teardownMermaid } from "../core/render/mermaidrenderer.js";
 import { packageJson as pkg } from "../util/paths.js";
 import { outputDirs, parseConfig } from "../config/options.js";
 import { isValidPort } from "../config/schema.js";
 // Позиционные подкоманды: allowExcessArguments пропускает любые, список — единственный фильтр.
-const COMMANDS = ['check', 'jre', 'site', 'new', 'config', 'update'];
+const COMMANDS = ['check', 'jre', 'site', 'new', 'config', 'update', 'feedback'];
 const intro = () => {
     console.log(chalk.blue(figlet.textSync('c4builder')));
     console.log(chalk.gray('Blow up your software documentation writing skills'));
@@ -103,6 +106,7 @@ function getOptions(c) {
         EXCLUDE_OTHER_FILES: c.excludeOtherFiles,
         USE_SYSTEM_FONTS: c.useSystemFonts,
         QUESTIONS_HEADING: c.questionsHeading,
+        UI_LANGUAGE: c.uiLanguage,
         PLUGINS: c.plugins
     };
 }
@@ -120,6 +124,9 @@ export default async () => {
         .option('--site', 'serve the generated site')
         .option('-w, --watch', 'watch for changes and rebuild')
         .option('-o, --open', 'open the generated site in the browser (with --site)')
+        .option('--agent', 'with --site -w: accept page feedback for a coding agent (c4builder feedback)')
+        .option('--no-agent', 'with --site -w: no agent feedback even when run by a coding agent')
+        .option('--wait', 'for `feedback`: wait for the next batch of page feedback')
         .option('--docs', 'a brief explanation for the available configuration options')
         .option('--system-fonts', 'render with system fonts instead of the bundled one (not deterministic)')
         .option('-p, --port <n>', 'port used for serving the generated site', (v) => {
@@ -140,8 +147,8 @@ export default async () => {
         process.exit(1);
     }
     // --version/--help уже вышли в parse. Уведомление — по кэшу прошлой проверки, до её
-    // перезапуска; exit покрывает и выходы через process.exit.
-    if (cmd !== 'update') {
+    // перезапуска; exit покрывает и выходы через process.exit. Вывод `feedback` читает агент.
+    if (cmd !== 'update' && cmd !== 'feedback') {
         const next = pendingUpdate();
         if (next)
             process.once('exit', () => process.stderr.write(`c4builder ${next} is available (current ${pkg.version}). Run: c4builder update\n`));
@@ -156,6 +163,9 @@ export default async () => {
     // Обновление CLI — до Configstore, чтобы не создавать .c4builder в любом каталоге.
     if (cmd === 'update')
         return cmdUpdate();
+    // Замечания со страницы `site -w` — тоже до Configstore: команду запускают в любом каталоге.
+    if (cmd === 'feedback')
+        return cmdFeedback(path.join(process.cwd(), opts.configFile ?? '.c4builder'), opts);
     // `site`/`new`/`config` — позиционные синонимы одноимённых флагов: эту форму печатают
     // подсказки CLI и учат README, шаблон и скиллы.
     if (cmd)
@@ -344,11 +354,12 @@ export default async () => {
             if (!opts.watch) {
                 await teardownD2();
                 await teardownBpmn();
+                await teardownMermaid();
             }
         }
         isBuilding = false;
         if (opts.site)
-            return await cmdSite(options, opts, reloadEmitter, () => pages);
+            return await cmdSite(options, { ...opts, agent: detectAgent(process.env, opts) }, reloadEmitter, () => pages);
         if (options.GENERATE_WEBSITE && !opts.watch) {
             console.log(chalk.gray('\nto view the generated website run'));
             console.log(`> c4builder site`);

package/dist/config/defaults.js

@@ -32,6 +32,7 @@ const defaultConfig = {
     d2Layout: 'dagre',
     charset: 'UTF-8',
     useSystemFonts: false,
-    questionsHeading: 'Open questions'
+    questionsHeading: 'Open questions',
+    uiLanguage: 'auto'
 };
 export { defaultConfig };

package/dist/config/schema.js

@@ -60,6 +60,8 @@ export const configSchema = z.object({
     // Заголовок раздела, куда `site -w` дописывает комментарии к странице (в коде кириллицы
     // быть не может — русский заголовок задаёт сам проект).
     questionsHeading: str(defaultConfig.questionsHeading),
+    // Язык интерфейса страницы `site -w`; `auto` — по языку браузера (change site-ui-language).
+    uiLanguage: z.preprocess(strPre, z.enum(['auto', 'en', 'ru'], 'expected auto, en or ru').default(defaultConfig.uiLanguage)),
     // Задаются явно (флаг/промпт) либо тонкой правкой файла — в defaultConfig не входят.
     projectName: optStr(),
     webFileName: optStr(),

package/dist/core/compose/markdown.js

@@ -223,7 +223,7 @@ export const generateLlmsTxt = (tree, options) => {
     });
     return (`# ${options.PROJECT_NAME}\n\n` +
         '> Architecture documentation built with c4builder. Pages are markdown; full text with ' +
-        'diagram sources (PlantUML/D2/BPMN): [llms-full.txt](llms-full.txt).\n\n' +
+        'diagram sources (PlantUML/D2/BPMN/Mermaid): [llms-full.txt](llms-full.txt).\n\n' +
         `## Pages\n\n${pages.join('')}`);
 };
 // Fence длиннее самой длинной серии обратных кавычек текста — иначе блок закрылся бы изнутри.
@@ -235,7 +235,8 @@ const FENCE_LANG = {
     '.puml': 'plantuml',
     '.iuml': 'plantuml',
     '.d2': 'd2',
-    '.bpmn': 'xml'
+    '.bpmn': 'xml',
+    '.mmd': 'mermaid'
 };
 // llms-full.txt: состав complete-документа, но диаграмма — исходником (C4-PlantUML/D2-текст
 // агенту полезнее SVG). Локальные include/импорты — один раз в приложении, а не инлайном:

package/dist/core/feedback.js

@@ -0,0 +1,59 @@
+// Пачка замечаний агенту со страницы `site -w` (change site-agent-feedback, design D6–D7):
+// схема тела запроса страницы и markdown, который печатает `c4builder feedback`.
+import path from 'node:path';
+import { z } from 'zod';
+const TEXT_MAX = 2000;
+const text = z.string().max(TEXT_MAX);
+const collapse = (s) => s.replace(/\s+/g, ' ').trim();
+// Цитата — только ориентир для агента: длинное выделение обрезается, а не валит всю пачку.
+const clip = (s) => {
+    const q = collapse(s);
+    return q.length > TEXT_MAX ? `${q.slice(0, TEXT_MAX - 1).trimEnd()}…` : q;
+};
+export const batchSchema = z.object({
+    decision: z.enum(['submitted', 'approved']),
+    comments: z
+        .array(z.object({
+        // Ключ карты «страница → исходники»: тот же вид, что у вопросов (без ведущего «/»).
+        page: z
+            .string()
+            .max(1000)
+            .transform((p) => path.posix.normalize(p.replace(/^\/+/, ''))),
+        quote: z.string().transform(clip),
+        section: text.default(''),
+        comment: text.trim().min(1)
+    }))
+        .max(200),
+    general: text.trim().default('')
+});
+const quoted = (s) => s
+    .split('\n')
+    .map((l) => (l.trim() ? `> ${l}` : '>'))
+    .join('\n');
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+// Исходники — относительно cwd: агент правит их из каталога проекта.
+export const formatBatch = (batch, pages, cwd) => {
+    const { comments, general } = batch;
+    const pageCount = new Set(comments.map((c) => c.page)).size;
+    const out = [
+        '# Page feedback (c4builder)',
+        '',
+        `Decision: ${batch.decision}`,
+        `Comments: ${comments.length}${comments.length ? ` on ${plural(pageCount, 'page')}` : ''}`
+    ];
+    comments.forEach((c, i) => {
+        const section = collapse(c.section);
+        const sources = (pages.get(c.page) ?? []).map((s) => path.relative(cwd, s).split(path.sep).join('/'));
+        // Страница схлопывается только в заголовке: перевод строки в ней сломал бы формат пачки,
+        // а ключ карты исходников остаётся как есть.
+        out.push('', `## ${i + 1}. ${collapse(c.page)}${section ? ` (§ ${section})` : ''}`);
+        if (sources.length)
+            out.push(`Sources: ${sources.join(', ')}`);
+        if (c.quote)
+            out.push(`Quote: "${c.quote}"`);
+        out.push('', quoted(c.comment));
+    });
+    if (general)
+        out.push('', '## General', '', quoted(general));
+    return `${out.join('\n')}\n`;
+};

package/dist/core/render/bpmnrenderer.js

@@ -10,7 +10,7 @@ import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import chalk from 'chalk';
 import { DEFAULT_FONT_NAME } from "./fonts.js";
-import { getResvg, resvgFontOptions } from "./pngraster.js";
+import { ASCENT, DESCENT, clearTextWidths, textWidth } from "./textmetrics.js";
 // Третий бэкенд рендера: BPMN 2.0 XML без координат → валидация (bpmnlint) → раскладка
 // (bpmn-auto-layout) → рендер bpmn-js в jsdom → SVG. Все пакеты — optionalDependencies,
 // грузятся лениво при первом .bpmn: проекты без BPMN их не трогают (как D2).
@@ -112,32 +112,7 @@ const C4BUILDER_RULES = {
     })
 };
 // Ширины строк для переноса подписей: diagram-js меряет текст только через
-// canvas.measureText, а jsdom канваса не умеет. Меряем вендорный Nimbus Sans тем же
-// resvg, что растрирует PNG: ширина = bbox «|текст|» минус bbox «||» — так получается
-// advance-ширина с пробелами по краям, а не ширина чернил. Режим системных шрифтов на
-// BPMN не влияет (как и на D2): детерминизм важнее.
-const widthMemo = new Map();
-const escapeXml = (s) => s.replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' })[c]);
-const inkWidth = (text, size) => {
-    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}" xml:space="preserve">${escapeXml(text)}</text></svg>`;
-    return new Resvg(svg, { font: resvgFontOptions(false) }).getBBox()?.width ?? 0;
-};
-const textWidth = (text, size) => {
-    const key = `${size}\0${text}`;
-    let width = widthMemo.get(key);
-    if (width === undefined) {
-        // Округление гасит f32-шум resvg между платформами: координаты текста в SVG
-        // считаются из этой ширины и должны совпадать побайтно.
-        width = Math.round((inkWidth(`|${text}|`, size) - inkWidth('||', size)) * 100) / 100;
-        widthMemo.set(key, width);
-    }
-    return width;
-};
-// hhea Nimbus Sans Regular: ascender 729, descender −271 на 1000 единиц (vendor/fonts).
-const ASCENT = 0.729;
-const DESCENT = 0.271;
+// canvas.measureText, а jsdom канваса не умеет — меряем вендорный шрифт (textmetrics).
 // Полифилы окна jsdom: ровно то, что bpmn-js зовёт при импорте и saveSVG. Трансформации
 // пишутся в атрибут сразу — сериализатор берёт атрибуты, а не baseVal.
 const installPolyfills = (window) => {
@@ -334,7 +309,7 @@ export const teardownBpmn = async () => {
         return;
     const pending = enginePromise;
     enginePromise = null;
-    widthMemo.clear();
+    clearTextWidths();
     try {
         (await pending).window.close();
     }

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')