@matfsw/docusaurus-plantuml-plugin 1.7.1 → 1.8.0

package/dist/theme/PlantUmlDiagram/routeMatching.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Whether a path belongs to the Docusaurus build that is currently running.
+ *
+ * In-diagram links are navigated through the router, which is only correct for a path this
+ * build actually routes. A site published as **several** builds — one per product area, a
+ * docs build beside a marketing build, two builds stitched together by a reverse proxy —
+ * shares an origin across bundles that each route only their own subtree. Pushing a sibling
+ * build's path into this build's router matches no route, renders this build's own "Page not
+ * found", and never reaches the server that could have served it. Reloading that URL works,
+ * which is the tell.
+ *
+ * So the rule is: push what this build routes, and hand everything else to the browser.
+ */
+/**
+ * One entry of the generated route table, narrowed to what matching needs.
+ *
+ * `path` widens to an array because react-router allows one route to answer to several
+ * paths. Docusaurus' own codegen never emits that, but the generated table is typed as
+ * react-router's `RouteConfig`, and quietly ignoring the array form would silently treat
+ * such a route as unrouted.
+ */
+export interface RouteLike {
+    path?: string | string[];
+    exact?: boolean;
+    routes?: RouteLike[];
+}
+/**
+ * Whether `pathname` matches any real route of `routes`.
+ *
+ * A flat walk rather than `react-router-config`'s `matchRoutes`: it gives the same answer for
+ * every shape a Docusaurus table takes — verified against a generated `routes.js`, including
+ * nested docs trees, non-exact parents and segment-boundary near-misses like `/docsomething` —
+ * and it needs only `matchPath`, which `@docusaurus/router` exports for theme code. Reaching
+ * past that export into `react-router-config` would mean depending on a transitive package of
+ * `@docusaurus/core` that a strict installer need not hoist.
+ *
+ * Non-exact parent routes match their whole subtree, so an unknown page *inside* this build's
+ * own docs tree still counts as routed. That is deliberate: this build owns that prefix, and
+ * its own `NotFound` is the right answer there. Only a path no route claims at all is handed
+ * back to the browser.
+ */
+export declare function isRoutedPathname(routes: readonly RouteLike[], pathname: string): boolean;

package/dist/theme/PlantUmlDiagram/routeMatching.js

@@ -0,0 +1,38 @@
+import { matchPath } from '@docusaurus/router';
+/**
+ * The catch-all every generated route table ends with.
+ *
+ * `codegenRoutes` appends `{path: '*', component: ComponentCreator('*')}` to every build,
+ * and that route is what renders `NotFound`. It therefore matches *every* path, which would
+ * make the check below vacuous — excluding it is the whole point.
+ */
+const CATCH_ALL_PATH = '*';
+/** Depth-first flattening; nested routes are how Docusaurus expresses a docs plugin's tree. */
+function flattenRoutes(routes) {
+    return routes.flatMap((route) => [route, ...flattenRoutes(route.routes ?? [])]);
+}
+/**
+ * Whether `pathname` matches any real route of `routes`.
+ *
+ * A flat walk rather than `react-router-config`'s `matchRoutes`: it gives the same answer for
+ * every shape a Docusaurus table takes — verified against a generated `routes.js`, including
+ * nested docs trees, non-exact parents and segment-boundary near-misses like `/docsomething` —
+ * and it needs only `matchPath`, which `@docusaurus/router` exports for theme code. Reaching
+ * past that export into `react-router-config` would mean depending on a transitive package of
+ * `@docusaurus/core` that a strict installer need not hoist.
+ *
+ * Non-exact parent routes match their whole subtree, so an unknown page *inside* this build's
+ * own docs tree still counts as routed. That is deliberate: this build owns that prefix, and
+ * its own `NotFound` is the right answer there. Only a path no route claims at all is handed
+ * back to the browser.
+ */
+export function isRoutedPathname(routes, pathname) {
+    return flattenRoutes(routes).some((route) => {
+        if (route.path === undefined)
+            return false;
+        const paths = (Array.isArray(route.path) ? route.path : [route.path]).filter((path) => path !== CATCH_ALL_PATH);
+        if (paths.length === 0)
+            return false;
+        return matchPath(pathname, { path: paths, exact: route.exact === true }) !== null;
+    });
+}

