@matfsw/docusaurus-plantuml-plugin 1.2.0 → 1.3.0

package/dist/stdlib.d.ts

@@ -0,0 +1,35 @@
+import type { ResolvedStdlibOptions } from './options.js';
+import type { StdlibRuntimeManifest } from './stdlibShared.js';
+/**
+ * Decides which standard library bundles a site build emits, and where each one comes from.
+ *
+ * The vendored bundles in `assets/stdlib` cover the namespaces this package ships (see
+ * `assets/stdlib/LICENSES.md`). Anything named in `stdlib.include` is generated on demand
+ * from a `plantuml-stdlib` checkout the site points at, and cached, because `aws` alone is
+ * 114 MB of source that nobody wants to re-read on every rebuild.
+ */
+export type { StdlibNamespaceEntry, StdlibRuntimeManifest } from './stdlibShared.js';
+export interface StdlibAssets {
+    /** Absolute paths of the bundles to copy into the site's assets directory. */
+    files: string[];
+    manifest: StdlibRuntimeManifest;
+}
+export interface ResolveStdlibInput {
+    options: ResolvedStdlibOptions;
+    /** Directory of the calling module, used to locate the vendored bundles. */
+    currentDir: string;
+    /** Site directory, which relative `stdlib.source` entries are resolved against. */
+    siteDir: string;
+    /**
+     * Where bundles generated for `stdlib.include` are cached. Docusaurus passes its
+     * `generatedFilesDir`; when it is absent the site's `.docusaurus` directory is assumed.
+     */
+    cacheDir?: string;
+}
+/**
+ * Resolves the standard library for one site build.
+ *
+ * Returns `null` when the feature is switched off, in which case nothing is emitted and the
+ * browser side never looks for a bundle.
+ */
+export declare function resolveStdlibAssets({ options, currentDir, siteDir, cacheDir, }: ResolveStdlibInput): StdlibAssets | null;

package/dist/stdlib.js

