@matfsw/docusaurus-plantuml-plugin 1.2.0 → 1.3.0

package/dist/index.js

@@ -4,6 +4,7 @@ import CopyWebpackPlugin from 'copy-webpack-plugin';
 import { locatePlantUmlCore } from './assets.js';
 import { assetsDirForVersion, DEFAULT_PLUGIN_ID, PLUGIN_NAME } from './constants.js';
 import { resolveOptions, } from './options.js';
+import { resolveStdlibAssets } from './stdlib.js';
 export { DEFAULT_OPTIONS, PlantUmlOptionsError, resolveOptions } from './options.js';
 export { PLUGIN_ID, PLUGIN_NAME } from './constants.js';
 const currentDir = path.dirname(fileURLToPath(import.meta.url));
@@ -25,12 +26,22 @@ export function createCopyPlugin(currentBundler, patterns) {
     }
     return new CopyWebpackPlugin({ patterns });
 }
-export default function plantumlPlugin(_context, options = {}) {
+export default function plantumlPlugin(context, options = {}) {
     // Docusaurus already ran `validateOptions`, but the plugin function is also callable
     // directly (and from JS configs that skip validation), so normalize defensively.
     const resolved = resolveOptions(options);
     const core = locatePlantUmlCore();
     const assetsDir = assetsDirForVersion(core.version);
+    const stdlib = resolveStdlibAssets({
+        options: resolved.stdlib,
+        currentDir,
+        siteDir: context.siteDir,
+        cacheDir: context.generatedFilesDir,
+    });
+    // The revision is part of the directory name, not just of the cache key: refreshing the
+    // standard library without moving the URL would leave readers on a cached bundle from
+    // before the refresh, and the mismatch would surface as an unresolved include.
+    const stdlibDir = stdlib ? `${assetsDir}/stdlib-${stdlib.manifest.revision}` : null;
     return {
         name: PLUGIN_NAME,
         getThemePath() {
@@ -41,6 +52,7 @@ export default function plantumlPlugin(_context, options = {}) {
                 options: resolved,
                 assetsDir,
                 coreVersion: core.version,
+                stdlib: stdlib && stdlibDir ? { dir: stdlibDir, manifest: stdlib.manifest } : null,
             };
             actions.setGlobalData(globalData);
         },
@@ -56,6 +68,13 @@ export default function plantumlPlugin(_context, options = {}) {
                 // These files are already minified upstream; re-processing 8 MB is wasted work.
                 info: { minimized: true },
             }));
+            if (stdlib && stdlibDir) {
+                patterns.push(...stdlib.files.map((absolutePath) => ({
+                    from: absolutePath,
+                    to: `${stdlibDir}/[name][ext]`,
+                    info: { minimized: true },
+                })));
+            }
             // Optional chaining, not laziness: `currentBundler` is absent on Docusaurus 3.5.x.
             return { plugins: [createCopyPlugin(utils?.currentBundler, patterns)] };
         },

package/dist/options.d.ts

@@ -39,6 +39,50 @@ export type ResolvedGraphvizOptions = Required<Omit<GraphvizOptions, 'languages'
     /** Normalized to lower case; matching is case-insensitive. */
     languages: string[];
 };
