@matfsw/docusaurus-plantuml-plugin 1.2.0 → 1.3.0

package/dist/index.cjs

@@ -46,7 +46,7 @@ var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${_
 var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
 
 // src/index.ts
-var import_node_path2 = __toESM(require("path"), 1);
+var import_node_path4 = __toESM(require("path"), 1);
 var import_node_url = require("url");
 var import_copy_webpack_plugin = __toESM(require("copy-webpack-plugin"), 1);
 
@@ -116,6 +116,12 @@ var DEFAULT_GRAPHVIZ_OPTIONS = {
   maxSourceBytes: 1e5,
   transparentBackground: true
 };
+var DEFAULT_STDLIB_OPTIONS = {
+  enabled: true,
+  include: [],
+  source: [],
+  namespaces: null
+};
 var DEFAULT_OPTIONS = {
   languages: ["plantuml", "puml"],
   theme: "auto",
@@ -127,7 +133,8 @@ var DEFAULT_OPTIONS = {
   cacheMaxEntries: 50,
   zoom: true,
   showSource: true,
-  graphviz: DEFAULT_GRAPHVIZ_OPTIONS
+  graphviz: DEFAULT_GRAPHVIZ_OPTIONS,
+  stdlib: DEFAULT_STDLIB_OPTIONS
 };
 var CACHE_MODES = ["none", "memory", "session"];
 var THEMES = ["auto", "light", "dark"];
@@ -234,6 +241,68 @@ function validateGraphviz(value) {
     )
   };
 }
