@matfsw/docusaurus-plantuml-plugin 1.7.1 → 1.8.1

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_path5 = __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);
 
@@ -59,10 +59,9 @@ var import_node_path = __toESM(require("path"), 1);
 var PLUGIN_ID = "plantuml-client";
 var DEFAULT_PLUGIN_ID = "default";
 var PLUGIN_NAME = `docusaurus-plugin-${PLUGIN_ID}`;
-var UPSTREAM_MAX_DIAGRAM_SIZE = 4096;
-var MAX_DIAGRAM_SIZE = 32768;
+var MINIMUM_CORE_VERSION = "1.2026.8";
 function assetsDirForVersion(coreVersion) {
-  return `assets/${PLUGIN_ID}-${coreVersion}-max${MAX_DIAGRAM_SIZE}`;
+  return `assets/${PLUGIN_ID}-${coreVersion}`;
 }
 var VIZ_SCRIPT_FILENAME = "viz-global.js";
 var PLANTUML_MODULE_FILENAME = "plantuml.js";
@@ -82,6 +81,7 @@ function locatePlantUmlCore() {
   const packageDir = import_node_path.default.dirname(packageJsonPath);
   const packageJson = JSON.parse(import_node_fs.default.readFileSync(packageJsonPath, "utf8"));
   const version = typeof packageJson.version === "string" ? packageJson.version : "0.0.0";
+  assertSupportedVersion(version);
   const files = [
     import_node_path.default.join(packageDir, VIZ_SCRIPT_FILENAME),
     import_node_path.default.join(packageDir, PLANTUML_MODULE_FILENAME)
@@ -95,52 +95,22 @@ function assertRuntimeFile(file, version) {
     `[${PLUGIN_NAME}] '@plantuml/core@${version}' does not contain '${import_node_path.default.basename(file)}', which this plugin serves as a runtime asset. This means the installed version of @plantuml/core is not one this plugin supports. Pin a supported version, or open an issue if the package has genuinely changed its layout.`
   );
 }
-
-// src/enginePatch.ts
-var import_node_fs2 = __toESM(require("fs"), 1);
-var import_node_path2 = __toESM(require("path"), 1);
-var COMPARISON = `>${UPSTREAM_MAX_DIAGRAM_SIZE}.0)`;
-var COMPARISON_OCCURRENCES = 2;
-var MESSAGE_SUFFIX = ` (max ${UPSTREAM_MAX_DIAGRAM_SIZE})`;
-var MESSAGE_SUFFIX_OCCURRENCES = 1;
-var PATCHED_COMPARISON = `>${MAX_DIAGRAM_SIZE}.0)`;
-var PATCHED_MESSAGE_SUFFIX = ` (max ${MAX_DIAGRAM_SIZE})`;
-var PATCH_SIZE_DELTA = COMPARISON_OCCURRENCES * (PATCHED_COMPARISON.length - COMPARISON.length) + MESSAGE_SUFFIX_OCCURRENCES * (PATCHED_MESSAGE_SUFFIX.length - MESSAGE_SUFFIX.length);
-var CACHE_SUBDIRECTORY = "plantuml-engine";
-function countOccurrences(haystack, needle) {
-  let count = 0;
-  let index = haystack.indexOf(needle);
-  while (index !== -1) {
-    count += 1;
-    index = haystack.indexOf(needle, index + needle.length);
-  }
-  return count;
-}
-function assertOccurrences(source, needle, expected, coreVersion) {
-  const found = countOccurrences(source, needle);
-  if (found === expected) return;
+function compareVersions(left, right) {
+  const parse = (value) => (value.split("-")[0] ?? "").split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const a = parse(left);
+  const b = parse(right);
+  for (let index = 0; index < 3; index += 1) {
+    const difference = (a[index] ?? 0) - (b[index] ?? 0);
+    if (difference !== 0) return difference;
+  }
+  return 0;
+}
+function assertSupportedVersion(version) {
+  if (compareVersions(version, MINIMUM_CORE_VERSION) >= 0) return;
   throw new Error(
-    `[${PLUGIN_NAME}] Cannot raise the diagram size ceiling of '@plantuml/core@${coreVersion}': expected ${expected} occurrence(s) of ${JSON.stringify(needle)} in '${PLANTUML_MODULE_FILENAME}', found ${found}. The engine no longer has the shape this plugin patches, which means the installed @plantuml/core is not one this plugin supports. Pin @plantuml/core to the last version that worked, or upgrade this plugin.`
+    `[${PLUGIN_NAME}] '@plantuml/core@${version}' is older than the minimum this plugin supports, ${MINIMUM_CORE_VERSION}. That release added the 'maxSvgSize' render option this plugin's \`maxSvgSize\` setting relies on; on an older engine the setting would be silently ignored and diagrams larger than 4096 points would be refused. Update @plantuml/core, or remove the override or stale lockfile entry pinning it.`
   );
 }
-function patchEngineSource(source, coreVersion) {
-  assertOccurrences(source, COMPARISON, COMPARISON_OCCURRENCES, coreVersion);
-  assertOccurrences(source, MESSAGE_SUFFIX, MESSAGE_SUFFIX_OCCURRENCES, coreVersion);
-  return source.split(COMPARISON).join(PATCHED_COMPARISON).split(MESSAGE_SUFFIX).join(PATCHED_MESSAGE_SUFFIX);
-}
-function resolvePatchedEngine(options) {
-  const { vendoredPath, coreVersion, siteDir, cacheDir } = options;
-  const generatedDir = cacheDir ?? import_node_path2.default.join(siteDir, ".docusaurus");
-  const target = import_node_path2.default.join(generatedDir, CACHE_SUBDIRECTORY, coreVersion, PLANTUML_MODULE_FILENAME);
-  const expectedSize = import_node_fs2.default.statSync(vendoredPath).size + PATCH_SIZE_DELTA;
-  if (import_node_fs2.default.existsSync(target) && import_node_fs2.default.statSync(target).size === expectedSize) return target;
-  const patched = patchEngineSource(import_node_fs2.default.readFileSync(vendoredPath, "utf8"), coreVersion);
-  import_node_fs2.default.mkdirSync(import_node_path2.default.dirname(target), { recursive: true });
-  const temporary = `${target}.${process.pid}.tmp`;
-  import_node_fs2.default.writeFileSync(temporary, patched, "utf8");
-  import_node_fs2.default.renameSync(temporary, target);
-  return target;
-}
 
 // src/options.ts
 var GRAPHVIZ_ENGINES = [
@@ -179,6 +149,7 @@ var DEFAULT_OPTIONS = {
   showSourceOnError: true,
   renderTimeoutMs: 2e4,
   cacheMaxEntries: 50,
+  maxSvgSize: 32768,
   zoom: true,
   showSource: true,
   graphviz: DEFAULT_GRAPHVIZ_OPTIONS,
@@ -373,6 +344,15 @@ function validateCacheMaxEntries(value) {
   }
   return value;
 }
+function validateMaxSvgSize(value) {
+  if (value === void 0) return DEFAULT_OPTIONS.maxSvgSize;
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    fail(
+      `options.maxSvgSize must be a non-negative integer (0 disables the ceiling), received ${JSON.stringify(value)}.`
+    );
+  }
+  return value;
+}
 function resolveOptions(rawOptions) {
   if (rawOptions === void 0 || rawOptions === null) {
     return {
@@ -394,6 +374,7 @@ function resolveOptions(rawOptions) {
     "showSourceOnError",
     "renderTimeoutMs",
     "cacheMaxEntries",
+    "maxSvgSize",
     "zoom",
     "showSource",
     "graphviz",
@@ -446,6 +427,7 @@ function resolveOptions(rawOptions) {
     ),
     renderTimeoutMs: validateRenderTimeout(rawOptions.renderTimeoutMs),
     cacheMaxEntries: validateCacheMaxEntries(rawOptions.cacheMaxEntries),
+    maxSvgSize: validateMaxSvgSize(rawOptions.maxSvgSize),
     zoom: validateBoolean(rawOptions.zoom, "zoom", DEFAULT_OPTIONS.zoom),
     showSource: validateBoolean(rawOptions.showSource, "showSource", DEFAULT_OPTIONS.showSource)
   };
@@ -453,13 +435,13 @@ function resolveOptions(rawOptions) {
 
 // src/stdlib.ts
 var import_node_crypto = __toESM(require("crypto"), 1);
-var import_node_fs4 = __toESM(require("fs"), 1);
-var import_node_path4 = __toESM(require("path"), 1);
-
-// src/stdlibBundle.ts
 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;
@@ -492,17 +474,17 @@ function isSkippedDirectory(name) {
   return name.startsWith("_") && name.endsWith("_");
 }
 function collectFiles(directory, namespaceRoot) {
-  const entries = import_node_fs3.default.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+  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_path3.default.join(directory, entry.name);
+    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_path3.default.extname(entry.name).toLowerCase();
+    const extension = import_node_path2.default.extname(entry.name).toLowerCase();
     if (extension !== ".puml" && extension !== ".json") continue;
-    const key = import_node_path3.default.relative(namespaceRoot, absolutePath).split(import_node_path3.default.sep).join("/").toLowerCase();
+    const key = import_node_path2.default.relative(namespaceRoot, absolutePath).split(import_node_path2.default.sep).join("/").toLowerCase();
     files.push({
       key,
       absolutePath,
@@ -513,9 +495,9 @@ function collectFiles(directory, namespaceRoot) {
   return files;
 }
 function readNamespaceInfo(namespaceRoot) {
-  const readme = import_node_path3.default.join(namespaceRoot, "README.md");
-  if (!import_node_fs3.default.existsSync(readme)) return {};
-  const lines = import_node_fs3.default.readFileSync(readme, "utf8").split(/\r\n|\r|\n/);
+  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)) {
@@ -554,8 +536,8 @@ function stdlibBundleFileName(namespace) {
   return `${namespace.toLowerCase()}.min.js`;
 }
 function buildStdlibNamespace(stdlibRoot, directoryName) {
-  const namespaceRoot = import_node_path3.default.join(stdlibRoot, directoryName);
-  if (!import_node_fs3.default.existsSync(namespaceRoot) || !import_node_fs3.default.statSync(namespaceRoot).isDirectory()) {
+  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();
@@ -576,7 +558,7 @@ function buildStdlibNamespace(stdlibRoot, directoryName) {
     `  var J = (w.PLANTUML_STDLIB_JSON[${quoted}] = w.PLANTUML_STDLIB_JSON[${quoted}] || {});`
   ];
   for (const file of files) {
-    const text = import_node_fs3.default.readFileSync(file.absolutePath, "utf8");
+    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);
@@ -604,16 +586,16 @@ function buildStdlibNamespace(stdlibRoot, directoryName) {
 
 // src/stdlib.ts
 function vendoredDirectory(currentDir2) {
-  return import_node_path4.default.join(currentDir2, "..", "assets", "stdlib");
+  return import_node_path3.default.join(currentDir2, "..", "assets", "stdlib");
 }
 function readVendoredManifest(directory) {
-  const manifestPath = import_node_path4.default.join(directory, "manifest.json");
-  if (!import_node_fs4.default.existsSync(manifestPath)) {
+  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_fs4.default.readFileSync(manifestPath, "utf8"));
+  return JSON.parse(import_node_fs3.default.readFileSync(manifestPath, "utf8"));
 }
 function digest(...parts) {
   const hash = import_node_crypto.default.createHash("sha256");
@@ -623,13 +605,13 @@ function digest(...parts) {
 function directoryStamp(directory) {
   const parts = [];
   const walk = (current) => {
-    for (const entry of import_node_fs4.default.readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : 1)) {
-      const absolute = import_node_path4.default.join(current, entry.name);
+    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_fs4.default.statSync(absolute);
+      const stats = import_node_fs3.default.statSync(absolute);
       parts.push(`${absolute}:${stats.size}:${stats.mtimeMs}`);
     }
   };
@@ -638,10 +620,10 @@ function directoryStamp(directory) {
 }
 function findNamespaceDirectory(sourceRoots, namespace) {
   for (const root of sourceRoots) {
-    if (!import_node_fs4.default.existsSync(root)) continue;
-    for (const entry of import_node_fs4.default.readdirSync(root, { withFileTypes: true })) {
+    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_path4.default.join(root, entry.name);
+        return import_node_path3.default.join(root, entry.name);
       }
     }
   }
@@ -663,8 +645,8 @@ function resolveStdlibAssets({
     if (namespace in namespaces) return;
     const entry = vendoredNamespaces[namespace];
     if (!entry) return;
-    const bundlePath = import_node_path4.default.join(directory, entry.file);
-    if (!import_node_fs4.default.existsSync(bundlePath)) {
+    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.`
       );
@@ -688,8 +670,8 @@ function resolveStdlibAssets({
     }
   }
   for (const namespace of selected) addVendored(namespace);
-  const sourceRoots = options.source.map((entry) => import_node_path4.default.resolve(siteDir, entry));
-  const generatedDir = import_node_path4.default.join(cacheDir ?? import_node_path4.default.join(siteDir, ".docusaurus"), "plantuml-stdlib");
+  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);
@@ -700,12 +682,12 @@ function resolveStdlibAssets({
     }
     const stamp = directoryStamp(namespaceDir);
     stamps.push(`${namespace}:${stamp}`);
-    const cached = import_node_path4.default.join(generatedDir, stamp, stdlibBundleFileName(namespace));
-    if (!import_node_fs4.default.existsSync(cached)) {
-      const bundle = buildStdlibNamespace(import_node_path4.default.dirname(namespaceDir), import_node_path4.default.basename(namespaceDir));
-      import_node_fs4.default.mkdirSync(import_node_path4.default.dirname(cached), { recursive: true });
-      import_node_fs4.default.writeFileSync(cached, bundle.script, "utf8");
-      import_node_fs4.default.writeFileSync(
+    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,
@@ -714,9 +696,9 @@ function resolveStdlibAssets({
         "utf8"
       );
     }
-    const meta = JSON.parse(import_node_fs4.default.readFileSync(`${cached}.json`, "utf8"));
+    const meta = JSON.parse(import_node_fs3.default.readFileSync(`${cached}.json`, "utf8"));
     const previous = files.findIndex(
-      (file) => import_node_path4.default.basename(file) === stdlibBundleFileName(namespace)
+      (file) => import_node_path3.default.basename(file) === stdlibBundleFileName(namespace)
     );
     if (previous !== -1) files.splice(previous, 1);
     files.push(cached);
@@ -735,7 +717,7 @@ function resolveStdlibAssets({
 }
 
 // src/index.ts
-var currentDir = import_node_path5.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;
@@ -762,7 +744,7 @@ function plantumlPlugin(context, options = {}) {
   return {
     name: PLUGIN_NAME,
     getThemePath() {
-      return import_node_path5.default.join(currentDir, "theme");
+      return import_node_path4.default.join(currentDir, "theme");
     },
     contentLoaded({ actions }) {
       const globalData = {
@@ -777,14 +759,8 @@ function plantumlPlugin(context, options = {}) {
       if (isServer) {
         return {};
       }
-      const engine = resolvePatchedEngine({
-        vendoredPath: import_node_path5.default.join(core.packageDir, PLANTUML_MODULE_FILENAME),
-        coreVersion: core.version,
-        siteDir: context.siteDir,
-        cacheDir: context.generatedFilesDir
-      });
       const patterns = core.files.map((absolutePath) => ({
-        from: import_node_path5.default.basename(absolutePath) === PLANTUML_MODULE_FILENAME ? engine : absolutePath,
+        from: absolutePath,
         to: `${assetsDir}/[name][ext]`,
         // These files are already minified upstream; re-processing 8 MB is wasted work.
         info: { minimized: true }

package/dist/index.d.cts

@@ -108,6 +108,20 @@ interface PlantUmlPluginOptions {
     renderTimeoutMs?: number;
     /** Maximum number of cached SVG entries kept per browsing session. */
     cacheMaxEntries?: number;
+    /**
+     * Refuse to render a PlantUML diagram wider or taller than this many points.
+     *
+     * The engine measures the laid-out diagram before serializing it and reports anything
+     * larger through its error callback. Its own default is 8192; this plugin raises it to
+     * 32768, which is high enough that a real architecture diagram or release runbook does not
+     * hit it. `0` removes the check entirely.
+     *
+     * Raising it is not free: the resulting SVG is parsed synchronously twice on its way into
+     * the page, so a diagram of many thousands of points can stall the tab and may need
+     * `renderTimeoutMs` raised with it. Graphviz fences are bounded by
+     * `graphviz.maxSourceBytes` instead — this option does not apply to them.
+     */
+    maxSvgSize?: number;
     /**
      * Let readers zoom and pan rendered diagrams, with a small control toolbar.
      * Override for a single fence with `zoom` or `zoom=false` in its metastring.

package/dist/index.js

@@ -2,8 +2,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import CopyWebpackPlugin from 'copy-webpack-plugin';
 import { locatePlantUmlCore } from './assets.js';
-import { assetsDirForVersion, DEFAULT_PLUGIN_ID, PLANTUML_MODULE_FILENAME, PLUGIN_NAME, } from './constants.js';
-import { resolvePatchedEngine } from './enginePatch.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';
@@ -63,18 +62,8 @@ export default function plantumlPlugin(context, options = {}) {
             if (isServer) {
                 return {};
             }
-            // The engine is patched to raise its 4096-point diagram ceiling, so what is emitted is
-            // a generated file rather than the vendored one. It happens here rather than in the
-            // plugin factory so that `swizzle`, `write-translations` and the server compilation do
-            // not each pay to read and rewrite 7 MB for output they never emit.
-            const engine = resolvePatchedEngine({
-                vendoredPath: path.join(core.packageDir, PLANTUML_MODULE_FILENAME),
-                coreVersion: core.version,
-                siteDir: context.siteDir,
-                cacheDir: context.generatedFilesDir,
-            });
             const patterns = core.files.map((absolutePath) => ({
-                from: path.basename(absolutePath) === PLANTUML_MODULE_FILENAME ? engine : absolutePath,
+                from: absolutePath,
                 to: `${assetsDir}/[name][ext]`,
                 // These files are already minified upstream; re-processing 8 MB is wasted work.
                 info: { minimized: true },

package/dist/options.d.ts

@@ -105,6 +105,20 @@ export interface PlantUmlPluginOptions {
     renderTimeoutMs?: number;
     /** Maximum number of cached SVG entries kept per browsing session. */
     cacheMaxEntries?: number;
+    /**
+     * Refuse to render a PlantUML diagram wider or taller than this many points.
+     *
+     * The engine measures the laid-out diagram before serializing it and reports anything
+     * larger through its error callback. Its own default is 8192; this plugin raises it to
+     * 32768, which is high enough that a real architecture diagram or release runbook does not
+     * hit it. `0` removes the check entirely.
+     *
+     * Raising it is not free: the resulting SVG is parsed synchronously twice on its way into
+     * the page, so a diagram of many thousands of points can stall the tab and may need
+     * `renderTimeoutMs` raised with it. Graphviz fences are bounded by
+     * `graphviz.maxSourceBytes` instead — this option does not apply to them.
+     */
+    maxSvgSize?: number;
     /**
      * Let readers zoom and pan rendered diagrams, with a small control toolbar.
      * Override for a single fence with `zoom` or `zoom=false` in its metastring.

package/dist/options.js

@@ -42,6 +42,7 @@ export const DEFAULT_OPTIONS = {
     showSourceOnError: true,
     renderTimeoutMs: 20_000,
     cacheMaxEntries: 50,
+    maxSvgSize: 32_768,
     zoom: true,
     showSource: true,
     graphviz: DEFAULT_GRAPHVIZ_OPTIONS,
@@ -240,6 +241,24 @@ function validateCacheMaxEntries(value) {
     }
     return value;
 }
+/**
+ * Validates `maxSvgSize`, which is a size in PlantUML points and not a byte count.
+ *
+ * `0` is accepted and means "no ceiling" — that is the engine's own convention for the
+ * option, and it is the only value that is not simply a size. Negative numbers are rejected
+ * rather than passed through: the engine treats a negative as "unspecified" and falls back to
+ * its 8192 default, so `-1` would silently mean something quite different from what it reads
+ * like.
+ */
+function validateMaxSvgSize(value) {
+    if (value === undefined)
+        return DEFAULT_OPTIONS.maxSvgSize;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        fail('options.maxSvgSize must be a non-negative integer (0 disables the ceiling), ' +
+            `received ${JSON.stringify(value)}.`);
+    }
+    return value;
+}
 /**
  * Validates raw plugin options and applies defaults.
  *
@@ -267,6 +286,7 @@ export function resolveOptions(rawOptions) {
         'showSourceOnError',
         'renderTimeoutMs',
         'cacheMaxEntries',
+        'maxSvgSize',
         'zoom',
         'showSource',
         'graphviz',
@@ -309,6 +329,7 @@ export function resolveOptions(rawOptions) {
         showSourceOnError: validateBoolean(rawOptions.showSourceOnError, 'showSourceOnError', DEFAULT_OPTIONS.showSourceOnError),
         renderTimeoutMs: validateRenderTimeout(rawOptions.renderTimeoutMs),
         cacheMaxEntries: validateCacheMaxEntries(rawOptions.cacheMaxEntries),
+        maxSvgSize: validateMaxSvgSize(rawOptions.maxSvgSize),
         zoom: validateBoolean(rawOptions.zoom, 'zoom', DEFAULT_OPTIONS.zoom),
         showSource: validateBoolean(rawOptions.showSource, 'showSource', DEFAULT_OPTIONS.showSource),
     };

package/dist/runtime/cache.d.ts

@@ -9,6 +9,14 @@ export interface CacheKeyInput {
      * invalidates the entries whose pictures it shaped. `null` when it is switched off.
      */
     stdlibRevision: string | null;
+    /**
+     * The size ceiling the entry was rendered under.
+     *
+     * Part of the key because the option can be *lowered*, and `session` mode outlives a
+     * rebuild: without it, a site that tightened `maxSvgSize` would keep serving readers the
+     * oversized diagram their tab had already cached.
+     */
+    maxSvgSize: number;
 }
 export interface DiagramCache {
     readonly mode: CacheMode;
@@ -18,7 +26,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, stdlibRevision, }: CacheKeyInput): string;
+export declare function computeCacheKey({ source, dark, sanitized, coreVersion, stdlibRevision, maxSvgSize, }: 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,13 @@ function hash(input) {
     }
     return value.toString(36).padStart(7, '0');
 }
-export function computeCacheKey({ source, dark, sanitized, coreVersion, stdlibRevision, }) {
+export function computeCacheKey({ source, dark, sanitized, coreVersion, stdlibRevision, maxSvgSize, }) {
     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}|${stdlibRevision ?? 'nostd'}|${mode}|${clean}|${source.length}|${hash(source)}`;
+    return (`${coreVersion}|${stdlibRevision ?? 'nostd'}|${mode}|${clean}|max${maxSvgSize}|` +
+        `${source.length}|${hash(source)}`);
 }
 /**
  * Cache key for a Graphviz diagram.

package/dist/runtime/renderer.d.ts

@@ -6,6 +6,8 @@ export interface RenderDiagramRequest {
     dark: boolean;
     sanitize: boolean;
     timeoutMs: number;
+    /** Size ceiling in PlantUML points, passed straight to the engine. `0` disables it. */
+    maxSvgSize: number;
     assetsBaseUrl: string;
     coreVersion: string;
     /** Standard library assets for this site, or `null` when the feature is switched off. */

package/dist/runtime/renderer.js

@@ -9,8 +9,12 @@ import { loadStdlibForSource } from './stdlibLoader.js';
  * This was verified against the installed `@plantuml/core` rather than assumed: the
  * function's arity is 4 and `{dark: true}` produces different fill colours from `{dark:
  * false}`, which itself is byte-identical to omitting the argument.
+ *
+ * `maxSvgSize` is always passed rather than omitted when it matches a default. The engine's
+ * own default (8192) is lower than this plugin's (32768), so omitting it would quietly
+ * tighten the ceiling.
  */
-function renderWithEngine(engine, source, dark) {
+function renderWithEngine(engine, source, dark, maxSvgSize) {
     return new Promise((resolve, reject) => {
         let settled = false;
         const lines = source.split(/\r\n|\r|\n/);
@@ -25,7 +29,7 @@ function renderWithEngine(engine, source, dark) {
                     return;
                 settled = true;
                 reject(new PlantUmlError('engine', describeEngineError(raw)));
-            }, { dark });
+            }, { dark, maxSvgSize });
         }
         catch (error) {
             if (settled)
@@ -42,13 +46,14 @@ 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, stdlib, signal, onPhase } = request;
+    const { source, dark, sanitize, timeoutMs, maxSvgSize, cache, coreVersion, stdlib, signal, onPhase, } = request;
     const cacheKey = computeCacheKey({
         source,
         dark,
         sanitized: sanitize,
         coreVersion,
         stdlibRevision: stdlib?.manifest.revision ?? null,
+        maxSvgSize,
     });
     const cached = cache.get(cacheKey);
     if (cached !== undefined)
@@ -70,7 +75,7 @@ export async function renderDiagram(request) {
     ]);
     onPhase?.('rendering');
     const svg = await enqueueRender(async () => {
-        const raw = await renderWithEngine(engine, source, dark);
+        const raw = await renderWithEngine(engine, source, dark, maxSvgSize);
         // Invalid PlantUML is reported as a successfully rendered "error picture", not through
         // the error callback, so a rendered SVG still has to be inspected before it is trusted.
         const diagramError = detectDiagramError(raw);

package/dist/runtime/types.d.ts

@@ -1,9 +1,9 @@
 /**
  * The public surface of `@plantuml/core@1.2026.x`, verified against the installed package.
  *
- * `plantuml.js` exports exactly two functions. Both take an optional trailing options
- * object whose only recognized member is `dark`; see `docs/architecture.md` for how this
- * was established and `tests/e2e/engine-contract.spec.ts` for the regression guard.
+ * `plantuml.js` exports exactly two functions. Both take an optional trailing options object
+ * whose recognized members are `dark` and `maxSvgSize`; see `docs/architecture.md` for how
+ * this was established and `tests/e2e/engine-contract.spec.ts` for the regression guard.
  */
 export interface PlantUmlCoreModule {
     render(lines: string[], targetId: string, options?: PlantUmlRenderOptions): void;
@@ -11,6 +11,15 @@ export interface PlantUmlCoreModule {
 }
 export interface PlantUmlRenderOptions {
     dark?: boolean;
+    /**
+     * Ceiling, in PlantUML points, on the laid-out diagram's width and height.
+     *
+     * Added in `@plantuml/core@1.2026.8`; `src/assets.ts` refuses to build against anything
+     * older, because an engine that does not know the option ignores it silently. `0` disables
+     * the check; a *negative* value is treated by the engine as unspecified and falls back to
+     * its own 8192 default, which is why `options.maxSvgSize` rejects negatives outright.
+     */
+    maxSvgSize?: number;
 }
 export type DiagramStatus = 'idle' | 'loading' | 'rendering' | 'ready' | 'error';
 /** Which engine renders a given fence. */

package/dist/theme/PlantUmlDiagram/index.js

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