package/dist/theme/PlantUmlDiagram/useDiagramLinks.d.ts

@@ -8,13 +8,16 @@ import type { DiagramEngine } from '../../runtime/types.js';
  * `diagramLinks.ts` for the correlation. Graphviz needs none of this; `URL=` already emits
  * real anchors.
  *
- * **Navigation** (both engines): a click on any in-diagram link to a same-site URL goes
- * through the router instead of a full page load, so a node can link to a diagram on
+ * **Navigation** (both engines): a click on any in-diagram link to a URL *this build routes*
+ * goes through the router instead of a full page load, so a node can link to a diagram on
  * another page and arrive instantly — with the target page's diagrams reacting to the
  * hash through the same router-driven deep-link tracking. Site-absolute paths get the
  * site's `baseUrl`, exactly as markdown links do, so authors write the same `/docs/…`
  * everywhere. External links and pure `#…` anchors stay native: the browser handles both
  * correctly on its own, and the router observes hash navigations anyway.
+ *
+ * A same-origin path that this build does *not* route stays native too. See
+ * `routeMatching.ts` for why that matters on a site published as several builds.
  */
 export interface UseDiagramLinksParams {
     /** Whether the diagram is rendered and its SVG is in the DOM. */

package/dist/theme/PlantUmlDiagram/useDiagramLinks.js

@@ -1,7 +1,9 @@
 import { useEffect } from 'react';
+import generatedRoutes from '@generated/routes';
 import { useHistory } from '@docusaurus/router';
 import { useBaseUrlUtils } from '@docusaurus/useBaseUrl';
 import { attachDiagramLinks, detachDiagramLinks, extractSourceLinks } from './diagramLinks.js';
+import { isRoutedPathname } from './routeMatching.js';
 export function useDiagramLinks({ ready, svg, engine, source, containerRef, }) {
     const history = useHistory();
     const { withBaseUrl } = useBaseUrlUtils();
@@ -53,6 +55,10 @@ export function useDiagramLinks({ ready, svg, engine, source, containerRef, }) {
             }
             if (url.origin !== window.location.origin)
                 return;
+            // Same origin is not the same bundle. A path this build has no route for must reach
+            // the server, which can serve it, rather than this build's own "Page not found".
+            if (!isRoutedPathname(generatedRoutes, url.pathname))
+                return;
             event.preventDefault();
             history.push(url.pathname + url.search + url.hash);
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matfsw/docusaurus-plantuml-plugin",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "Render PlantUML diagrams in Docusaurus 3 entirely in the browser - no Java, no PlantUML server, no CDN.",
   "keywords": [
     "docusaurus",
@@ -71,7 +71,7 @@
     "prepublishOnly": "node scripts/assert-built.mjs"
   },
   "dependencies": {
-    "@plantuml/core": "^1.2026.6",
+    "@plantuml/core": "^1.2026.8",
     "copy-webpack-plugin": "^14.0.0",
     "dompurify": "^3.2.7"
   },
@@ -96,7 +96,7 @@
     "@types/node": "^26.2.0",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.4",
-    "@vitest/coverage-v8": "^4.1.10",
+    "@vitest/coverage-v8": "^5.0.0",
     "eslint": "^9.39.5",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-react": "^7.37.5",
@@ -109,7 +109,7 @@
     "tsup": "^8.5.0",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.67.0",
-    "vitest": "^4.1.10"
+    "vitest": "^5.0.0"
   },
   "overrides": {
     "serialize-javascript": "^7.1.1",

package/dist/enginePatch.d.ts

@@ -1,41 +0,0 @@
-/**
- * How many bytes the patch adds. Every replacement is ASCII, so the byte delta is the
- * character delta, and it is fixed for a given {@link MAX_DIAGRAM_SIZE}. This is what makes
- * an already-generated file cheap to validate: its size is an exact fingerprint.
- */
-export declare const PATCH_SIZE_DELTA: number;
-/**
- * Rewrites the engine source so it accepts diagrams up to {@link MAX_DIAGRAM_SIZE} points.
- *
- * Both literals are counted *before* anything is replaced, so an engine that changed shape
- * fails the build with a name attached rather than being silently half-patched. Patching the
- * message as well as the comparison is not cosmetic — an engine that still reported
- * `(max 4096)` while refusing at 32768 would send every future reader of that error down the
- * wrong path. It is also safe: TeaVM's string pool is a plain list of JavaScript string
- * literals, so a literal that changes length does not disturb its neighbours.
- */
-export declare function patchEngineSource(source: string, coreVersion: string): string;
-export interface ResolvePatchedEngineOptions {
-    /** Absolute path of the vendored `plantuml.js` inside the installed `@plantuml/core`. */
-    vendoredPath: string;
-    /** Installed `@plantuml/core` version, which names the cache directory. */
-    coreVersion: string;
-    /** Site directory, used when `cacheDir` is absent. */
-    siteDir: string;
-    /**
-     * Where the patched engine is cached. Docusaurus passes its `generatedFilesDir`; when it
-     * is absent the site's `.docusaurus` directory is assumed, as in `src/stdlib.ts`.
-     */
-    cacheDir?: string;
-}
-/**
- * Returns the path of the `plantuml.js` this build should serve, generating it if needed.
- *
- * The basename stays `plantuml.js`: the copy pattern emits `[name][ext]`, and the browser
- * loader joins {@link PLANTUML_MODULE_FILENAME} onto the assets directory.
- *
- * Generation is skipped when the cached file is already the right size. That check is exact
- * rather than approximate — {@link PATCH_SIZE_DELTA} is fixed — and it is O(1) where reading
- * 7 MB back to inspect its contents would not be.
- */
-export declare function resolvePatchedEngine(options: ResolvePatchedEngineOptions): string;

package/dist/enginePatch.js

@@ -1,120 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { MAX_DIAGRAM_SIZE, PLANTUML_MODULE_FILENAME, PLUGIN_NAME, UPSTREAM_MAX_DIAGRAM_SIZE, } from './constants.js';
-/**
- * Raises the diagram size ceiling compiled into `@plantuml/core`.
- *
- * The engine measures the laid-out diagram and refuses to serialize anything wider or taller
- * than 4096 points, reporting `Diagram too large for browser rendering: 78x12916 (max 4096)`
- * through its error callback. `renderToString` takes only `{dark}`, so there is no option to
- * turn this off, and no way to work around it from diagram source: the check runs *before* a
- * `scale` directive is applied, `skinparam dpi` does not move it, and `left to right
- * direction` only transposes the two numbers. Shrinking the Graphviz layout by hand —
- * `skinparam ranksep`, fewer nodes, smaller fonts — is the only lever an author has.
- *
- * The ceiling is arbitrary. It is not an SVG or a browser constraint; patched to 65536 the
- * same engine produced correct SVG for a 79x43157 diagram. So this plugin patches it, and
- * serves the patched file rather than the vendored one.
- *
- * See `docs/adr/0007-engine-size-ceiling-patch.md` for the evidence and the rejected
- * alternatives.
- */
-/**
- * The comparison the engine guards on, as it appears in the minified bundle:
- *
- * ```js
- * p=o.bBY;if(!(p>4096.0)){q=o.bB0;if(!(q>4096.0)){ …serialize… }}
- * ```
- *
- * Deliberately anchored on `>4096.0)` rather than on the surrounding code: `p`, `q` and `o`
- * are TeaVM-mangled locals that are renamed by every `@plantuml/core` build, so a pattern
- * that named them would break on a release that changed nothing meaningful.
- */
-const COMPARISON = `>${UPSTREAM_MAX_DIAGRAM_SIZE}.0)`;
-/**
- * `4096.0` occurs exactly twice in the whole 7 MB bundle, and both occurrences are the width
- * and height halves of this one guard. That makes the count the safety property: two matches
- * means the engine still has the shape this patch was written against, and any other number
- * means it does not.
- */
-const COMPARISON_OCCURRENCES = 2;
-/** The suffix of the engine's own error message, in TeaVM's string pool. */
-const MESSAGE_SUFFIX = ` (max ${UPSTREAM_MAX_DIAGRAM_SIZE})`;
-const MESSAGE_SUFFIX_OCCURRENCES = 1;
-const PATCHED_COMPARISON = `>${MAX_DIAGRAM_SIZE}.0)`;
-const PATCHED_MESSAGE_SUFFIX = ` (max ${MAX_DIAGRAM_SIZE})`;
-/**
- * How many bytes the patch adds. Every replacement is ASCII, so the byte delta is the
- * character delta, and it is fixed for a given {@link MAX_DIAGRAM_SIZE}. This is what makes
- * an already-generated file cheap to validate: its size is an exact fingerprint.
- */
-export const PATCH_SIZE_DELTA = COMPARISON_OCCURRENCES * (PATCHED_COMPARISON.length - COMPARISON.length) +
-    MESSAGE_SUFFIX_OCCURRENCES * (PATCHED_MESSAGE_SUFFIX.length - MESSAGE_SUFFIX.length);
-/** Directory under the Docusaurus cache that generated engine builds live in. */
-const 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;
-    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.');
-}
-/**
- * Rewrites the engine source so it accepts diagrams up to {@link MAX_DIAGRAM_SIZE} points.
- *
- * Both literals are counted *before* anything is replaced, so an engine that changed shape
- * fails the build with a name attached rather than being silently half-patched. Patching the
- * message as well as the comparison is not cosmetic — an engine that still reported
- * `(max 4096)` while refusing at 32768 would send every future reader of that error down the
- * wrong path. It is also safe: TeaVM's string pool is a plain list of JavaScript string
- * literals, so a literal that changes length does not disturb its neighbours.
- */
-export 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);
-}
-/**
- * Returns the path of the `plantuml.js` this build should serve, generating it if needed.
- *
- * The basename stays `plantuml.js`: the copy pattern emits `[name][ext]`, and the browser
- * loader joins {@link PLANTUML_MODULE_FILENAME} onto the assets directory.
- *
- * Generation is skipped when the cached file is already the right size. That check is exact
- * rather than approximate — {@link PATCH_SIZE_DELTA} is fixed — and it is O(1) where reading
- * 7 MB back to inspect its contents would not be.
- */
-export function resolvePatchedEngine(options) {
-    const { vendoredPath, coreVersion, siteDir, cacheDir } = options;
-    const generatedDir = cacheDir ?? path.join(siteDir, '.docusaurus');
-    const target = path.join(generatedDir, CACHE_SUBDIRECTORY, coreVersion, PLANTUML_MODULE_FILENAME);
-    const expectedSize = fs.statSync(vendoredPath).size + PATCH_SIZE_DELTA;
-    if (fs.existsSync(target) && fs.statSync(target).size === expectedSize)
-        return target;
-    const patched = patchEngineSource(fs.readFileSync(vendoredPath, 'utf8'), coreVersion);
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    // `.docusaurus` is shared by every locale, and Docusaurus builds locales in separate
-    // processes. Writing 7 MB in place would let a concurrent build read a torn file — and a
-    // torn file of the right length would pass the size check above. Rename is atomic.
-    const temporary = `${target}.${process.pid}.tmp`;
-    fs.writeFileSync(temporary, patched, 'utf8');
-    fs.renameSync(temporary, target);
-    return target;
-}