@matfsw/docusaurus-plantuml-plugin 1.0.2 → 1.1.0

package/dist/runtime/cache.d.ts

@@ -14,6 +14,27 @@ export interface DiagramCache {
     size(): number;
 }
 export declare function computeCacheKey({ source, dark, sanitized, coreVersion }: CacheKeyInput): string;
+export interface GraphvizCacheKeyInput {
+    source: string;
+    /** Graphviz layout engine; `dot` and `neato` draw different pictures from one source. */
+    layout: string;
+    sanitized: boolean;
+    transparentBackground: boolean;
+    /**
+     * `@plantuml/core` version. The Graphviz build is bundled inside that package, so its
+     * version is what changes when the engine changes — and unlike `Viz.graphvizVersion` it is
+     * known before the engine has loaded, which is what lets a cache hit skip loading entirely.
+     */
+    coreVersion: string;
+}
+/**
+ * Cache key for a Graphviz diagram.
+ *
+ * The colour mode is deliberately **absent**: Graphviz output is colour-mode independent and
+ * adapts through CSS rather than through a re-render, so one entry serves both modes. The
+ * `graphviz|` prefix keeps these entries in a separate namespace from PlantUML's.
+ */
+export declare function computeGraphvizCacheKey({ source, layout, sanitized, transparentBackground, coreVersion, }: GraphvizCacheKeyInput): string;
 export declare function createDiagramCache(mode: CacheMode, maxEntries: number): DiagramCache;
 export declare function getSharedCache(mode: CacheMode, maxEntries: number): DiagramCache;
 /** Test-only: drops every shared cache instance. */

package/dist/runtime/cache.js

@@ -22,6 +22,18 @@ export function computeCacheKey({ source, dark, sanitized, coreVersion }) {
     // two different sources that happen to share every other key component.
     return `${coreVersion}|${mode}|${clean}|${source.length}|${hash(source)}`;
 }
