@riebeckite/plugin-mermaid 0.0.21 → 0.0.23

package/README.md

@@ -1,5 +1,7 @@
 # @riebeckite/plugin-mermaid
 
+<!-- Generated from docs/docs/plugins/mermaid.md. Edit the canonical documentation in docs/docs/plugins and run `pnpm docs:sync`. -->
+
 Mermaid diagram rendering for ` ```mermaid ` code blocks.
 
 [日本語](./README_ja.md)
@@ -8,7 +10,7 @@ Mermaid diagram rendering for ` ```mermaid ` code blocks.
 
 `mermaid()` replaces mermaid code blocks with a `<figure class="rr-mermaid">`
 that renders to SVG. Diagrams are rendered at build time with a headless browser by
-default, with an automatic client-side fallback. It runs with `order: -10`.
+default. It runs with `order: -10`.
 
 ## Usage
 
@@ -42,10 +44,11 @@ export default defineConfig({
   Rendering uses Chromium's layout engine, not JSDOM polyfills or custom
   `getBBox` / text-width estimation
 - Mermaid runs with `securityLevel: "strict"`, the selected theme, transparent
-  background, and a unique SVG id per diagram
+  background, deterministic IDs seeded by the diagram ID, and a unique SVG id per
+  diagram
 - Invalid diagrams report `ruleId: "invalid-diagram"`; Chromium renderer
-  failures report `ruleId: "renderer-error"`. When build SVG is unavailable,
-  the figure remains `data-mermaid="pending"` for client fallback
+  failures report `ruleId: "renderer-error"`. Build rendering failures stop the
+  build by default, so a failed render cannot be stored as successful content
 
 ### Client (`initMermaidDiagrams`)
 
@@ -61,16 +64,21 @@ export default defineConfig({
 | Option | Type | Default | Description |
 | ------ | ---- | ------- | ----------- |
 | `render` | `"build" \| "client"` | `"build"` | When diagrams are rendered |
+| `onRenderError` | `"error" \| "client"` | `"error"` | Behavior when build rendering fails |
 | `theme` | `string \| { light: string; dark: string }` | `{ light: "default", dark: "dark" }` | Mermaid theme |
 | `caption` | `boolean` | `true` | Show title / `%% caption:` as `figcaption` |
 | `fallback` | `boolean` | `true` | Show the diagram source in `<details>` |
 
 `render` modes:
 
-- `"build"` — render SVG at build time; diagrams that fail fall back to client
-  rendering
+- `"build"` — render SVG at build time; failures stop the build unless
+  `onRenderError` is `"client"`
 - `"client"` — skip build-time rendering, render in the browser only
 
+Set `onRenderError: "client"` only when client-side retry is an intentional
+availability trade-off. This makes the generated HTML depend on the renderer's
+availability.
+
 ## Exports
 
 - `mermaid(options?)` — plugin factory
@@ -79,4 +87,4 @@ export default defineConfig({
 
 ## See also
 
-- [Plugin guide](../../../docs/docs/reference/plugin-api.md)
+- [Plugin guide](https://github.com/Rerurate514/riebeckite/blob/main/docs/docs/reference/plugin-api.md)

package/README_ja.md

@@ -1,6 +1,8 @@
 # @riebeckite/plugin-mermaid
 
-`mermaid` コードブロックを SVG の図として表示するプラグインです。既定ではビルド時に描画し、描画できなかった図だけをブラウザ側で再試行します。
+<!-- Generated from docs/docs/plugins/mermaid.ja.md. Edit the canonical documentation in docs/docs/plugins and run `pnpm docs:sync`. -->
+
+`mermaid` コードブロックを SVG の図として表示するプラグインです。既定ではビルド時に描画します。
 
 [English](./README.md)
 
@@ -29,7 +31,7 @@ export default defineConfig({
 
 `render: "build"` では、Puppeteer が起動するヘッドレス Chromium 上で Mermaid を実行し、静的な SVG を生成します。簡易な DOM 実装や寸法の推測には頼らないため、ブラウザと同じレイアウトエンジンで図を作れます。Mermaid は `securityLevel: "strict"` で実行されます。
 
-構文エラーは `invalid-diagram`、描画環境の問題は `renderer-error` として区別して診断します。ビルドで SVG を作れなかった図には `data-mermaid="pending"` が付き、クライアント側が描画を引き継ぎます。
+構文エラーは `invalid-diagram`、描画環境の問題は `renderer-error` として区別して診断します。ビルド時の描画に失敗した場合、既定ではビルドを失敗させます。失敗した図を成功したコンテンツとして保存しません。SVG ID は図の ID をシードにして決定的に生成します。
 
 ## クライアント側の再試行
 
@@ -42,11 +44,12 @@ export default defineConfig({
 | 項目 | 既定値 | 説明 |
 | --- | --- | --- |
 | `render` | `"build"` | `"build"` または `"client"` のいずれで描画するか |
+| `onRenderError` | `"error"` | ビルド時の描画失敗時に `"error"` または `"client"` のどちらにするか |
 | `theme` | `{ light: "default", dark: "dark" }` | Mermaid のテーマ名、または明暗別のテーマ |
 | `caption` | `true` | タイトルまたは `%% caption:` をキャプションとして表示する |
 | `fallback` | `true` | 元の Mermaid 記法を `<details>` に残す |
 
-`"client"` はビルド時の描画を行いません。
+`"client"` はビルド時の描画を行いません。`render: "build"` で `onRenderError: "client"` を指定するときだけ、ビルド時の描画失敗をクライアント側へ明示的に委譲します。この設定では生成HTMLが描画環境の可用性に依存します。
 
 ## 主なエクスポート
 
@@ -56,4 +59,4 @@ export default defineConfig({
 
 ## 関連資料
 
-- [プラグインシステム](../../../docs/docs/reference/plugin-api.ja.md)
+- [プラグインシステム](https://github.com/Rerurate514/riebeckite/blob/main/docs/docs/reference/plugin-api.ja.md)

package/dist/index.d.ts

@@ -1,3 +1,3 @@
 import type { MermaidOptions } from "./src/types.js";
-export type { MermaidClientOptions, MermaidOptions, MermaidRenderMode, MermaidRenderSession, MermaidTheme, } from "./src/types.js";
+export type { MermaidClientOptions, MermaidOptions, MermaidRenderFailureMode, MermaidRenderMode, MermaidRenderSession, MermaidTheme, } from "./src/types.js";
 export declare function mermaid(options?: MermaidOptions): import("@riebeckite/core").RiebeckitePlugin<MermaidOptions>;

package/dist/index.js

@@ -66,6 +66,7 @@ var init_hast = __esm({
 // src/rehype.ts
 var rehype_exports = {};
 __export(rehype_exports, {
+  MermaidBuildRenderError: () => MermaidBuildRenderError,
   rehypeMermaid: () => rehypeMermaid
 });
 function rehypeMermaid(options = {}, session) {
@@ -81,6 +82,7 @@ function rehypeMermaid(options = {}, session) {
           theme,
           caption: options.caption !== false,
           fallback: options.fallback !== false,
+          onRenderError: options.onRenderError ?? "error",
           session
         })
       );
@@ -94,6 +96,9 @@ async function replaceMermaidBlock(parent, index, pre, file, options) {
   const caption = options.caption ? extractCaption(source, pre, code) : null;
   const id = `rr-mermaid-${hashSource(source)}`;
   const renderResult = shouldRenderAtBuild(options.render) ? await renderStaticSvg(id, source, options.theme, file, options.session) : null;
+  if (renderResult?.ok === false && options.onRenderError === "error") {
+    throw new MermaidBuildRenderError(renderResult);
+  }
   const staticSvg = renderResult?.ok ? renderResult.svg : null;
   parent.children = parent.children ?? [];
   parent.children[index] = buildFigure({
@@ -102,7 +107,7 @@ async function replaceMermaidBlock(parent, index, pre, file, options) {
     caption,
     staticSvg,
     fallback: options.fallback,
-    clientFallback: shouldRenderAtClient(options.render) || renderResult?.ok === false
+    clientFallback: shouldRenderAtClient(options.render) || renderResult?.ok === false && options.onRenderError === "client"
   });
 }
 function buildFigure(input) {
@@ -154,14 +159,11 @@ async function renderStaticSvg(id, source, theme, file, session) {
     );
     if (result.ok === false) {
       reportMermaidDiagnostic(file, result.message, result.kind);
-      const label = result.kind === "invalid-diagram" ? "invalid diagram" : "renderer failed";
-      console.warn(`[mermaid] ${label}: ${result.message}`);
     }
     return result;
   } catch (error) {
     const message = formatError2(error);
     reportMermaidDiagnostic(file, message, "renderer-error");
-    console.warn(`[mermaid] renderer failed: ${message}`);
     return { ok: false, kind: "renderer-error", message };
   }
 }
@@ -212,12 +214,20 @@ function formatError2(error) {
   if (error instanceof Error) return error.message;
   return String(error);
 }
-var DEFAULT_THEME, CAPTION_PATTERN;
+var DEFAULT_THEME, CAPTION_PATTERN, MermaidBuildRenderError;
 var init_rehype = __esm({
   "src/rehype.ts"() {
     init_hast();
     DEFAULT_THEME = { light: "default", dark: "dark" };
     CAPTION_PATTERN = /^%%\s*caption\s*:\s*(.+)$/im;
+    MermaidBuildRenderError = class extends Error {
+      kind;
+      constructor(result) {
+        super(`Mermaid build rendering failed: ${result.message}`);
+        this.name = "MermaidBuildRenderError";
+        this.kind = result.kind;
+      }
+    };
   }
 });
 
@@ -230,12 +240,15 @@ import {
 
 // src/render-static.ts
 import { access } from "node:fs/promises";
+import { createRequire } from "node:module";
 import { join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 var RENDER_TIMEOUT_MS = 3e4;
 var MERMAID_SCRIPT_SUBPATH = "mermaid/dist/mermaid.min.js";
+var PUPPETEER_PACKAGE = "puppeteer";
 function createMermaidRenderSession(dependencies = {}) {
   const launchBrowser = dependencies.launch ?? defaultLaunchBrowser;
+  const timeoutMs = dependencies.timeoutMs ?? RENDER_TIMEOUT_MS;
   let state = null;
   let queue = Promise.resolve();
   let exitListenerAttached = false;
@@ -264,7 +277,7 @@ function createMermaidRenderSession(dependencies = {}) {
     attachExitListener();
     try {
       const page = await browser.newPage();
-      page.setDefaultTimeout(RENDER_TIMEOUT_MS);
+      page.setDefaultTimeout(timeoutMs);
       await page.setContent("<!doctype html><html><body></body></html>");
       await page.addScriptTag({ path: await resolveMermaidScriptPath() });
       state = { browser, page };
@@ -288,11 +301,10 @@ function createMermaidRenderSession(dependencies = {}) {
     if (current) await teardownBrowser(current.browser);
   }
   async function evaluateRender(session, id, source, theme) {
-    const result = await session.page.evaluate(
-      renderMermaidInPage,
-      id,
-      source,
-      theme
+    const result = await withTimeout(
+      session.page.evaluate(renderMermaidInPage, id, source, theme),
+      timeoutMs,
+      "Mermaid rendering timed out."
     );
     return normalizeRenderResult(result);
   }
@@ -347,7 +359,9 @@ async function renderMermaidInPage(id, source, theme) {
     mermaid2.initialize({
       startOnLoad: false,
       securityLevel: "strict",
-      theme
+      theme,
+      deterministicIds: true,
+      deterministicIDSeed: id
     });
     const { svg } = await mermaid2.render(id, source);
     return { ok: true, svg };
@@ -371,7 +385,21 @@ async function importPuppeteer() {
     "specifier",
     "return import(specifier)"
   );
-  return importModule("puppeteer");
+  try {
+    return await importModule(PUPPETEER_PACKAGE);
+  } catch (error) {
+    const fallback = resolvePuppeteerFromWorkingDirectory();
+    if (!fallback) throw error;
+    return importModule(fallback);
+  }
+}
+function resolvePuppeteerFromWorkingDirectory() {
+  try {
+    const require2 = createRequire(join(process.cwd(), "package.json"));
+    return pathToFileURL(require2.resolve(PUPPETEER_PACKAGE)).href;
+  } catch {
+    return null;
+  }
 }
 async function resolveMermaidScriptPath() {
   const candidates = [
@@ -420,7 +448,7 @@ function normalizeRenderResult(value) {
     };
   }
   const result = value;
-  if (result.ok === true && typeof result.svg === "string") {
+  if (result.ok === true && typeof result.svg === "string" && result.svg.trimStart().startsWith("<svg")) {
     return { ok: true, svg: result.svg };
   }
   if (result.ok === false) {
@@ -436,6 +464,15 @@ function normalizeRenderResult(value) {
     message: "Mermaid renderer returned an invalid result."
   };
 }
+function withTimeout(promise, timeoutMs, message) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(message)), timeoutMs);
+  });
+  return Promise.race([promise, timeout]).finally(() => {
+    if (timer !== void 0) clearTimeout(timer);
+  });
+}
 function normalizeErrorKind(value) {
   return value === "invalid-diagram" || value === "renderer-error" ? value : "renderer-error";
 }
@@ -451,8 +488,9 @@ function mermaid(options = {}) {
     name: "mermaid",
     order: -10,
     processedContentCache: {
-      version: "mermaid-v1",
-      dependencyMode: "none"
+      version: "mermaid-v3",
+      dependencyMode: "unsafe",
+      appliesToContent: ({ source }) => containsMermaidFence(source) ? "applies" : "does-not-apply"
     },
     options,
     validateOptions: validateMermaidOptions,
@@ -465,10 +503,21 @@ function mermaid(options = {}) {
     dispose: async () => {
       await session.dispose();
     },
-    assets: [createStyleAsset("mermaid")],
-    clientEntries: [createClientEntry("mermaid", "initMermaidDiagrams")]
+    assets: [
+      createStyleAsset("mermaid", "@riebeckite/plugin-mermaid/style.css")
+    ],
+    clientEntries: [
+      createClientEntry(
+        "mermaid",
+        "@riebeckite/plugin-mermaid/client",
+        "initMermaidDiagrams"
+      )
+    ]
   });
 }
+function containsMermaidFence(source) {
+  return /^\s*(?:`{3,}|~{3,})[^\n`~]*\bmermaid\b[^\n`~]*$/im.test(source);
+}
 function validateMermaidOptions(options) {
   if (!options) return [];
   const issues = [];
@@ -478,6 +527,12 @@ function validateMermaidOptions(options) {
       message: 'Expected "build" or "client".'
     });
   }
+  if (options.onRenderError !== void 0 && options.onRenderError !== "error" && options.onRenderError !== "client") {
+    issues.push({
+      path: "onRenderError",
+      message: 'Expected "error" or "client".'
+    });
+  }
   if (!isMermaidTheme(options.theme)) {
     issues.push({
       path: "theme",

package/dist/src/rehype.d.ts

@@ -1,2 +1,8 @@
-import type { HastNode, MermaidOptions, MermaidRenderSession } from "./types.js";
+import type { HastNode, MermaidBuildRenderErrorKind, MermaidBuildRenderResult, MermaidOptions, MermaidRenderSession } from "./types.js";
+export declare class MermaidBuildRenderError extends Error {
+    readonly kind: MermaidBuildRenderErrorKind;
+    constructor(result: Extract<MermaidBuildRenderResult, {
+        ok: false;
+    }>);
+}
 export declare function rehypeMermaid(options: MermaidOptions, session: MermaidRenderSession): (tree: HastNode, file: unknown) => Promise<void>;

package/dist/src/render-static.d.ts

@@ -6,6 +6,7 @@ export type MermaidSessionDependencies = {
      * lifecycle can be asserted without launching Chrome.
      */
     launch?: () => Promise<Browser>;
+    timeoutMs?: number;
 };
 /**
  * Creates a build-scoped Mermaid render session.

package/dist/src/types.d.ts

@@ -1,10 +1,12 @@
 export type MermaidRenderMode = "build" | "client";
+export type MermaidRenderFailureMode = "error" | "client";
 export type MermaidTheme = string | {
     light: string;
     dark: string;
 };
 export type MermaidOptions = {
     render?: MermaidRenderMode;
+    onRenderError?: MermaidRenderFailureMode;
     theme?: MermaidTheme;
     caption?: boolean;
     fallback?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@riebeckite/plugin-mermaid",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,7 +23,7 @@
   "dependencies": {
     "mermaid": "^11.12.2",
     "puppeteer": "^25.11.0",
-    "@riebeckite/core": "0.0.21"
+    "@riebeckite/core": "0.0.23"
   },
   "publishConfig": {
     "access": "public"