+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)}.`
+      );
+    }
+    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 === void 0) 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();
+  });
+}
+function validateStdlib(value) {
+  if (value === void 0) 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 === void 0 ? [] : validateNamespaceList(value.include, "stdlib.include");
+  const source = validateStdlibSource(value.source);
+  const namespaces = value.namespaces === void 0 ? 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 === void 0) return DEFAULT_OPTIONS.renderTimeoutMs;
   if (typeof value !== "number" || !Number.isFinite(value)) {
@@ -261,7 +330,8 @@ function resolveOptions(rawOptions) {
     return {
       ...DEFAULT_OPTIONS,
       languages: [...DEFAULT_OPTIONS.languages],
-      graphviz: { ...DEFAULT_GRAPHVIZ_OPTIONS, languages: [...DEFAULT_GRAPHVIZ_OPTIONS.languages] }
+      graphviz: { ...DEFAULT_GRAPHVIZ_OPTIONS, languages: [...DEFAULT_GRAPHVIZ_OPTIONS.languages] },
+      stdlib: { ...DEFAULT_STDLIB_OPTIONS, include: [], source: [] }
     };
   }
   if (!isPlainObject(rawOptions)) {
@@ -279,6 +349,7 @@ function resolveOptions(rawOptions) {
     "zoom",
     "showSource",
     "graphviz",
+    "stdlib",
     // Docusaurus injects `id` for multi-instance plugins.
     "id"
   ]);
@@ -299,6 +370,7 @@ function resolveOptions(rawOptions) {
   }
   const languages = validateLanguages(rawOptions.languages, "languages", DEFAULT_OPTIONS.languages);
   const graphviz = validateGraphviz(rawOptions.graphviz);
+  const stdlib = validateStdlib(rawOptions.stdlib);
   if (graphviz.enabled) {
     const claimedTwice = graphviz.languages.filter((entry) => languages.includes(entry));
     if (claimedTwice.length > 0) {
@@ -310,6 +382,7 @@ 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,
@@ -330,8 +403,291 @@ function resolveOptions(rawOptions) {
   };
 }
 
+// src/stdlib.ts
+var import_node_crypto = __toESM(require("crypto"), 1);
+var import_node_fs3 = __toESM(require("fs"), 1);
+var import_node_path3 = __toESM(require("path"), 1);
+
+// src/stdlibBundle.ts
+var import_node_fs2 = __toESM(require("fs"), 1);
+var import_node_path2 = __toESM(require("path"), 1);
+
+// src/stdlibShared.ts
+var STDLIB_EXAMPLES_DIRECTORY = "_examples_";
+var STDLIB_INCLUDE_PATTERN = /^[^\S\r\n]*!include(?:sub|url|_many)?[^\S\r\n]+<([^>\r\n]+)>/gim;
+function findStdlibIncludes(source) {
+  const found = [];
+  const seen = /* @__PURE__ */ new Set();
+  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;
+}
+
+// src/stdlibBundle.ts
+function isSkippedDirectory(name) {
+  if (name === STDLIB_EXAMPLES_DIRECTORY) return false;
+  return name.startsWith("_") && name.endsWith("_");
+}
+function collectFiles(directory, namespaceRoot) {
+  const entries = import_node_fs2.default.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+  const files = [];
+  for (const entry of entries) {
+    const absolutePath = import_node_path2.default.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      if (!isSkippedDirectory(entry.name)) files.push(...collectFiles(absolutePath, namespaceRoot));
+      continue;
+    }
+    const extension = import_node_path2.default.extname(entry.name).toLowerCase();
+    if (extension !== ".puml" && extension !== ".json") continue;
+    const key = import_node_path2.default.relative(namespaceRoot, absolutePath).split(import_node_path2.default.sep).join("/").toLowerCase();
+    files.push({
+      key,
+      absolutePath,
+      extension,
+      fromExamples: key.startsWith(`${STDLIB_EXAMPLES_DIRECTORY}/`)
+    });
+  }
+  return files;
+}
+function readNamespaceInfo(namespaceRoot) {
+  const readme = import_node_path2.default.join(namespaceRoot, "README.md");
+  if (!import_node_fs2.default.existsSync(readme)) return {};
+  const lines = import_node_fs2.default.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;
+}
+function toJsLiteral(value) {
+  return JSON.stringify(value).replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+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 });
+  }
+}
+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);
+}
+function withoutExtension(key) {
+  return key.replace(/\.(puml|json)$/, "");
+}
+function stdlibBundleFileName(namespace) {
+  return `${namespace.toLowerCase()}.min.js`;
+}
+function buildStdlibNamespace(stdlibRoot, directoryName) {
+  const namespaceRoot = import_node_path2.default.join(stdlibRoot, directoryName);
+  if (!import_node_fs2.default.existsSync(namespaceRoot) || !import_node_fs2.default.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 = /* @__PURE__ */ new Set();
+  const exampleDependencies = /* @__PURE__ */ 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 = import_node_fs2.default.readFileSync(file.absolutePath, "utf8");
+    const bare = withoutExtension(file.key);
+    const target = file.extension === ".puml" ? "P" : "J";
+    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
+  };
+}
+
+// src/stdlib.ts
+function vendoredDirectory(currentDir2) {
+  return import_node_path3.default.join(currentDir2, "..", "assets", "stdlib");
+}
+function readVendoredManifest(directory) {
+  const manifestPath = import_node_path3.default.join(directory, "manifest.json");
+  if (!import_node_fs3.default.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(import_node_fs3.default.readFileSync(manifestPath, "utf8"));
+}
+function digest(...parts) {
+  const hash = import_node_crypto.default.createHash("sha256");
+  for (const part of parts) hash.update(part).update("\0");
+  return hash.digest("hex").slice(0, 12);
+}
+function directoryStamp(directory) {
+  const parts = [];
+  const walk = (current) => {
+    for (const entry of import_node_fs3.default.readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : 1)) {
+      const absolute = import_node_path3.default.join(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(absolute);
+        continue;
+      }
+      const stats = import_node_fs3.default.statSync(absolute);
+      parts.push(`${absolute}:${stats.size}:${stats.mtimeMs}`);
+    }
+  };
+  walk(directory);
+  return digest(...parts);
+}
+function findNamespaceDirectory(sourceRoots, namespace) {
+  for (const root of sourceRoots) {
+    if (!import_node_fs3.default.existsSync(root)) continue;
+    for (const entry of import_node_fs3.default.readdirSync(root, { withFileTypes: true })) {
+      if (entry.isDirectory() && entry.name.toLowerCase() === namespace) {
+        return import_node_path3.default.join(root, entry.name);
+      }
+    }
+  }
+  return null;
+}
+function resolveStdlibAssets({
+  options,
+  currentDir: currentDir2,
+  siteDir,
+  cacheDir
+}) {
+  if (!options.enabled) return null;
+  const directory = vendoredDirectory(currentDir2);
+  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 = import_node_path3.default.join(directory, entry.file);
+    if (!import_node_fs3.default.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 ?? []
+    };
+    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);
+  const sourceRoots = options.source.map((entry) => import_node_path3.default.resolve(siteDir, entry));
+  const generatedDir = import_node_path3.default.join(cacheDir ?? import_node_path3.default.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 = import_node_path3.default.join(generatedDir, stamp, stdlibBundleFileName(namespace));
+    if (!import_node_fs3.default.existsSync(cached)) {
+      const bundle = buildStdlibNamespace(import_node_path3.default.dirname(namespaceDir), import_node_path3.default.basename(namespaceDir));
+      import_node_fs3.default.mkdirSync(import_node_path3.default.dirname(cached), { recursive: true });
+      import_node_fs3.default.writeFileSync(cached, bundle.script, "utf8");
+      import_node_fs3.default.writeFileSync(
+        `${cached}.json`,
+        JSON.stringify({
+          dependencies: bundle.dependencies,
+          exampleDependencies: bundle.exampleDependencies
+        }),
+        "utf8"
+      );
+    }
+    const meta = JSON.parse(import_node_fs3.default.readFileSync(`${cached}.json`, "utf8"));
+    const previous = files.findIndex(
+      (file) => import_node_path3.default.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
+    }
+  };
+}
+
 // src/index.ts
-var currentDir = import_node_path2.default.dirname((0, import_node_url.fileURLToPath)(importMetaUrl));
+var currentDir = import_node_path4.default.dirname((0, import_node_url.fileURLToPath)(importMetaUrl));
 function createCopyPlugin(currentBundler, patterns) {
   if (currentBundler?.name === "rspack") {
     const { CopyRspackPlugin } = currentBundler.instance;
@@ -344,20 +700,28 @@ function createCopyPlugin(currentBundler, patterns) {
   }
   return new import_copy_webpack_plugin.default({ patterns });
 }
-function plantumlPlugin(_context, options = {}) {
+function plantumlPlugin(context, options = {}) {
   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
+  });
+  const stdlibDir = stdlib ? `${assetsDir}/stdlib-${stdlib.manifest.revision}` : null;
   return {
     name: PLUGIN_NAME,
     getThemePath() {
-      return import_node_path2.default.join(currentDir, "theme");
+      return import_node_path4.default.join(currentDir, "theme");
     },
     contentLoaded({ actions }) {
       const globalData = {
         options: resolved,
         assetsDir,
-        coreVersion: core.version
+        coreVersion: core.version,
+        stdlib: stdlib && stdlibDir ? { dir: stdlibDir, manifest: stdlib.manifest } : null
       };
       actions.setGlobalData(globalData);
     },
@@ -371,6 +735,15 @@ 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 }
+          }))
+        );
+      }
       return { plugins: [createCopyPlugin(utils?.currentBundler, patterns)] };
     }
   };

package/dist/index.d.cts

@@ -42,6 +42,50 @@ 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.
+ */
+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. */
+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.*`.
  *
