@matfsw/docusaurus-plantuml-plugin 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -7,6 +7,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-08-13
+
+### Added
+
+- **A Fit control in the maximized view.** While a diagram fills the screen, one press
+  returns it to the fitted scale — the whole diagram filling the screen, magnified or shrunk
+  as the picture demands — after zooming or panning away from it. Maximizing itself now
+  opens at that truly fitted scale too: the view's content measurement tracks the rendered
+  picture rather than the full-width frame, which is also what tightens the minimap around
+  the actual diagram. (The pan clamp deliberately keeps its old frame-wide bounds, so focal
+  wheel zoom holds the point under the pointer exactly as before.) The button is
+  deliberately absent from the inline toolbar, where the frame grows with the diagram and a
+  fit would merely duplicate Reset; it sits between Reset and Maximize, is drawn as inline
+  SVG like the rest of the toolbar, and carries `aria-label="Fit diagram to screen"`.
+
+- **A minimap.** A new toggle in the bottom-left corner opens a small copy of the diagram
+  with a rectangle marking what the viewport currently shows; pressing or dragging anywhere
+  on the map centres the view there, so a single press doubles as "jump there". The map
+  follows every zoom, pan and resize without re-rendering the figure — it subscribes to the
+  same imperative transform writes the zoom hook itself uses — and works while maximized.
+  The figure carries `data-plantuml-minimap-open="true"` while the map is up.
+
+  The map is pointer-only and hidden from assistive technology on purpose: the real viewport
+  is already keyboard-operable, so a second, duplicated view of the same diagram would add
+  noise without adding a capability. Its close button stays outside the hidden subtree and
+  remains focusable.
+
+- **Search within a diagram.** The new lens button opens a search bar beside the toolbar: a
+  case-insensitive substring search over the rendered SVG's text. Every match is marked with
+  `data-plantuml-search-match` and highlighted from the stylesheet — the cached SVG string is
+  never mutated — and the current match additionally carries `data-plantuml-search-current`.
+  Enter and the chevron buttons step through the matches (Shift+Enter backwards), each step
+  centres the view on its match at the current zoom level, and Escape or ✕ closes the bar
+  and sweeps every highlight. The figure carries `data-plantuml-search-open="true"` while
+  the bar is up.
+
+- **Deep links into diagrams.** A URL hash of the form `#graph?highlight-node=REACTION_1234`
+  focuses a node: every diagram on the page reacts - none needs an id of its own, and a
+  diagram without the node does nothing - the page scrolls to the first matching figure, the
+  node is marked with `data-plantuml-focused-node` and highlighted from the stylesheet, and
+  a zoomable diagram snaps to 100% centred on it. The hash is watched through the router, so
+  every kind of navigation reacts — pushed, replaced, popped and native `#…` clicks alike,
+  including a `<Link>` navigation that *drops* the hash, which sweeps the highlight — and a
+  `#graph?…` hash defeats lazy loading so below-the-fold targets still react.
+
+  The identifier resolves through a ladder - explicit SVG `id` (Graphviz `node [id="…"]`),
+  the PlantUML alias (`component "X" as REACTION_1234`, aliased notes included, via the
+  `data-qualified-name` the engine writes into its SVG), a self-anchor link
+  (Graphviz `URL="#graph?…"`, which doubles as the node's own permalink when clicked),
+  Graphviz node names via their `<title>`, multiline labels with `%0A`-encoded newlines
+  matched against consecutive text lines within one node's group, and finally a
+  case-insensitive substring of a single line. The first level that matches wins, so a
+  deterministic id always beats loose text matching.
+
+  Alongside this, Graphviz author links are pinned by tests, and sanitization keeps
+  `target="_top"` on links instead of silently dropping it. One engine limitation surfaced
+  and is now documented: the bundled PlantUML engine renders `[[url]]` link text but emits
+  no `<a>` elements, so PlantUML links are not clickable - which is why PlantUML deep-link
+  ids ride on aliases rather than on links.
+
+### Fixed
+
+- **The rendered SVG is no longer re-parsed on every re-render under React 19.** React 19
+  compares `dangerouslySetInnerHTML` by the wrapper object's identity rather than by its
+  `__html` string, so the inline `{{__html: svg}}` literal made every state change — opening
+  the source view, maximizing, a copy confirmation — throw away and re-parse the entire SVG
+  subtree. The wrapper is now memoized per SVG string. This is also what makes the search's
+  in-DOM highlights survive unrelated re-renders.
+
 ## [1.3.1]
 
 ### Fixed
@@ -380,7 +449,8 @@ 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.3.1...HEAD
+[Unreleased]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.4.0...HEAD
+[1.4.0]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.3.1...v1.4.0
 [1.3.1]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.3.0...v1.3.1
 [1.3.0]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.1.2...v1.2.0

package/README.md

@@ -529,18 +529,24 @@ pannable by default, with a small control toolbar in the top-right corner.
 
 ### Interaction
 
-| Input                               | What happens                         |
-| ----------------------------------- | ------------------------------------ |
-| Plain scroll wheel                  | Scrolls the page. Never intercepted. |
-| **Ctrl** + wheel, or trackpad pinch | Zooms about the pointer              |
-| Drag                                | Pans, once zoomed in                 |
-| One finger on a touchscreen         | Scrolls the page                     |
-| Two-finger pinch on a touchscreen   | The browser's own page zoom          |
-| Toolbar buttons                     | Zoom out, zoom in, reset, maximize   |
+| Input                               | What happens                                                   |
+| ----------------------------------- | -------------------------------------------------------------- |
+| Plain scroll wheel                  | Scrolls the page. Never intercepted.                           |
+| **Ctrl** + wheel, or trackpad pinch | Zooms about the pointer                                        |
+| Drag                                | Pans, once zoomed in                                           |
+| One finger on a touchscreen         | Scrolls the page                                               |
+| Two-finger pinch on a touchscreen   | The browser's own page zoom                                    |
+| Toolbar buttons                     | Zoom out, zoom in, reset, maximize — plus fit, while maximized |
 
 `Cmd` + wheel is deliberately **not** intercepted: on macOS that is the browser's own page
 zoom, and taking it over would fight the platform.
 
+**Fit** appears only while the diagram is maximized: it scales the diagram to fill the
+screen — the fitted view maximizing opens with — after you have zoomed or panned away from
+it. It is deliberately absent from the inline toolbar: the inline frame grows with the
+diagram, so at 100% everything is already visible and a fit would merely duplicate
+**Reset**.
+
 ### Keyboard
 
 The diagram viewport is focusable. Once focused:
@@ -566,11 +572,37 @@ space instead and keeps it visible as long as possible.
 Scale is limited to 0.25×–8×, and the view resets to 100% whenever the diagram source or the
 site colour mode changes.
 
+### Search
+
+The lens button opens a search bar beside the toolbar. Matching is a case-insensitive
+substring search over the rendered SVG's text, so what you see is what you are searching.
+Every match is highlighted, the current one distinctly; the counter shows where you are;
+<kbd>Enter</kbd> / the chevrons step through the matches, <kbd>Shift</kbd>+<kbd>Enter</kbd>
+steps backwards, and each step pans the view so the match is centred — at whatever zoom
+level you are on. <kbd>Escape</kbd> or ✕ closes the bar and removes every highlight.
+
+Matches are marked with `data-plantuml-search-match` (and the current one additionally with
+`data-plantuml-search-current`) and coloured from the stylesheet, so site CSS can restyle the
+highlight without touching the plugin.
+
+### Minimap
+
+The button in the bottom-left corner opens a minimap: a small copy of the diagram with a
+rectangle marking what the viewport currently shows. Press or drag anywhere on the map to
+centre the view there — a single press works as "jump there". The map follows every zoom,
+pan and resize, works while maximized, and closes from its own ✕ or the toggle.
+
+The map is pointer-only and hidden from assistive technology on purpose: the real viewport is
+already keyboard-operable with the arrow keys, so announcing a second, duplicated view of the
+same diagram would add noise without adding a capability.
+
 ### Maximizing
 
-The fourth toolbar button expands the diagram to fill the browser viewport, fitted to the
-available space, over an opaque background. <kbd>Escape</kbd> or the same button restores it,
-along with whatever zoom level you had before.
+The maximize button expands the diagram to fill the browser viewport over an opaque
+background, opening at the fitted scale — magnified or shrunk so the whole diagram fills the
+screen. The **fit** button (present only in this view) returns to that scale after zooming
+or panning. <kbd>Escape</kbd> or the maximize button restores the inline view, along with
+whatever zoom level you had before.
 
 This is an in-page overlay rather than the Fullscreen API. `requestFullscreen()` takes the
 entire browser window fullscreen in Firefox instead of presenting the element, and its
@@ -601,8 +633,8 @@ Alice -> Bob : Hello
 A reader who needs to zoom is rarely the author who would have enabled it, so leaving it off
 would mean most readers never discover it. The costs are real and worth knowing:
 
-- Each zoomable diagram adds roughly **four keyboard tab stops** (the viewport and three or
-  four buttons). On a page with six diagrams that is a meaningful amount of tabbing.
+- Each zoomable diagram adds a **keyboard tab stop for the viewport and one per toolbar
+  button**. On a page with six diagrams that is a meaningful amount of tabbing.
 - The rendered markup gains a viewport and transform wrapper around the `role="img"` container.
   Site CSS that targets `[data-plantuml-diagram] > div[role="img"]` as a **direct child** needs
   updating — see [Accessibility](#accessibility) for both shapes.
@@ -663,6 +695,63 @@ before either feature existed.
 This is separate from `showSourceOnError`, which offers the source in the error panel when a
 diagram _fails_ to render.
 
+## Links and deep links
+
+### Links written in the diagram source
+
+**Graphviz** emits real hyperlinks: `URL=`/`href=` on a node or edge becomes an `<a>` in the
+rendered SVG, preserved through sanitization (`javascript:` URLs are stripped). Links stay
+clickable inside the zoomable viewport: a plain click follows the link, while a click that
+ends a drag does not.
+
+````markdown
+```dot
+digraph { docs [URL="https://graphviz.org/doc/info/attrs.html"]; }
+```
+````
+
+**PlantUML** links are an engine limitation today: the bundled browser engine renders
+`[[url]]` link _text_ (styled blue and underlined) but emits no `<a>` elements, so PlantUML
+links are not clickable. Deep-link addressing does not depend on them - PlantUML nodes are
+addressed by alias, below. Should the engine gain anchor output, links will pass through
+sanitization unchanged (that path is pinned by tests, `target="_top"` included).
+
+### Deep links: `#graph?highlight-node=…`
+
+A URL hash of the form `#graph?highlight-node=REACTION_1234` focuses a node:
+
+- **Every diagram on the page reacts** - no diagram needs an id of its own. A diagram that
+  does not contain the node simply does nothing.
+- The page scrolls to the first matching figure, the node is visibly highlighted
+  (`data-plantuml-focused-node`, restylable from site CSS), and a zoomable diagram snaps to
+  **100% centred on the node**. The highlight stays until the hash changes.
+- The hash is watched live, so following a `#graph?…` link anywhere on the page - including
+  one inside a Graphviz diagram - focuses the node without a reload.
+- A `#graph?…` hash defeats lazy loading for the page's diagrams, so a target below the
+  fold still reacts. That costs the render of every diagram on the page, exactly as
+  `lazy: false` would.
+
+The identifier is resolved per diagram through a ladder; the first level that matches wins:
+
+| #   | Level             | Works in | Authoring                                                                                                                               |
+| --- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | Explicit SVG `id` | Graphviz | `node [id="REACTION-1234"]`                                                                                                             |
+| 2   | PlantUML alias    | PlantUML | `component "X" as REACTION_1234`, `note "…" as REACTION_1234` - the alias lands in the SVG as `data-qualified-name`                     |
+| 3   | Self-anchor link  | Graphviz | `node [URL="#graph?highlight-node=REACTION-1234"]` - carries the id _and_, being a real link, clicking the node mints its own permalink |
+| 4   | Node name         | Graphviz | plain DOT node names, via the `<title>` Graphviz emits                                                                                  |
+| 5   | Multiline label   | both     | `%0A` encodes the newline: `#graph?highlight-node=Archive%0A12345` matches _consecutive_ label lines, kept within one node's group      |
+| 6   | Substring         | both     | any text line containing the identifier, case-insensitively                                                                             |
+
+Level 2 is the PlantUML spelling of a hidden, deterministic id: the alias never appears in
+the picture, but the engine writes it onto the entity's group - and aliased **notes** get
+one too, so `note "…" as MYNOTE_123` makes the note itself navigable. PlantUML aliases are
+identifiers: use underscores (`REACTION_1234`), not hyphens, which do not parse.
+
+Level 6 is what makes an unannotated node reachable by the unique part of its label - for a
+node labelled `caminus-process-archive\n12345`, the hash `#graph?highlight-node=12345`
+suffices. Levels 1-4 exist so that a deterministic, author-chosen identifier always beats
+loose text matching.
+
 ## Lazy loading
 
 With `lazy: true` (the default), a diagram is not rendered until it scrolls within 300 px of
@@ -1164,6 +1253,10 @@ package.
 - **Diagrams are not rendered during static-site generation.** The HTML Docusaurus emits
   contains the deferred placeholder and the `<noscript>` source. Search engines that do not
   execute JavaScript will not see the diagram image.
+- **PlantUML `[[url]]` hyperlinks are not clickable.** The bundled browser engine renders
+  the link text (styled blue and underlined) but emits no `<a>` elements into its SVG.
+  Graphviz links work; PlantUML deep-link addressing works through aliases and does not
+  need links. See [Links and deep links](#links-and-deep-links).
 - **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.

package/dist/constants.d.ts

@@ -41,4 +41,14 @@ export declare const DATA_ATTR: {
     readonly maximized: "data-plantuml-maximized";
     /** `"true"` on the figure while the source panel is open. */
     readonly sourceOpen: "data-plantuml-source-open";
+    /** `"true"` on the figure while the minimap is open. */
+    readonly minimapOpen: "data-plantuml-minimap-open";
+    /** `"true"` on the figure while the search bar is open. */
+    readonly searchOpen: "data-plantuml-search-open";
+    /** On every `<text>` element in the rendered SVG that matches the search query. */
+    readonly searchMatch: "data-plantuml-search-match";
+    /** On the one match the search is currently focused on; always also a `searchMatch`. */
+    readonly searchCurrent: "data-plantuml-search-current";
+    /** On the node (or its text lines) a `#graph?highlight-node=…` deep link resolved to. */
+    readonly focusedNode: "data-plantuml-focused-node";
 };

package/dist/constants.js

@@ -43,4 +43,14 @@ export const DATA_ATTR = {
     maximized: 'data-plantuml-maximized',
     /** `"true"` on the figure while the source panel is open. */
     sourceOpen: 'data-plantuml-source-open',
+    /** `"true"` on the figure while the minimap is open. */
+    minimapOpen: 'data-plantuml-minimap-open',
+    /** `"true"` on the figure while the search bar is open. */
+    searchOpen: 'data-plantuml-search-open',
+    /** On every `<text>` element in the rendered SVG that matches the search query. */
+    searchMatch: 'data-plantuml-search-match',
+    /** On the one match the search is currently focused on; always also a `searchMatch`. */
+    searchCurrent: 'data-plantuml-search-current',
+    /** On the node (or its text lines) a `#graph?highlight-node=…` deep link resolved to. */
+    focusedNode: 'data-plantuml-focused-node',
 };

package/dist/runtime/sanitize.js

@@ -30,7 +30,11 @@ export function sanitizeSvgMarkup(svg) {
         USE_PROFILES: { svg: true, svgFilters: true },
         FORBID_TAGS: FORBIDDEN_TAGS,
         FORBID_ATTR: ['formaction', 'xlink:show', 'ping'],
-        ADD_ATTR: ['role', 'aria-label', 'aria-labelledby', 'aria-describedby'],
+        // `target` is in DOMPurify's HTML profile but not its SVG profile, and PlantUML puts
+        // `target="_top"` on every `[[link]]` it renders. The attribute carries no script
+        // surface — modern browsers imply `noopener` for `target="_blank"` — so it is allowed
+        // rather than silently rewriting where the author's links open.
+        ADD_ATTR: ['role', 'aria-label', 'aria-labelledby', 'aria-describedby', 'target'],
         ALLOW_DATA_ATTR: true,
         KEEP_CONTENT: true,
         RETURN_DOM: false,

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

@@ -0,0 +1,9 @@
+import { type ReactNode } from 'react';
+import type { ZoomPanHandle } from './useZoomPan.js';
+export interface MinimapProps {
+    /** The rendered diagram, already sanitized — the same string the canvas shows. */
+    svg: string;
+    zoom: ZoomPanHandle;
+    onClose: () => void;
+}
+export default function Minimap({ svg, zoom, onClose }: MinimapProps): ReactNode;

package/dist/theme/PlantUmlDiagram/Minimap.js

@@ -0,0 +1,137 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import { CloseIcon } from './icons.js';
+import { centerViewportOn, minimapScale, visibleContentRect } from './zoomMath.js';
+import styles from './styles.module.css';
+/**
+ * The minimap: a small copy of the diagram with a rectangle marking what the viewport
+ * currently shows. Pressing or dragging anywhere on the map centres the view there.
+ *
+ * Everything that changes per pan frame — the map's sizes and the rectangle — is written
+ * straight to the DOM through `zoom.subscribe`, for the same reason `useZoomPan` writes its
+ * transform imperatively: mirroring a per-frame value through React state would re-render the
+ * whole figure once per frame of every drag.
+ *
+ * The map handles the pointer itself rather than making the rectangle the draggable thing:
+ * a rectangle a few pixels wide would be a hopeless drag target, and centring on the pressed
+ * point makes a single click work as "jump there" with no extra code path.
+ */
+/** The box the diagram is scaled into. The map is smaller when the aspect ratio demands it. */
+const MAP_MAX_WIDTH = 200;
+const MAP_MAX_HEIGHT = 150;
+export default function Minimap({ svg, zoom, onClose }) {
+    // React 19 compares `dangerouslySetInnerHTML` by wrapper identity, not by `__html`; an
+    // inline literal would re-parse the copy on every re-render of the figure.
+    const svgHtml = useMemo(() => ({ __html: svg }), [svg]);
+    const canvasRef = useRef(null);
+    const layerRef = useRef(null);
+    const rectRef = useRef(null);
+    const scaleRef = useRef(0);
+    const update = useCallback(() => {
+        const canvas = canvasRef.current;
+        const layer = layerRef.current;
+        const rect = rectRef.current;
+        if (!canvas || !layer || !rect)
+            return;
+        const bounds = zoom.measure();
+        const scale = minimapScale(bounds, MAP_MAX_WIDTH, MAP_MAX_HEIGHT);
+        scaleRef.current = scale;
+        // Nothing measurable yet (jsdom, or a picture that has not laid out): keep the box at
+        // its maximum size rather than collapsing to a zero-sized, unclickable sliver.
+        if (scale <= 0) {
+            canvas.style.width = `${MAP_MAX_WIDTH}px`;
+            canvas.style.height = `${MAP_MAX_HEIGHT}px`;
+            rect.style.width = '0px';
+            rect.style.height = '0px';
+            return;
+        }
+        canvas.style.width = `${bounds.contentWidth * scale}px`;
+        canvas.style.height = `${bounds.contentHeight * scale}px`;
+        // The copy is laid out at the content's own width and scaled down as one block, so it
+        // keeps exactly the layout — and therefore the geometry — of the real canvas.
+        layer.style.width = `${bounds.contentWidth}px`;
+        layer.style.transform = `scale(${scale})`;
+        const visible = visibleContentRect(zoom.getTransform(), bounds);
+        rect.style.left = `${visible.x * scale}px`;
+        rect.style.top = `${visible.y * scale}px`;
+        rect.style.width = `${visible.width * scale}px`;
+        rect.style.height = `${visible.height * scale}px`;
+    }, [zoom]);
+    // `svg` is a dependency so a re-rendered picture re-measures once its new layout is
+    // committed; the subscription covers every transform change in between.
+    useEffect(() => {
+        update();
+        return zoom.subscribe(update);
+    }, [svg, update, zoom]);
+    useEffect(() => {
+        const canvas = canvasRef.current;
+        if (!canvas)
+            return undefined;
+        let pointerId = null;
+        const panTo = (event) => {
+            const scale = scaleRef.current;
+            if (scale <= 0)
+                return;
+            const box = canvas.getBoundingClientRect();
+            zoom.applyTransform(centerViewportOn(zoom.getTransform(), (event.clientX - box.left) / scale, (event.clientY - box.top) / scale, zoom.measure()));
+        };
+        const setContinuous = (on) => {
+            // The main layer eases discrete zoom steps; a drag tracked through the minimap is
+            // direct manipulation and must not lag behind the pointer, exactly like a canvas drag.
+            const layer = zoom.layerRef.current;
+            if (layer)
+                layer.dataset['plantumlContinuous'] = on ? 'true' : 'false';
+        };
+        const onPointerDown = (event) => {
+            if (!event.isPrimary || event.button !== 0)
+                return;
+            pointerId = event.pointerId;
+            // Unlike the canvas there is nothing to select or focus in here, so the press can be
+            // consumed outright — this is also what stops a drag from selecting page text.
+            event.preventDefault();
+            setContinuous(true);
+            try {
+                canvas.setPointerCapture(pointerId);
+            }
+            catch {
+                // Capture is unavailable in some environments; dragging still works without it.
+            }
+            panTo(event);
+        };
+        const onPointerMove = (event) => {
+            if (pointerId === null || event.pointerId !== pointerId)
+                return;
+            event.preventDefault();
+            panTo(event);
+        };
+        const endDrag = (event) => {
+            if (pointerId === null || event.pointerId !== pointerId)
+                return;
+            try {
+                if (canvas.hasPointerCapture(pointerId))
+                    canvas.releasePointerCapture(pointerId);
+            }
+            catch {
+                // Nothing to release.
+            }
+            pointerId = null;
+            setContinuous(false);
+        };
+        canvas.addEventListener('pointerdown', onPointerDown);
+        canvas.addEventListener('pointermove', onPointerMove);
+        canvas.addEventListener('pointerup', endDrag);
+        canvas.addEventListener('pointercancel', endDrag);
+        canvas.addEventListener('lostpointercapture', endDrag);
+        return () => {
+            canvas.removeEventListener('pointerdown', onPointerDown);
+            canvas.removeEventListener('pointermove', onPointerMove);
+            canvas.removeEventListener('pointerup', endDrag);
+            canvas.removeEventListener('pointercancel', endDrag);
+            canvas.removeEventListener('lostpointercapture', endDrag);
+            setContinuous(false);
+        };
+    }, [zoom]);
+    return (_jsxs("div", { className: styles.minimap, "data-plantuml-minimap": "true", children: [_jsxs("div", { ref: canvasRef, className: styles.minimapCanvas, "aria-hidden": "true", children: [_jsx("div", { ref: layerRef, className: styles.minimapLayer, 
+                        // The same sanitized string the visible canvas renders — nothing new to sanitize.
+                        dangerouslySetInnerHTML: svgHtml }), _jsx("div", { ref: rectRef, className: styles.minimapRect })] }), _jsx("button", { type: "button", className: `${styles.toolbarButton} ${styles.minimapClose}`, "aria-label": "Close minimap", onClick: onClose, children: _jsx(CloseIcon, {}) })] }));
+}

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

@@ -0,0 +1,55 @@
+/**
+ * Deep links into diagrams: `#graph?highlight-node=<TARGET>`.
+ *
+ * Every diagram on the page reacts to the hash — none of them needs an id of its own, and a
+ * diagram that does not contain the target simply does nothing. The matcher below is a
+ * ladder: the first level that yields a match wins, so a deterministic, author-chosen ID
+ * always beats the loose text matching that exists for diagrams nobody annotated.
+ *
+ * Everything here is DOM-in, elements-out and free of React, which is what makes the ladder
+ * testable against synthetic SVG.
+ */
+/**
+ * Extracts the deeplink target from a location hash.
+ *
+ * Returns the decoded identifier — `%0A` becomes a real newline, so multiline labels can be
+ * addressed — or `null` when the hash is absent, not diagram-shaped, or names no node.
+ */
+export declare function parseDiagramHash(hash: string): string | null;
+export interface DeeplinkMatch {
+    /** The elements to mark as the focused node — one group or anchor, or several text lines. */
+    elements: Element[];
+    /** The element whose position the viewport centres on. */
+    anchor: Element;
+}
+/**
+ * Finds the node a deeplink target refers to inside one rendered diagram.
+ *
+ * The ladder, from most to least deterministic:
+ *
+ * 1. **Explicit id** — an element whose `id` equals the target. Graphviz emits these for
+ *    `node [id="…"]`, giving a hidden, deterministic handle. (PlantUML's own `id`s are
+ *    generated — `ent0001` — and deliberately not part of the contract.)
+ * 2. **PlantUML alias** — the engine writes every entity's alias into
+ *    `data-qualified-name` on its `g.entity` group, so `component "X" as REACTION_1234`
+ *    and `note "…" as REACTION_1234` are addressable by an id that never appears in the
+ *    picture. This is PlantUML's spelling of a hidden deterministic id.
+ * 3. **Self-anchor** — an `<a>` whose href's hash parses to the same target, which doubles
+ *    as the node's own permalink. Graphviz emits these for `node [URL="#graph?…"]`; the
+ *    bundled PlantUML engine currently emits no anchors at all, so for PlantUML this level
+ *    is future-proofing rather than an authoring channel.
+ * 4. **Graphviz node name** — the `<title>` Graphviz writes into every `g.node`, so plain
+ *    DOT node names work with no annotation at all.
+ * 5. **Multiline label** — a target containing newlines (`%0A` in the URL) matches that many
+ *    *consecutive* text lines, each containing its line of the target. The window stays
+ *    inside one node's group where groups exist (Graphviz `g.node`, PlantUML `g.entity`)
+ *    and runs over the document order otherwise — which is how a two-line label is told
+ *    apart from two nodes that each contain one of the lines.
+ * 6. **Single-line substring** — the first text line containing the target,
+ *    case-insensitively. This is what lets the unique half of a label (`12345` of
+ *    `caminus-process-archive\n12345`) address the node without spelling out the rest.
+ */
+export declare function findDeeplinkTarget(root: Element, target: string): DeeplinkMatch | null;
+export declare function claimDeeplinkScroll(claimKey: string, figure: Element): void;
+/** Test-only: lets each test start with the scroll unclaimed. */
+export declare function resetDeeplinkScroll(): void;

package/dist/theme/PlantUmlDiagram/deeplink.js

@@ -0,0 +1,149 @@
+/**
+ * Deep links into diagrams: `#graph?highlight-node=<TARGET>`.
+ *
+ * Every diagram on the page reacts to the hash — none of them needs an id of its own, and a
+ * diagram that does not contain the target simply does nothing. The matcher below is a
+ * ladder: the first level that yields a match wins, so a deterministic, author-chosen ID
+ * always beats the loose text matching that exists for diagrams nobody annotated.
+ *
+ * Everything here is DOM-in, elements-out and free of React, which is what makes the ladder
+ * testable against synthetic SVG.
+ */
+/** The hash prefix that separates diagram deep links from ordinary heading anchors. */
+const HASH_PREFIX = '#graph?';
+/** The query parameter carrying the node identifier. */
+const NODE_PARAM = 'highlight-node';
+/**
+ * Extracts the deeplink target from a location hash.
+ *
+ * Returns the decoded identifier — `%0A` becomes a real newline, so multiline labels can be
+ * addressed — or `null` when the hash is absent, not diagram-shaped, or names no node.
+ */
+export function parseDiagramHash(hash) {
+    if (!hash.startsWith(HASH_PREFIX))
+        return null;
+    const target = new URLSearchParams(hash.slice(HASH_PREFIX.length)).get(NODE_PARAM);
+    return target === null || target.trim() === '' ? null : target;
+}
+/** Escapes a value for use inside a double-quoted CSS attribute selector. */
+function escapeAttributeValue(value) {
+    return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+/** The target of an `<a>` element, whichever spelling the engine used. */
+function hrefOf(anchor) {
+    return anchor.getAttribute('href') ?? anchor.getAttribute('xlink:href');
+}
+/** Whether every line of the window contains its target line, case-insensitively. */
+function windowMatches(texts, start, lines) {
+    return lines.every((line, index) => (texts[start + index]?.textContent ?? '').toLowerCase().includes(line));
+}
+/**
+ * Finds the node a deeplink target refers to inside one rendered diagram.
+ *
+ * The ladder, from most to least deterministic:
+ *
+ * 1. **Explicit id** — an element whose `id` equals the target. Graphviz emits these for
+ *    `node [id="…"]`, giving a hidden, deterministic handle. (PlantUML's own `id`s are
+ *    generated — `ent0001` — and deliberately not part of the contract.)
+ * 2. **PlantUML alias** — the engine writes every entity's alias into
+ *    `data-qualified-name` on its `g.entity` group, so `component "X" as REACTION_1234`
+ *    and `note "…" as REACTION_1234` are addressable by an id that never appears in the
+ *    picture. This is PlantUML's spelling of a hidden deterministic id.
+ * 3. **Self-anchor** — an `<a>` whose href's hash parses to the same target, which doubles
+ *    as the node's own permalink. Graphviz emits these for `node [URL="#graph?…"]`; the
+ *    bundled PlantUML engine currently emits no anchors at all, so for PlantUML this level
+ *    is future-proofing rather than an authoring channel.
+ * 4. **Graphviz node name** — the `<title>` Graphviz writes into every `g.node`, so plain
+ *    DOT node names work with no annotation at all.
+ * 5. **Multiline label** — a target containing newlines (`%0A` in the URL) matches that many
+ *    *consecutive* text lines, each containing its line of the target. The window stays
+ *    inside one node's group where groups exist (Graphviz `g.node`, PlantUML `g.entity`)
+ *    and runs over the document order otherwise — which is how a two-line label is told
+ *    apart from two nodes that each contain one of the lines.
+ * 6. **Single-line substring** — the first text line containing the target,
+ *    case-insensitively. This is what lets the unique half of a label (`12345` of
+ *    `caminus-process-archive\n12345`) address the node without spelling out the rest.
+ */
+export function findDeeplinkTarget(root, target) {
+    // A target with a newline is a multiline label, never an id or alias — and selector
+    // engines reject the literal newline outright.
+    if (!target.includes('\n')) {
+        // 1. Explicit id. An attribute selector rather than #…: ids here are author-chosen and
+        // may start with a digit or contain characters a bare id selector would reject.
+        const byId = root.querySelector(`[id="${escapeAttributeValue(target)}"]`);
+        if (byId)
+            return { elements: [byId], anchor: byId };
+        // 2. PlantUML alias.
+        const byAlias = root.querySelector(`[data-qualified-name="${escapeAttributeValue(target)}"]`);
+        if (byAlias)
+            return { elements: [byAlias], anchor: byAlias };
+    }
+    // 3. Self-anchor.
+    for (const anchor of Array.from(root.querySelectorAll('a'))) {
+        const href = hrefOf(anchor);
+        const hashIndex = href?.indexOf('#') ?? -1;
+        if (href !== null && hashIndex >= 0 && parseDiagramHash(href.slice(hashIndex)) === target) {
+            return { elements: [anchor], anchor };
+        }
+    }
+    // 4. Graphviz node name.
+    for (const title of Array.from(root.querySelectorAll('g.node > title'))) {
+        const node = title.parentElement;
+        if (node && (title.textContent ?? '').trim() === target) {
+            return { elements: [node], anchor: node };
+        }
+    }
+    const lines = target
+        .split('\n')
+        .map((line) => line.trim().toLowerCase())
+        .filter((line) => line !== '');
+    if (lines.length === 0)
+        return null;
+    // 5. Multiline label.
+    if (lines.length > 1) {
+        const groups = Array.from(root.querySelectorAll('g.node, g.entity'));
+        const scopes = groups.length > 0 ? groups : [root];
+        for (const scope of scopes) {
+            const texts = Array.from(scope.querySelectorAll('text'));
+            for (let start = 0; start + lines.length <= texts.length; start += 1) {
+                if (windowMatches(texts, start, lines)) {
+                    const window = texts.slice(start, start + lines.length);
+                    return { elements: window, anchor: window[0] };
+                }
+            }
+        }
+        return null;
+    }
+    // 6. Single-line substring.
+    const needle = lines[0];
+    for (const text of Array.from(root.querySelectorAll('text'))) {
+        if ((text.textContent ?? '').toLowerCase().includes(needle)) {
+            return { elements: [text], anchor: text };
+        }
+    }
+    return null;
+}
+/**
+ * Scrolls the page to the first figure that claims a given deeplink navigation — and only
+ * that one.
+ *
+ * Diagrams evaluate the hash independently, so without an arbiter every matching figure
+ * would fight over the scroll position. The caller keys the claim on one *navigation* to
+ * one target (history entry key + pathname + target): the many diagrams reacting to a
+ * single navigation yield a single scroll, while following the same deep link again — a new
+ * history entry, unchanged hash — scrolls again. Keying on the target alone got that second
+ * follow wrong: the stale claim swallowed the scroll. On a page whose diagrams were
+ * force-rendered by the hash, renders complete in mount order, so the first claimant is in
+ * practice the first matching figure in the document.
+ */
+let scrolledKey = null;
+export function claimDeeplinkScroll(claimKey, figure) {
+    if (scrolledKey === claimKey)
+        return;
+    scrolledKey = claimKey;
+    figure.scrollIntoView({ block: 'center' });
+}
+/** Test-only: lets each test start with the scroll unclaimed. */
+export function resetDeeplinkScroll() {
+    scrolledKey = null;
+}