+/**
+ * Cache key for a Graphviz diagram.
+ *
+ * The colour mode is deliberately **absent**: Graphviz output is colour-mode independent and
+ * adapts through CSS rather than through a re-render, so one entry serves both modes. The
+ * `graphviz|` prefix keeps these entries in a separate namespace from PlantUML's.
+ */
+export function computeGraphvizCacheKey({ source, layout, sanitized, transparentBackground, coreVersion, }) {
+    const clean = sanitized ? 'san' : 'raw';
+    const background = transparentBackground ? 'bg-none' : 'bg-default';
+    return `graphviz|${coreVersion}|${layout}|${background}|${clean}|${source.length}|${hash(source)}`;
+}
 class MemoryCache {
     mode = 'memory';
     #entries = new Map();

package/dist/runtime/errors.d.ts

@@ -1,4 +1,5 @@
-export type PlantUmlErrorKind = 'load' | 'engine' | 'diagram' | 'timeout' | 'config' | 'aborted';
+import type { VizRenderError } from './types.js';
+export type PlantUmlErrorKind = 'load' | 'engine' | 'diagram' | 'syntax' | 'timeout' | 'config' | 'aborted' | 'too-large';
 /** Every failure surfaced to the UI is one of these, so the panel can explain what broke. */
 export declare class PlantUmlError extends Error {
     readonly kind: PlantUmlErrorKind;
@@ -29,3 +30,17 @@ export declare function describeEngineError(raw: unknown): string;
  * so their `kind` survives a trip through the render queue.
  */
 export declare function toError(value: unknown): Error;
+/**
+ * Joins Graphviz's own diagnostics into one message.
+ *
+ * Unlike PlantUML, Graphviz reports failures as structured data rather than as a rendered
+ * error picture, so the reader can be shown exactly what the engine said — typically
+ * `syntax error in line 3 near '}'`. Warnings are dropped here: they accompany *successful*
+ * renders and must not be presented as failures.
+ */
+export declare function formatGraphvizErrors(errors: readonly VizRenderError[]): string;
+/**
+ * Extracts the 1-based source line from a Graphviz diagnostic, so the error panel can point
+ * at the offending line of the fence. Returns `null` when no line is named.
+ */
+export declare function graphvizErrorLine(message: string): number | null;

package/dist/runtime/errors.js

@@ -106,3 +106,35 @@ export function describeEngineError(raw) {
 export function toError(value) {
     return value instanceof Error ? value : new PlantUmlError('engine', describeEngineError(value));
 }
+const GRAPHVIZ_UNKNOWN_ERROR = 'Graphviz rejected this diagram without reporting a reason.';
+/**
+ * Joins Graphviz's own diagnostics into one message.
+ *
+ * Unlike PlantUML, Graphviz reports failures as structured data rather than as a rendered
+ * error picture, so the reader can be shown exactly what the engine said — typically
+ * `syntax error in line 3 near '}'`. Warnings are dropped here: they accompany *successful*
+ * renders and must not be presented as failures.
+ */
+export function formatGraphvizErrors(errors) {
+    const messages = errors
+        .filter((entry) => entry.level !== 'warning')
+        .map((entry) => entry.message.trim())
+        .filter((message) => message.length > 0);
+    // A failure with only warning-level diagnostics still failed; show them rather than nothing.
+    const fallback = errors
+        .map((entry) => entry.message.trim())
+        .filter((message) => message.length > 0);
+    const chosen = messages.length > 0 ? messages : fallback;
+    return chosen.length > 0 ? [...new Set(chosen)].join('\n') : GRAPHVIZ_UNKNOWN_ERROR;
+}
+/**
+ * Extracts the 1-based source line from a Graphviz diagnostic, so the error panel can point
+ * at the offending line of the fence. Returns `null` when no line is named.
+ */
+export function graphvizErrorLine(message) {
+    const match = /\bin line (\d+)\b/i.exec(message);
+    if (!match?.[1])
+        return null;
+    const line = Number.parseInt(match[1], 10);
+    return Number.isInteger(line) && line > 0 ? line : null;
+}

package/dist/runtime/graphvizRenderer.d.ts

@@ -0,0 +1,24 @@
+import { type DiagramCache } from './cache.js';
+export interface RenderGraphvizRequest {
+    source: string;
+    /** Graphviz layout engine to lay the graph out with. */
+    layout: string;
+    sanitize: boolean;
+    transparentBackground: boolean;
+    /** Refuse sources larger than this many UTF-8 bytes rather than freeze the main thread. */
+    maxSourceBytes: number;
+    timeoutMs: number;
+    assetsBaseUrl: string;
+    coreVersion: string;
+    cache: DiagramCache;
+    signal?: AbortSignal;
+    /** Reports which long-running phase is in progress, so the UI can show an accurate state. */
+    onPhase?: (phase: 'loading' | 'rendering') => void;
+}
+/**
+ * Renders one Graphviz diagram to sanitized SVG.
+ *
+ * Cache hits return before the engine is even loaded, which is what keeps a page of repeated
+ * diagrams from downloading 1.4 MB it does not need.
+ */
+export declare function renderGraphvizDiagram(request: RenderGraphvizRequest): Promise<string>;

package/dist/runtime/graphvizRenderer.js

@@ -0,0 +1,95 @@
+import { loadVizRuntime } from './assetLoader.js';
+import { computeGraphvizCacheKey } from './cache.js';
+import { formatGraphvizErrors, PlantUmlError } from './errors.js';
+import { sanitizeSvgMarkup } from './sanitize.js';
+function utf8ByteLength(value) {
+    // `TextEncoder` is universal in browsers and in jsdom; the fallback keeps this honest in
+    // any exotic host that lacks it, at the cost of counting code units instead of bytes.
+    if (typeof TextEncoder === 'undefined')
+        return value.length;
+    return new TextEncoder().encode(value).length;
+}
+function abortedError() {
+    return new PlantUmlError('aborted', 'Render aborted.');
+}
+/**
+ * Runs one Graphviz layout.
+ *
+ * Deliberately **not** routed through `runtime/queue.ts`. That queue exists because the
+ * PlantUML engine keeps in-flight state in module globals, so overlapping renders corrupt
+ * each other. Viz.js has no such defect: `render` is synchronous and has returned before
+ * anything else can observe the engine, so serializing would add latency and buy nothing.
+ */
+function renderWithViz(viz, source, layout, transparentBackground) {
+    // Checked against the live engine rather than only against the compile-time list, so a
+    // fence naming an engine this build lacks fails with the available set spelled out.
+    if (!viz.engines.includes(layout)) {
+        throw new PlantUmlError('config', `Unknown Graphviz layout engine '${layout}'. This build supports: ` +
+            `${viz.engines.join(', ')}.`);
+    }
+    let result;
+    try {
+        result = viz.render(source, {
+            format: 'svg',
+            engine: layout,
+            // Graphviz paints an opaque white rectangle over the whole canvas unless told not to,
+            // which would show as a white slab on a dark page. `transparent` omits it entirely.
+            ...(transparentBackground ? { graphAttributes: { bgcolor: 'transparent' } } : {}),
+        });
+    }
+    catch (error) {
+        // `render` reports invalid DOT in its result rather than by throwing, so reaching here
+        // means the engine itself broke — a different failure with a different explanation.
+        throw new PlantUmlError('engine', 'The Graphviz engine failed while laying out this diagram.', {
+            cause: error,
+        });
+    }
+    if (result.status !== 'success') {
+        throw new PlantUmlError('syntax', formatGraphvizErrors(result.errors));
+    }
+    return result.output;
+}
+/**
+ * Renders one Graphviz diagram to sanitized SVG.
+ *
+ * Cache hits return before the engine is even loaded, which is what keeps a page of repeated
+ * diagrams from downloading 1.4 MB it does not need.
+ */
+export async function renderGraphvizDiagram(request) {
+    const { source, layout, sanitize, transparentBackground, maxSourceBytes, timeoutMs, cache, coreVersion, signal, onPhase, } = request;
+    if (signal?.aborted)
+        throw abortedError();
+    const cacheKey = computeGraphvizCacheKey({
+        source,
+        layout,
+        sanitized: sanitize,
+        transparentBackground,
+        coreVersion,
+    });
+    const cached = cache.get(cacheKey);
+    if (cached !== undefined)
+        return cached;
+    // Checked before loading the engine: refusing a 5 MB graph should not first cost a 1.4 MB
+    // download. Graphviz lays out synchronously, so an oversized source freezes the tab rather
+    // than merely taking a while — an explanatory panel is the better failure.
+    const bytes = utf8ByteLength(source);
+    if (bytes > maxSourceBytes) {
+        throw new PlantUmlError('too-large', `This diagram's source is ${bytes} bytes, above the ${maxSourceBytes}-byte limit. ` +
+            'Graphviz lays out synchronously, so rendering it would freeze the page. Raise ' +
+            '`graphviz.maxSourceBytes` if this diagram is genuinely meant to be this large.');
+    }
+    onPhase?.('loading');
+    const viz = await loadVizRuntime({
+        assetsBaseUrl: request.assetsBaseUrl,
+        timeoutMs,
+    });
+    // Loading is shared work that a caller-side abort cannot cancel, so the signal is re-checked
+    // afterwards: an unmounted diagram must not go on to lay out a graph nobody will see.
+    if (signal?.aborted)
+        throw abortedError();
+    onPhase?.('rendering');
+    const raw = renderWithViz(viz, source, layout, transparentBackground);
+    const svg = sanitize ? sanitizeSvgMarkup(raw) : raw;
+    cache.set(cacheKey, svg);
+    return svg;
+}

package/dist/runtime/types.d.ts

@@ -13,3 +13,44 @@ export interface PlantUmlRenderOptions {
     dark?: boolean;
 }
 export type DiagramStatus = 'idle' | 'loading' | 'rendering' | 'ready' | 'error';
+/** Which engine renders a given fence. */
+export type DiagramEngine = 'plantuml' | 'graphviz';
+/**
+ * The subset of Viz.js 3.x this plugin uses, verified against the `viz-global.js` that
+ * `@plantuml/core` ships (Viz.js 3.24.0 / Graphviz 14.1.1).
+ *
+ * `render` is deliberately preferred over `renderString`: it reports invalid DOT as a result
+ * object carrying Graphviz's own diagnostics — including the line number — instead of throwing
+ * a bare `Error`.
+ */
+export interface VizGlobal {
+    instance(): Promise<VizInstance>;
+    readonly engines: string[];
+    readonly formats: string[];
+    readonly graphvizVersion: string;
+}
+export interface VizInstance {
+    render(input: string, options?: VizRenderOptions): VizRenderResult;
+    readonly engines: string[];
+    readonly graphvizVersion: string;
+}
+export interface VizRenderOptions {
+    format?: string;
+    engine?: string;
+    graphAttributes?: Record<string, string | number | boolean>;
+    nodeAttributes?: Record<string, string | number | boolean>;
+    edgeAttributes?: Record<string, string | number | boolean>;
+}
+export interface VizRenderError {
+    level?: 'error' | 'warning';
+    message: string;
+}
+export type VizRenderResult = {
+    status: 'success';
+    output: string;
+    errors: VizRenderError[];
+} | {
+    status: 'failure';
+    output: undefined;
+    errors: VizRenderError[];
+};

package/dist/theme/MDXComponents/Code/index.d.ts

@@ -3,14 +3,19 @@ import { type CodeBlockProps } from '../../codeBlockMeta.js';
 /**
  * Wraps Docusaurus' `MDXComponents/Code` extension point.
  *
- * Only fences whose language is configured as PlantUML are intercepted. Everything else —
- * inline code, ordinary fenced blocks, JSX-authored blocks — is delegated to the original
- * component with its props untouched, so no existing code-block behaviour changes.
+ * Only fences whose language is configured for one of the two diagram engines are
+ * intercepted. Everything else — inline code, ordinary fenced blocks, JSX-authored blocks —
+ * is delegated to the original component with its props untouched, so no existing code-block
+ * behaviour changes.
  *
  * The delegate is imported from `@theme-init/`, not `@theme-original/`. Docusaurus points
  * *both* `@theme/X` and `@theme-original/X` at the last plugin theme that provides `X`, so
  * a plugin importing `@theme-original/MDXComponents/Code` imports itself and recurses until
  * the stack overflows. `@theme-init/X` is the alias that keeps pointing at the first theme
  * to provide the component — see `docs/adr/0001-theme-init-alias.md`.
+ *
+ * Handling both engines in this one wrapper is not merely convenient: only one plugin can
+ * usefully wrap this component, so two engines shipped as two plugins would silently disable
+ * each other. That is the reason Graphviz lives here rather than in a package of its own.
  */
 export default function Code(props: CodeBlockProps): ReactNode;

package/dist/theme/MDXComponents/Code/index.js

@@ -1,28 +1,51 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import OriginalCode from '@theme-init/MDXComponents/Code';
 import PlantUmlDiagram from '@theme/PlantUmlDiagram';
-import { extractLanguage, extractSource, parseBooleanMeta, parseTitle, } from '../../codeBlockMeta.js';
+import { extractLanguage, extractSource, parseBooleanMeta, parseStringMeta, parseTitle, } from '../../codeBlockMeta.js';
 import { usePlantUmlConfig } from '../../usePlantUmlConfig.js';
 /**
  * Wraps Docusaurus' `MDXComponents/Code` extension point.
  *
- * Only fences whose language is configured as PlantUML are intercepted. Everything else —
- * inline code, ordinary fenced blocks, JSX-authored blocks — is delegated to the original
- * component with its props untouched, so no existing code-block behaviour changes.
+ * Only fences whose language is configured for one of the two diagram engines are
+ * intercepted. Everything else — inline code, ordinary fenced blocks, JSX-authored blocks —
+ * is delegated to the original component with its props untouched, so no existing code-block
+ * behaviour changes.
  *
  * The delegate is imported from `@theme-init/`, not `@theme-original/`. Docusaurus points
  * *both* `@theme/X` and `@theme-original/X` at the last plugin theme that provides `X`, so
  * a plugin importing `@theme-original/MDXComponents/Code` imports itself and recurses until
  * the stack overflows. `@theme-init/X` is the alias that keeps pointing at the first theme
  * to provide the component — see `docs/adr/0001-theme-init-alias.md`.
+ *
+ * Handling both engines in this one wrapper is not merely convenient: only one plugin can
+ * usefully wrap this component, so two engines shipped as two plugins would silently disable
+ * each other. That is the reason Graphviz lives here rather than in a package of its own.
  */
 export default function Code(props) {
     const config = usePlantUmlConfig();
     const language = extractLanguage(props);
-    const isPlantUml = config !== null && language !== undefined && config.options.languages.includes(language);
-    const source = isPlantUml ? extractSource(props.children) : null;
-    if (!isPlantUml || source === null) {
+    const engine = matchEngine(config, language);
+    const source = engine !== null ? extractSource(props.children) : null;
+    if (engine === null || source === null) {
         return _jsx(OriginalCode, { ...props });
     }
-    return (_jsx(PlantUmlDiagram, { source: source, title: parseTitle(props), language: language, zoom: parseBooleanMeta(props, 'zoom') }));
+    return (_jsx(PlantUmlDiagram, { source: source, title: parseTitle(props), language: language, engine: engine, layout: engine === 'graphviz' ? parseStringMeta(props, 'engine') : undefined, zoom: parseBooleanMeta(props, 'zoom') }));
+}
+/**
+ * Decides which engine — if either — owns this fence.
+ *
+ * `resolveOptions` rejects a configuration where both engines claim the same language, so the
+ * order these are checked in cannot change what a site renders.
+ */
+function matchEngine(config, language) {
+    if (config === null || language === undefined)
+        return null;
+    if (config.options.languages.includes(language))
+        return 'plantuml';
+    // `usePlantUmlConfig` fills the group in when older global data lacks it, so it is always
+    // present here even if the site's `.docusaurus` cache predates Graphviz support.
+    const { graphviz } = config.options;
+    if (graphviz.enabled && graphviz.languages.includes(language))
+        return 'graphviz';
+    return null;
 }

package/dist/theme/PlantUmlDiagram/index.d.ts

@@ -1,11 +1,19 @@
 import { type ReactNode } from 'react';
+import type { DiagramEngine } from '../../runtime/types.js';
 export interface PlantUmlDiagramProps {
-    /** Raw PlantUML source, exactly as authored between the fence markers. */
+    /** Raw diagram source, exactly as authored between the fence markers. */
     source: string;
     /** `title="..."` from the fence metastring; used as caption and accessible label. */
     title?: string;
-    /** The fence language that matched, e.g. `plantuml` or `puml`. */
+    /** The fence language that matched, e.g. `plantuml`, `puml`, `dot`. */
     language?: string;
+    /** Which engine renders this fence. Defaults to `plantuml`. */
+    engine?: DiagramEngine;
+    /**
+     * Graphviz layout engine from the fence metastring (`engine=neato`). Ignored for PlantUML,
+     * and ignored entirely when `graphviz.allowEngineOverride` is off.
+     */
+    layout?: string;
     /**
      * Overrides the `zoom` plugin option for this diagram. `undefined` follows the option.
      * Set from the fence metastring: `zoom` or `zoom=false`.
@@ -13,9 +21,13 @@ export interface PlantUmlDiagramProps {
     zoom?: boolean;
 }
 /**
- * Renders one PlantUML diagram in the browser.
+ * Renders one diagram in the browser, with either engine.
+ *
+ * The component is deliberately engine-agnostic: its job is states, ARIA, zoom and error
+ * presentation, none of which differs between PlantUML and Graphviz. Only the render call and
+ * the wording around it branch. (The name is historical — it predates Graphviz support.)
  *
  * Nothing happens during server-side rendering: the markup emitted on the server is the
  * same deferred placeholder the client renders first, so hydration never mismatches.
  */
-export default function PlantUmlDiagram({ source, title, language, zoom: zoomProp, }: PlantUmlDiagramProps): ReactNode;
+export default function PlantUmlDiagram({ source, title, language, engine, layout, zoom: zoomProp, }: PlantUmlDiagramProps): ReactNode;

package/dist/theme/PlantUmlDiagram/index.js

@@ -4,11 +4,19 @@ import { useColorMode } from '@docusaurus/theme-common';
 import { DATA_ATTR } from '../../constants.js';
 import { getSharedCache } from '../../runtime/cache.js';
 import { PlantUmlError } from '../../runtime/errors.js';
+import { renderGraphvizDiagram } from '../../runtime/graphvizRenderer.js';
 import { renderDiagram } from '../../runtime/renderer.js';
 import { usePlantUmlConfig } from '../usePlantUmlConfig.js';
 import { useZoomPan } from './useZoomPan.js';
 import styles from './styles.module.css';
-const DEFAULT_LABEL = 'PlantUML diagram';
+/**
+ * Human-readable engine names, used in labels, progress text and error headings so that a
+ * reader is told which engine is involved rather than being shown a generic failure.
+ */
+const ENGINE_LABEL = {
+    plantuml: 'PlantUML',
+    graphviz: 'Graphviz',
+};
 /** Margin large enough that a diagram is usually ready by the time it is scrolled into view. */
 const LAZY_ROOT_MARGIN = '300px';
 const INITIAL_STATE = { status: 'idle', svg: null, error: null };
@@ -27,12 +35,16 @@ function messageFor(error) {
     return 'The diagram could not be rendered.';
 }
 /**
- * Renders one PlantUML diagram in the browser.
+ * Renders one diagram in the browser, with either engine.
+ *
+ * The component is deliberately engine-agnostic: its job is states, ARIA, zoom and error
+ * presentation, none of which differs between PlantUML and Graphviz. Only the render call and
+ * the wording around it branch. (The name is historical — it predates Graphviz support.)
  *
  * Nothing happens during server-side rendering: the markup emitted on the server is the
  * same deferred placeholder the client renders first, so hydration never mismatches.
  */
-export default function PlantUmlDiagram({ source, title, language, zoom: zoomProp, }) {
+export default function PlantUmlDiagram({ source, title, language, engine = 'plantuml', layout, zoom: zoomProp, }) {
     const config = usePlantUmlConfig();
     const { colorMode } = useColorMode();
     const containerRef = useRef(null);
@@ -40,6 +52,14 @@ export default function PlantUmlDiagram({ source, title, language, zoom: zoomPro
     const themeOption = config?.options.theme ?? 'auto';
     const dark = themeOption === 'auto' ? colorMode === 'dark' : themeOption === 'dark';
     const lazy = config?.options.lazy ?? true;
+    const engineName = ENGINE_LABEL[engine];
+    const graphvizOptions = config?.options.graphviz;
+    // A fence may only pick a layout engine when the site allows it; otherwise the configured
+    // default wins silently, exactly as it would if the fence had said nothing.
+    const resolvedLayout = (graphvizOptions?.allowEngineOverride ? layout : undefined) ?? graphvizOptions?.engine ?? 'dot';
+    // Graphviz output does not depend on the colour mode — it adapts through CSS instead — so a
+    // colour-mode toggle must not re-run the render effect for a DOT diagram.
+    const renderDark = engine === 'graphviz' ? false : dark;
     // A fence flag wins over the plugin option, which in turn wins over the built-in default.
     const interactive = zoomProp ?? config?.options.zoom ?? true;
     const [state, setState] = useState(INITIAL_STATE);
@@ -47,7 +67,10 @@ export default function PlantUmlDiagram({ source, title, language, zoom: zoomPro
     // Called unconditionally, as hooks must be; it attaches nothing when not interactive.
     const zoom = useZoomPan({
         enabled: interactive && state.status === 'ready',
-        resetKey: `${source}|${dark ? 'dark' : 'light'}`,
+        // Keyed on what can change the picture. `renderDark`, not `dark`: a Graphviz diagram is
+        // not re-rendered on a colour-mode toggle, so resetting the reader's zoom would be a
+        // gratuitous jump.
+        resetKey: `${source}|${engine}|${resolvedLayout}|${renderDark ? 'dark' : 'light'}`,
     });
     useEffect(() => {
         if (!lazy || inView)
@@ -77,7 +100,7 @@ export default function PlantUmlDiagram({ source, title, language, zoom: zoomPro
             setState({
                 status: 'error',
                 svg: null,
-                error: 'PlantUML plugin data is missing. Add the plugin to the `plugins` array in your ' +
+                error: 'Diagram plugin data is missing. Add the plugin to the `plugins` array in your ' +
                     'Docusaurus configuration and restart the build.',
             });
             return undefined;
@@ -96,9 +119,8 @@ export default function PlantUmlDiagram({ source, title, language, zoom: zoomPro
                 ? previous
                 : next);
         };
-        void renderDiagram({
+        const shared = {
             source,
-            dark,
             sanitize: options.sanitizeSvg,
             timeoutMs: options.renderTimeoutMs,
             assetsBaseUrl: config.assetsBaseUrl,
@@ -106,7 +128,16 @@ export default function PlantUmlDiagram({ source, title, language, zoom: zoomPro
             cache: getSharedCache(options.cache, options.cacheMaxEntries),
             signal: controller.signal,
             onPhase: (phase) => commit({ status: phase, svg: null, error: null }),
-        })
+        };
+        const pending = engine === 'graphviz'
+            ? renderGraphvizDiagram({
+                ...shared,
+                layout: resolvedLayout,
+                transparentBackground: options.graphviz.transparentBackground,
+                maxSourceBytes: options.graphviz.maxSourceBytes,
+            })
+            : renderDiagram({ ...shared, dark: renderDark });
+        void pending
             .then((svg) => commit({ status: 'ready', svg, error: null }))
             .catch((error) => {
             if (error instanceof PlantUmlError && error.kind === 'aborted')
@@ -119,7 +150,9 @@ export default function PlantUmlDiagram({ source, title, language, zoom: zoomPro
     }, [
         inView,
         source,
-        dark,
+        renderDark,
+        engine,
+        resolvedLayout,
         config,
         config?.assetsBaseUrl,
         config?.coreVersion,
@@ -127,22 +160,26 @@ export default function PlantUmlDiagram({ source, title, language, zoom: zoomPro
         config?.options.renderTimeoutMs,
         config?.options.cache,
         config?.options.cacheMaxEntries,
+        config?.options.graphviz.transparentBackground,
+        config?.options.graphviz.maxSourceBytes,
     ]);
-    const label = title ?? DEFAULT_LABEL;
+    const label = title ?? `${engineName} diagram`;
     const busy = state.status === 'loading' || state.status === 'rendering';
     // The sanitized SVG always lives in this element, zoomable or not, so `role="img" > svg`
     // stays a stable contract for tests and for author CSS.
     const canvas = state.svg !== null && (_jsx("div", { className: styles.canvas, role: "img", "aria-label": label, 
         // Sanitized above unless `sanitizeSvg: false` was explicitly opted into.
         dangerouslySetInnerHTML: { __html: state.svg } }));
-    return (_jsxs("figure", { ref: containerRef, className: styles.figure, "aria-busy": busy || undefined, [DATA_ATTR.diagram]: language ?? 'plantuml',
+    return (_jsxs("figure", { ref: containerRef, className: styles.figure, "aria-busy": busy || undefined, [DATA_ATTR.diagram]: language ?? engine,
+        [DATA_ATTR.engine]: engine,
+        ...(engine === 'graphviz' ? { [DATA_ATTR.layout]: resolvedLayout } : {}),
         [DATA_ATTR.status]: state.status,
         [DATA_ATTR.theme]: dark ? 'dark' : 'light',
         ...(interactive ? { [DATA_ATTR.interactive]: 'true' } : {}),
         ...(zoom.maximized ? { [DATA_ATTR.maximized]: 'true' } : {}), children: [state.status === 'ready' && state.svg !== null && !interactive && canvas, state.status === 'ready' && state.svg !== null && interactive && (_jsxs("div", { ref: zoom.stageRef, className: zoom.maximized ? `${styles.stage} ${styles.maximized}` : styles.stage, children: [_jsx("div", { ref: zoom.viewportRef, className: styles.viewport, tabIndex: 0, "aria-describedby": hintId, "aria-keyshortcuts": "Plus Minus 0 ArrowUp ArrowDown ArrowLeft ArrowRight", onKeyDown: zoom.onKeyDown, [DATA_ATTR.zoom]: '1', children: _jsx("div", { ref: zoom.layerRef, className: styles.layer, children: canvas }) }), _jsxs("div", { className: styles.toolbar, role: "group", "aria-label": `${label} zoom controls`, children: [_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Zoom out", onClick: zoom.zoomOut, children: _jsx("span", { "aria-hidden": "true", children: "\u2212" }) }), _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Zoom in", onClick: zoom.zoomIn, children: _jsx("span", { "aria-hidden": "true", children: "+" }) }), _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Reset zoom", onClick: zoom.reset, children: _jsx("span", { "aria-hidden": "true", children: "\u27F2" }) }), _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Maximize diagram", "aria-pressed": zoom.maximized, onClick: zoom.toggleMaximize, children: _jsx("span", { "aria-hidden": "true", children: zoom.maximized ? '✕' : '⛶' }) }), _jsx("span", { ref: zoom.readoutRef, className: styles.readout, "aria-hidden": "true", children: "100%" })] })] })), state.status === 'ready' && state.svg !== null && interactive && (_jsx("p", { id: hintId, className: styles.visuallyHidden, children: "Zoomable diagram. Use the zoom controls, or press plus and minus to zoom, the arrow keys to pan, and zero to reset." })), state.status !== 'ready' && state.status !== 'error' && (
             // `aria-busy` on the figure already conveys progress; announcing every phase change
             // would make a page with several diagrams unusable with a screen reader.
-            _jsxs("div", { className: styles.placeholder, children: [_jsx("span", { className: styles.spinner, "aria-hidden": "true" }), _jsxs("span", { children: [state.status === 'loading' ? 'Loading PlantUML runtime…' : null, state.status === 'rendering' ? `Rendering ${label}…` : null, state.status === 'idle' ? `${label} (waiting to render)` : null] })] })), state.status === 'error' && (_jsxs("div", { className: styles.error, role: "alert", children: [_jsxs("p", { className: styles.errorHeading, children: [_jsx("span", { className: styles.errorIcon, "aria-hidden": "true", children: "\u26A0" }), _jsx("span", { children: "Error: PlantUML diagram could not be rendered" })] }), _jsx("pre", { className: styles.errorMessage, children: state.error }), config?.options.showSourceOnError !== false && (_jsxs("details", { className: styles.errorDetails, children: [_jsx("summary", { children: "Show diagram source" }), _jsx("pre", { className: styles.source, children: source })] }))] })), title !== undefined && _jsx("figcaption", { className: styles.caption, children: title }), _jsx("noscript", { dangerouslySetInnerHTML: {
+            _jsxs("div", { className: styles.placeholder, children: [_jsx("span", { className: styles.spinner, "aria-hidden": "true" }), _jsxs("span", { children: [state.status === 'loading' ? `Loading ${engineName} runtime…` : null, state.status === 'rendering' ? `Rendering ${label}…` : null, state.status === 'idle' ? `${label} (waiting to render)` : null] })] })), state.status === 'error' && (_jsxs("div", { className: styles.error, role: "alert", children: [_jsxs("p", { className: styles.errorHeading, children: [_jsx("span", { className: styles.errorIcon, "aria-hidden": "true", children: "\u26A0" }), _jsxs("span", { children: ["Error: ", engineName, " diagram could not be rendered"] })] }), _jsx("pre", { className: styles.errorMessage, children: state.error }), config?.options.showSourceOnError !== false && (_jsxs("details", { className: styles.errorDetails, children: [_jsx("summary", { children: "Show diagram source" }), _jsx("pre", { className: styles.source, children: source })] }))] })), title !== undefined && _jsx("figcaption", { className: styles.caption, children: title }), _jsx("noscript", { dangerouslySetInnerHTML: {
                     __html: `<pre class="${styles.source ?? ''}">${escapeHtml(source)}</pre>`,
                 } })] }));
 }

package/dist/theme/PlantUmlDiagram/styles.module.css

@@ -14,6 +14,37 @@
   height: auto;
 }
 
+/*
+ * Graphviz colour adaptation.
+ *
+ * Graphviz has no dark theme: it draws black on white regardless of the page. Rather than
+ * re-rendering the graph for each colour mode — which would double the cache and fight authors
+ * who set their own colours — the *defaults* are retargeted at `currentColor`, so a diagram
+ * inherits the page's text colour in both modes.
+ *
+ * The selectors are deliberately narrow. Graphviz emits `stroke="black"` / `fill="black"` for
+ * everything it colours by default, and leaves `<text>` with no fill at all; anything the DOT
+ * source colours explicitly comes out as that colour (`stroke="red"`, `fill="lightblue"`) and
+ * is therefore never matched here. Colours set in the diagram source always win.
+ *
+ * `fill="none"` is likewise untouched, which is what keeps unfilled node shapes unfilled.
+ */
+[data-diagram-engine='graphviz'] .canvas svg text:not([fill]) {
+  fill: currentColor;
+}
+
+[data-diagram-engine='graphviz'] .canvas svg [stroke='black'],
+[data-diagram-engine='graphviz'] .canvas svg [stroke='#000000'],
+[data-diagram-engine='graphviz'] .canvas svg [stroke='#000'] {
+  stroke: currentColor;
+}
+
+[data-diagram-engine='graphviz'] .canvas svg [fill='black'],
+[data-diagram-engine='graphviz'] .canvas svg [fill='#000000'],
+[data-diagram-engine='graphviz'] .canvas svg [fill='#000'] {
+  fill: currentColor;
+}
+
 /*
  * Zoom and pan.
  *

package/dist/theme/PlantUmlDiagram/useZoomPan.js

@@ -121,8 +121,6 @@ export function useZoomPan({ enabled, resetKey }) {
         const viewport = viewportRef.current;
         if (!viewport)
             return undefined;
-        // The layer node is replaced whenever the rendered SVG changes; start from a clean view.
-        write(IDENTITY);
         let dragging = false;
         let pointerId = null;
         let startX = 0;
@@ -255,9 +253,16 @@ export function useZoomPan({ enabled, resetKey }) {
         // the listeners against a clean view.
     }, [apply, enabled, measure, resetKey, write]);
     /**
-     * A cache hit resolves before any phase is reported, so a colour-mode toggle can go
-     * `ready -> ready` without ever unmounting the layer. The effect above would not re-run in
-     * that case, which is why the reset is also driven directly by `resetKey`.
+     * The single owner of "reset the view".
+     *
+     * `resetKey` identifies the rendered picture, so this covers both a new diagram and a
+     * colour-mode change — including the case where a cache hit resolves before any phase is
+     * reported and the component goes `ready -> ready` without the layer ever unmounting.
+     *
+     * The listener effect deliberately does *not* also reset. Its dependencies are a superset of
+     * this one's, so any re-attach for an unrelated reason — a remount, or a callback identity
+     * change from a future refactor — would silently throw away a zoom the reader had chosen.
+     * One owner means a reset happens when the picture changes, and at no other time.
      */
     useEffect(() => {
         if (!enabled)

package/dist/theme/codeBlockMeta.d.ts

@@ -32,5 +32,14 @@ export declare function extractSource(children: ReactNode): string | null;
  * unrecognized value is ignored rather than failing the site build.
  */
 export declare function parseBooleanMeta(props: CodeBlockProps, key: string): boolean | undefined;
+/**
+ * Reads a `key=value` pair from the fence metastring, accepting `engine=neato`,
+ * `engine="neato"` and `engine='neato'` alike.
+ *
+ * Unlike {@link parseBooleanMeta} this runs against the raw metastring, because the value it
+ * is looking for may itself be the quoted part. Returns `undefined` when the key is absent or
+ * carries no value, which the caller reads as "fall back to the plugin option".
+ */
+export declare function parseStringMeta(props: CodeBlockProps, key: string): string | undefined;
 /** Reads `title="..."` (or `title='...'`) from the fence metastring. */
 export declare function parseTitle(props: CodeBlockProps): string | undefined;