@matfsw/docusaurus-plantuml-plugin 1.3.1 → 1.5.0

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;
+}

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

@@ -0,0 +1,51 @@
+/**
+ * Synthesizes the hyperlinks PlantUML's bundled engine drops.
+ *
+ * The engine parses `[[url]]` on components, participants and edges but emits no `<a>`
+ * elements, so authored links are silently lost. What it *does* emit is enough to put them
+ * back: every entity carries its alias in `data-qualified-name` and its source position in
+ * `data-source-line`, and every edge carries `data-source-line` plus its endpoints in
+ * `data-entity-1`/`data-entity-2`. This module extracts the links from the fence source the
+ * plugin already has, correlates each with the rendered element, and wraps that element in a
+ * real `<a>` — clickable, keyboard-focusable, and marked for styling.
+ *
+ * Correlation is a two-layer affair because of `!include`: the engine numbers lines in the
+ * *preprocessed* text, so a stdlib include shifts every `data-source-line` after it and
+ * line-equality silently stops holding. Aliases survive preprocessing untouched, which makes
+ * them the include-proof primary; exact line matching is the fallback that covers unnamed
+ * things (edges, mostly) in include-free sources. Everything here fails safe: a link that
+ * cannot be correlated attaches to nothing.
+ */
+export interface ExtractedLink {
+    /** Zero-based index of the line in the fence source, matching `data-source-line`. */
+    line: number;
+    /** The line's text, used for alias-candidate extraction. */
+    text: string;
+    href: string;
+}
+/**
+ * Schemes a synthesized link may carry. The engine's own output goes through DOMPurify, but
+ * these anchors are built by this module *after* sanitization, so the check lives here.
+ */
+export declare function isSafeLinkHref(href: string): boolean;
+/**
+ * Extracts at most one link per source line.
+ *
+ * One per line is a deliberate ceiling, not laziness: `data-source-line` identifies a line,
+ * not a token, so two links on one line cannot be told apart on the SVG side.
+ */
+export declare function extractSourceLinks(source: string): ExtractedLink[];
+/**
+ * Attaches extracted links to the rendered SVG. Returns how many elements were wrapped.
+ *
+ * Resolution per link, in order:
+ *
+ * 1. **Alias** (include-proof): a declaration line's single candidate that names emitted
+ *    `data-qualified-name` elements wraps all of them. An arrow line whose identifiers name
+ *    exactly two entities wraps the `g.link` connecting them.
+ * 2. **Exact line**: elements whose `data-source-line` equals the author's line index —
+ *    which holds whenever the source was not shifted by preprocessing.
+ */
+export declare function attachDiagramLinks(root: Element, links: ExtractedLink[]): number;
+/** Undoes {@link attachDiagramLinks}: unwraps every synthesized anchor under `root`. */
+export declare function detachDiagramLinks(root: Element): void;

package/dist/theme/PlantUmlDiagram/diagramLinks.js