@@ -76,14 +120,20 @@ 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. */
-type ResolvedPlantUmlOptions = Required<Omit<PlantUmlPluginOptions, 'id' | 'languages' | 'graphviz'>> & {
+type ResolvedPlantUmlOptions = Required<Omit<PlantUmlPluginOptions, 'id' | 'languages' | 'graphviz' | 'stdlib'>> & {
     /** Normalized to lower case; matching is case-insensitive. */
     languages: string[];
     graphviz: ResolvedGraphvizOptions;
+    stdlib: ResolvedStdlibOptions;
 };
 declare const DEFAULT_OPTIONS: ResolvedPlantUmlOptions;
 /** Thrown for invalid plugin options so Docusaurus fails the build with a useful message. */
@@ -98,6 +148,31 @@ declare class PlantUmlOptionsError extends Error {
  */
 declare function resolveOptions(rawOptions: unknown): ResolvedPlantUmlOptions;
 
+/**
+ * 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. */
+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[];
+}
+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>;
+}
+
 /**
  * Identifiers shared by the Node-side plugin and the browser-side theme components.
  *
@@ -116,6 +191,14 @@ interface PlantUmlGlobalData {
     assetsDir: string;
     /** Installed `@plantuml/core` version; part of the cache key. */
     coreVersion: string;
