@matfsw/docusaurus-plantuml-plugin 1.3.1 → 1.5.0

package/dist/theme/PlantUmlDiagram/styles.module.css

@@ -82,6 +82,20 @@
 }
 
 .layer {
+  /*
+   * Shrinks to the rendered picture instead of stretching across the viewport. The zoom
+   * hook measures content through `offsetWidth`/`offsetHeight` — layout sizes, immune to
+   * both the transform and its transition — so this is what makes those measurements mean
+   * "the diagram" rather than "the full-width frame". Fitting (which fills the screen when
+   * maximized) and the minimap both read that measurement.
+   *
+   * `max-width` is load-bearing, not decoration: in intrinsic (`fit-content`) sizing the
+   * SVG's own `max-width: 100%` resolves against an indefinite width and is ignored, so
+   * without this cap a diagram wider than the column would blow the layer out to the SVG's
+   * intrinsic width and overflow the frame.
+   */
+  width: fit-content;
+  max-width: 100%;
   transform-origin: 0 0;
   transition: transform var(--plantuml-zoom-transition, 150ms) ease-out;
 }
@@ -91,10 +105,31 @@
   transition: none;
 }
 
-.toolbar {
+/*
+ * One flex row holds the search bar and the toolbar, so opening the search never needs to
+ * know how wide the toolbar happens to be — it simply takes the space to its left.
+ */
+.controls {
   position: absolute;
   top: 0.5rem;
   right: 0.5rem;
+  display: flex;
+  gap: 0.5rem;
+  align-items: flex-start;
+}
+
+.toolbar {
+  display: flex;
+  gap: 0.25rem;
+  align-items: center;
+  padding: 0.25rem;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: var(--ifm-global-radius);
+  background: var(--ifm-background-surface-color);
+  opacity: 0.92;
+}
+
+.searchBar {
   display: flex;
   gap: 0.25rem;
   align-items: center;
@@ -105,6 +140,96 @@
   opacity: 0.92;
 }
 
+.searchInput {
+  width: 10rem;
+  max-width: 40vw;
+  height: 1.75rem;
+  padding: 0 0.5rem;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: var(--ifm-global-radius);
+  /* Not `--ifm-background-color`: Infima defines it as `#0000` in light mode. */
+  background: var(--ifm-background-surface-color);
+  color: var(--ifm-font-color-base);
+  font-size: 0.8125rem;
+}
+
+.searchInput:focus-visible {
+  outline: 2px solid var(--ifm-color-primary);
+  outline-offset: 1px;
+}
+
+.searchCount {
+  min-width: 2.25rem;
+  color: var(--ifm-color-emphasis-700);
+  font-size: 0.75rem;
+  font-variant-numeric: tabular-nums;
+  text-align: center;
+}
+
+/*
+ * Search highlights, keyed on the attributes the search hook sets. Attribute + CSS rather
+ * than mutating the SVG string: the string is shared through the render cache, and a
+ * highlight must never leak into another figure showing the same diagram.
+ *
+ * These rules sit after the Graphviz `currentColor` retargeting above and tie on
+ * specificity, so source order is what makes the highlight win there too.
+ */
+.layer .canvas svg text[data-plantuml-search-match] {
+  fill: var(--ifm-color-primary);
+}
+
+.layer .canvas svg text[data-plantuml-search-current] {
+  fill: var(--ifm-color-danger-dark);
+  text-decoration: underline;
+}
+
+/*
+ * The node a `#graph?highlight-node=…` deep link resolved to.
+ *
+ * The attribute may sit on a text line itself, or on the group/anchor wrapping a whole node
+ * (Graphviz `g.node`, a PlantUML self-anchor), so both spellings are styled. Scoped to
+ * `.figure` rather than `.layer`: a diagram that opted out of zoom still highlights, it
+ * just cannot pan.
+ *
+ * Placed after the Graphviz `currentColor` retargeting, whose specificity these tie —
+ * source order is what makes the highlight win there.
+ */
+.figure .canvas svg text[data-plantuml-focused-node],
+.figure .canvas svg [data-plantuml-focused-node] text {
+  /*
+   * The theme's success green, not danger red: this highlight persists until the hash
+   * changes, and a standing red reads as an error. Text stays *filled* with an accent
+   * rather than boxed in a light tint because SVG text has no background to tint — and
+   * the variable lets a site pick its own colour without fighting specificity.
+   */
+  fill: var(--plantuml-focus-color, var(--ifm-color-success));
+  text-decoration: underline;
+}
+
+/*
+ * Links inside the picture — Graphviz-native and the anchors synthesized from PlantUML
+ * `[[url]]` links the engine drops. The synthesized ones get the site's link colour so a
+ * linked node is discoverable; Graphviz authors colour their own (`fontcolor=`), so only
+ * the cursor and focus treatment apply there.
+ */
+.canvas svg a {
+  cursor: pointer;
+}
+
+.canvas svg a:focus-visible {
+  outline: 2px solid var(--ifm-color-primary);
+  outline-offset: 1px;
+}
+
+.canvas svg a[data-plantuml-diagram-link] text {
+  fill: var(--ifm-link-color);
+}
+
+.canvas svg a[data-plantuml-diagram-link]:hover text,
+.canvas svg a[data-plantuml-diagram-link]:focus-visible text {
+  text-decoration: underline;
+}
+
 .toolbarButton {
   display: flex;
   align-items: center;
@@ -169,6 +294,80 @@
   max-height: none;
 }
 
+/*
+ * Minimap.
+ *
+ * A small copy of the diagram, bottom-left where the toolbar is top-right, with a rectangle
+ * marking the visible part. The copy is laid out at the content's own width and scaled down
+ * as one block, so it keeps exactly the geometry of the real canvas and the rectangle's
+ * coordinates can be multiplied straight through.
+ */
+.minimapBar {
+  position: absolute;
+  bottom: 0.5rem;
+  left: 0.5rem;
+  display: flex;
+  padding: 0.25rem;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: var(--ifm-global-radius);
+  background: var(--ifm-background-surface-color);
+  opacity: 0.92;
+}
+
+.minimap {
+  position: absolute;
+  bottom: 3.25rem;
+  left: 0.5rem;
+  /*
+   * The close control sits *beside* the map, not floating over it: a wide, short diagram
+   * makes a map only a couple of buttons tall, and an overlaid control would cover — and
+   * steal presses from — the map's whole right end.
+   */
+  display: flex;
+  gap: 0.25rem;
+  align-items: flex-start;
+  max-width: calc(100% - 1rem);
+  padding: 0.25rem;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: var(--ifm-global-radius);
+  background: var(--ifm-background-surface-color);
+  opacity: 0.95;
+}
+
+.minimapCanvas {
+  position: relative;
+  max-width: 100%;
+  overflow: hidden;
+  cursor: crosshair;
+  /* The map pans the diagram; a drag on it must never scroll the page instead. */
+  touch-action: none;
+}
+
+.minimapLayer {
+  transform-origin: 0 0;
+  /* The map is one press-or-drag surface; its copy of the diagram must not eat the events. */
+  pointer-events: none;
+}
+
+.minimapLayer svg {
+  display: block;
+  max-width: 100%;
+  height: auto;
+}
+
+.minimapRect {
+  position: absolute;
+  border: 2px solid var(--ifm-color-primary);
+  background: color-mix(in srgb, var(--ifm-color-primary) 20%, transparent);
+  pointer-events: none;
+}
+
+.minimapClose {
+  flex: none;
+  width: 1.5rem;
+  height: 1.5rem;
+}
+
 .visuallyHidden {
   position: absolute;
   width: 1px;
@@ -182,7 +381,10 @@
 }
 
 @media (forced-colors: active) {
-  .toolbar {
+  .toolbar,
+  .searchBar,
+  .minimapBar,
+  .minimap {
     border-color: ButtonBorder;
   }
 
@@ -190,6 +392,12 @@
     border-color: ButtonBorder;
     color: ButtonText;
   }
+
+  /* `color-mix` resolves to nothing useful here; the outline alone must carry the meaning. */
+  .minimapRect {
+    border-color: Highlight;
+    background: transparent;
+  }
 }
 
 .placeholder {

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

@@ -0,0 +1,32 @@
+import { type MutableRefObject } from 'react';
+import type { ZoomPanHandle } from './useZoomPan.js';
+/**
+ * Makes one diagram react to `#graph?highlight-node=…` deep links.
+ *
+ * On a matching hash the target node is marked (`data-plantuml-focused-node`, styled from
+ * the stylesheet), the page scrolls to the first matching figure, and — when the diagram is
+ * zoomable — the view snaps to 100% centred on the node. A diagram without the node does
+ * nothing, which is what lets every diagram on the page react without any of them carrying
+ * an id.
+ *
+ * The hash comes from the router, not from a `hashchange` listener: Docusaurus `<Link>`
+ * navigations are `history.pushState` calls, which fire no `hashchange` — so a listener
+ * kept a stale hash whenever a link changed or dropped it while the page (and this
+ * component) stayed mounted, leaving the old node highlighted. `useLocation` re-renders on
+ * push, replace and pop alike, and native `#…` anchor clicks reach it too, via the
+ * `popstate` the browser fires for hash navigations.
+ *
+ * Highlighting is imperative for the same reason the search's is: the marked elements live
+ * in a `dangerouslySetInnerHTML` subtree React cannot render into.
+ */
+export interface UseDiagramDeeplinkParams {
+    /** Whether the diagram is rendered and its SVG is in the DOM. */
+    ready: boolean;
+    /** The rendered SVG string — a dependency, so a re-rendered picture is re-matched. */
+    svg: string | null;
+    /** Whether the diagram is zoomable; centring and the 100% snap need the viewport. */
+    interactive: boolean;
+    zoom: ZoomPanHandle;
+    containerRef: MutableRefObject<HTMLElement | null>;
+}
+export declare function useDiagramDeeplink({ ready, svg, interactive, zoom, containerRef, }: UseDiagramDeeplinkParams): void;

package/dist/theme/PlantUmlDiagram/useDiagramDeeplink.js

@@ -0,0 +1,54 @@
+import { useEffect } from 'react';
+import { useLocation } from '@docusaurus/router';
+import { DATA_ATTR } from '../../constants.js';
+import { claimDeeplinkScroll, findDeeplinkTarget, parseDiagramHash } from './deeplink.js';
+import { centerViewportOn } from './zoomMath.js';
+export function useDiagramDeeplink({ ready, svg, interactive, zoom, containerRef, }) {
+    const location = useLocation();
+    const target = parseDiagramHash(location.hash);
+    // One value per history entry. Undefined on entries the router did not create itself
+    // (native hash clicks, the initial load); those still differ in `target`, which the
+    // scroll claim includes.
+    const navigationKey = location.key ?? 'pop';
+    const pathname = location.pathname;
+    /**
+     * Marks, scrolls and centres. The cleanup unmarks, so a changed hash, a navigation that
+     * drops the hash and an unmounting diagram all sweep up through the same code path; a
+     * replaced SVG re-runs the effect (via `svg`) against the new elements.
+     *
+     * `navigationKey` is a dependency on purpose: following the same deep link again is a new
+     * history entry with an unchanged `target`, and it should scroll and re-centre again.
+     */
+    useEffect(() => {
+        if (!ready || target === null)
+            return undefined;
+        const figure = containerRef.current;
+        const canvas = figure?.querySelector('[role="img"]');
+        if (!figure || !canvas)
+            return undefined;
+        const match = findDeeplinkTarget(canvas, target);
+        if (!match)
+            return undefined;
+        for (const element of match.elements) {
+            element.setAttribute(DATA_ATTR.focusedNode, 'true');
+        }
+        claimDeeplinkScroll(`${navigationKey}|${pathname}|${target}`, figure);
+        if (interactive) {
+            const layer = zoom.layerRef.current;
+            if (layer) {
+                // The node's offset inside the layer, divided back by the current scale, is its
+                // position in content coordinates whatever the zoom was; the view then snaps to
+                // 100% centred there — the zoom level a deep link promises.
+                const transform = zoom.getTransform();
+                const layerBox = layer.getBoundingClientRect();
+                const box = match.anchor.getBoundingClientRect();
+                zoom.applyTransform(centerViewportOn({ k: 1, x: 0, y: 0 }, (box.left + box.width / 2 - layerBox.left) / transform.k, (box.top + box.height / 2 - layerBox.top) / transform.k, zoom.measure()));
+            }
+        }
+        return () => {
+            for (const element of match.elements) {
+                element.removeAttribute(DATA_ATTR.focusedNode);
+            }
+        };
+    }, [containerRef, interactive, navigationKey, pathname, ready, svg, target, zoom]);
+}

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

@@ -0,0 +1,29 @@
+import { type MutableRefObject } from 'react';
+import type { DiagramEngine } from '../../runtime/types.js';
+/**
+ * Author-written links inside one diagram: synthesis and navigation.
+ *
+ * **Synthesis** (PlantUML only): the bundled engine drops `[[url]]` links, so they are
+ * rebuilt from the fence source and attached to the rendered elements — see
+ * `diagramLinks.ts` for the correlation. Graphviz needs none of this; `URL=` already emits
+ * real anchors.
+ *
+ * **Navigation** (both engines): a click on any in-diagram link to a same-site URL goes
+ * through the router instead of a full page load, so a node can link to a diagram on
+ * another page and arrive instantly — with the target page's diagrams reacting to the
+ * hash through the same router-driven deep-link tracking. Site-absolute paths get the
+ * site's `baseUrl`, exactly as markdown links do, so authors write the same `/docs/…`
+ * everywhere. External links and pure `#…` anchors stay native: the browser handles both
+ * correctly on its own, and the router observes hash navigations anyway.
+ */
+export interface UseDiagramLinksParams {
+    /** Whether the diagram is rendered and its SVG is in the DOM. */
+    ready: boolean;
+    /** The rendered SVG string — a dependency, so a re-rendered picture is re-linked. */
+    svg: string | null;
+    engine: DiagramEngine;
+    /** The fence source, exactly as authored — where the links are read from. */
+    source: string;
+    containerRef: MutableRefObject<HTMLElement | null>;
+}
+export declare function useDiagramLinks({ ready, svg, engine, source, containerRef, }: UseDiagramLinksParams): void;

package/dist/theme/PlantUmlDiagram/useDiagramLinks.js

@@ -0,0 +1,62 @@
+import { useEffect } from 'react';
+import { useHistory } from '@docusaurus/router';
+import { useBaseUrlUtils } from '@docusaurus/useBaseUrl';
+import { attachDiagramLinks, detachDiagramLinks, extractSourceLinks } from './diagramLinks.js';
+export function useDiagramLinks({ ready, svg, engine, source, containerRef, }) {
+    const history = useHistory();
+    const { withBaseUrl } = useBaseUrlUtils();
+    // Synthesis. The cleanup unwraps, so a re-rendered or unmounting diagram never leaks
+    // anchors; a replaced SVG re-runs the effect (via `svg`) against the new elements.
+    useEffect(() => {
+        if (!ready || engine !== 'plantuml')
+            return undefined;
+        const canvas = containerRef.current?.querySelector('[role="img"]');
+        if (!canvas)
+            return undefined;
+        const links = extractSourceLinks(source);
+        if (links.length === 0)
+            return undefined;
+        attachDiagramLinks(canvas, links);
+        return () => detachDiagramLinks(canvas);
+    }, [containerRef, engine, ready, source, svg]);
+    // Navigation. One listener on the figure covers synthesized and engine-native anchors
+    // alike. Bubble phase on purpose: the zoom hook suppresses post-drag clicks in the
+    // capture phase, and a suppressed click must not navigate.
+    useEffect(() => {
+        if (!ready)
+            return undefined;
+        const figure = containerRef.current;
+        if (!figure)
+            return undefined;
+        const onClick = (event) => {
+            // Modified clicks are the reader asking the browser for its own behaviour
+            // (new tab, download); never take those over.
+            if (event.defaultPrevented || event.button !== 0)
+                return;
+            if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+                return;
+            const target = event.target instanceof Element ? event.target : null;
+            const anchor = target?.closest('a');
+            if (!anchor || !figure.querySelector('[role="img"]')?.contains(anchor))
+                return;
+            const href = anchor.getAttribute('href') ?? anchor.getAttribute('xlink:href');
+            // Hash-only anchors navigate natively; the router sees hash navigations by itself.
+            if (!href || href.startsWith('#'))
+                return;
+            const resolved = href.startsWith('/') ? withBaseUrl(href) : href;
+            let url;
+            try {
+                url = new URL(resolved, window.location.href);
+            }
+            catch {
+                return;
+            }
+            if (url.origin !== window.location.origin)
+                return;
+            event.preventDefault();
+            history.push(url.pathname + url.search + url.hash);
+        };
+        figure.addEventListener('click', onClick);
+        return () => figure.removeEventListener('click', onClick);
+    }, [containerRef, history, ready, withBaseUrl]);
+}

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

@@ -0,0 +1,37 @@
+import { type MutableRefObject } from 'react';
+import type { ZoomPanHandle } from './useZoomPan.js';
+/**
+ * Text search over one rendered diagram.
+ *
+ * The search runs against the *rendered SVG's* `<text>` elements rather than the diagram
+ * source: what the reader sees is what they are searching, and a match can be highlighted and
+ * panned to because it is a real element with a position. Matches are marked with data
+ * attributes and coloured from the stylesheet, so the SVG string itself — which the cache
+ * shares between diagrams — is never mutated.
+ *
+ * Highlighting is imperative for the same reason the zoom transform is: the elements live in
+ * a `dangerouslySetInnerHTML` subtree that React cannot render into. React state carries only
+ * what drives markup — the query, the match count and the current position.
+ */
+export interface DiagramSearchHandle {
+    /** Whether the search bar is shown. */
+    open: boolean;
+    query: string;
+    /** Number of `<text>` elements matching the query; 0 when the query is empty. */
+    matchCount: number;
+    /** Zero-based position of the current match, or -1 when there is none. */
+    currentIndex: number;
+    inputRef: MutableRefObject<HTMLInputElement | null>;
+    toggle: () => void;
+    close: () => void;
+    setQuery: (value: string) => void;
+    next: () => void;
+    previous: () => void;
+}
+export interface UseDiagramSearchParams {
+    enabled: boolean;
+    zoom: ZoomPanHandle;
+    /** The rendered SVG string — a dependency, so a re-rendered picture is re-searched. */
+    svg: string | null;
+}
+export declare function useDiagramSearch({ enabled, zoom, svg, }: UseDiagramSearchParams): DiagramSearchHandle;

package/dist/theme/PlantUmlDiagram/useDiagramSearch.js

@@ -0,0 +1,107 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { DATA_ATTR } from '../../constants.js';
+import { centerViewportOn } from './zoomMath.js';
+export function useDiagramSearch({ enabled, zoom, svg, }) {
+    const [open, setOpen] = useState(false);
+    const [query, setQuery] = useState('');
+    const [matchCount, setMatchCount] = useState(0);
+    const [currentIndex, setCurrentIndex] = useState(-1);
+    const matchesRef = useRef([]);
+    const inputRef = useRef(null);
+    const toggle = useCallback(() => setOpen((value) => !value), []);
+    const close = useCallback(() => setOpen(false), []);
+    const next = useCallback(() => {
+        setCurrentIndex((index) => {
+            const total = matchesRef.current.length;
+            return total === 0 ? -1 : (index + 1) % total;
+        });
+    }, []);
+    const previous = useCallback(() => {
+        setCurrentIndex((index) => {
+            const total = matchesRef.current.length;
+            return total === 0 ? -1 : (index - 1 + total) % total;
+        });
+    }, []);
+    // Typing should not require a second click after pressing the toggle.
+    useEffect(() => {
+        if (open)
+            inputRef.current?.focus();
+    }, [open]);
+    // A diagram that lost its zoom lost the viewport the search pans; the bar goes with it.
+    useEffect(() => {
+        if (!enabled)
+            setOpen(false);
+    }, [enabled]);
+    /**
+     * Finds and marks the matches. The effect's cleanup unmarks them, so closing the bar,
+     * changing the query and unmounting all sweep up through the same code path. A replaced
+     * SVG needs no sweeping — its marked elements left the document with it — but re-runs the
+     * effect (via `svg`) so the new elements are searched.
+     */
+    useEffect(() => {
+        if (!enabled || !open)
+            return undefined;
+        const layer = zoom.layerRef.current;
+        const needle = query.trim().toLowerCase();
+        if (!layer || needle === '') {
+            matchesRef.current = [];
+            setMatchCount(0);
+            setCurrentIndex(-1);
+            return undefined;
+        }
+        // `<text>` elements, not their tspans: a PlantUML label is one text element, and marking
+        // the whole label keeps the highlight readable instead of colouring a fragment.
+        const matches = Array.from(layer.querySelectorAll('svg text')).filter((element) => (element.textContent ?? '').toLowerCase().includes(needle));
+        matchesRef.current = matches;
+        for (const match of matches)
+            match.setAttribute(DATA_ATTR.searchMatch, 'true');
+        setMatchCount(matches.length);
+        // Every new query starts at its first match, exactly like the browser's own find bar.
+        setCurrentIndex(matches.length > 0 ? 0 : -1);
+        return () => {
+            matchesRef.current = [];
+            for (const match of matches)
+                match.removeAttribute(DATA_ATTR.searchMatch);
+        };
+    }, [enabled, open, query, svg, zoom]);
+    /**
+     * Marks the current match and centres the viewport on it.
+     *
+     * Declared after the match effect on purpose: effects run in order, so by the time this
+     * one reads `matchesRef` the list belongs to the current query. `query` and `svg` are
+     * dependencies because a new list can leave the index at 0 — unchanged — while element 0
+     * is a different match.
+     */
+    useEffect(() => {
+        if (!enabled || !open)
+            return undefined;
+        const target = currentIndex >= 0 ? matchesRef.current[currentIndex] : undefined;
+        if (!target)
+            return undefined;
+        target.setAttribute(DATA_ATTR.searchCurrent, 'true');
+        const layer = zoom.layerRef.current;
+        if (layer) {
+            // The match's offset inside the layer, both measured in the same transformed space,
+            // divided back by the scale — which yields content coordinates whatever the zoom is.
+            const transform = zoom.getTransform();
+            const layerBox = layer.getBoundingClientRect();
+            const box = target.getBoundingClientRect();
+            zoom.applyTransform(centerViewportOn(transform, (box.left + box.width / 2 - layerBox.left) / transform.k, (box.top + box.height / 2 - layerBox.top) / transform.k, zoom.measure()));
+        }
+        return () => target.removeAttribute(DATA_ATTR.searchCurrent);
+    }, [currentIndex, enabled, open, query, svg, zoom]);
+    // Stable per set of values, like the zoom handle: consumers may hang callbacks and
+    // effects off the handle, and those must not churn on unrelated re-renders.
+    return useMemo(() => ({
+        open,
+        query,
+        matchCount,
+        currentIndex,
+        inputRef,
+        toggle,
+        close,
+        setQuery,
+        next,
+        previous,
+    }), [open, query, matchCount, currentIndex, toggle, close, next, previous]);
+}

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

@@ -1,5 +1,5 @@
 import { type KeyboardEvent as ReactKeyboardEvent, type MutableRefObject } from 'react';
-import { MAX_SCALE, MIN_SCALE } from './zoomMath.js';
+import { MAX_SCALE, MIN_SCALE, type Bounds, type Transform } from './zoomMath.js';
 export interface ZoomPanHandle {
     viewportRef: MutableRefObject<HTMLDivElement | null>;
     layerRef: MutableRefObject<HTMLDivElement | null>;
@@ -8,10 +8,26 @@ export interface ZoomPanHandle {
     zoomIn: () => void;
     zoomOut: () => void;
     reset: () => void;
+    /** Fits the whole diagram inside the viewport, at whatever scale that takes to fill it. */
+    fit: () => void;
     toggleMaximize: () => void;
     onKeyDown: (event: ReactKeyboardEvent<HTMLDivElement>) => void;
     /** Whether the diagram currently fills the browser viewport. */
     maximized: boolean;
+    /** Reads the live transform without subscribing to it. */
+    getTransform: () => Transform;
+    /** Applies a transform through the same clamp as every gesture. */
+    applyTransform: (next: Transform) => void;
+    /** Layout sizes of the viewport and content — the bounds the clamp runs against. */
+    measure: () => Bounds;
+    /**
+     * Calls the listener after every committed transform write; returns the unsubscribe.
+     *
+     * This is how the minimap tracks the view: the transform is written straight to the DOM on
+     * every pan frame, so anything that mirrored it through React state would re-render the
+     * component once per frame.
+     */
+    subscribe: (listener: (transform: Transform) => void) => () => void;
 }
 export interface UseZoomPanParams {
     enabled: boolean;