@@ -0,0 +1,163 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { PLUGIN_NAME } from './constants.js';
+import { buildStdlibNamespace, stdlibBundleFileName } from './stdlibBundle.js';
+/**
+ * `assets/` sits beside `dist/` in the published package and beside `src/` in the repository,
+ * so one relative step out of the compiled module's directory finds it either way.
+ */
+function vendoredDirectory(currentDir) {
+    return path.join(currentDir, '..', 'assets', 'stdlib');
+}
+function readVendoredManifest(directory) {
+    const manifestPath = path.join(directory, 'manifest.json');
+    if (!fs.existsSync(manifestPath)) {
+        throw new Error(`[${PLUGIN_NAME}] The vendored standard library manifest is missing from ` +
+            `'${manifestPath}'. This is a packaging fault: reinstall the plugin, or run ` +
+            "'npm run stdlib:update' if you are working in a checkout of it.");
+    }
+    return JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+}
+/** Short, stable content identity for a generated bundle, used to name its cache file. */
+function digest(...parts) {
+    const hash = crypto.createHash('sha256');
+    for (const part of parts)
+        hash.update(part).update('\0');
+    return hash.digest('hex').slice(0, 12);
+}
+/**
+ * Cheap identity for a namespace directory: every file's path, size and mtime.
+ *
+ * Reading 114 MB of `aws` sources to hash them would defeat the point of the cache, and this
+ * is the same trade every bundler makes for its own file watching.
+ */
+function directoryStamp(directory) {
+    const parts = [];
+    const walk = (current) => {
+        for (const entry of fs
+            .readdirSync(current, { withFileTypes: true })
+            .sort((a, b) => (a.name < b.name ? -1 : 1))) {
+            const absolute = path.join(current, entry.name);
+            if (entry.isDirectory()) {
+                walk(absolute);
+                continue;
+            }
+            const stats = fs.statSync(absolute);
+            parts.push(`${absolute}:${stats.size}:${stats.mtimeMs}`);
+        }
+    };
+    walk(directory);
+    return digest(...parts);
+}
+/**
+ * Finds a namespace directory in one of the configured source trees.
+ *
+ * Matching is case-insensitive because the option is written in the same lower case the
+ * engine uses (`'aws'`), while upstream spells some directories differently (`'C4'`).
+ */
+function findNamespaceDirectory(sourceRoots, namespace) {
+    for (const root of sourceRoots) {
+        if (!fs.existsSync(root))
+            continue;
+        for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+            if (entry.isDirectory() && entry.name.toLowerCase() === namespace) {
+                return path.join(root, entry.name);
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Resolves the standard library for one site build.
+ *
+ * Returns `null` when the feature is switched off, in which case nothing is emitted and the
+ * browser side never looks for a bundle.
+ */
+export function resolveStdlibAssets({ options, currentDir, siteDir, cacheDir, }) {
+    if (!options.enabled)
+        return null;
+    const directory = vendoredDirectory(currentDir);
+    const vendored = readVendoredManifest(directory);
+    const vendoredNamespaces = vendored.namespaces ?? {};
+    const files = [];
+    const namespaces = {};
+    const addVendored = (namespace) => {
+        if (namespace in namespaces)
+            return;
+        const entry = vendoredNamespaces[namespace];
+        if (!entry)
+            return;
+        const bundlePath = path.join(directory, entry.file);
+        if (!fs.existsSync(bundlePath)) {
+            throw new Error(`[${PLUGIN_NAME}] The vendored standard library manifest lists '${entry.file}', but ` +
+                `'${bundlePath}' does not exist. Reinstall the plugin.`);
+        }
+        files.push(bundlePath);
+        namespaces[namespace] = {
+            dependencies: entry.dependencies ?? [],
+            exampleDependencies: entry.exampleDependencies ?? [],
+        };
+        // A namespace is useless without the ones its own files include, so `stdlib.namespaces`
+        // narrows the selection but can never narrow it into something that cannot render.
+        for (const dependency of entry.dependencies ?? [])
+            addVendored(dependency);
+    };
+    const selected = options.namespaces ?? Object.keys(vendoredNamespaces);
+    if (options.namespaces) {
+        const unknown = options.namespaces.filter((namespace) => !(namespace in vendoredNamespaces) && !options.include.includes(namespace));
+        if (unknown.length > 0) {
+            throw new Error(`[${PLUGIN_NAME}] options.stdlib.namespaces names ${unknown
+                .map((name) => `'${name}'`)
+                .join(', ')}, which ${unknown.length > 1 ? 'are' : 'is'} not vendored with this ` +
+                `plugin. Vendored namespaces: ${Object.keys(vendoredNamespaces).join(', ')}. To use ` +
+                'another one, add it to options.stdlib.include and point options.stdlib.source at a ' +
+                'plantuml-stdlib checkout.');
+        }
+    }
+    for (const namespace of selected)
+        addVendored(namespace);
+    // Extra namespaces come last so that naming a vendored one in `include` replaces it with
+    // the copy from the site's own checkout.
+    const sourceRoots = options.source.map((entry) => path.resolve(siteDir, entry));
+    const generatedDir = path.join(cacheDir ?? path.join(siteDir, '.docusaurus'), 'plantuml-stdlib');
+    const stamps = [];
+    for (const namespace of options.include) {
+        const namespaceDir = findNamespaceDirectory(sourceRoots, namespace);
+        if (!namespaceDir) {
+            throw new Error(`[${PLUGIN_NAME}] options.stdlib.include names '${namespace}', which was not found in ` +
+                `${sourceRoots.map((root) => `'${root}'`).join(', ')}. Clone the standard library ` +
+                '(git clone --depth 1 https://github.com/plantuml/plantuml-stdlib) and point ' +
+                "options.stdlib.source at its 'stdlib' directory.");
+        }
+        const stamp = directoryStamp(namespaceDir);
+        stamps.push(`${namespace}:${stamp}`);
+        const cached = path.join(generatedDir, stamp, stdlibBundleFileName(namespace));
+        if (!fs.existsSync(cached)) {
+            const bundle = buildStdlibNamespace(path.dirname(namespaceDir), path.basename(namespaceDir));
+            fs.mkdirSync(path.dirname(cached), { recursive: true });
+            fs.writeFileSync(cached, bundle.script, 'utf8');
+            fs.writeFileSync(`${cached}.json`, JSON.stringify({
+                dependencies: bundle.dependencies,
+                exampleDependencies: bundle.exampleDependencies,
+            }), 'utf8');
+        }
+        const meta = JSON.parse(fs.readFileSync(`${cached}.json`, 'utf8'));
+        // Replacing a vendored bundle means dropping its file, not shipping both under one name.
+        const previous = files.findIndex((file) => path.basename(file) === stdlibBundleFileName(namespace));
+        if (previous !== -1)
+            files.splice(previous, 1);
+        files.push(cached);
+        namespaces[namespace] = {
+            dependencies: meta.dependencies,
+            exampleDependencies: meta.exampleDependencies,
+        };
+    }
+    return {
+        files,
+        manifest: {
+            revision: digest(vendored.upstream?.commit ?? 'unknown', ...stamps.sort()),
+            namespaces,
+        },
+    };
+}

package/dist/stdlibBundle.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Turns a `plantuml-stdlib` namespace directory into the JavaScript bundle that
+ * `@plantuml/core` resolves `!include <namespace/file>` against.
+ *
+ * The engine reads three globals, all keyed by a *lower-cased* namespace and a *lower-cased*
+ * path with the extension stripped:
+ *
+ * ```js
+ * window.PLANTUML_STDLIB['c4']['c4_container'] = ['line', 'line', ...]
+ * window.PLANTUML_STDLIB_JSON['awslib10']['awslib10']    = { ... }
+ * window.PLANTUML_STDLIB_INFO['c4']                      = { name: 'C4', license: 'MIT', ... }
+ * ```
+ *
+ * That layout is not documented anywhere; it was read out of the installed `plantuml.js`
+ * (helpers `CCf`, `DJm` and `DID`) and reproduced from upstream's own generator,
+ * `src/main/java/com/plantuml/stdlibencoder/js/JsBuilder.java` in plantuml/plantuml-stdlib.
+ * See `docs/adr/0005-stdlib-bundles.md`.
+ *
+ * This port deviates from upstream in exactly one way, and deliberately: every entry is also
+ * registered under its name *with* the `.puml` (or `.json`) suffix. Upstream strips the
+ * suffix while the engine looks the name up as written, so `!include <C4/C4_Container.puml>`
+ * — a spelling that appears throughout C4-PlantUML's own documentation — cannot resolve
+ * against an upstream bundle. Both spellings share one array, so the alias costs no memory.
+ */
+/** Bumped when the emitted bundle layout changes in a way a stale manifest cannot describe. */
+export declare const STDLIB_BUNDLE_FORMAT = 1;
+export interface StdlibNamespaceBundle {
+    /** Lower-cased namespace key, as the engine looks it up: `c4`, `awslib10`. */
+    namespace: string;
+    /** Directory name as it appears upstream, which is not always lower case: `C4`. */
+    directoryName: string;
+    /** The bundle source, ready to be written as `<namespace>.min.js`. */
+    script: string;
+    /** The namespace's README front matter: `display_name`, `version`, `license`, `source`. */
+    info: Record<string, string>;
+    /**
+     * Other namespaces this one includes from its *library* files. Loading the namespace
+     * without these leaves the engine unable to resolve those includes.
+     */
+    dependencies: string[];
+    /**
+     * Other namespaces included only from `_examples_/`. Kept apart because they are dead
+     * weight for everyone who includes the library itself: C4's examples pull in `office`,
+     * 1.4 MB that a C4 diagram has no use for.
+     */
+    exampleDependencies: string[];
+    /** Number of `.puml` and `.json` files registered. */
+    fileCount: number;
+}
+/** The file name a namespace's bundle is served under. The engine's own loader assumes it. */
+export declare function stdlibBundleFileName(namespace: string): string;
+/**
+ * Builds the bundle for one namespace directory of a `plantuml-stdlib` checkout.
+ *
+ * @param stdlibRoot the checkout's `stdlib/` directory
+ * @param directoryName the namespace directory inside it, spelled as it is on disk
+ */
+export declare function buildStdlibNamespace(stdlibRoot: string, directoryName: string): StdlibNamespaceBundle;
+/** Namespace directories of a `plantuml-stdlib` checkout, in on-disk spelling. */
+export declare function listStdlibNamespaceDirectories(stdlibRoot: string): string[];

package/dist/stdlibBundle.js

@@ -0,0 +1,218 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { findStdlibIncludes, STDLIB_EXAMPLES_DIRECTORY } from './stdlibShared.js';
+/**
+ * Turns a `plantuml-stdlib` namespace directory into the JavaScript bundle that
+ * `@plantuml/core` resolves `!include <namespace/file>` against.
+ *
+ * The engine reads three globals, all keyed by a *lower-cased* namespace and a *lower-cased*
+ * path with the extension stripped:
+ *
+ * ```js
+ * window.PLANTUML_STDLIB['c4']['c4_container'] = ['line', 'line', ...]
+ * window.PLANTUML_STDLIB_JSON['awslib10']['awslib10']    = { ... }
+ * window.PLANTUML_STDLIB_INFO['c4']                      = { name: 'C4', license: 'MIT', ... }
+ * ```
+ *
+ * That layout is not documented anywhere; it was read out of the installed `plantuml.js`
+ * (helpers `CCf`, `DJm` and `DID`) and reproduced from upstream's own generator,
+ * `src/main/java/com/plantuml/stdlibencoder/js/JsBuilder.java` in plantuml/plantuml-stdlib.
+ * See `docs/adr/0005-stdlib-bundles.md`.
+ *
+ * This port deviates from upstream in exactly one way, and deliberately: every entry is also
+ * registered under its name *with* the `.puml` (or `.json`) suffix. Upstream strips the
+ * suffix while the engine looks the name up as written, so `!include <C4/C4_Container.puml>`
+ * — a spelling that appears throughout C4-PlantUML's own documentation — cannot resolve
+ * against an upstream bundle. Both spellings share one array, so the alias costs no memory.
+ */
+/** Bumped when the emitted bundle layout changes in a way a stale manifest cannot describe. */
+export const STDLIB_BUNDLE_FORMAT = 1;
+/**
+ * Upstream's rule: `_foo_` directories hold metadata and are skipped, except `_examples_`,
+ * which holds includable examples. Mirrored so a bundle carries the same files as the
+ * `.repx` the PlantUML jar would use.
+ */
+function isSkippedDirectory(name) {
+    if (name === STDLIB_EXAMPLES_DIRECTORY)
+        return false;
+    return name.startsWith('_') && name.endsWith('_');
+}
+function collectFiles(directory, namespaceRoot) {
+    const entries = fs
+        .readdirSync(directory, { withFileTypes: true })
+        // Sorted so a regenerated bundle is byte-identical on every platform.
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    const files = [];
+    for (const entry of entries) {
+        const absolutePath = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            if (!isSkippedDirectory(entry.name))
+                files.push(...collectFiles(absolutePath, namespaceRoot));
+            continue;
+        }
+        const extension = path.extname(entry.name).toLowerCase();
+        if (extension !== '.puml' && extension !== '.json')
+            continue;
+        const key = path.relative(namespaceRoot, absolutePath).split(path.sep).join('/').toLowerCase();
+        files.push({
+            key,
+            absolutePath,
+            extension,
+            fromExamples: key.startsWith(`${STDLIB_EXAMPLES_DIRECTORY}/`),
+        });
+    }
+    return files;
+}
+/**
+ * Reads the YAML front matter every stdlib namespace README carries.
+ *
+ * Deliberately not a YAML parser: upstream's own reader accepts flat `key: value` lines and
+ * nothing else, and matching it keeps the emitted `PLANTUML_STDLIB_INFO` identical.
+ */
+function readNamespaceInfo(namespaceRoot) {
+    const readme = path.join(namespaceRoot, 'README.md');
+    if (!fs.existsSync(readme))
+        return {};
+    const lines = fs.readFileSync(readme, 'utf8').split(/\r\n|\r|\n/);
+    if (lines[0]?.trim() !== '---')
+        return {};
+    const info = {};
+    for (const line of lines.slice(1)) {
+        const trimmed = line.trim();
+        if (trimmed === '---')
+            break;
+        const colon = trimmed.indexOf(':');
+        if (colon === -1)
+            continue;
+        info[trimmed.slice(0, colon).trim()] = trimmed.slice(colon + 1).trim();
+    }
+    return info;
+}
+/**
+ * `JSON.stringify` output is valid JavaScript except for U+2028/U+2029, which are legal in
+ * JSON strings and were illegal in JavaScript ones before ES2019. Escaping them keeps the
+ * bundle parseable by anything that can run the site.
+ */
+function toJsLiteral(value) {
+    return JSON.stringify(value)
+        .replace(/\u2028/g, '\\u2028')
+        .replace(/\u2029/g, '\\u2029');
+}
+/**
+ * Re-serializes a `.json` file so the bundle registers an object rather than a string.
+ *
+ * Parsing first is what makes that safe: a malformed file becomes a build error naming the
+ * file, instead of a syntax error inside a 500 KB generated bundle in a reader's browser.
+ */
+function toJsonLiteral(text, file) {
+    try {
+        return toJsLiteral(JSON.parse(text));
+    }
+    catch (cause) {
+        throw new Error(`'${file ?? 'a standard library JSON file'}' is not valid JSON.`, { cause });
+    }
+}
+/**
+ * Unwraps a library file that is itself a complete `@startuml … @enduml` document.
+ *
+ * PlantUML's file-based `!include` takes the *contents* of such a file rather than the
+ * document markers, but the standard library lookup this bundle feeds does not: the markers
+ * come through verbatim and the diagram fails on a nested `@startuml`. That is not a corner
+ * case — 81 of `cloudinsight`'s 83 sprite files are written this way, which would leave the
+ * whole namespace unusable.
+ *
+ * Only a single-block file is unwrapped. A file with more than one `@startuml` is left alone,
+ * because there the markers are what separates one block from the next.
+ *
+ * (`!include <ns/file!0>`, which selects a block by index, does not work through the standard
+ * library lookup either way — verified against the engine — so nothing is lost by unwrapping.)
+ */
+function unwrapDocument(lines) {
+    if (lines.filter((line) => /^@startuml\b/.test(line.trim())).length !== 1)
+        return lines;
+    let first = 0;
+    while (first < lines.length && lines[first]?.trim() === '')
+        first += 1;
+    if (!/^@startuml\b/.test(lines[first]?.trim() ?? ''))
+        return lines;
+    let last = lines.length - 1;
+    while (last > first && lines[last]?.trim() === '')
+        last -= 1;
+    if (lines[last]?.trim() !== '@enduml')
+        return lines;
+    return lines.slice(first + 1, last);
+}
+/** Strips the extension the way the engine does before looking a name up. */
+function withoutExtension(key) {
+    return key.replace(/\.(puml|json)$/, '');
+}
+/** The file name a namespace's bundle is served under. The engine's own loader assumes it. */
+export function stdlibBundleFileName(namespace) {
+    return `${namespace.toLowerCase()}.min.js`;
+}
+/**
+ * Builds the bundle for one namespace directory of a `plantuml-stdlib` checkout.
+ *
+ * @param stdlibRoot the checkout's `stdlib/` directory
+ * @param directoryName the namespace directory inside it, spelled as it is on disk
+ */
+export function buildStdlibNamespace(stdlibRoot, directoryName) {
+    const namespaceRoot = path.join(stdlibRoot, directoryName);
+    if (!fs.existsSync(namespaceRoot) || !fs.statSync(namespaceRoot).isDirectory()) {
+        throw new Error(`'${namespaceRoot}' is not a plantuml-stdlib namespace directory.`);
+    }
+    const namespace = directoryName.toLowerCase();
+    const info = readNamespaceInfo(namespaceRoot);
+    const files = collectFiles(namespaceRoot, namespaceRoot);
+    const dependencies = new Set();
+    const exampleDependencies = new Set();
+    const quoted = toJsLiteral(namespace);
+    const lines = [
+        `// ${namespace}.min.js - generated from plantuml-stdlib by @matfsw/docusaurus-plantuml-plugin.`,
+        '(function () {',
+        '  var w = window;',
+        '  w.PLANTUML_STDLIB = w.PLANTUML_STDLIB || {};',
+        '  w.PLANTUML_STDLIB_JSON = w.PLANTUML_STDLIB_JSON || {};',
+        '  w.PLANTUML_STDLIB_INFO = w.PLANTUML_STDLIB_INFO || {};',
+        `  w.PLANTUML_STDLIB_INFO[${quoted}] = ${toJsLiteral(info)};`,
+        `  var P = (w.PLANTUML_STDLIB[${quoted}] = w.PLANTUML_STDLIB[${quoted}] || {});`,
+        `  var J = (w.PLANTUML_STDLIB_JSON[${quoted}] = w.PLANTUML_STDLIB_JSON[${quoted}] || {});`,
+    ];
+    for (const file of files) {
+        const text = fs.readFileSync(file.absolutePath, 'utf8');
+        const bare = withoutExtension(file.key);
+        const target = file.extension === '.puml' ? 'P' : 'J';
+        // `.puml` becomes an array of lines and `.json` an object: the engine reads the two
+        // globals differently, joining the first with newlines and indexing into the second.
+        const value = file.extension === '.puml'
+            ? toJsLiteral(unwrapDocument(text.split(/\r\n|\r|\n/)))
+            : toJsonLiteral(text, file.absolutePath);
+        lines.push(`  ${target}[${toJsLiteral(bare)}] = ${target}[${toJsLiteral(file.key)}] = ${value};`);
+        if (file.extension !== '.puml')
+            continue;
+        for (const reference of findStdlibIncludes(text)) {
+            if (reference.namespace === namespace)
+                continue;
+            (file.fromExamples ? exampleDependencies : dependencies).add(reference.namespace);
+        }
+    }
+    lines.push('})();', '');
+    return {
+        namespace,
+        directoryName,
+        script: lines.join('\n'),
+        info,
+        dependencies: [...dependencies].sort(),
+        // An example-only dependency that the library already needs is not worth recording twice.
+        exampleDependencies: [...exampleDependencies].filter((name) => !dependencies.has(name)).sort(),
+        fileCount: files.length,
+    };
+}
+/** Namespace directories of a `plantuml-stdlib` checkout, in on-disk spelling. */
+export function listStdlibNamespaceDirectories(stdlibRoot) {
+    return fs
+        .readdirSync(stdlibRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+        .map((entry) => entry.name)
+        .sort();
+}

package/dist/stdlibShared.d.ts

@@ -0,0 +1,51 @@
+/**
+ * What the Node side and the browser side of standard library support both need: the shape
+ * of the manifest, and the one definition of what a `<namespace/…>` include looks like.
+ *
+ * Deliberately free of `node:` imports. `stdlibBundle.ts` reads the file system and
+ * `stdlib.ts` resolves paths; neither may be pulled into a theme component's bundle, and
+ * keeping the shared half here is what stops that from happening by accident.
+ */
+/** One namespace as the browser needs to know about it. Kept small: this ships in global data. */
+export interface StdlibNamespaceEntry {
+    /** Namespaces the engine will need as soon as this one is included. */
+    dependencies: string[];
+    /** Namespaces needed only by this one's `_examples_/` files. */
+    exampleDependencies: string[];
+}
+export interface StdlibRuntimeManifest {
+    /**
+     * Changes whenever the emitted bundles change. Part of the asset directory name, so a
+     * refreshed standard library can never be served from a stale HTTP cache, and part of the
+     * render cache key, so it can never be served from a stale SVG either.
+     */
+    revision: string;
+    namespaces: Record<string, StdlibNamespaceEntry>;
+}
+/** Directory holding a namespace's includable examples, which upstream keeps in the bundle. */
+export declare const STDLIB_EXAMPLES_DIRECTORY = "_examples_";
+/**
+ * `<namespace/path>` in an `!include` and its variants.
+ *
+ * Anchored to the start of a line because `!include` is only a directive there. Applied to
+ * stdlib sources when bundling and to author sources when rendering — one syntax, one place
+ * to correct it.
+ */
+export declare const STDLIB_INCLUDE_PATTERN: RegExp;
+export interface StdlibIncludeReference {
+    /** Lower-cased namespace. */
+    namespace: string;
+    /** The rest of the path, lower-cased, as written minus the namespace. */
+    target: string;
+    /** Whether the target lives under `_examples_/`. */
+    fromExamples: boolean;
+}
+/**
+ * Extracts the `<namespace/…>` includes of a PlantUML source.
+ *
+ * Includes whose path is computed (`!include <material2.1.19/$icon>`, as DomainStory does
+ * inside an `!if`) are skipped: the namespace is knowable but the file is not, so treating it
+ * as a hard dependency would make every DomainStory diagram drag in 6.8 MB of icons for a
+ * branch it will probably not take.
+ */
+export declare function findStdlibIncludes(source: string): StdlibIncludeReference[];

package/dist/stdlibShared.js

@@ -0,0 +1,54 @@
+/**
+ * What the Node side and the browser side of standard library support both need: the shape
+ * of the manifest, and the one definition of what a `<namespace/…>` include looks like.
+ *
+ * Deliberately free of `node:` imports. `stdlibBundle.ts` reads the file system and
+ * `stdlib.ts` resolves paths; neither may be pulled into a theme component's bundle, and
+ * keeping the shared half here is what stops that from happening by accident.
+ */
+/** Directory holding a namespace's includable examples, which upstream keeps in the bundle. */
+export const STDLIB_EXAMPLES_DIRECTORY = '_examples_';
+/**
+ * `<namespace/path>` in an `!include` and its variants.
+ *
+ * Anchored to the start of a line because `!include` is only a directive there. Applied to
+ * stdlib sources when bundling and to author sources when rendering — one syntax, one place
+ * to correct it.
+ */
+export const STDLIB_INCLUDE_PATTERN = /^[^\S\r\n]*!include(?:sub|url|_many)?[^\S\r\n]+<([^>\r\n]+)>/gim;
+/**
+ * Extracts the `<namespace/…>` includes of a PlantUML source.
+ *
+ * Includes whose path is computed (`!include <material2.1.19/$icon>`, as DomainStory does
+ * inside an `!if`) are skipped: the namespace is knowable but the file is not, so treating it
+ * as a hard dependency would make every DomainStory diagram drag in 6.8 MB of icons for a
+ * branch it will probably not take.
+ */
+export function findStdlibIncludes(source) {
+    const found = [];
+    const seen = new Set();
+    // `matchAll` on a shared global regex is safe: it clones the regex rather than advancing
+    // `lastIndex` on the original.
+    for (const match of source.matchAll(STDLIB_INCLUDE_PATTERN)) {
+        const raw = match[1]?.trim() ?? '';
+        if (raw.includes('$') || raw.includes('%'))
+            continue;
+        const slash = raw.indexOf('/');
+        if (slash <= 0)
+            continue;
+        const namespace = raw.slice(0, slash).toLowerCase();
+        const target = raw.slice(slash + 1).toLowerCase();
+        if (target === '')
+            continue;
+        const key = `${namespace}/${target}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        found.push({
+            namespace,
+            target,
+            fromExamples: target.startsWith(`${STDLIB_EXAMPLES_DIRECTORY}/`),
+        });
+    }
+    return found;
+}

package/dist/theme/PlantUmlDiagram/index.js

@@ -170,7 +170,7 @@ export default function PlantUmlDiagram({ source, title, language, engine = 'pla
                 transparentBackground: options.graphviz.transparentBackground,
                 maxSourceBytes: options.graphviz.maxSourceBytes,
             })
-            : renderDiagram({ ...shared, dark: renderDark });
+            : renderDiagram({ ...shared, dark: renderDark, stdlib: config.stdlib });
         void pending
             .then((svg) => commit({ status: 'ready', svg, error: null }))
             .catch((error) => {
@@ -190,6 +190,7 @@ export default function PlantUmlDiagram({ source, title, language, engine = 'pla
         config,
         config?.assetsBaseUrl,
         config?.coreVersion,
+        config?.stdlib,
         config?.options.sanitizeSvg,
         config?.options.renderTimeoutMs,
         config?.options.cache,

package/dist/theme/usePlantUmlConfig.d.ts

@@ -1,9 +1,17 @@
 import { type ResolvedPlantUmlOptions } from '../options.js';
+import type { StdlibRuntimeManifest } from '../stdlibShared.js';
+/** The standard library as the browser sees it: a URL to fetch bundles from, and an index. */
+export interface StdlibRuntimeConfig {
+    baseUrl: string;
+    manifest: StdlibRuntimeManifest;
+}
 export interface PlantUmlRuntimeConfig {
     options: ResolvedPlantUmlOptions;
     /** Absolute, `baseUrl`-prefixed URL of the directory holding the runtime assets. */
     assetsBaseUrl: string;
     coreVersion: string;
+    /** `null` when the standard library is switched off for this site. */
+    stdlib: StdlibRuntimeConfig | null;
 }
 /**
  * Reads the plugin's configuration from Docusaurus global data.

package/dist/theme/usePlantUmlConfig.js

@@ -2,7 +2,7 @@ import { useMemo } from 'react';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 import { useAllPluginInstancesData } from '@docusaurus/useGlobalData';
 import { PLUGIN_NAME } from '../constants.js';
-import { DEFAULT_GRAPHVIZ_OPTIONS } from '../options.js';
+import { DEFAULT_GRAPHVIZ_OPTIONS, DEFAULT_STDLIB_OPTIONS, } from '../options.js';
 function isGlobalData(value) {
     if (typeof value !== 'object' || value === null)
         return false;
@@ -23,26 +23,32 @@ export function usePlantUmlConfig() {
     const first = instances ? Object.values(instances).find(isGlobalData) : undefined;
     // `useBaseUrl` must be called unconditionally; the placeholder path is discarded below.
     const assetsBaseUrl = useBaseUrl(first ? first.assetsDir : '/');
+    const stdlibBaseUrl = useBaseUrl(first?.stdlib ? first.stdlib.dir : '/');
     // Memoized because consumers use this object as an effect dependency. Returning a fresh
     // object on every render would restart the render effect on every state update, which
     // re-enters rendering forever.
     return useMemo(() => first
         ? {
-            options: withGraphvizDefaults(first.options),
+            options: withDefaults(first.options),
             assetsBaseUrl,
             coreVersion: first.coreVersion,
+            stdlib: first.stdlib ? { baseUrl: stdlibBaseUrl, manifest: first.stdlib.manifest } : null,
         }
-        : null, [first, assetsBaseUrl]);
+        : null, [first, assetsBaseUrl, stdlibBaseUrl]);
 }
 /**
- * Fills in the `graphviz` group when it is missing from global data.
+ * Fills in the nested option groups when they are missing from global data.
  *
- * `resolveOptions` always produces it, so this only matters for data written by an older
+ * `resolveOptions` always produces them, so this only matters for data written by an older
  * version of the plugin — a stale `.docusaurus` cache surviving an upgrade, most plausibly.
  * Substituting the defaults keeps such a site rendering instead of failing on a missing key.
  */
-function withGraphvizDefaults(options) {
-    if (options.graphviz)
+function withDefaults(options) {
+    if (options.graphviz && options.stdlib)
         return options;
-    return { ...options, graphviz: DEFAULT_GRAPHVIZ_OPTIONS };
+    return {
+        ...options,
+        graphviz: options.graphviz ?? DEFAULT_GRAPHVIZ_OPTIONS,
+        stdlib: options.stdlib ?? DEFAULT_STDLIB_OPTIONS,
+    };
 }