+    /**
+     * `baseUrl`-relative directory holding the standard library bundles, and what is in it.
+     * `null` when the standard library is switched off.
+     */
+    stdlib: {
+        dir: string;
+        manifest: StdlibRuntimeManifest;
+    } | null;
 }
 /** One copy pattern per runtime file, shared by the webpack and Rspack code paths. */
 interface CopyPattern {
@@ -132,7 +215,7 @@ interface CopyPattern {
  * it is `undefined` and webpack is the only bundler, so an absent value is not an error.
  */
 declare function createCopyPlugin(currentBundler: ConfigureWebpackUtils['currentBundler'] | undefined, patterns: CopyPattern[]): WebpackPluginInstance;
-declare function plantumlPlugin(_context: LoadContext, options?: PlantUmlPluginOptions): Plugin<void>;
+declare function plantumlPlugin(context: LoadContext, options?: PlantUmlPluginOptions): Plugin<void>;
 /**
  * Docusaurus option validation hook. Runs before the plugin function so configuration
  * mistakes fail the build immediately with an actionable message.
@@ -144,4 +227,4 @@ declare function validateOptions({ options, }: {
     options: PlantUmlPluginOptions & Partial<PluginOptions>;
 }): PlantUmlPluginOptions & PluginOptions;
 
-export { type CacheMode, DEFAULT_OPTIONS, type DiagramTheme, PLUGIN_ID, PLUGIN_NAME, type PlantUmlGlobalData, PlantUmlOptionsError, type PlantUmlPluginOptions, type ResolvedPlantUmlOptions, createCopyPlugin, plantumlPlugin as default, resolveOptions, validateOptions };
+export { type CacheMode, DEFAULT_OPTIONS, type DiagramTheme, PLUGIN_ID, PLUGIN_NAME, type PlantUmlGlobalData, PlantUmlOptionsError, type PlantUmlPluginOptions, type ResolvedPlantUmlOptions, type ResolvedStdlibOptions, type StdlibOptions, type StdlibRuntimeManifest, createCopyPlugin, plantumlPlugin as default, resolveOptions, validateOptions };

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 import type { ConfigureWebpackUtils, LoadContext, Plugin, PluginOptions as DocusaurusPluginOptions } from '@docusaurus/types';
 import type { WebpackPluginInstance } from 'webpack';
 import { type PlantUmlPluginOptions, type ResolvedPlantUmlOptions } from './options.js';
-export type { CacheMode, DiagramTheme, PlantUmlPluginOptions, ResolvedPlantUmlOptions, } from './options.js';
+import { type StdlibRuntimeManifest } from './stdlib.js';
+export type { CacheMode, DiagramTheme, PlantUmlPluginOptions, ResolvedPlantUmlOptions, StdlibOptions, ResolvedStdlibOptions, } from './options.js';
 export { DEFAULT_OPTIONS, PlantUmlOptionsError, resolveOptions } from './options.js';
 export { PLUGIN_ID, PLUGIN_NAME } from './constants.js';
+export type { StdlibRuntimeManifest } from './stdlib.js';
 /** Shape of the data this plugin publishes to the browser through Docusaurus global data. */
 export interface PlantUmlGlobalData {
     options: ResolvedPlantUmlOptions;
@@ -11,6 +13,14 @@ export interface PlantUmlGlobalData {
     assetsDir: string;
     /** Installed `@plantuml/core` version; part of the cache key. */
     coreVersion: string;
+    /**
+     * `baseUrl`-relative directory holding the standard library bundles, and what is in it.
+     * `null` when the standard library is switched off.
+     */
+    stdlib: {
+        dir: string;
+        manifest: StdlibRuntimeManifest;
+    } | null;
 }
 /** One copy pattern per runtime file, shared by the webpack and Rspack code paths. */
 interface CopyPattern {
@@ -27,7 +37,7 @@ interface CopyPattern {
  * it is `undefined` and webpack is the only bundler, so an absent value is not an error.
  */
 export declare function createCopyPlugin(currentBundler: ConfigureWebpackUtils['currentBundler'] | undefined, patterns: CopyPattern[]): WebpackPluginInstance;
-export default function plantumlPlugin(_context: LoadContext, options?: PlantUmlPluginOptions): Plugin<void>;
+export default function plantumlPlugin(context: LoadContext, options?: PlantUmlPluginOptions): Plugin<void>;
 /**
  * Docusaurus option validation hook. Runs before the plugin function so configuration
  * mistakes fail the build immediately with an actionable message.