@@ -0,0 +1,185 @@
+/**
+ * Synthesizes the hyperlinks PlantUML's bundled engine drops.
+ *
+ * The engine parses `[[url]]` on components, participants and edges but emits no `<a>`
+ * elements, so authored links are silently lost. What it *does* emit is enough to put them
+ * back: every entity carries its alias in `data-qualified-name` and its source position in
+ * `data-source-line`, and every edge carries `data-source-line` plus its endpoints in
+ * `data-entity-1`/`data-entity-2`. This module extracts the links from the fence source the
+ * plugin already has, correlates each with the rendered element, and wraps that element in a
+ * real `<a>` — clickable, keyboard-focusable, and marked for styling.
+ *
+ * Correlation is a two-layer affair because of `!include`: the engine numbers lines in the
+ * *preprocessed* text, so a stdlib include shifts every `data-source-line` after it and
+ * line-equality silently stops holding. Aliases survive preprocessing untouched, which makes
+ * them the include-proof primary; exact line matching is the fallback that covers unnamed
+ * things (edges, mostly) in include-free sources. Everything here fails safe: a link that
+ * cannot be correlated attaches to nothing.
+ */
+import { DATA_ATTR } from '../../constants.js';
+/**
+ * Schemes a synthesized link may carry. The engine's own output goes through DOMPurify, but
+ * these anchors are built by this module *after* sanitization, so the check lives here.
+ */
+export function isSafeLinkHref(href) {
+    if (/^(https?:)/i.test(href))
+        return true;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(href))
+        return false; // any other explicit scheme
+    return (href.startsWith('/') || href.startsWith('./') || href.startsWith('../') || href.startsWith('#'));
+}
+/** `[[href]]`, `[[href label]]`, `[[href{tooltip}]]` — the href ends at `{`, space, or `]]`. */
+const LINK_PATTERN = /\[\[([^\s{\]]+)[^\]]*\]\]/;
+/** Note lines carry body links the engine renders as styled text; nothing to attach. */
+const NOTE_LINE = /^\s*[rh]?note\b/i;
+/**
+ * Extracts at most one link per source line.
+ *
+ * One per line is a deliberate ceiling, not laziness: `data-source-line` identifies a line,
+ * not a token, so two links on one line cannot be told apart on the SVG side.
+ */
+export function extractSourceLinks(source) {
+    const links = [];
+    const lines = source.split(/\r\n|\r|\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+        const text = lines[index];
+        if (NOTE_LINE.test(text))
+            continue;
+        const match = LINK_PATTERN.exec(text);
+        if (!match)
+            continue;
+        const href = match[1];
+        if (!isSafeLinkHref(href))
+            continue;
+        links.push({ line: index, text, href });
+    }
+    return links;
+}
+/** `as ALIAS` — the strongest signal a declaration line gives. */
+const AS_ALIAS = /\bas\s+([A-Za-z_][\w]*)/;
+/** C4-style macro: `Container(alias, …)` — the alias is the first argument. */
+const MACRO_ALIAS = /^\s*[A-Za-z_][\w]*\s*\(\s*([A-Za-z_][\w]*)\s*[,)]/;
+/** `component ALIAS [[…]]` — a declaration whose bare name is the alias. */
+const DECL_ALIAS = /^\s*(?:component|actor|participant|database|queue|node|usecase|rectangle|interface|boundary|control|entity|collections|agent|artifact|card|cloud|file|folder|frame|hexagon|package|person|stack|storage|state|object|class|circle|label)\s+([A-Za-z_][\w]*)/i;
+/** Lines with an arrow are relations; their identifiers name the two endpoints. */
+const ARROW = /(-+[->]|\.+[.>]|<[-.]|[-.]{2,})/;
+const IDENTIFIER = /[A-Za-z_][\w]*/g;
+/**
+ * The alias candidates a link line offers, most specific first. `null` means the line's
+ * shape gives no safe candidates and only exact line matching may be used.
+ */
+function aliasCandidates(text) {
+    const as = AS_ALIAS.exec(text);
+    if (as)
+        return [as[1]];
+    const macro = MACRO_ALIAS.exec(text);
+    if (macro)
+        return [macro[1]];
+    const decl = DECL_ALIAS.exec(text);
+    if (decl)
+        return [decl[1]];
+    if (ARROW.test(text)) {
+        // Identifiers before the link only: the label after `:` may contain arbitrary words.
+        const beforeLink = text.slice(0, text.indexOf('[['));
+        return beforeLink.match(IDENTIFIER) ?? [];
+    }
+    return null;
+}
+/**
+ * Participant lifelines run the full height of a sequence diagram; wrapping them would turn
+ * most of the background into a link.
+ */
+function isWrappable(element) {
+    return !(element.getAttribute('class') ?? '').includes('lifeline');
+}
+function wrap(element, href) {
+    if (!isWrappable(element))
+        return false;
+    if (element.closest('a'))
+        return false; // already linked — never nest anchors
+    const parent = element.parentNode;
+    if (!parent)
+        return false;
+    const anchor = element.ownerDocument.createElementNS('http://www.w3.org/2000/svg', 'a');
+    anchor.setAttribute('href', href);
+    anchor.setAttribute(DATA_ATTR.diagramLink, 'true');
+    parent.insertBefore(anchor, element);
+    anchor.appendChild(element);
+    return true;
+}
+/**
+ * Attaches extracted links to the rendered SVG. Returns how many elements were wrapped.
+ *
+ * Resolution per link, in order:
+ *
+ * 1. **Alias** (include-proof): a declaration line's single candidate that names emitted
+ *    `data-qualified-name` elements wraps all of them. An arrow line whose identifiers name
+ *    exactly two entities wraps the `g.link` connecting them.
+ * 2. **Exact line**: elements whose `data-source-line` equals the author's line index —
+ *    which holds whenever the source was not shifted by preprocessing.
+ */
+export function attachDiagramLinks(root, links) {
+    const named = new Map();
+    for (const element of Array.from(root.querySelectorAll('[data-qualified-name]'))) {
+        const name = element.getAttribute('data-qualified-name');
+        const list = named.get(name);
+        if (list)
+            list.push(element);
+        else
+            named.set(name, [element]);
+    }
+    // Entity ids (`ent0001`) are what edges reference in `data-entity-1`/`data-entity-2`.
+    const idToName = new Map();
+    for (const [name, elements] of named) {
+        for (const element of elements) {
+            const id = element.getAttribute('id');
+            if (id)
+                idToName.set(id, name);
+        }
+    }
+    let wrapped = 0;
+    for (const link of links) {
+        const candidates = aliasCandidates(link.text);
+        // 1a. A single alias candidate that exists → wrap every element carrying it.
+        if (candidates !== null) {
+            const matching = candidates.filter((candidate) => named.has(candidate));
+            if (matching.length === 1) {
+                for (const element of named.get(matching[0]) ?? []) {
+                    if (wrap(element, link.href))
+                        wrapped += 1;
+                }
+                continue;
+            }
+            // 1b. Exactly two entities on an arrow line → the edge between them.
+            if (matching.length === 2) {
+                const [a, b] = matching;
+                const edge = Array.from(root.querySelectorAll('g.link')).find((element) => {
+                    const e1 = idToName.get(element.getAttribute('data-entity-1') ?? '');
+                    const e2 = idToName.get(element.getAttribute('data-entity-2') ?? '');
+                    return (e1 === a && e2 === b) || (e1 === b && e2 === a);
+                });
+                if (edge && wrap(edge, link.href)) {
+                    wrapped += 1;
+                    continue;
+                }
+            }
+        }
+        // 2. Exact line match — the fallback for unnamed elements in unshifted sources.
+        for (const element of Array.from(root.querySelectorAll(`[data-source-line="${link.line}"]`))) {
+            if (wrap(element, link.href))
+                wrapped += 1;
+        }
+    }
+    return wrapped;
+}
+/** Undoes {@link attachDiagramLinks}: unwraps every synthesized anchor under `root`. */
+export function detachDiagramLinks(root) {
+    for (const anchor of Array.from(root.querySelectorAll(`a[${DATA_ATTR.diagramLink}]`))) {
+        const parent = anchor.parentNode;
+        if (!parent)
+            continue;
+        while (anchor.firstChild)
+            parent.insertBefore(anchor.firstChild, anchor);
+        anchor.remove();
+    }
+}

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

