@matfsw/docusaurus-plantuml-plugin 1.3.1 → 1.5.0

package/CHANGELOG.md

@@ -7,6 +7,108 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-08-14
+
+### Added
+
+- **Deep links *from* diagram nodes — including to diagrams on other pages.** A node can now
+  carry a link to another diagram's deep link, and clicking it navigates there and focuses
+  the target node: `component "Order Service" as ORDER_SVC
+  [[/docs/orders#graph?highlight-node=ORDER_DETAIL_1]]` in PlantUML, or
+  `orders [URL="/docs/orders#graph?highlight-node=ORDER_DETAIL_1"]` in Graphviz.
+
+  For PlantUML this means the plugin now **synthesizes the anchors the bundled engine
+  drops**: `[[url]]` on components, participants, C4 macros and relations is read back out
+  of the fence source and wrapped around the rendered element — clickable,
+  keyboard-focusable, marked `data-plantuml-diagram-link`, coloured with the site's link
+  colour. Correlation runs on the alias the engine writes into `data-qualified-name`, with
+  `data-source-line` as the fallback, so it survives `!include` — standard-library diagrams
+  included, whose preprocessing shifts every line number. Synthesized hrefs pass a scheme
+  allowlist; a link that cannot be correlated attaches to nothing. Links inside note bodies
+  remain the engine's styled-but-inert text, and one link per source line is correlatable.
+
+  Navigation is SPA-aware in both engines: in-diagram links to same-site URLs go through
+  the Docusaurus router — no full page load — and site-absolute paths get the site's
+  `baseUrl` exactly as markdown links do. External links and pure `#…` anchors stay native,
+  and clicks that end a drag never navigate.
+
+### Changed
+
+- **The deep-link highlight is green, not red.** The focused-node colour was the theme's
+  danger red, which reads as an error on a highlight that persists until the hash changes;
+  it now defaults to the theme's success green. Sites can pick any colour by setting
+  `--plantuml-focus-color` — the rule reads
+  `var(--plantuml-focus-color, var(--ifm-color-success))`.
+
+## [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 +482,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.3.1...HEAD
+[Unreleased]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.5.0...HEAD
+[1.5.0]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.4.0...v1.5.0
+[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,133 @@ 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
+
+### Linking from a node
+
+A node (or edge) can carry a link — to an external site, another docs page, or another
+diagram's node via a [deep link](#deep-links-graphhighlight-node). What to write differs by
+engine.
+
+#### PlantUML
+
+**Recommended form — give the node an alias** and put the link on the same line:
+
+````markdown
+```plantuml
+@startuml
+component "Order Service" as ORDER_SVC [[/docs/orders#graph?highlight-node=ORDER_DETAIL_1]]
+
+' The same through a C4 macro — the alias is the macro's first argument:
+!include <C4/C4_Container>
+Container(billing, "Billing", "Java") [[/docs/billing#graph?highlight-node=INVOICE_QUEUE]]
+@enduml
+```
+````
+
+The bundled engine parses `[[url]]` but emits no `<a>` elements, so the plugin
+**synthesizes** the anchor: it reads the link back out of the fence source and wraps the
+rendered element in a real anchor — clickable, keyboard-focusable, coloured with the site's
+link colour, underlined on hover, and marked `data-plantuml-diagram-link` for site CSS. The
+alias is the correlation key (the engine writes it into the SVG as `data-qualified-name`),
+which is what makes this form work in **every** diagram — including ones whose
+`!include <…>` shifts the engine's internal line numbering.
+
+**Fallback form — no alias.** A plain quoted declaration or an edge label also works:
+
+````markdown
+```plantuml
+@startuml
+component "Order Service" [[/docs/orders#graph?highlight-node=ORDER_DETAIL_1]]
+"Order Service" --> "Billing" : invoices [[/docs/billing]]
+@enduml
+```
+````
+
+With nothing alias-shaped on the line, the plugin correlates by the line number the engine
+stamps on each element (`data-source-line`) — which is exact **only in diagrams without
+`!include`**. In a standard-library diagram these links attach to nothing; use the aliased
+form there.
+
+Boundaries, by design: hrefs pass a scheme allowlist (`http(s)`, site-relative, `#…` —
+anything else is dropped); links inside _note bodies_ stay the styled-but-inert text the
+engine renders; one link per source line is correlatable; and a link that cannot be
+correlated attaches to nothing rather than to the wrong node.
+
+#### Graphviz
+
+One form, no fallback involved — the engine emits the anchor itself, preserved through
+sanitization (`javascript:` URLs are stripped):
+
+````markdown
+```dot
+digraph {
+  orders [URL="/docs/orders#graph?highlight-node=ORDER_DETAIL_1", label="Order Service", fontcolor=blue];
+}
+```
+````
+
+#### 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.
+
+Clicking either example node above therefore navigates — without a reload — to
+`/docs/orders`, where the diagram containing `ORDER_DETAIL_1` highlights and centres it.
+
+**Rule of thumb: in PlantUML, give a node an alias if you link it or link to it.** The
+aliased spelling is immune to includes on both ends — as the outgoing link's correlation
+key here, and as the incoming deep link's `data-qualified-name` target below. The
+unaliased form exists so quick, plain diagrams work without ceremony.
+
+### 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`), and a zoomable diagram snaps to **100% centred on the
+  node**. The highlight stays until the hash changes. It uses the theme's success green by
+  default; set `--plantuml-focus-color` in site CSS to pick any other colour:
+
+  ```css
+  :root {
+    --plantuml-focus-color: #3578e5; /* a light blue instead */
+  }
+  ```
+
+- 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 +1323,11 @@ 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 links inside note bodies are not clickable.** The plugin synthesizes the
+  `[[url]]` anchors the bundled engine drops on components, participants, macros and
+  relations — but a link in a note's _text_ renders as the styled-but-inert text the engine
+  emits, with nothing to correlate it to. One link per source line is correlatable, for the
+  same reason. 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,16 @@ 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";
+    /** On anchors the plugin synthesized from `[[url]]` links the PlantUML engine dropped. */
+    readonly diagramLink: "data-plantuml-diagram-link";
 };

package/dist/constants.js

@@ -43,4 +43,16 @@ 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',
+    /** On anchors the plugin synthesized from `[[url]]` links the PlantUML engine dropped. */
+    diagramLink: 'data-plantuml-diagram-link',
 };

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;