+/**
+ * PlantUML standard library support: `!include <C4/C4_Container>` and friends.
+ *
+ * On by default and normally not worth configuring. The two lists exist for the namespaces
+ * this package does not vendor — the standard library is 265 MB in full, and several of its
+ * namespaces carry no upstream licence — which a site can still opt into from its own
+ * checkout. See `assets/stdlib/LICENSES.md` for what is vendored and under what terms.
+ */
+export interface StdlibOptions {
+    /**
+     * Resolve `!include <namespace/…>` at all. `false` (or `stdlib: false`) leaves such
+     * diagrams to fail in the engine, exactly as they did before this feature existed.
+     */
+    enabled?: boolean;
+    /**
+     * Extra namespaces to make available, beyond the vendored ones — `['aws', 'tupadr3']`.
+     * Each must be found in one of {@link StdlibOptions.source}, and the build fails naming
+     * the namespace if it is not.
+     */
+    include?: string[];
+    /**
+     * Directories to resolve {@link StdlibOptions.include} from: the `stdlib/` directory of a
+     * `plantuml-stdlib` checkout, relative to the site directory or absolute. Searched in
+     * order, before the vendored bundles, so a namespace can also be replaced with a newer one
+     * by naming it in `include`.
+     */
+    source?: string | string[];
+    /**
+     * Narrow the vendored namespaces emitted into the build, for sites that care more about
+     * build output size than about which diagrams keep working. Dependencies of the named
+     * namespaces are kept regardless. Defaults to all of them; a reader only downloads the
+     * ones a page uses either way.
+     */
+    namespaces?: string[];
+}
+/** Standard library options after validation, with every default applied. */
+export interface ResolvedStdlibOptions {
+    enabled: boolean;
+    /** Normalized to lower case. */
+    include: string[];
+    source: string[];
+    /** Normalized to lower case. `null` means "every vendored namespace". */
+    namespaces: string[] | null;
+}
 /**
  * Options accepted by the plugin in `docusaurus.config.*`.
  *
@@ -73,16 +117,23 @@ export interface PlantUmlPluginOptions {
     showSource?: boolean;
     /** Graphviz/DOT diagram support. See {@link GraphvizOptions}. */
     graphviz?: GraphvizOptions;
+    /**
+     * PlantUML standard library support. See {@link StdlibOptions}. `false` is shorthand for
+     * `{enabled: false}`.
+     */
+    stdlib?: StdlibOptions | false;
     /** 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' | 'graphviz'>> & {
+export type ResolvedPlantUmlOptions = Required<Omit<PlantUmlPluginOptions, 'id' | 'languages' | 'graphviz' | 'stdlib'>> & {
     /** Normalized to lower case; matching is case-insensitive. */
     languages: string[];
     graphviz: ResolvedGraphvizOptions;
+    stdlib: ResolvedStdlibOptions;
 };
 export declare const DEFAULT_GRAPHVIZ_OPTIONS: ResolvedGraphvizOptions;
+export declare const DEFAULT_STDLIB_OPTIONS: ResolvedStdlibOptions;
 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

@@ -27,6 +27,12 @@ export const DEFAULT_GRAPHVIZ_OPTIONS = {
     maxSourceBytes: 100_000,
     transparentBackground: true,
 };
+export const DEFAULT_STDLIB_OPTIONS = {
+    enabled: true,
+    include: [],
+    source: [],
+    namespaces: null,
+};
 export const DEFAULT_OPTIONS = {
     languages: ['plantuml', 'puml'],
     theme: 'auto',
@@ -39,6 +45,7 @@ export const DEFAULT_OPTIONS = {
     zoom: true,
     showSource: true,
     graphviz: DEFAULT_GRAPHVIZ_OPTIONS,
+    stdlib: DEFAULT_STDLIB_OPTIONS,
 };
 const CACHE_MODES = ['none', 'memory', 'session'];
 const THEMES = ['auto', 'light', 'dark'];
@@ -140,6 +147,76 @@ function validateGraphviz(value) {
         transparentBackground: validateBoolean(value.transparentBackground, 'graphviz.transparentBackground', DEFAULT_GRAPHVIZ_OPTIONS.transparentBackground),
     };
 }
