@matfsw/docusaurus-plantuml-plugin 1.0.3 → 1.1.1

package/dist/index.cjs

@@ -80,17 +80,42 @@ function locatePlantUmlCore() {
   const packageDir = import_node_path.default.dirname(packageJsonPath);
   const packageJson = JSON.parse(import_node_fs.default.readFileSync(packageJsonPath, "utf8"));
   const version = typeof packageJson.version === "string" ? packageJson.version : "0.0.0";
-  return {
-    packageDir,
-    version,
-    files: [
-      import_node_path.default.join(packageDir, VIZ_SCRIPT_FILENAME),
-      import_node_path.default.join(packageDir, PLANTUML_MODULE_FILENAME)
-    ]
-  };
+  const files = [
+    import_node_path.default.join(packageDir, VIZ_SCRIPT_FILENAME),
+    import_node_path.default.join(packageDir, PLANTUML_MODULE_FILENAME)
+  ];
+  files.forEach((file) => assertRuntimeFile(file, version));
+  return { packageDir, version, files };
+}
+function assertRuntimeFile(file, version) {
+  if (import_node_fs.default.existsSync(file)) return;
+  throw new Error(
+    `[${PLUGIN_NAME}] '@plantuml/core@${version}' does not contain '${import_node_path.default.basename(file)}', which this plugin serves as a runtime asset. This means the installed version of @plantuml/core is not one this plugin supports. Pin a supported version, or open an issue if the package has genuinely changed its layout.`
+  );
 }
 
 // src/options.ts
+var GRAPHVIZ_ENGINES = [
+  "circo",
+  "dot",
+  "fdp",
+  "neato",
+  "nop",
+  "nop1",
+  "nop2",
+  "osage",
+  "patchwork",
+  "sfdp",
+  "twopi"
+];
+var DEFAULT_GRAPHVIZ_OPTIONS = {
+  enabled: true,
+  languages: ["dot", "graphviz", "gv"],
+  engine: "dot",
+  allowEngineOverride: true,
+  maxSourceBytes: 1e5,
+  transparentBackground: true
+};
 var DEFAULT_OPTIONS = {
   languages: ["plantuml", "puml"],
   theme: "auto",
@@ -100,7 +125,8 @@ var DEFAULT_OPTIONS = {
   showSourceOnError: true,
   renderTimeoutMs: 2e4,
   cacheMaxEntries: 50,
-  zoom: true
+  zoom: true,
+  graphviz: DEFAULT_GRAPHVIZ_OPTIONS
 };
 var CACHE_MODES = ["none", "memory", "session"];
 var THEMES = ["auto", "light", "dark"];
@@ -128,28 +154,85 @@ function validateBoolean(value, key, fallback) {
   }
   return value;
 }