@@ -24,10 +24,23 @@ export declare function ZoomOutIcon(): ReactElement;
 export declare function ZoomInIcon(): ReactElement;
 /** Replaces `⟲` U+27F2: a circular arrow, open at the top right where the arrowhead sits. */
 export declare function ResetZoomIcon(): ReactElement;
+/**
+ * Fit to view: the maximize corners with the diagram drawn inside them, so the two controls
+ * read as siblings — both are about the frame, one keeps you in the page.
+ */
+export declare function FitIcon(): ReactElement;
 /** Replaces `⛶` U+26F6, the character that had no glyph. */
 export declare function MaximizeIcon(): ReactElement;
 /** Replaces `✕` U+2715, shown in place of maximize while the diagram fills the viewport. */
 export declare function CloseIcon(): ReactElement;
+/** The search toggle: a lens. */
+export declare function SearchIcon(): ReactElement;
+/** Previous search match. */
+export declare function ChevronUpIcon(): ReactElement;
+/** Next search match. */
+export declare function ChevronDownIcon(): ReactElement;
+/** The minimap toggle: a map frame with the viewport rectangle marked inside it. */
+export declare function MinimapIcon(): ReactElement;
 /**
  * Replaces the literal `</>` of the source toggle.
  *

package/dist/theme/PlantUmlDiagram/icons.js

@@ -24,6 +24,13 @@ export function ZoomInIcon() {
 export function ResetZoomIcon() {
     return (_jsxs("svg", { ...iconProps, children: [_jsx("path", { d: "M13 8A5 5 0 1 1 11.4 4.3" }), _jsx("path", { d: "M13 2v3h-3" })] }));
 }
+/**
+ * Fit to view: the maximize corners with the diagram drawn inside them, so the two controls
+ * read as siblings — both are about the frame, one keeps you in the page.
+ */
+export function FitIcon() {
+    return (_jsxs("svg", { ...iconProps, children: [_jsx("path", { d: "M2 6V2h4M14 6V2h-4M2 10v4h4M14 10v4h-4" }), _jsx("rect", { x: "5.5", y: "5.5", width: "5", height: "5", rx: "1" })] }));
+}
 /** Replaces `⛶` U+26F6, the character that had no glyph. */
 export function MaximizeIcon() {
     return (_jsx("svg", { ...iconProps, children: _jsx("path", { d: "M2 6V2h4M14 6V2h-4M2 10v4h4M14 10v4h-4" }) }));
@@ -32,6 +39,22 @@ export function MaximizeIcon() {
 export function CloseIcon() {
     return (_jsx("svg", { ...iconProps, children: _jsx("path", { d: "M4 4l8 8M12 4l-8 8" }) }));
 }
+/** The search toggle: a lens. */
+export function SearchIcon() {
+    return (_jsxs("svg", { ...iconProps, children: [_jsx("circle", { cx: "7", cy: "7", r: "4" }), _jsx("path", { d: "M10 10l4 4" })] }));
+}
+/** Previous search match. */
+export function ChevronUpIcon() {
+    return (_jsx("svg", { ...iconProps, children: _jsx("path", { d: "M4 10l4-4 4 4" }) }));
+}
+/** Next search match. */
+export function ChevronDownIcon() {
+    return (_jsx("svg", { ...iconProps, children: _jsx("path", { d: "M4 6l4 4 4-4" }) }));
+}
+/** The minimap toggle: a map frame with the viewport rectangle marked inside it. */
+export function MinimapIcon() {
+    return (_jsxs("svg", { ...iconProps, children: [_jsx("rect", { x: "2", y: "3", width: "12", height: "10", rx: "1" }), _jsx("rect", { x: "4.5", y: "7.5", width: "4", height: "3", fill: "currentColor", stroke: "none" })] }));
+}
 /**
  * Replaces the literal `</>` of the source toggle.
  *

package/dist/theme/PlantUmlDiagram/index.js

@@ -1,5 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useId, useRef, useState } from 'react';
+import { useCallback, useEffect, useId, useMemo, useRef, useState, } from 'react';
+import { useLocation } from '@docusaurus/router';
 import { useColorMode } from '@docusaurus/theme-common';
 import { DATA_ATTR } from '../../constants.js';
 import { getSharedCache } from '../../runtime/cache.js';
@@ -7,7 +8,12 @@ import { PlantUmlError } from '../../runtime/errors.js';
 import { renderGraphvizDiagram } from '../../runtime/graphvizRenderer.js';
 import { renderDiagram } from '../../runtime/renderer.js';
 import { usePlantUmlConfig } from '../usePlantUmlConfig.js';
-import { CloseIcon, MaximizeIcon, ResetZoomIcon, SourceIcon, ZoomInIcon, ZoomOutIcon, } from './icons.js';
+import { ChevronDownIcon, ChevronUpIcon, CloseIcon, FitIcon, MaximizeIcon, MinimapIcon, ResetZoomIcon, SearchIcon, SourceIcon, ZoomInIcon, ZoomOutIcon, } from './icons.js';
+import { parseDiagramHash } from './deeplink.js';
+import Minimap from './Minimap.js';
+import { useDiagramDeeplink } from './useDiagramDeeplink.js';
+import { useDiagramLinks } from './useDiagramLinks.js';
+import { useDiagramSearch } from './useDiagramSearch.js';
 import { useZoomPan } from './useZoomPan.js';
 import styles from './styles.module.css';
 /**
@@ -50,6 +56,9 @@ function messageFor(error) {
 export default function PlantUmlDiagram({ source, title, language, engine = 'plantuml', layout, zoom: zoomProp, showSource: showSourceProp, }) {
     const config = usePlantUmlConfig();
     const { colorMode } = useColorMode();
+    // The router, not `window.location`: `<Link>` navigations are `history.pushState` calls
+    // that fire no DOM event, so only the router sees every way the hash can change.
+    const routerLocation = useLocation();
     const containerRef = useRef(null);
     const hintId = useId();
     const sourcePanelId = useId();
@@ -68,8 +77,12 @@ export default function PlantUmlDiagram({ source, title, language, engine = 'pla
     const interactive = zoomProp ?? config?.options.zoom ?? true;
     const sourceAvailable = showSourceProp ?? config?.options.showSource ?? true;
     const [state, setState] = useState(INITIAL_STATE);
-    const [inView, setInView] = useState(!lazy);
+    // A diagram deep link must be able to reach a diagram below the fold, so a `#graph?…`
+    // hash defeats lazy rendering. The router's server-side location has no hash, and the
+    // first paint is the placeholder either way, so hydration cannot mismatch.
+    const [inView, setInView] = useState(() => !lazy || parseDiagramHash(routerLocation.hash) !== null);
     const [sourceOpen, setSourceOpen] = useState(false);
+    const [minimapOpen, setMinimapOpen] = useState(false);
     const [copyState, setCopyState] = useState('idle');
     const copyTimer = useRef(undefined);
     // A pending "Copied" message must not fire into an unmounted component.
@@ -107,6 +120,55 @@ export default function PlantUmlDiagram({ source, title, language, engine = 'pla
         // gratuitous jump.
         resetKey: `${source}|${engine}|${resolvedLayout}|${renderDark ? 'dark' : 'light'}`,
     });
+    const search = useDiagramSearch({
+        enabled: interactive && state.status === 'ready',
+        zoom,
+        svg: state.svg,
+    });
+    useDiagramDeeplink({
+        ready: state.status === 'ready' && state.svg !== null,
+        svg: state.svg,
+        interactive,
+        zoom,
+        containerRef,
+    });
+    useDiagramLinks({
+        ready: state.status === 'ready' && state.svg !== null,
+        svg: state.svg,
+        engine,
+        source,
+        containerRef,
+    });
+    // A hash arriving *after* mount must defeat lazy rendering too — a deep link followed
+    // from another diagram on the same page may point below the fold. Driven by the router
+    // location rather than `hashchange`, which `<Link>` navigations never fire.
+    useEffect(() => {
+        if (!inView && parseDiagramHash(routerLocation.hash) !== null)
+            setInView(true);
+    }, [inView, routerLocation.hash]);
+    const searchToggleRef = useRef(null);
+    // Escape and the ✕ hand focus back to the toggle, so the keyboard is not left stranded on
+    // a control that just left the page.
+    const closeSearch = useCallback(() => {
+        search.close();
+        searchToggleRef.current?.focus();
+    }, [search]);
+    const onSearchKeyDown = useCallback((event) => {
+        if (event.key === 'Enter') {
+            event.preventDefault();
+            if (event.shiftKey)
+                search.previous();
+            else
+                search.next();
+        }
+        else if (event.key === 'Escape') {
+            event.preventDefault();
+            // Escape in the search closes the search. Without this, the document-level listener
+            // would also un-maximize the diagram in the same keystroke.
+            event.stopPropagation();
+            closeSearch();
+        }
+    }, [closeSearch, search]);
     useEffect(() => {
         if (!lazy || inView)
             return undefined;
@@ -201,11 +263,18 @@ export default function PlantUmlDiagram({ source, title, language, engine = 'pla
     ]);
     const label = title ?? `${engineName} diagram`;
     const busy = state.status === 'loading' || state.status === 'rendering';
+    /**
+     * One wrapper object per SVG string, not a fresh literal in the JSX: React 19 compares
+     * `dangerouslySetInnerHTML` by the wrapper's identity, not by `__html`, so an inline
+     * literal makes every re-render of the figure re-parse the whole SVG subtree — visibly
+     * so once anything marks the rendered elements, as the search's highlights do.
+     */
+    const svgHtml = useMemo(() => (state.svg === null ? null : { __html: state.svg }), [state.svg]);
     // The sanitized SVG always lives in this element, zoomable or not, so `role="img" > svg`
     // stays a stable contract for tests and for author CSS.
-    const canvas = state.svg !== null && (_jsx("div", { className: !interactive && sourceOpen ? `${styles.canvas} ${styles.hiddenView}` : styles.canvas, role: "img", "aria-label": label, 
+    const canvas = state.svg !== null && svgHtml !== null && (_jsx("div", { className: !interactive && sourceOpen ? `${styles.canvas} ${styles.hiddenView}` : styles.canvas, role: "img", "aria-label": label, 
         // Sanitized above unless `sanitizeSvg: false` was explicitly opted into.
-        dangerouslySetInnerHTML: { __html: state.svg } }));
+        dangerouslySetInnerHTML: svgHtml }));
     const copyControl = sourceAvailable && sourceOpen && state.status === 'ready' && (_jsx("button", { type: "button", className: `${styles.toolbarButton} ${styles.toolbarTextButton}`, "aria-label": `Copy ${engineName} source to clipboard`, onClick: copySource, children: "Copy" }));
     const sourceToggle = sourceAvailable && (_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": sourceOpen ? 'Hide diagram source' : 'Show diagram source', "aria-expanded": sourceOpen, "aria-controls": sourcePanelId, onClick: () => setSourceOpen((open) => !open), children: _jsx(SourceIcon, {}) }));
     /**
@@ -225,7 +294,11 @@ export default function PlantUmlDiagram({ source, title, language, engine = 'pla
         [DATA_ATTR.theme]: dark ? 'dark' : 'light',
         ...(interactive ? { [DATA_ATTR.interactive]: 'true' } : {}),
         ...(zoom.maximized ? { [DATA_ATTR.maximized]: 'true' } : {}),
-        ...(sourceOpen ? { [DATA_ATTR.sourceOpen]: 'true' } : {}), children: [state.status === 'ready' && state.svg !== null && !interactive && canvas, state.status === 'ready' && state.svg !== null && !interactive && sourceView, state.status === 'ready' && state.svg !== null && !interactive && sourceAvailable && (_jsxs("div", { className: styles.plainToolbar, role: "group", "aria-label": `${label} source controls`, children: [sourceToggle, copyControl] })), state.status === 'ready' && state.svg !== null && interactive && (_jsxs("div", { ref: zoom.stageRef, className: zoom.maximized ? `${styles.stage} ${styles.maximized}` : styles.stage, children: [_jsxs("div", { className: styles.stageBody, children: [_jsx("div", { ref: zoom.viewportRef, className: sourceOpen ? `${styles.viewport} ${styles.invisibleView}` : styles.viewport, tabIndex: sourceOpen ? -1 : 0, "aria-describedby": hintId, "aria-keyshortcuts": "Plus Minus 0 ArrowUp ArrowDown ArrowLeft ArrowRight", onKeyDown: zoom.onKeyDown, [DATA_ATTR.zoom]: '1', children: _jsx("div", { ref: zoom.layerRef, className: styles.layer, children: canvas }) }), sourceView] }), _jsxs("div", { className: styles.toolbar, role: "group", "aria-label": `${label} zoom controls`, children: [!sourceOpen && (_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Zoom out", onClick: zoom.zoomOut, children: _jsx(ZoomOutIcon, {}) })), !sourceOpen && (_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Zoom in", onClick: zoom.zoomIn, children: _jsx(ZoomInIcon, {}) })), !sourceOpen && (_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Reset zoom", onClick: zoom.reset, children: _jsx(ResetZoomIcon, {}) })), _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Maximize diagram", "aria-pressed": zoom.maximized, onClick: zoom.toggleMaximize, children: zoom.maximized ? _jsx(CloseIcon, {}) : _jsx(MaximizeIcon, {}) }), sourceToggle, copyControl, _jsx("span", { ref: zoom.readoutRef, className: sourceOpen ? `${styles.readout} ${styles.hiddenView}` : styles.readout, "aria-hidden": "true", children: "100%" })] })] })), state.status === 'ready' && state.svg !== null && interactive && (_jsx("p", { id: hintId, className: styles.visuallyHidden, children: "Zoomable diagram. Use the zoom controls, or press plus and minus to zoom, the arrow keys to pan, and zero to reset." })), state.status !== 'ready' && state.status !== 'error' && (
+        ...(sourceOpen ? { [DATA_ATTR.sourceOpen]: 'true' } : {}),
+        ...(minimapOpen ? { [DATA_ATTR.minimapOpen]: 'true' } : {}),
+        ...(search.open ? { [DATA_ATTR.searchOpen]: 'true' } : {}), children: [state.status === 'ready' && state.svg !== null && !interactive && canvas, state.status === 'ready' && state.svg !== null && !interactive && sourceView, state.status === 'ready' && state.svg !== null && !interactive && sourceAvailable && (_jsxs("div", { className: styles.plainToolbar, role: "group", "aria-label": `${label} source controls`, children: [sourceToggle, copyControl] })), state.status === 'ready' && state.svg !== null && interactive && (_jsxs("div", { ref: zoom.stageRef, className: zoom.maximized ? `${styles.stage} ${styles.maximized}` : styles.stage, children: [_jsxs("div", { className: styles.stageBody, children: [_jsx("div", { ref: zoom.viewportRef, className: sourceOpen ? `${styles.viewport} ${styles.invisibleView}` : styles.viewport, tabIndex: sourceOpen ? -1 : 0, "aria-describedby": hintId, "aria-keyshortcuts": "Plus Minus 0 ArrowUp ArrowDown ArrowLeft ArrowRight", onKeyDown: zoom.onKeyDown, [DATA_ATTR.zoom]: '1', children: _jsx("div", { ref: zoom.layerRef, className: styles.layer, children: canvas }) }), sourceView] }), _jsxs("div", { className: styles.controls, children: [search.open && !sourceOpen && (_jsxs("div", { className: styles.searchBar, role: "search", "aria-label": `${label} search`, children: [_jsx("input", { ref: search.inputRef, type: "text", className: styles.searchInput, placeholder: "Search diagram", "aria-label": "Search diagram text", value: search.query, onChange: (event) => search.setQuery(event.target.value), onKeyDown: onSearchKeyDown }), _jsx("span", { className: styles.searchCount, role: "status", children: search.matchCount === 0
+                                            ? '0/0'
+                                            : `${search.currentIndex + 1}/${search.matchCount}` }), _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Previous match", onClick: search.previous, children: _jsx(ChevronUpIcon, {}) }), _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Next match", onClick: search.next, children: _jsx(ChevronDownIcon, {}) }), _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Close search", onClick: closeSearch, children: _jsx(CloseIcon, {}) })] })), _jsxs("div", { className: styles.toolbar, role: "group", "aria-label": `${label} zoom controls`, children: [!sourceOpen && (_jsx("button", { ref: searchToggleRef, type: "button", className: styles.toolbarButton, "aria-label": "Search diagram", "aria-expanded": search.open, onClick: search.toggle, children: _jsx(SearchIcon, {}) })), !sourceOpen && (_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Zoom out", onClick: zoom.zoomOut, children: _jsx(ZoomOutIcon, {}) })), !sourceOpen && (_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Zoom in", onClick: zoom.zoomIn, children: _jsx(ZoomInIcon, {}) })), !sourceOpen && (_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Reset zoom", onClick: zoom.reset, children: _jsx(ResetZoomIcon, {}) })), !sourceOpen && zoom.maximized && (_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Fit diagram to screen", onClick: zoom.fit, children: _jsx(FitIcon, {}) })), _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Maximize diagram", "aria-pressed": zoom.maximized, onClick: zoom.toggleMaximize, children: zoom.maximized ? _jsx(CloseIcon, {}) : _jsx(MaximizeIcon, {}) }), sourceToggle, copyControl, _jsx("span", { ref: zoom.readoutRef, className: sourceOpen ? `${styles.readout} ${styles.hiddenView}` : styles.readout, "aria-hidden": "true", children: "100%" })] })] }), !sourceOpen && minimapOpen && (_jsx(Minimap, { svg: state.svg, zoom: zoom, onClose: () => setMinimapOpen(false) })), !sourceOpen && (_jsx("div", { className: styles.minimapBar, children: _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": minimapOpen ? 'Hide minimap' : 'Show minimap', "aria-expanded": minimapOpen, onClick: () => setMinimapOpen((open) => !open), children: _jsx(MinimapIcon, {}) }) }))] })), state.status === 'ready' && state.svg !== null && interactive && (_jsx("p", { id: hintId, className: styles.visuallyHidden, children: "Zoomable diagram. Use the zoom controls, or press plus and minus to zoom, the arrow keys to pan, and zero to reset." })), state.status !== 'ready' && state.status !== 'error' && (
             // `aria-busy` on the figure already conveys progress; announcing every phase change
             // would make a page with several diagrams unusable with a screen reader.
             _jsxs("div", { className: styles.placeholder, children: [_jsx("span", { className: styles.spinner, "aria-hidden": "true" }), _jsxs("span", { children: [state.status === 'loading' ? `Loading ${engineName} runtime…` : null, state.status === 'rendering' ? `Rendering ${label}…` : null, state.status === 'idle' ? `${label} (waiting to render)` : null] })] })), state.status === 'error' && (_jsxs("div", { className: styles.error, role: "alert", children: [_jsxs("p", { className: styles.errorHeading, children: [_jsx("span", { className: styles.errorIcon, "aria-hidden": "true", children: "\u26A0" }), _jsxs("span", { children: ["Error: ", engineName, " diagram could not be rendered"] })] }), _jsx("pre", { className: styles.errorMessage, children: state.error }), config?.options.showSourceOnError !== false && (_jsxs("details", { className: styles.errorDetails, children: [_jsx("summary", { children: "Show diagram source" }), _jsx("pre", { className: styles.source, children: source })] }))] })), title !== undefined && _jsx("figcaption", { className: styles.caption, children: title }), _jsx("noscript", { dangerouslySetInnerHTML: {