+/** Shared by `stdlib.include` and `stdlib.namespaces`, which are both lists of namespaces. */
+function validateNamespaceList(value, key) {
+    if (!Array.isArray(value)) {
+        fail(`options.${key} must be an array of strings, received ${JSON.stringify(value)}.`);
+    }
+    const normalized = value.map((entry, index) => {
+        if (typeof entry !== 'string' || entry.trim() === '') {
+            fail(`options.${key}[${index}] must be a non-empty string, received ${JSON.stringify(entry)}.`);
+        }
+        // Namespaces are matched case-insensitively: the engine lower-cases `<C4/…>` before
+        // looking it up, so `'C4'` and `'c4'` have to mean the same thing here too.
+        return entry.trim().toLowerCase();
+    });
+    const duplicates = normalized.filter((entry, index) => normalized.indexOf(entry) !== index);
+    if (duplicates.length > 0) {
+        fail(`options.${key} contains duplicate entries: ${quoteList([...new Set(duplicates)])}.`);
+    }
+    return normalized;
+}
+function validateStdlibSource(value) {
+    if (value === undefined)
+        return [];
+    const entries = Array.isArray(value) ? value : [value];
+    return entries.map((entry, index) => {
+        if (typeof entry !== 'string' || entry.trim() === '') {
+            const where = Array.isArray(value) ? `stdlib.source[${index}]` : 'stdlib.source';
+            fail(`options.${where} must be a non-empty string, received ${JSON.stringify(entry)}.`);
+        }
+        return entry.trim();
+    });
+}
+/**
+ * Validates the nested `stdlib` group, accepting `false` as shorthand for `{enabled: false}`.
+ */
+function validateStdlib(value) {
+    if (value === undefined)
+        return { ...DEFAULT_STDLIB_OPTIONS, include: [], source: [] };
+    if (value === false)
+        return { ...DEFAULT_STDLIB_OPTIONS, enabled: false, include: [], source: [] };
+    if (!isPlainObject(value)) {
+        fail(`options.stdlib must be an object or false, received ${JSON.stringify(value)}.`);
+    }
+    const allowedKeys = ['enabled', 'include', 'source', 'namespaces'];
+    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) => `stdlib.${key}`))}. ` +
+            `Supported options: ${quoteList(allowedKeys.map((key) => `stdlib.${key}`))}.`);
+    }
+    const include = value.include === undefined ? [] : validateNamespaceList(value.include, 'stdlib.include');
+    const source = validateStdlibSource(value.source);
+    const namespaces = value.namespaces === undefined
+        ? null
+        : validateNamespaceList(value.namespaces, 'stdlib.namespaces');
+    if (namespaces !== null && namespaces.length === 0) {
+        fail('options.stdlib.namespaces must name at least one namespace. To turn the standard ' +
+            'library off entirely, use `stdlib: false`.');
+    }
+    if (include.length > 0 && source.length === 0) {
+        fail(`options.stdlib.include names ${quoteList(include)}, but options.stdlib.source is not ` +
+            'set, so there is nowhere to read them from. Point it at the `stdlib` directory of a ' +
+            'plantuml-stdlib checkout.');
+    }
+    return {
+        enabled: validateBoolean(value.enabled, 'stdlib.enabled', DEFAULT_STDLIB_OPTIONS.enabled),
+        include,
+        source,
+        namespaces,
+    };
+}
 function validateRenderTimeout(value) {
     if (value === undefined)
         return DEFAULT_OPTIONS.renderTimeoutMs;
@@ -175,6 +252,7 @@ export function resolveOptions(rawOptions) {
             ...DEFAULT_OPTIONS,
             languages: [...DEFAULT_OPTIONS.languages],
             graphviz: { ...DEFAULT_GRAPHVIZ_OPTIONS, languages: [...DEFAULT_GRAPHVIZ_OPTIONS.languages] },
+            stdlib: { ...DEFAULT_STDLIB_OPTIONS, include: [], source: [] },
         };
     }
     if (!isPlainObject(rawOptions)) {
@@ -192,6 +270,7 @@ export function resolveOptions(rawOptions) {
         'zoom',
         'showSource',
         'graphviz',
+        'stdlib',
         // Docusaurus injects `id` for multi-instance plugins.
         'id',
     ]);
@@ -209,6 +288,7 @@ export function resolveOptions(rawOptions) {
     }
     const languages = validateLanguages(rawOptions.languages, 'languages', DEFAULT_OPTIONS.languages);
     const graphviz = validateGraphviz(rawOptions.graphviz);
+    const stdlib = validateStdlib(rawOptions.stdlib);
     // 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) {
@@ -221,6 +301,7 @@ export function resolveOptions(rawOptions) {
     return {
         languages,
         graphviz,
+        stdlib,
         theme: theme ?? DEFAULT_OPTIONS.theme,
         lazy: validateBoolean(rawOptions.lazy, 'lazy', DEFAULT_OPTIONS.lazy),
         cache: cache ?? DEFAULT_OPTIONS.cache,

package/dist/runtime/assetLoader.d.ts

@@ -10,6 +10,17 @@ export interface LoadRuntimeOptions {
      */
     importModule?: (url: string) => Promise<unknown>;
 }
+/**
+ * Injects a classic script once, reusing an existing tag for the same URL.
+ *
+ * Client-side navigation re-mounts diagram components but does not reload the document, so
+ * the marker attribute is what keeps a second `<script>` from ever being appended. The URL is
+ * the marker's value, because the standard library loader adds a tag per namespace and a
+ * bare marker could not tell them apart.
+ *
+ * @param label how the asset is named in an error message, e.g. `Graphviz runtime`
+ */
+export declare function loadClassicScript(url: string, timeoutMs: number, label: string): Promise<void>;
 /**
  * Resolves a ready-to-use Graphviz instance, loading `viz-global.js` on first use.
  *
@@ -29,5 +40,6 @@ export declare function loadPlantUmlRuntime(options: LoadRuntimeOptions): Promis
 export declare function isRuntimeRequested(): boolean;
 /** 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 onRuntimeReset(hook: () => void): void;
+/** Test-only: forgets every cached runtime and removes the injected script tags. */
 export declare function resetRuntimeLoader(): void;

package/dist/runtime/assetLoader.js

@@ -28,31 +28,41 @@ function defaultImportModule(url) {
     return import(/* webpackIgnore: true */ url);
 }
 /**
- * Injects `viz-global.js` as a classic script, reusing an existing tag.
+ * Injects a classic script once, reusing an existing tag for the same URL.
  *
  * Client-side navigation re-mounts diagram components but does not reload the document, so
- * the marker attribute is what keeps a second `<script>` from ever being appended.
+ * the marker attribute is what keeps a second `<script>` from ever being appended. The URL is
+ * the marker's value, because the standard library loader adds a tag per namespace and a
+ * bare marker could not tell them apart.
+ *
+ * @param label how the asset is named in an error message, e.g. `Graphviz runtime`
  */
-function loadVizGlobal(url, timeoutMs) {
-    const existing = document.querySelector(`script[${SCRIPT_MARKER}]`);
+export function loadClassicScript(url, timeoutMs, label) {
+    const existing = document.querySelector(`script[${SCRIPT_MARKER}=${JSON.stringify(url)}]`);
     if (existing) {
         if (existing.dataset.plantumlRuntimeState === 'loaded')
             return Promise.resolve();
-        if (existing.dataset.plantumlRuntimeState === 'error') {
-            return Promise.reject(new PlantUmlError('load', `Failed to load the Graphviz runtime from ${url}.`));
-        }
-        return waitForScript(existing, url, timeoutMs);
+        // A failed tag is discarded rather than reused. The caller that reaches this point has
+        // already dropped its cached promise in order to retry, and reusing the dead tag would
+        // make that retry impossible — a single flaky response would poison the page.
+        if (existing.dataset.plantumlRuntimeState === 'error')
+            existing.remove();
+        else
+            return waitForScript(existing, url, timeoutMs, label);
     }
     const script = document.createElement('script');
-    script.setAttribute(SCRIPT_MARKER, '');
+    script.setAttribute(SCRIPT_MARKER, url);
     script.dataset.plantumlRuntimeState = 'loading';
     script.async = false;
     script.src = url;
-    const promise = waitForScript(script, url, timeoutMs);
+    const promise = waitForScript(script, url, timeoutMs, label);
     document.head.appendChild(script);
     return promise;
 }
-function waitForScript(script, url, timeoutMs) {
+function loadVizGlobal(url, timeoutMs) {
+    return loadClassicScript(url, timeoutMs, 'Graphviz runtime');
+}
+function waitForScript(script, url, timeoutMs, label) {
     return new Promise((resolve, reject) => {
         let done = false;
         const finish = (fn) => {
@@ -70,7 +80,7 @@ function waitForScript(script, url, timeoutMs) {
         };
         const onError = () => {
             script.dataset.plantumlRuntimeState = 'error';
-            finish(() => reject(new PlantUmlError('load', `Failed to load the Graphviz runtime from ${url}. ` +
+            finish(() => reject(new PlantUmlError('load', `Failed to load the ${label} from ${url}. ` +
                 'Check that the asset is served under your Docusaurus baseUrl with a JavaScript MIME type.')));
         };
         const timer = setTimeout(() => {
@@ -175,10 +185,23 @@ export function isRuntimeRequested() {
 export function isVizRuntimeRequested() {
     return cachedViz !== null;
 }
-/** Test-only: forgets both cached runtimes and removes the injected script tag. */
+/**
+ * Registers a callback for {@link resetRuntimeLoader}.
+ *
+ * The standard library loader keeps its own per-namespace cache but shares the script tags
+ * this module injects, so a reset that removed the tags without clearing that cache would
+ * leave it claiming namespaces are loaded when their globals are gone. The dependency points
+ * this way — loader to registry — so that `assetLoader` needs no import of its callers.
+ */
+const resetHooks = [];
+export function onRuntimeReset(hook) {
+    resetHooks.push(hook);
+}
+/** Test-only: forgets every cached runtime and removes the injected script tags. */
 export function resetRuntimeLoader() {
     cachedRuntime = null;
     cachedViz = null;
+    resetHooks.forEach((hook) => hook());
     if (typeof document !== 'undefined') {
         document.querySelectorAll(`script[${SCRIPT_MARKER}]`).forEach((node) => node.remove());
     }

package/dist/runtime/cache.d.ts

@@ -4,6 +4,11 @@ export interface CacheKeyInput {
     dark: boolean;
     sanitized: boolean;
     coreVersion: string;
+    /**
+     * Identifies the standard library the diagram was rendered against, so refreshing it
+     * invalidates the entries whose pictures it shaped. `null` when it is switched off.
+     */
+    stdlibRevision: string | null;
 }
 export interface DiagramCache {
     readonly mode: CacheMode;
@@ -13,7 +18,7 @@ export interface DiagramCache {
     /** Number of entries currently held. Exposed for tests and the documented size limit. */
     size(): number;
 }
-export declare function computeCacheKey({ source, dark, sanitized, coreVersion }: CacheKeyInput): string;
+export declare function computeCacheKey({ source, dark, sanitized, coreVersion, stdlibRevision, }: CacheKeyInput): string;
 export interface GraphvizCacheKeyInput {
     source: string;
     /** Graphviz layout engine; `dot` and `neato` draw different pictures from one source. */

package/dist/runtime/cache.js

@@ -15,12 +15,12 @@ function hash(input) {
     }
     return value.toString(36).padStart(7, '0');
 }
-export function computeCacheKey({ source, dark, sanitized, coreVersion }) {
+export function computeCacheKey({ source, dark, sanitized, coreVersion, stdlibRevision, }) {
     const mode = dark ? 'dark' : 'light';
     const clean = sanitized ? 'san' : 'raw';
     // The length guards against the (astronomically unlikely) 32-bit hash collision between
     // two different sources that happen to share every other key component.
-    return `${coreVersion}|${mode}|${clean}|${source.length}|${hash(source)}`;
+    return `${coreVersion}|${stdlibRevision ?? 'nostd'}|${mode}|${clean}|${source.length}|${hash(source)}`;
 }
 /**
  * Cache key for a Graphviz diagram.

package/dist/runtime/errors.d.ts

@@ -1,5 +1,7 @@
 import type { VizRenderError } from './types.js';
-export type PlantUmlErrorKind = 'load' | 'engine' | 'diagram' | 'syntax' | 'timeout' | 'config' | 'aborted' | 'too-large';
+export type PlantUmlErrorKind = 'load' | 'engine' | 'diagram' | 'syntax' | 'timeout' | 'config' | 'aborted' | 'too-large'
+/** A `!include <namespace/…>` the site cannot resolve. */
+ | 'stdlib';
 /** 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;

package/dist/runtime/errors.js

@@ -18,6 +18,24 @@ const BOILERPLATE_PATTERNS = [
     /^\s*$/,
 ];
 const NOT_SUPPORTED_HEADING = 'Diagram not supported by this release of PlantUML';
+/**
+ * Failures raised by PlantUML's *preprocessor* rather than by its parser.
+ *
+ * These matter far more now that `!include <namespace/…>` is resolvable. Calling a macro the
+ * included version does not define, naming a file that is not in the namespace, and an
+ * include the preprocessor could not resolve at all are the three likeliest ways a standard
+ * library diagram goes wrong. *None* of them produces the `Syntax Error?` marker below — the
+ * picture says only `Function not found RelIndex`, `cannot include <…>` or `Fatal parsing
+ * error` — so without this signature the engine's error card was passed through as a
+ * successful render.
+ */
+const PREPROCESSOR_FAILURE_PATTERN = /^\s*(?:function not found|cannot include|fatal parsing error)\b/i;
+/**
+ * The header PlantUML puts above the source listing in every error picture. Required to
+ * co-occur with the line above, so that a diagram merely containing the words "cannot
+ * include" in a note is not mistaken for a failure.
+ */
+const SOURCE_LISTING_PATTERN = /^\[From .+\(line \d+\)/;
 function textNodesOf(svg) {
     if (typeof DOMParser === 'undefined')
         return [];
@@ -49,8 +67,16 @@ export function detectDiagramError(svg) {
     const isEmptyDescription = texts.some((text) => /Empty description/.test(text) && text.includes('(Assumed diagram type:'));
     const isUnsupported = texts.some((text) => text.includes(NOT_SUPPORTED_HEADING)) &&
         texts.some((text) => text.includes('is not recognized.'));
-    if (!isSyntaxError && !isEmptyDescription && !isUnsupported)
+    const preprocessorFailures = texts.filter((text) => PREPROCESSOR_FAILURE_PATTERN.test(text));
+    const isPreprocessorError = preprocessorFailures.length > 0 && texts.some((text) => SOURCE_LISTING_PATTERN.test(text));
+    if (!isSyntaxError && !isEmptyDescription && !isUnsupported && !isPreprocessorError)
         return null;
+    // A preprocessor failure lists the *expanded* source, which for a standard library macro
+    // runs to thousands of lines. The failure itself is the only part worth showing; the
+    // reader still has the original fence a click away in the source view.
+    if (isPreprocessorError && !isSyntaxError) {
+        return preprocessorFailures.map((text) => text.trim()).join('\n');
+    }
     const meaningful = texts
         .map((text) => text.replace(/\s+$/, ''))
         .filter((text) => !BOILERPLATE_PATTERNS.some((pattern) => pattern.test(text)));

package/dist/runtime/renderer.d.ts

@@ -1,5 +1,6 @@
 import { type LoadRuntimeOptions } from './assetLoader.js';
 import { type DiagramCache } from './cache.js';
+import { type StdlibRuntime } from './stdlibLoader.js';
 export interface RenderDiagramRequest {
     source: string;
     dark: boolean;
@@ -7,6 +8,8 @@ export interface RenderDiagramRequest {
     timeoutMs: number;
     assetsBaseUrl: string;
     coreVersion: string;
+    /** Standard library assets for this site, or `null` when the feature is switched off. */
+    stdlib: StdlibRuntime | null;
     cache: DiagramCache;
     signal?: AbortSignal;
     /** Reports which long-running phase is in progress, so the UI can show an accurate state. */

package/dist/runtime/renderer.js

@@ -3,6 +3,7 @@ import { computeCacheKey } from './cache.js';
 import { describeEngineError, detectDiagramError, PlantUmlError } from './errors.js';
 import { enqueueRender } from './queue.js';
 import { sanitizeSvgMarkup } from './sanitize.js';
+import { loadStdlibForSource } from './stdlibLoader.js';
 /**
  * `renderToString` takes its options as a *fourth* argument, after the two callbacks.
  * This was verified against the installed `@plantuml/core` rather than assumed: the
@@ -41,19 +42,32 @@ function renderWithEngine(engine, source, dark) {
  * {@link enqueueRender} because the engine cannot render two diagrams at once.
  */
 export async function renderDiagram(request) {
-    const { source, dark, sanitize, timeoutMs, cache, coreVersion, signal, onPhase } = request;
-    const cacheKey = computeCacheKey({ source, dark, sanitized: sanitize, coreVersion });
+    const { source, dark, sanitize, timeoutMs, cache, coreVersion, stdlib, signal, onPhase } = request;
+    const cacheKey = computeCacheKey({
+        source,
+        dark,
+        sanitized: sanitize,
+        coreVersion,
+        stdlibRevision: stdlib?.manifest.revision ?? null,
+    });
     const cached = cache.get(cacheKey);
     if (cached !== undefined)
         return cached;
     // Loading happens outside the queue: it is shared, idempotent work, and holding the
     // single render slot for an 8 MB download would stall every other diagram on the page.
+    //
+    // The standard library loads alongside the engine rather than after it. The two are
+    // independent downloads, and the engine cannot be asked for a diagram whose includes are
+    // not resolvable yet — by the time it looks, the namespaces have to be in place already.
     onPhase?.('loading');
-    const engine = await loadPlantUmlRuntime({
-        assetsBaseUrl: request.assetsBaseUrl,
-        timeoutMs,
-        importModule: request.importModule,
-    });
+    const [engine] = await Promise.all([
+        loadPlantUmlRuntime({
+            assetsBaseUrl: request.assetsBaseUrl,
+            timeoutMs,
+            importModule: request.importModule,
+        }),
+        loadStdlibForSource({ source, stdlib, timeoutMs }),
+    ]);
     onPhase?.('rendering');
     const svg = await enqueueRender(async () => {
         const raw = await renderWithEngine(engine, source, dark);

package/dist/runtime/stdlibLoader.d.ts

@@ -0,0 +1,31 @@
+import { type StdlibRuntimeManifest } from '../stdlibShared.js';
+export interface StdlibRuntime {
+    /** Absolute, `baseUrl`-prefixed URL of the directory holding the namespace bundles. */
+    baseUrl: string;
+    manifest: StdlibRuntimeManifest;
+}
+/**
+ * The namespaces a source needs, in load order, including what those namespaces need in turn.
+ *
+ * Dependencies come from the manifest rather than from parsing the library sources in the
+ * browser: `k8s` includes `<c4/…>` from its own `Common.puml`, and the engine would ask for
+ * it mid-render, far too late to fetch anything. Example-only dependencies are pulled in
+ * solely when the diagram includes something from `_examples_/` — C4's examples reference
+ * `office`, and charging every C4 diagram 160 KB for that would be absurd.
+ *
+ * A dependency the site does not provide is skipped rather than raised: it may well sit
+ * behind an `!if` the diagram never takes, and failing here would break diagrams that work.
+ */
+export declare function collectStdlibNamespaces(source: string, manifest: StdlibRuntimeManifest): string[];
+export interface LoadStdlibOptions {
+    source: string;
+    stdlib: StdlibRuntime | null;
+    timeoutMs: number;
+}
+/**
+ * Loads whatever the source needs from the standard library. Resolves immediately when it
+ * needs nothing, which is the common case and must stay free.
+ */
+export declare function loadStdlibForSource({ source, stdlib, timeoutMs, }: LoadStdlibOptions): Promise<void>;
+/** Whether a namespace bundle has been requested on this page. For tests and diagnostics. */
+export declare function isStdlibNamespaceRequested(url: string): boolean;

package/dist/runtime/stdlibLoader.js

@@ -0,0 +1,99 @@
+import { findStdlibIncludes } from '../stdlibShared.js';
+import { loadClassicScript, onRuntimeReset } from './assetLoader.js';
+import { PlantUmlError } from './errors.js';
+/** One in-flight or settled load per bundle URL, shared by every diagram on the page. */
+const loaded = new Map();
+onRuntimeReset(() => loaded.clear());
+function bundleFileName(namespace) {
+    return `${namespace}.min.js`;
+}
+function joinUrl(base, file) {
+    return `${base.replace(/\/+$/, '')}/${file}`;
+}
+/**
+ * Tells the engine the namespace bundle is already in the document.
+ *
+ * The key is the bare file name because that is exactly the `src` the engine would have set,
+ * and its bookkeeping is keyed by that string rather than by the resolved URL.
+ */
+function markLoadedForEngine(namespace) {
+    const engineWindow = window;
+    const state = (engineWindow.__pl_script_state ??= Object.create(null));
+    state[bundleFileName(namespace)] = { state: 'loaded', ok: [], err: [] };
+}
+/**
+ * The namespaces a source needs, in load order, including what those namespaces need in turn.
+ *
+ * Dependencies come from the manifest rather than from parsing the library sources in the
+ * browser: `k8s` includes `<c4/…>` from its own `Common.puml`, and the engine would ask for
+ * it mid-render, far too late to fetch anything. Example-only dependencies are pulled in
+ * solely when the diagram includes something from `_examples_/` — C4's examples reference
+ * `office`, and charging every C4 diagram 160 KB for that would be absurd.
+ *
+ * A dependency the site does not provide is skipped rather than raised: it may well sit
+ * behind an `!if` the diagram never takes, and failing here would break diagrams that work.
+ */
+export function collectStdlibNamespaces(source, manifest) {
+    const references = findStdlibIncludes(source);
+    const ordered = [];
+    const seen = new Set();
+    const visit = (namespace, withExamples, direct) => {
+        const entry = manifest.namespaces[namespace];
+        if (!entry) {
+            if (!direct)
+                return;
+            throw new PlantUmlError('stdlib', `This diagram includes <${namespace}/…>, but the '${namespace}' standard library ` +
+                "namespace is not available on this site. Add it to the plugin's " +
+                `\`stdlib.include\` option and point \`stdlib.source\` at a plantuml-stdlib ` +
+                'checkout that contains it.');
+        }
+        if (seen.has(namespace))
+            return;
+        seen.add(namespace);
+        for (const dependency of entry.dependencies)
+            visit(dependency, false, false);
+        if (withExamples) {
+            for (const dependency of entry.exampleDependencies)
+                visit(dependency, false, false);
+        }
+        ordered.push(namespace);
+    };
+    for (const reference of references) {
+        visit(reference.namespace, reference.fromExamples, true);
+    }
+    return ordered;
+}
+/**
+ * Loads whatever the source needs from the standard library. Resolves immediately when it
+ * needs nothing, which is the common case and must stay free.
+ */
+export async function loadStdlibForSource({ source, stdlib, timeoutMs, }) {
+    const references = findStdlibIncludes(source);
+    if (references.length === 0)
+        return;
+    if (!stdlib) {
+        const names = [...new Set(references.map((reference) => reference.namespace))];
+        throw new PlantUmlError('stdlib', `This diagram includes ${names.map((name) => `<${name}/…>`).join(', ')} from the ` +
+            'PlantUML standard library, which is switched off for this site (`stdlib: false`).');
+    }
+    const namespaces = collectStdlibNamespaces(source, stdlib.manifest);
+    await Promise.all(namespaces.map(async (namespace) => {
+        const url = joinUrl(stdlib.baseUrl, bundleFileName(namespace));
+        let pending = loaded.get(url);
+        if (!pending) {
+            pending = loadClassicScript(url, timeoutMs, `standard library namespace '${namespace}'`)
+                .then(() => markLoadedForEngine(namespace))
+                .catch((error) => {
+                // Clearing the entry lets a later diagram retry rather than inherit the failure.
+                loaded.delete(url);
+                throw error;
+            });
+            loaded.set(url, pending);
+        }
+        await pending;
+    }));
+}
+/** Whether a namespace bundle has been requested on this page. For tests and diagnostics. */
+export function isStdlibNamespaceRequested(url) {
+    return loaded.has(url);
+}