-function validateLanguages(value) {
-  if (value === void 0) return [...DEFAULT_OPTIONS.languages];
+function validateLanguages(value, key, fallback) {
+  if (value === void 0) return [...fallback];
   if (!Array.isArray(value)) {
-    fail(`options.languages must be an array of strings, received ${JSON.stringify(value)}.`);
+    fail(`options.${key} must be an array of strings, received ${JSON.stringify(value)}.`);
   }
   if (value.length === 0) {
-    fail("options.languages must contain at least one language.");
+    fail(`options.${key} must contain at least one language.`);
   }
   const normalized = value.map((entry, index) => {
     if (typeof entry !== "string" || entry.trim() === "") {
       fail(
-        `options.languages[${index}] must be a non-empty string, received ${JSON.stringify(entry)}.`
+        `options.${key}[${index}] must be a non-empty string, received ${JSON.stringify(entry)}.`
       );
     }
     return entry.trim().toLowerCase();
   });
   const duplicates = normalized.filter((entry, index) => normalized.indexOf(entry) !== index);
   if (duplicates.length > 0) {
-    fail(`options.languages contains duplicate entries: ${quoteList([...new Set(duplicates)])}.`);
+    fail(`options.${key} contains duplicate entries: ${quoteList([...new Set(duplicates)])}.`);
   }
   return normalized;
 }
+function validateMaxSourceBytes(value) {
+  if (value === void 0) return DEFAULT_GRAPHVIZ_OPTIONS.maxSourceBytes;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+    fail(
+      `options.graphviz.maxSourceBytes must be a positive integer, received ${JSON.stringify(value)}.`
+    );
+  }
+  return value;
+}
+function validateGraphviz(value) {
+  if (value === void 0) {
+    return { ...DEFAULT_GRAPHVIZ_OPTIONS, languages: [...DEFAULT_GRAPHVIZ_OPTIONS.languages] };
+  }
+  if (!isPlainObject(value)) {
+    fail(`options.graphviz must be an object, received ${JSON.stringify(value)}.`);
+  }
+  const allowedKeys = [
+    "enabled",
+    "languages",
+    "engine",
+    "allowEngineOverride",
+    "maxSourceBytes",
+    "transparentBackground"
+  ];
+  const unknownKeys = Object.keys(value).filter((key) => !allowedKeys.includes(key));
+  if (unknownKeys.length > 0) {
+    fail(
+      `Unknown option${unknownKeys.length > 1 ? "s" : ""} ${quoteList(unknownKeys.map((key) => `graphviz.${key}`))}. Supported options: ${quoteList(allowedKeys.map((key) => `graphviz.${key}`))}.`
+    );
+  }
+  const { engine } = value;
+  if (engine !== void 0 && !GRAPHVIZ_ENGINES.includes(engine)) {
+    fail(
+      `options.graphviz.engine must be one of ${quoteList(GRAPHVIZ_ENGINES)}, received ${JSON.stringify(engine)}.`
+    );
+  }
+  return {
+    enabled: validateBoolean(value.enabled, "graphviz.enabled", DEFAULT_GRAPHVIZ_OPTIONS.enabled),
+    languages: validateLanguages(
+      value.languages,
+      "graphviz.languages",
+      DEFAULT_GRAPHVIZ_OPTIONS.languages
+    ),
+    engine: engine ?? DEFAULT_GRAPHVIZ_OPTIONS.engine,
+    allowEngineOverride: validateBoolean(
+      value.allowEngineOverride,
+      "graphviz.allowEngineOverride",
+      DEFAULT_GRAPHVIZ_OPTIONS.allowEngineOverride
+    ),
+    maxSourceBytes: validateMaxSourceBytes(value.maxSourceBytes),
+    transparentBackground: validateBoolean(
+      value.transparentBackground,
+      "graphviz.transparentBackground",
+      DEFAULT_GRAPHVIZ_OPTIONS.transparentBackground
+    )
+  };
+}
 function validateRenderTimeout(value) {
   if (value === void 0) return DEFAULT_OPTIONS.renderTimeoutMs;
   if (typeof value !== "number" || !Number.isFinite(value)) {
@@ -174,7 +257,11 @@ function validateCacheMaxEntries(value) {
 }
 function resolveOptions(rawOptions) {
   if (rawOptions === void 0 || rawOptions === null) {
-    return { ...DEFAULT_OPTIONS, languages: [...DEFAULT_OPTIONS.languages] };
+    return {
+      ...DEFAULT_OPTIONS,
+      languages: [...DEFAULT_OPTIONS.languages],
+      graphviz: { ...DEFAULT_GRAPHVIZ_OPTIONS, languages: [...DEFAULT_GRAPHVIZ_OPTIONS.languages] }
+    };
   }
   if (!isPlainObject(rawOptions)) {
     fail(`options must be an object, received ${JSON.stringify(rawOptions)}.`);
@@ -189,6 +276,7 @@ function resolveOptions(rawOptions) {
     "renderTimeoutMs",
     "cacheMaxEntries",
     "zoom",
+    "graphviz",
     // Docusaurus injects `id` for multi-instance plugins.
     "id"
   ]);
@@ -207,8 +295,19 @@ function resolveOptions(rawOptions) {
       `options.cache must be one of ${quoteList(CACHE_MODES)}, received ${JSON.stringify(cache)}.`
     );
   }
+  const languages = validateLanguages(rawOptions.languages, "languages", DEFAULT_OPTIONS.languages);
+  const graphviz = validateGraphviz(rawOptions.graphviz);
+  if (graphviz.enabled) {
+    const claimedTwice = graphviz.languages.filter((entry) => languages.includes(entry));
+    if (claimedTwice.length > 0) {
+      fail(
+        `options.graphviz.languages and options.languages both claim ${quoteList(claimedTwice)}. A fence language can only belong to one engine.`
+      );
+    }
+  }
   return {
-    languages: validateLanguages(rawOptions.languages),
+    languages,
+    graphviz,
     theme: theme ?? DEFAULT_OPTIONS.theme,
     lazy: validateBoolean(rawOptions.lazy, "lazy", DEFAULT_OPTIONS.lazy),
     cache: cache ?? DEFAULT_OPTIONS.cache,

package/dist/index.d.cts

@@ -5,6 +5,43 @@ import { WebpackPluginInstance } from 'webpack';
 type CacheMode = 'none' | 'memory' | 'session';
 /** Which PlantUML colour scheme to render. `auto` follows the Docusaurus colour mode. */
 type DiagramTheme = 'auto' | 'light' | 'dark';
+/**
+ * Graphviz layout engines available in the bundled build.
+ *
+ * Taken from `Viz.engines` of the `viz-global.js` that `@plantuml/core` ships. The loader
+ * re-checks the requested engine against the live list at render time, so this array only has
+ * to be good enough to reject typos in `docusaurus.config.*` at build time.
+ */
+declare const GRAPHVIZ_ENGINES: readonly ["circo", "dot", "fdp", "neato", "nop", "nop1", "nop2", "osage", "patchwork", "sfdp", "twopi"];
+type GraphvizEngine = (typeof GRAPHVIZ_ENGINES)[number];
+/** Graphviz/DOT options, nested so the two engines cannot collide in the option namespace. */
+interface GraphvizOptions {
+    /** Intercept DOT fences at all. Set to `false` to leave `dot` code blocks as code blocks. */
+    enabled?: boolean;
+    /** Fenced-code languages treated as Graphviz DOT. Matched case-insensitively. */
+    languages?: string[];
+    /** Default layout engine used when a fence does not name one. */
+    engine?: GraphvizEngine;
+    /** Allow a fence to select a different layout engine with `engine=neato`. */
+    allowEngineOverride?: boolean;
+    /**
+     * Refuse to render sources larger than this many UTF-8 bytes.
+     *
+     * Graphviz renders synchronously, so an enormous graph blocks the main thread; the guard
+     * turns a frozen tab into an explanatory panel. See `docs/adr/0004-graphviz-engine-reuse.md`.
+     */
+    maxSourceBytes?: number;
+    /**
+     * Render on a transparent background instead of Graphviz's opaque white, so diagrams sit on
+     * the page background in both colour modes.
+     */
+    transparentBackground?: boolean;
+}
+/** Graphviz options after validation, with every default applied. */
+type ResolvedGraphvizOptions = Required<Omit<GraphvizOptions, 'languages'>> & {
+    /** Normalized to lower case; matching is case-insensitive. */
+    languages: string[];
+};
 /**
  * Options accepted by the plugin in `docusaurus.config.*`.
  *
@@ -32,13 +69,16 @@ interface PlantUmlPluginOptions {
      * Override for a single fence with `zoom` or `zoom=false` in its metastring.
      */
     zoom?: boolean;
+    /** Graphviz/DOT diagram support. See {@link GraphvizOptions}. */
+    graphviz?: GraphvizOptions;
     /** Docusaurus plugin instance id, used when the plugin is registered more than once. */
     id?: string;
 }
 /** Plugin options after validation, with every default applied. */
-type ResolvedPlantUmlOptions = Required<Omit<PlantUmlPluginOptions, 'id' | 'languages'>> & {
+type ResolvedPlantUmlOptions = Required<Omit<PlantUmlPluginOptions, 'id' | 'languages' | 'graphviz'>> & {
     /** Normalized to lower case; matching is case-insensitive. */
     languages: string[];
+    graphviz: ResolvedGraphvizOptions;
 };
 declare const DEFAULT_OPTIONS: ResolvedPlantUmlOptions;
 /** Thrown for invalid plugin options so Docusaurus fails the build with a useful message. */

package/dist/options.d.ts

@@ -2,6 +2,43 @@
 export type CacheMode = 'none' | 'memory' | 'session';
 /** Which PlantUML colour scheme to render. `auto` follows the Docusaurus colour mode. */
 export type DiagramTheme = 'auto' | 'light' | 'dark';
+/**
+ * Graphviz layout engines available in the bundled build.
+ *
+ * Taken from `Viz.engines` of the `viz-global.js` that `@plantuml/core` ships. The loader
+ * re-checks the requested engine against the live list at render time, so this array only has
+ * to be good enough to reject typos in `docusaurus.config.*` at build time.
+ */
+export declare const GRAPHVIZ_ENGINES: readonly ["circo", "dot", "fdp", "neato", "nop", "nop1", "nop2", "osage", "patchwork", "sfdp", "twopi"];
+export type GraphvizEngine = (typeof GRAPHVIZ_ENGINES)[number];
+/** Graphviz/DOT options, nested so the two engines cannot collide in the option namespace. */
+export interface GraphvizOptions {
+    /** Intercept DOT fences at all. Set to `false` to leave `dot` code blocks as code blocks. */
+    enabled?: boolean;
+    /** Fenced-code languages treated as Graphviz DOT. Matched case-insensitively. */
+    languages?: string[];
+    /** Default layout engine used when a fence does not name one. */
+    engine?: GraphvizEngine;
+    /** Allow a fence to select a different layout engine with `engine=neato`. */
+    allowEngineOverride?: boolean;
+    /**
+     * Refuse to render sources larger than this many UTF-8 bytes.
+     *
+     * Graphviz renders synchronously, so an enormous graph blocks the main thread; the guard
+     * turns a frozen tab into an explanatory panel. See `docs/adr/0004-graphviz-engine-reuse.md`.
+     */
+    maxSourceBytes?: number;
+    /**
+     * Render on a transparent background instead of Graphviz's opaque white, so diagrams sit on
+     * the page background in both colour modes.
+     */
+    transparentBackground?: boolean;
+}
+/** Graphviz options after validation, with every default applied. */
+export type ResolvedGraphvizOptions = Required<Omit<GraphvizOptions, 'languages'>> & {
+    /** Normalized to lower case; matching is case-insensitive. */
+    languages: string[];
+};
 /**
  * Options accepted by the plugin in `docusaurus.config.*`.
  *
@@ -29,14 +66,18 @@ export interface PlantUmlPluginOptions {
      * Override for a single fence with `zoom` or `zoom=false` in its metastring.
      */
     zoom?: boolean;
+    /** Graphviz/DOT diagram support. See {@link GraphvizOptions}. */
+    graphviz?: GraphvizOptions;
     /** Docusaurus plugin instance id, used when the plugin is registered more than once. */
     id?: string;
 }
 /** Plugin options after validation, with every default applied. */
-export type ResolvedPlantUmlOptions = Required<Omit<PlantUmlPluginOptions, 'id' | 'languages'>> & {
+export type ResolvedPlantUmlOptions = Required<Omit<PlantUmlPluginOptions, 'id' | 'languages' | 'graphviz'>> & {
     /** Normalized to lower case; matching is case-insensitive. */
     languages: string[];
+    graphviz: ResolvedGraphvizOptions;
 };
+export declare const DEFAULT_GRAPHVIZ_OPTIONS: ResolvedGraphvizOptions;
 export declare const DEFAULT_OPTIONS: ResolvedPlantUmlOptions;
 /** Thrown for invalid plugin options so Docusaurus fails the build with a useful message. */
 export declare class PlantUmlOptionsError extends Error {

package/dist/options.js

@@ -1,4 +1,32 @@
 import { PLUGIN_NAME } from './constants.js';
+/**
+ * Graphviz layout engines available in the bundled build.
+ *
+ * Taken from `Viz.engines` of the `viz-global.js` that `@plantuml/core` ships. The loader
+ * re-checks the requested engine against the live list at render time, so this array only has
+ * to be good enough to reject typos in `docusaurus.config.*` at build time.
+ */
+export const GRAPHVIZ_ENGINES = [
+    'circo',
+    'dot',
+    'fdp',
+    'neato',
+    'nop',
+    'nop1',
+    'nop2',
+    'osage',
+    'patchwork',
+    'sfdp',
+    'twopi',
+];
+export const DEFAULT_GRAPHVIZ_OPTIONS = {
+    enabled: true,
+    languages: ['dot', 'graphviz', 'gv'],
+    engine: 'dot',
+    allowEngineOverride: true,
+    maxSourceBytes: 100_000,
+    transparentBackground: true,
+};
 export const DEFAULT_OPTIONS = {
     languages: ['plantuml', 'puml'],
     theme: 'auto',
@@ -9,6 +37,7 @@ export const DEFAULT_OPTIONS = {
     renderTimeoutMs: 20_000,
     cacheMaxEntries: 50,
     zoom: true,
+    graphviz: DEFAULT_GRAPHVIZ_OPTIONS,
 };
 const CACHE_MODES = ['none', 'memory', 'session'];
 const THEMES = ['auto', 'light', 'dark'];
@@ -38,27 +67,78 @@ function validateBoolean(value, key, fallback) {
     }
     return value;
 }
-function validateLanguages(value) {
+/** Shared by `options.languages` and `options.graphviz.languages`; `key` names the one in play. */
+function validateLanguages(value, key, fallback) {
     if (value === undefined)
-        return [...DEFAULT_OPTIONS.languages];
+        return [...fallback];
     if (!Array.isArray(value)) {
-        fail(`options.languages must be an array of strings, received ${JSON.stringify(value)}.`);
+        fail(`options.${key} must be an array of strings, received ${JSON.stringify(value)}.`);
     }
     if (value.length === 0) {
-        fail('options.languages must contain at least one language.');
+        fail(`options.${key} must contain at least one language.`);
     }
     const normalized = value.map((entry, index) => {
         if (typeof entry !== 'string' || entry.trim() === '') {
-            fail(`options.languages[${index}] must be a non-empty string, received ${JSON.stringify(entry)}.`);
+            fail(`options.${key}[${index}] must be a non-empty string, received ${JSON.stringify(entry)}.`);
         }
         return entry.trim().toLowerCase();
     });
     const duplicates = normalized.filter((entry, index) => normalized.indexOf(entry) !== index);
     if (duplicates.length > 0) {
-        fail(`options.languages contains duplicate entries: ${quoteList([...new Set(duplicates)])}.`);
+        fail(`options.${key} contains duplicate entries: ${quoteList([...new Set(duplicates)])}.`);
     }
     return normalized;
 }
+function validateMaxSourceBytes(value) {
+    if (value === undefined)
+        return DEFAULT_GRAPHVIZ_OPTIONS.maxSourceBytes;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+        fail('options.graphviz.maxSourceBytes must be a positive integer, ' +
+            `received ${JSON.stringify(value)}.`);
+    }
+    return value;
+}
+/**
+ * Validates the nested `graphviz` group.
+ *
+ * Unknown keys are rejected here too: a typo nested one level deep is exactly as silent — and
+ * exactly as confusing — as a typo at the top level.
+ */
+function validateGraphviz(value) {
+    if (value === undefined) {
+        return { ...DEFAULT_GRAPHVIZ_OPTIONS, languages: [...DEFAULT_GRAPHVIZ_OPTIONS.languages] };
+    }
+    if (!isPlainObject(value)) {
+        fail(`options.graphviz must be an object, received ${JSON.stringify(value)}.`);
+    }
+    const allowedKeys = [
+        'enabled',
+        'languages',
+        'engine',
+        'allowEngineOverride',
+        'maxSourceBytes',
+        'transparentBackground',
+    ];
+    const unknownKeys = Object.keys(value).filter((key) => !allowedKeys.includes(key));
+    if (unknownKeys.length > 0) {
+        fail(`Unknown option${unknownKeys.length > 1 ? 's' : ''} ` +
+            `${quoteList(unknownKeys.map((key) => `graphviz.${key}`))}. ` +
+            `Supported options: ${quoteList(allowedKeys.map((key) => `graphviz.${key}`))}.`);
+    }
+    const { engine } = value;
+    if (engine !== undefined && !GRAPHVIZ_ENGINES.includes(engine)) {
+        fail(`options.graphviz.engine must be one of ${quoteList(GRAPHVIZ_ENGINES)}, ` +
+            `received ${JSON.stringify(engine)}.`);
+    }
+    return {
+        enabled: validateBoolean(value.enabled, 'graphviz.enabled', DEFAULT_GRAPHVIZ_OPTIONS.enabled),
+        languages: validateLanguages(value.languages, 'graphviz.languages', DEFAULT_GRAPHVIZ_OPTIONS.languages),
+        engine: engine ?? DEFAULT_GRAPHVIZ_OPTIONS.engine,
+        allowEngineOverride: validateBoolean(value.allowEngineOverride, 'graphviz.allowEngineOverride', DEFAULT_GRAPHVIZ_OPTIONS.allowEngineOverride),
+        maxSourceBytes: validateMaxSourceBytes(value.maxSourceBytes),
+        transparentBackground: validateBoolean(value.transparentBackground, 'graphviz.transparentBackground', DEFAULT_GRAPHVIZ_OPTIONS.transparentBackground),
+    };
+}
 function validateRenderTimeout(value) {
     if (value === undefined)
         return DEFAULT_OPTIONS.renderTimeoutMs;
@@ -90,7 +170,11 @@ function validateCacheMaxEntries(value) {
  */
 export function resolveOptions(rawOptions) {
     if (rawOptions === undefined || rawOptions === null) {
-        return { ...DEFAULT_OPTIONS, languages: [...DEFAULT_OPTIONS.languages] };
+        return {
+            ...DEFAULT_OPTIONS,
+            languages: [...DEFAULT_OPTIONS.languages],
+            graphviz: { ...DEFAULT_GRAPHVIZ_OPTIONS, languages: [...DEFAULT_GRAPHVIZ_OPTIONS.languages] },
+        };
     }
     if (!isPlainObject(rawOptions)) {
         fail(`options must be an object, received ${JSON.stringify(rawOptions)}.`);
@@ -105,6 +189,7 @@ export function resolveOptions(rawOptions) {
         'renderTimeoutMs',
         'cacheMaxEntries',
         'zoom',
+        'graphviz',
         // Docusaurus injects `id` for multi-instance plugins.
         'id',
     ]);
@@ -120,8 +205,20 @@ export function resolveOptions(rawOptions) {
     if (cache !== undefined && !CACHE_MODES.includes(cache)) {
         fail(`options.cache must be one of ${quoteList(CACHE_MODES)}, received ${JSON.stringify(cache)}.`);
     }
+    const languages = validateLanguages(rawOptions.languages, 'languages', DEFAULT_OPTIONS.languages);
+    const graphviz = validateGraphviz(rawOptions.graphviz);
+    // A fence has exactly one language, so a language claimed by both engines would make the
+    // rendered output depend on the order the wrapper happens to check them in. Reject it.
+    if (graphviz.enabled) {
+        const claimedTwice = graphviz.languages.filter((entry) => languages.includes(entry));
+        if (claimedTwice.length > 0) {
+            fail(`options.graphviz.languages and options.languages both claim ` +
+                `${quoteList(claimedTwice)}. A fence language can only belong to one engine.`);
+        }
+    }
     return {
-        languages: validateLanguages(rawOptions.languages),
+        languages,
+        graphviz,
         theme: theme ?? DEFAULT_OPTIONS.theme,
         lazy: validateBoolean(rawOptions.lazy, 'lazy', DEFAULT_OPTIONS.lazy),
         cache: cache ?? DEFAULT_OPTIONS.cache,

package/dist/runtime/assetLoader.d.ts

@@ -1,4 +1,4 @@
-import type { PlantUmlCoreModule } from './types.js';
+import type { PlantUmlCoreModule, VizInstance } from './types.js';
 export interface LoadRuntimeOptions {
     /** Absolute, `baseUrl`-prefixed directory URL containing the two runtime files. */
     assetsBaseUrl: string;
@@ -10,6 +10,14 @@ export interface LoadRuntimeOptions {
      */
     importModule?: (url: string) => Promise<unknown>;
 }
+/**
+ * Resolves a ready-to-use Graphviz instance, loading `viz-global.js` on first use.
+ *
+ * One instance serves every DOT diagram on the page: Viz.js documents that an instance renders
+ * multiple graphs, and a 200-render soak with syntax errors interleaved left it fully healthy,
+ * so there is no reason to pay the instantiation cost per diagram.
+ */
+export declare function loadVizRuntime(options: LoadRuntimeOptions): Promise<VizInstance>;
 /**
  * Resolves the PlantUML engine, loading it on first use.
  *
@@ -17,7 +25,9 @@ export interface LoadRuntimeOptions {
  * diagram can retry rather than inheriting a permanent failure.
  */
 export declare function loadPlantUmlRuntime(options: LoadRuntimeOptions): Promise<PlantUmlCoreModule>;
-/** Whether the runtime has been requested on this page. Used by tests and diagnostics. */
+/** Whether the PlantUML runtime has been requested on this page. For tests and diagnostics. */
 export declare function isRuntimeRequested(): boolean;
-/** Test-only: forgets the cached runtime and removes the injected script tag. */
+/** Whether the Graphviz runtime has been requested on this page. For tests and diagnostics. */
+export declare function isVizRuntimeRequested(): boolean;
+/** Test-only: forgets both cached runtimes and removes the injected script tag. */
 export declare function resetRuntimeLoader(): void;

package/dist/runtime/assetLoader.js

@@ -1,14 +1,21 @@
 import { PLANTUML_MODULE_FILENAME, VIZ_SCRIPT_FILENAME } from '../constants.js';
 import { PlantUmlError } from './errors.js';
 /**
- * Loads the PlantUML browser runtime exactly once per page session.
+ * Loads the browser runtimes, each at most once per page session.
  *
- * `viz-global.js` is a classic script that installs the Graphviz layout engine on `window`,
- * and it must have finished executing before `plantuml.js` is imported. Both files are
- * served from the Docusaurus origin under `baseUrl`, never from a CDN.
+ * There are two, and they are loaded independently:
+ *
+ * - `viz-global.js` (~1.4 MB) is a classic script that installs Graphviz on `window.Viz`. It
+ *   is what renders DOT fences, and PlantUML also needs it for its own layout.
+ * - `plantuml.js` (~6.8 MB) is an ES module that renders PlantUML fences. It requires
+ *   `window.Viz` to already exist, so it builds on the first.
+ *
+ * The split matters: a page with only DOT diagrams must never pay for the 6.8 MB PlantUML
+ * engine. Both files are served from the Docusaurus origin under `baseUrl`, never from a CDN.
  */
 const SCRIPT_MARKER = 'data-plantuml-runtime';
 let cachedRuntime = null;
+let cachedViz = null;
 function isBrowser() {
     return typeof window !== 'undefined' && typeof document !== 'undefined';
 }
@@ -32,7 +39,7 @@ function loadVizGlobal(url, timeoutMs) {
         if (existing.dataset.plantumlRuntimeState === 'loaded')
             return Promise.resolve();
         if (existing.dataset.plantumlRuntimeState === 'error') {
-            return Promise.reject(new PlantUmlError('load', `Failed to load the PlantUML Graphviz runtime from ${url}.`));
+            return Promise.reject(new PlantUmlError('load', `Failed to load the Graphviz runtime from ${url}.`));
         }
         return waitForScript(existing, url, timeoutMs);
     }
@@ -63,7 +70,7 @@ function waitForScript(script, url, timeoutMs) {
         };
         const onError = () => {
             script.dataset.plantumlRuntimeState = 'error';
-            finish(() => reject(new PlantUmlError('load', `Failed to load the PlantUML Graphviz runtime from ${url}. ` +
+            finish(() => reject(new PlantUmlError('load', `Failed to load the Graphviz runtime from ${url}. ` +
                 'Check that the asset is served under your Docusaurus baseUrl with a JavaScript MIME type.')));
         };
         const timer = setTimeout(() => {
@@ -83,6 +90,54 @@ function assertCoreModule(value, url) {
     }
     return candidate;
 }
+/**
+ * Checks that the loaded script really installed the Viz.js API this plugin renders DOT with.
+ *
+ * `viz-global.js` reaches the browser via `@plantuml/core`, which ships it for PlantUML's own
+ * layout rather than for this plugin's benefit. Asserting the shape here means a future
+ * `@plantuml/core` that changed engines fails with a message naming the cause, instead of a
+ * `TypeError` on `Viz.instance` several frames away. See `docs/adr/0004-graphviz-engine-reuse.md`.
+ */
+function assertVizGlobal(url) {
+    const candidate = globalThis.Viz;
+    if (!candidate ||
+        typeof candidate.instance !== 'function' ||
+        !Array.isArray(candidate.engines) ||
+        typeof candidate.graphvizVersion !== 'string') {
+        throw new PlantUmlError('load', `The script at ${url} did not install the expected Graphviz (Viz.js) API on window.Viz. ` +
+            'This usually means a proxy or service worker returned the wrong file, or that the ' +
+            'installed @plantuml/core no longer bundles Viz.js.');
+    }
+    return candidate;
+}
+/**
+ * Resolves a ready-to-use Graphviz instance, loading `viz-global.js` on first use.
+ *
+ * One instance serves every DOT diagram on the page: Viz.js documents that an instance renders
+ * multiple graphs, and a 200-render soak with syntax errors interleaved left it fully healthy,
+ * so there is no reason to pay the instantiation cost per diagram.
+ */
+export function loadVizRuntime(options) {
+    if (!isBrowser()) {
+        return Promise.reject(new PlantUmlError('load', 'The Graphviz runtime cannot be loaded during server-side rendering.'));
+    }
+    if (cachedViz)
+        return cachedViz;
+    const vizUrl = joinUrl(options.assetsBaseUrl, VIZ_SCRIPT_FILENAME);
+    const viz = loadVizGlobal(vizUrl, options.timeoutMs)
+        .then(() => assertVizGlobal(vizUrl).instance())
+        .catch((error) => {
+        // Clearing the cache lets a later diagram retry rather than inherit a permanent failure.
+        cachedViz = null;
+        throw error instanceof PlantUmlError
+            ? error
+            : new PlantUmlError('load', `Failed to initialize the Graphviz engine from ${vizUrl}.`, {
+                cause: error,
+            });
+    });
+    cachedViz = viz;
+    return viz;
+}
 /**
  * Resolves the PlantUML engine, loading it on first use.
  *
@@ -112,13 +167,18 @@ export function loadPlantUmlRuntime(options) {
     cachedRuntime = runtime;
     return runtime;
 }
-/** Whether the runtime has been requested on this page. Used by tests and diagnostics. */
+/** Whether the PlantUML runtime has been requested on this page. For tests and diagnostics. */
 export function isRuntimeRequested() {
     return cachedRuntime !== null;
 }
-/** Test-only: forgets the cached runtime and removes the injected script tag. */
+/** Whether the Graphviz runtime has been requested on this page. For tests and diagnostics. */
+export function isVizRuntimeRequested() {
+    return cachedViz !== null;
+}
+/** Test-only: forgets both cached runtimes and removes the injected script tag. */
 export function resetRuntimeLoader() {
     cachedRuntime = null;
+    cachedViz = null;
     if (typeof document !== 'undefined') {
         document.querySelectorAll(`script[${SCRIPT_MARKER}]`).forEach((node) => node.remove());
     }

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. */