@matfsw/docusaurus-plantuml-plugin 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -7,6 +7,71 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.8.0] - 2026-09-08
+
+### Added
+
+- **`maxSvgSize` — the diagram size ceiling is now a plugin option.** It defaults to `32768`
+  points, exactly the value 1.7.0 applied, so nothing renders differently unless you change
+  it. Raise it for a diagram that still does not fit, or set it to `0` to remove the check:
+
+  ```ts
+  {
+    maxSvgSize: 65_536, // or 0 for no ceiling at all
+  }
+  ```
+
+  It takes a non-negative integer and applies to PlantUML fences only — Graphviz keeps its own
+  `graphviz.maxSourceBytes` guard. A negative value is rejected at build time rather than
+  passed through, because the engine reads a negative as "unspecified" and would quietly fall
+  back to its own 8192 default. See [Diagram size](README.md#diagram-size) and
+  [ADR 0008](docs/adr/0008-configurable-max-svg-size.md).
+
+### Changed
+
+- **The engine is no longer patched.** 1.7.0 rewrote two literals in `@plantuml/core`'s
+  minified bundle to raise a ceiling that had no option behind it. Upstream has since added
+  one ([plantuml/plantuml#2832](https://github.com/plantuml/plantuml/issues/2832)), so the
+  rewrite is gone and the vendored engine ships as published. The build no longer reads and
+  rewrites 7 MB, and `.docusaurus/plantuml-engine/` is no longer generated — an existing one
+  from 1.7.x is orphaned and can be deleted.
+- **`@plantuml/core` now requires `>= 1.2026.8`**, the release that added `maxSvgSize`. An
+  older engine ignores render options it does not know, which would leave `maxSvgSize` reading
+  as honoured while the stock 4096-point ceiling refused large diagrams — so the build fails
+  naming the installed version instead. If an override or a stale lockfile pins you below it,
+  update `@plantuml/core`.
+- **The runtime assets moved back to `assets/plantuml-client-<coreVersion>/`.** The
+  `-max32768` segment existed to distinguish differently patched engines; with no patch it
+  distinguishes nothing. The URL changes anyway because the engine version changes, so this
+  costs no extra cache churn. The standard library is nested inside that directory and is
+  re-downloaded once. No configuration changes.
+- **`maxSvgSize` is part of the render cache key.** The ceiling can be lowered, and `session`
+  cache entries outlive the rebuild that lowered it; without this a site that tightened the
+  setting would keep serving readers the oversized diagram their tab had already cached.
+
+### Fixed
+
+- **An in-diagram link to a path the running build does not route no longer dead-ends on
+  "Page not found".** Clicks used to go through the Docusaurus router whenever the target was
+  same-origin. On a site published as several Docusaurus builds — one per product area, a docs
+  build beside a marketing build, two builds joined by a reverse proxy — the bundles share an
+  origin but each routes only its own subtree, so a link to a sibling build's page matched no
+  route, rendered *this* build's `NotFound`, and never reached the server that could serve it.
+  The tell was that reloading the same URL worked.
+
+  The plugin now checks the running build's route table and pushes only what this build
+  routes, handing anything else to the browser as a normal navigation. An unknown page inside
+  a subtree this build owns still routes client-side, because its own 404 page is the right
+  answer there. Single-build sites are unaffected. As a side benefit, `experimental_router:
+  'hash'` — where a site-absolute link resolves to a path the router cannot push — now falls
+  back to a native load instead of going nowhere.
+
+## [1.7.1] - 2026-09-03
+
+### Changed
+
+- Bump the all-security group across 2 directories with 1 update (#37)
+
 ## [1.7.0] - 2026-09-02
 
 ### Added
@@ -652,7 +717,9 @@ Initial release.
   opt-out.
 - Plugin option validation that rejects unknown keys and out-of-range values at build time.
 
-[Unreleased]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.7.0...HEAD
+[Unreleased]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.8.0...HEAD
+[1.8.0]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.7.1...v1.8.0
+[1.7.1]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.7.0...v1.7.1
 [1.7.0]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.6.3...v1.7.0
 [1.6.3]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.6.2...v1.6.3
 [1.6.2]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.6.1...v1.6.2

package/README.md

@@ -60,7 +60,7 @@ them are exported.
 | Node.js (build) | `>= 20.9.0` (the Node 20 LTS line)                                                     |
 | React           | `18.x` or `19.x` (matching your Docusaurus install)                                    |
 | Bundler         | webpack (default) and Rspack (`future.v4` / `@docusaurus/faster`)                      |
-| PlantUML engine | `@plantuml/core` `1.2026.6`                                                            |
+| PlantUML engine | `@plantuml/core` `>= 1.2026.8`                                                         |
 | Browsers        | Modern evergreen browsers; no IE (see [Browser compatibility](#browser-compatibility)) |
 
 The plugin requires a theme that already provides `MDXComponents/Code` — in practice
@@ -100,8 +100,10 @@ exactly what the compatibility job in CI does to test the `3.5.2` leg.
 ### A note on the engine's licence
 
 `@plantuml/core` is MIT-licensed **from version `1.2026.6` onwards**. Earlier versions were
-published under GPL-3.0-or-later. This plugin depends on `^1.2026.6` for that reason; if you
-pin or dedupe `@plantuml/core` to an older version yourself, you inherit the older licence.
+published under GPL-3.0-or-later. This plugin depends on `^1.2026.8` — which is well past that
+line, and is also the release that added the `maxSvgSize` option
+[`maxSvgSize`](#diagram-size) relies on. Pinning or deduping `@plantuml/core` below `1.2026.8`
+fails the build with a message naming the version, rather than silently ignoring the option.
 
 ## Installation
 
@@ -149,6 +151,7 @@ const config: Config = {
         showSourceOnError: true,
         renderTimeoutMs: 20_000,
         cacheMaxEntries: 50,
+        maxSvgSize: 32_768,
         zoom: true,
         graphviz: {
           enabled: true,
@@ -231,26 +234,29 @@ props untouched. Existing code-block behaviour (highlighting, line numbers, titl
 
 ## Options
 
-| Option              | Type                              | Default                | Description                                                                                                                         |
-| ------------------- | --------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `languages`         | `string[]`                        | `['plantuml', 'puml']` | Fence languages treated as PlantUML. Matched case-insensitively; must contain at least one non-empty, non-duplicate entry.          |
-| `theme`             | `'auto' \| 'light' \| 'dark'`     | `'auto'`               | Diagram colour scheme. `auto` follows the Docusaurus colour mode; `light`/`dark` pin it.                                            |
-| `lazy`              | `boolean`                         | `true`                 | Render a diagram only once it scrolls near the viewport (300 px root margin).                                                       |
-| `cache`             | `'none' \| 'memory' \| 'session'` | `'memory'`             | Where rendered SVG is cached.                                                                                                       |
-| `sanitizeSvg`       | `boolean`                         | `true`                 | Run rendered SVG through DOMPurify before inserting it. See [Security model](#svg-sanitization-and-security-model).                 |
-| `showSourceOnError` | `boolean`                         | `true`                 | Include the diagram source in a `<details>` block on the error panel.                                                               |
-| `renderTimeoutMs`   | `number`                          | `20000`                | Abort a single render (and the runtime load) after this many milliseconds. Integer, `100`–`600000`.                                 |
-| `cacheMaxEntries`   | `number`                          | `50`                   | Upper bound on cached SVG entries. Positive integer.                                                                                |
-| `zoom`              | `boolean`                         | `true`                 | Let readers zoom and pan diagrams. Adds a control toolbar and a focusable viewport. Override per fence with `zoom=false`.           |
-| `showSource`        | `boolean`                         | `true`                 | Offer a toolbar control that reveals the diagram source and copies it to the clipboard. Override per fence with `showSource=false`. |
-| `graphviz`          | `object`                          | see below              | Graphviz/DOT support. See [Graphviz options](#graphviz-options).                                                                    |
-| `stdlib`            | `object \| false`                 | see below              | PlantUML standard library (`!include <C4/…>`). See [Standard library options](#standard-library-options).                           |
-| `id`                | `string`                          | `'default'`            | Docusaurus plugin instance id; only relevant if you register the plugin more than once.                                             |
-
-Every option above except `graphviz` and `stdlib` applies to **both** engines: `lazy`, `cache`,
-`sanitizeSvg`, `showSourceOnError`, `renderTimeoutMs`, `cacheMaxEntries` and `zoom` behave
-identically for a `dot` fence and a `plantuml` fence. `theme` is the exception — see
-[Light and dark mode](#light-and-dark-mode).
+| Option              | Type                              | Default                | Description                                                                                                                                       |
+| ------------------- | --------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `languages`         | `string[]`                        | `['plantuml', 'puml']` | Fence languages treated as PlantUML. Matched case-insensitively; must contain at least one non-empty, non-duplicate entry.                        |
+| `theme`             | `'auto' \| 'light' \| 'dark'`     | `'auto'`               | Diagram colour scheme. `auto` follows the Docusaurus colour mode; `light`/`dark` pin it.                                                          |
+| `lazy`              | `boolean`                         | `true`                 | Render a diagram only once it scrolls near the viewport (300 px root margin).                                                                     |
+| `cache`             | `'none' \| 'memory' \| 'session'` | `'memory'`             | Where rendered SVG is cached.                                                                                                                     |
+| `sanitizeSvg`       | `boolean`                         | `true`                 | Run rendered SVG through DOMPurify before inserting it. See [Security model](#svg-sanitization-and-security-model).                               |
+| `showSourceOnError` | `boolean`                         | `true`                 | Include the diagram source in a `<details>` block on the error panel.                                                                             |
+| `renderTimeoutMs`   | `number`                          | `20000`                | Abort a single render (and the runtime load) after this many milliseconds. Integer, `100`–`600000`.                                               |
+| `cacheMaxEntries`   | `number`                          | `50`                   | Upper bound on cached SVG entries. Positive integer.                                                                                              |
+| `maxSvgSize`        | `number`                          | `32768`                | Refuse a PlantUML diagram wider or taller than this many points. Non-negative integer; `0` disables the check. See [Diagram size](#diagram-size). |
+| `zoom`              | `boolean`                         | `true`                 | Let readers zoom and pan diagrams. Adds a control toolbar and a focusable viewport. Override per fence with `zoom=false`.                         |
+| `showSource`        | `boolean`                         | `true`                 | Offer a toolbar control that reveals the diagram source and copies it to the clipboard. Override per fence with `showSource=false`.               |
+| `graphviz`          | `object`                          | see below              | Graphviz/DOT support. See [Graphviz options](#graphviz-options).                                                                                  |
+| `stdlib`            | `object \| false`                 | see below              | PlantUML standard library (`!include <C4/…>`). See [Standard library options](#standard-library-options).                                         |
+| `id`                | `string`                          | `'default'`            | Docusaurus plugin instance id; only relevant if you register the plugin more than once.                                                           |
+
+Every option above except `graphviz`, `stdlib`, `theme` and `maxSvgSize` applies to **both**
+engines: `lazy`, `cache`, `sanitizeSvg`, `showSourceOnError`, `renderTimeoutMs`,
+`cacheMaxEntries` and `zoom` behave identically for a `dot` fence and a `plantuml` fence.
+`theme` is the exception for colour — see [Light and dark mode](#light-and-dark-mode) — and
+`maxSvgSize` is PlantUML-only, because Graphviz fences are bounded by
+`graphviz.maxSourceBytes` instead.
 
 Options are validated during the Docusaurus configuration phase, before anything is built.
 **Unknown keys are rejected** rather than ignored, because a typo in `docusaurus.config.ts`
@@ -259,7 +265,8 @@ would otherwise silently disable the option you meant to set:
 ```text
 [docusaurus-plugin-plantuml-client] Unknown option 'sanitiseSvg'. Supported options:
 'languages', 'theme', 'lazy', 'cache', 'sanitizeSvg', 'showSourceOnError',
-'renderTimeoutMs', 'cacheMaxEntries', 'zoom', 'showSource', 'graphviz', 'stdlib'.
+'renderTimeoutMs', 'cacheMaxEntries', 'maxSvgSize', 'zoom', 'showSource', 'graphviz',
+'stdlib'.
 ```
 
 The same is true one level deeper, so `graphviz: {enigne: 'neato'}` fails the build rather than
@@ -805,12 +812,22 @@ digraph {
 
 #### How clicks navigate
 
-Both engines share the same navigation behaviour: a click on an in-diagram link to a
-same-site URL goes through the Docusaurus router — no full page load — and site-absolute
-paths get the site's `baseUrl` exactly as markdown links do, so `/docs/orders` means the
-same thing in a diagram as in prose. External links and pure `#…` anchors stay native,
-modified clicks (Ctrl, Cmd, Shift) keep the browser's own behaviour, and a click that ends
-a drag never navigates.
+Both engines share the same navigation behaviour: a click on an in-diagram link to a URL
+**this build routes** goes through the Docusaurus router — no full page load — and
+site-absolute paths get the site's `baseUrl` exactly as markdown links do, so `/docs/orders`
+means the same thing in a diagram as in prose. External links and pure `#…` anchors stay
+native, modified clicks (Ctrl, Cmd, Shift) keep the browser's own behaviour, and a click that
+ends a drag never navigates.
+
+A same-origin path this build has **no route for** stays native too, and that exception
+matters if your site is published as more than one Docusaurus build — one per product area,
+a docs build beside a marketing build, or two builds stitched together by a reverse proxy.
+Those bundles share an origin but each routes only its own subtree, so pushing a sibling
+build's path into this build's router would render _this_ build's "Page not found" while the
+server that could serve it is never asked. (The tell is that reloading the same URL works.)
+The plugin checks the running build's route table and hands anything it does not own to the
+browser. An unknown page _inside_ a subtree this build does own still routes normally — its
+own 404 page is the right answer there.
 
 Clicking either example node above therefore navigates — without a reload — to
 `/docs/orders`, where the diagram containing `ORDER_DETAIL_1` highlights and centres it.
@@ -1043,7 +1060,7 @@ Failures are classified internally as one of:
 | Kind        | Cause                                                                                                                                                                                  |
 | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `load`      | `viz-global.js` or `plantuml.js` could not be fetched, timed out, or was not the expected module (usually a proxy or service worker returning the wrong file).                         |
-| `engine`    | The engine threw, or its output could not be used at all. Includes `Diagram too large for browser rendering: WxH (max 32768)` — see [Diagram size](#diagram-size).                     |
+| `engine`    | The engine threw, or its output could not be used at all. Includes `Diagram too large for browser rendering: WxH (max 32768; …)` — see [Diagram size](#diagram-size).                  |
 | `diagram`   | The source is not valid PlantUML.                                                                                                                                                      |
 | `syntax`    | The source is not valid DOT. Carries Graphviz's own diagnostic, including the line number.                                                                                             |
 | `too-large` | A DOT source exceeded `graphviz.maxSourceBytes`.                                                                                                                                       |
@@ -1067,19 +1084,35 @@ The two engines report invalid source very differently:
 
 ## Diagram size
 
-`@plantuml/core` refuses to serialize a diagram wider or taller than a fixed number of
-PlantUML points, reporting it through its error callback:
+`@plantuml/core` measures every diagram it lays out and refuses to serialize one wider or
+taller than a set number of PlantUML points, reporting it through its error callback:
 
 ```text
-Diagram too large for browser rendering: 78x12916 (max 4096)
+Diagram too large for browser rendering: 78x12916 (max 8192; override via the maxSvgSize
+option, or set it to 0 to disable this check)
 ```
 
-Upstream that limit is **4096**. This plugin patches the engine it serves and raises it to
-**32768**, so diagrams that the stock engine rejects render normally here. It is not
-configurable — one constant, applied on every build.
+The engine's own ceiling is **8192**. This plugin sets **32768** by default — high enough that
+a real architecture diagram or release runbook does not meet it — and `maxSvgSize` moves it:
 
-The limit is not something a diagram can talk its way around, which is why patching it was
-worth doing. Measured against the engine:
+```ts
+{
+  maxSvgSize: 65_536, // raise it
+}
+```
+
+```ts
+{
+  maxSvgSize: 0, // no ceiling at all
+}
+```
+
+It takes a non-negative integer. `0` is the engine's own convention for "no check"; a negative
+value is rejected at build time rather than passed through, because the engine reads a negative
+as "unspecified" and would quietly fall back to 8192.
+
+The ceiling is not something a diagram can talk its way around, which is why the option is the
+only real lever. Measured against the engine:
 
 | Attempt                   | Effect                                                   |
 | ------------------------- | -------------------------------------------------------- |
@@ -1088,38 +1121,38 @@ worth doing. Measured against the engine:
 | `left to right direction` | none; it transposes width and height                     |
 | `skinparam ranksep 5`     | works — it genuinely shrinks the layout                  |
 
-If you still hit the ceiling at 32768, the levers that work are the ones that make the
-diagram smaller: fewer nodes and edges, tighter `skinparam ranksep`/`nodesep`, a smaller
-`skinparam defaultFontSize`, or splitting one diagram into several fences.
+So if you would rather keep the ceiling where it is, the levers that work are the ones that
+make the diagram smaller: fewer nodes and edges, tighter `skinparam ranksep`/`nodesep`, a
+smaller `skinparam defaultFontSize`, or splitting one diagram into several fences.
+
+**Raising it is not free.** A 30 000-point diagram is a multi-hundred-KB SVG, and both the
+error detection and the DOMPurify sanitization parse it synchronously on the main thread. Such
+a diagram can visibly stall the tab while it lands, and may need `renderTimeoutMs` raised above
+its 20 s default. That cost is the reason the default is a number rather than `0`. See
+[ADR 0008](docs/adr/0008-configurable-max-svg-size.md).
 
-**A very large diagram is not free.** A 30 000-point diagram is a multi-hundred-KB SVG, and
-both the error detection and the DOMPurify sanitization parse it synchronously on the main
-thread. Such a diagram can visibly stall the tab while it lands, and may need
-`renderTimeoutMs` raised above its 20 s default. See
-[ADR 0007](docs/adr/0007-engine-size-ceiling-patch.md).
+`maxSvgSize` applies to PlantUML fences only; Graphviz has its own guard in
+`graphviz.maxSourceBytes`.
 
 ## `baseUrl` support
 
 The runtime assets are emitted into
 
 ```text
-<baseUrl>assets/plantuml-client-<coreVersion>-max32768/
+<baseUrl>assets/plantuml-client-<coreVersion>/
 ```
 
 and resolved in the browser through Docusaurus' own `useBaseUrl()`. A site deployed at
 `baseUrl: '/plantuml-test/'` therefore fetches:
 
 ```text
-/plantuml-test/assets/plantuml-client-1.2026.6-max32768/viz-global.js
-/plantuml-test/assets/plantuml-client-1.2026.6-max32768/plantuml.js
+/plantuml-test/assets/plantuml-client-1.2026.8/viz-global.js
+/plantuml-test/assets/plantuml-client-1.2026.8/plantuml.js
 ```
 
 No path is hard-coded to the site root, so project-pages deployments and reverse-proxied
 subpaths work without configuration. The engine version is part of the directory name, so an
-upgrade changes the URL and stale caches are defeated automatically. The `-max32768` segment
-is part of the same identity: what is served is a _patched_ engine (see
-[Diagram size](#diagram-size)), and a reader holding a cached copy from a plugin version that
-patched differently must not be handed it from the same URL. The bundled example site
+upgrade changes the URL and stale caches are defeated automatically. The bundled example site
 deploys under a non-root `baseUrl` precisely so this path is exercised on every build.
 
 ## Browser compatibility
@@ -1466,16 +1499,16 @@ too and was rejected: it carries one person's account reach and expires on a cal
 - **One PlantUML diagram renders at a time.** The PlantUML engine has module-level shared
   state, so a page with many large diagrams renders them sequentially. This is a correctness
   requirement, not a tuning knob. Graphviz has no such constraint and is not queued.
-- **PlantUML diagrams are capped at 32768 points in each dimension.** The bundled engine has
-  a hard ceiling with no option behind it; the plugin patches it up from the stock 4096, but
-  it cannot be removed or configured. Past that, the diagram itself has to get smaller — see
-  [Diagram size](#diagram-size). The raised ceiling also means a genuinely enormous diagram
-  now renders instead of failing fast, and both the error detection and the sanitizer parse
-  the resulting SVG synchronously, so it can stall the tab on its way in.
-- **A `@plantuml/core` release that changes the shape of that ceiling fails the build.** The
-  patch is anchored on two literals whose occurrence counts are verified before anything is
-  rewritten, and the plugin refuses to guess. The unit suite runs the patcher against the
-  installed engine, so a dependency bump that broke it goes red here rather than in your build.
+- **PlantUML diagrams are capped at 32768 points in each dimension by default.** The engine
+  measures the laid-out diagram and refuses anything larger. `maxSvgSize` raises the ceiling,
+  or removes it with `0` — see [Diagram size](#diagram-size) — but a genuinely enormous diagram
+  then renders instead of failing fast, and both the error detection and the sanitizer parse
+  the resulting SVG synchronously, so it can stall the tab on its way in. Past that, the
+  diagram itself has to get smaller.
+- **A `@plantuml/core` older than `1.2026.8` fails the build.** That release added the
+  `maxSvgSize` render option, and an engine that does not know the option ignores it in
+  silence — which would leave `maxSvgSize` reading as honoured while the engine's own ceiling
+  refused large diagrams. The plugin checks the installed version rather than guessing.
 - **Graphviz rendering blocks the main thread.** Viz.js lays out synchronously. A 300-edge
   graph takes ~26 ms, but a 3 000-edge graph takes ~2.25 s and visibly freezes the page;
   `graphviz.maxSourceBytes` is the guard. Rendering in a Web Worker would remove the ceiling
@@ -1498,7 +1531,7 @@ too and was rejected: it carries one person's account reach and expires on a cal
 ### Diagrams stay on "Loading PlantUML runtime…" and the assets 404 under a subpath
 
 Open the network tab and check the failing URL. It should be
-`<baseUrl>assets/plantuml-client-<version>-max32768/viz-global.js`. If the request goes to
+`<baseUrl>assets/plantuml-client-<version>/viz-global.js`. If the request goes to
 `/assets/...` when your site lives at `/docs/`, the site's `baseUrl` is wrong — not the
 plugin's paths, which are always resolved through `useBaseUrl()`.
 
@@ -1522,7 +1555,7 @@ served as `text/plain`, `application/octet-stream` or `text/html`. The console s
 MIME type checking error. Check with:
 
 ```bash
-curl -I https://example.com/your-base-url/assets/plantuml-client-1.2026.6-max32768/plantuml.js
+curl -I https://example.com/your-base-url/assets/plantuml-client-1.2026.8/plantuml.js
 ```
 
 The `content-type` must be a JavaScript type (`text/javascript` or

package/dist/assets.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
-import { PLANTUML_MODULE_FILENAME, PLUGIN_NAME, VIZ_SCRIPT_FILENAME } from './constants.js';
+import { MINIMUM_CORE_VERSION, PLANTUML_MODULE_FILENAME, PLUGIN_NAME, VIZ_SCRIPT_FILENAME, } from './constants.js';
 const require = createRequire(import.meta.url);
 /**
  * Locates the installed `@plantuml/core` package on disk.
@@ -21,6 +21,7 @@ export function locatePlantUmlCore() {
     const packageDir = path.dirname(packageJsonPath);
     const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
     const version = typeof packageJson.version === 'string' ? packageJson.version : '0.0.0';
+    assertSupportedVersion(version);
     const files = [
         path.join(packageDir, VIZ_SCRIPT_FILENAME),
         path.join(packageDir, PLANTUML_MODULE_FILENAME),
@@ -47,3 +48,39 @@ function assertRuntimeFile(file, version) {
         '@plantuml/core is not one this plugin supports. Pin a supported version, or open an ' +
         'issue if the package has genuinely changed its layout.');
 }
+/**
+ * Compares two `major.minor.patch` versions, ignoring any pre-release suffix.
+ *
+ * A hand-rolled comparison rather than a `semver` dependency: the only versions being
+ * compared are `@plantuml/core`'s own, which are plain three-part numbers.
+ */
+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;
+}
+/**
+ * Fails the build if the installed `@plantuml/core` predates the `maxSvgSize` render option.
+ *
+ * `package.json` already asks for a new enough version, but a site can end up on an older one
+ * through a hoisted duplicate, an override, or a stale lockfile. Without this check that would
+ * be silent: the engine ignores an option it does not know, so `options.maxSvgSize` would read
+ * as honoured while the engine's own 4096-point ceiling quietly refused large diagrams.
+ *
+ * See `docs/adr/0008-configurable-max-svg-size.md`.
+ */
+function assertSupportedVersion(version) {
+    if (compareVersions(version, MINIMUM_CORE_VERSION) >= 0)
+        return;
+    throw new Error(`[${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.');
+}

package/dist/constants.d.ts

@@ -11,24 +11,19 @@ export declare const PLUGIN_ID = "plantuml-client";
 export declare const DEFAULT_PLUGIN_ID = "default";
 export declare const PLUGIN_NAME = "docusaurus-plugin-plantuml-client";
 /**
- * The diagram size ceiling hard-coded in `@plantuml/core`'s own build, in PlantUML points.
+ * The lowest `@plantuml/core` this plugin supports, checked by `locatePlantUmlCore()`.
  *
- * The engine compares the laid-out diagram's width and height against it and refuses anything
- * larger with `Diagram too large for browser rendering: WxH (max 4096)`.
+ * 1.2026.8 is the release that added the `maxSvgSize` render option. On anything older the
+ * option is silently ignored and the engine's own 4096-point ceiling applies, which would
+ * turn `options.maxSvgSize` into a setting that reads as honoured and is not.
  */
-export declare const UPSTREAM_MAX_DIAGRAM_SIZE = 4096;
-/**
- * The ceiling this plugin patches into the engine it serves. See `src/enginePatch.ts` and
- * `docs/adr/0007-engine-size-ceiling-patch.md`.
- */
-export declare const MAX_DIAGRAM_SIZE = 32768;
+export declare const MINIMUM_CORE_VERSION = "1.2026.8";
 /**
  * Directory (relative to `baseUrl`) that the PlantUML runtime assets are emitted into.
  *
- * The `-max…` segment is part of the engine's identity, not decoration: the file served here
- * is a *patched* `plantuml.js`, so a reader holding a cached copy from a plugin version that
- * patched to a different ceiling — or did not patch at all — must not be handed it from the
- * same URL. Same reasoning as the `stdlib-<revision>` segment nested inside this one.
+ * The engine version is in the name so that upgrading `@plantuml/core` moves every asset URL
+ * and no stale cache entry can survive it. Same reasoning as the `stdlib-<revision>` segment
+ * nested inside this one.
  */
 export declare function assetsDirForVersion(coreVersion: string): string;
 export declare const VIZ_SCRIPT_FILENAME = "viz-global.js";

package/dist/constants.js

@@ -11,27 +11,22 @@ export const PLUGIN_ID = 'plantuml-client';
 export const DEFAULT_PLUGIN_ID = 'default';
 export const PLUGIN_NAME = `docusaurus-plugin-${PLUGIN_ID}`;
 /**
- * The diagram size ceiling hard-coded in `@plantuml/core`'s own build, in PlantUML points.
+ * The lowest `@plantuml/core` this plugin supports, checked by `locatePlantUmlCore()`.
  *
- * The engine compares the laid-out diagram's width and height against it and refuses anything
- * larger with `Diagram too large for browser rendering: WxH (max 4096)`.
+ * 1.2026.8 is the release that added the `maxSvgSize` render option. On anything older the
+ * option is silently ignored and the engine's own 4096-point ceiling applies, which would
+ * turn `options.maxSvgSize` into a setting that reads as honoured and is not.
  */
-export const UPSTREAM_MAX_DIAGRAM_SIZE = 4096;
-/**
- * The ceiling this plugin patches into the engine it serves. See `src/enginePatch.ts` and
- * `docs/adr/0007-engine-size-ceiling-patch.md`.
- */
-export const MAX_DIAGRAM_SIZE = 32_768;
+export const MINIMUM_CORE_VERSION = '1.2026.8';
 /**
  * Directory (relative to `baseUrl`) that the PlantUML runtime assets are emitted into.
  *
- * The `-max…` segment is part of the engine's identity, not decoration: the file served here
- * is a *patched* `plantuml.js`, so a reader holding a cached copy from a plugin version that
- * patched to a different ceiling — or did not patch at all — must not be handed it from the
- * same URL. Same reasoning as the `stdlib-<revision>` segment nested inside this one.
+ * The engine version is in the name so that upgrading `@plantuml/core` moves every asset URL
+ * and no stale cache entry can survive it. Same reasoning as the `stdlib-<revision>` segment
+ * nested inside this one.
  */
 export function assetsDirForVersion(coreVersion) {
-    return `assets/${PLUGIN_ID}-${coreVersion}-max${MAX_DIAGRAM_SIZE}`;
+    return `assets/${PLUGIN_ID}-${coreVersion}`;
 }
 export const VIZ_SCRIPT_FILENAME = 'viz-global.js';
 export const PLANTUML_MODULE_FILENAME = 'plantuml.js';