@matfsw/docusaurus-plantuml-plugin 0.1.0 → 1.0.1

package/CHANGELOG.md

@@ -7,6 +7,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.1]
+
+### Fixed
+
+- Maximizing a diagram no longer uses the Fullscreen API. It took the whole browser window
+  fullscreen in Firefox instead of presenting the diagram, and the `::backdrop` sits outside
+  the fullscreened element, so the page showed through behind a diagram with a transparent
+  background. The diagram now expands into an opaque in-page overlay that fills the browser
+  viewport, closed with the same button or <kbd>Escape</kbd>.
+- The maximize control is now available in every browser. It previously required
+  `Element.requestFullscreen()` and was hidden where that is missing, notably iOS Safari.
+
+### Added
+
+- `data-plantuml-maximized` on the figure while a diagram fills the viewport.
+
+### Changed
+
+- The fourth toolbar button is labelled `Maximize diagram` (was `Toggle fullscreen`) and
+  exposes `aria-pressed`. End-to-end tests selecting it by its accessible name need updating.
+
+## [1.0.0]
+
+First stable release. The public surface — plugin options, fence metadata flags, the `data-*`
+attributes and the shape of the rendered markup — is now covered by semantic versioning.
+
+### Added
+
+- Zoom and pan for rendered diagrams: Ctrl + wheel (and trackpad pinch) zooms about the
+  pointer, dragging pans, and a `role="group"` control toolbar offers zoom out, zoom in, reset
+  and — where the browser supports it — fullscreen.
+- Keyboard operation on a focusable viewport: `+`/`=`, `-`/`_`, `0`, arrow keys, and
+  Shift + arrows to pan by most of the viewport. Modified keys are left to the browser, and
+  `Tab` always escapes.
+- `zoom` plugin option (default `true`) and a per-fence `zoom` / `zoom=false` metastring flag
+  that overrides it for a single diagram.
+- `data-plantuml-interactive` on the figure and `data-plantuml-zoom` on the viewport.
+- `parseBooleanMeta()` for reading boolean flags from a fence metastring.
+
+### Changed
+
+- **Breaking: the rendered markup changed for zoomable diagrams.** With `zoom` enabled — the
+  default — the `role="img"` container is wrapped by a viewport and a transform layer, and a
+  control group is added beside it. Site CSS that targeted
+  `[data-plantuml-diagram] > div[role="img"]` as a **direct child** must be updated;
+  `div[role="img"] > svg` still holds. Setting `zoom: false` restores the `0.1.0` markup
+  exactly.
+- **Breaking: zoomable diagrams add keyboard tab stops.** A zoomable diagram contributes about
+  four (the viewport and its buttons).
+- Plain scrolling over a diagram is unaffected: only Ctrl + wheel zooms, and on touchscreens
+  one finger still scrolls the page and two-finger pinch is still the browser's own page zoom.
+
+### Fixed
+
+- `configureWebpack` no longer throws on Docusaurus `3.5.x`, where `currentBundler` does not
+  exist. That release line is now covered by the CI compatibility matrix.
+
 ## [0.1.0]
 
 Initial release.
@@ -29,5 +86,7 @@ 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/v0.1.0...HEAD
+[Unreleased]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.0.1...HEAD
+[1.0.1]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v0.1.0...v1.0.0
 [0.1.0]: https://github.com/matf/docusaurus-plantuml-plugin/releases/tag/v0.1.0

package/README.md

@@ -3,6 +3,9 @@
 Render PlantUML diagrams in Docusaurus 3 entirely in the browser — no Java, no PlantUML
 server, no Kroki, no CDN.
 
+**→ [Live demo](https://matf.github.io/docusaurus-plantuml-demo)** — every diagram on that site
+is rendered by your own browser.
+
 Write a `plantuml` fence in any `.md` or `.mdx` file and the code block is replaced, in the
 reader's browser, with an SVG rendered by the official [`@plantuml/core`][plantuml-core]
 package:
@@ -28,9 +31,13 @@ the engine itself is served from your own site's `baseUrl`.
 
 ## Status and compatibility
 
-Status: **beta**. The public surface (plugin options, `data-*` attributes, fence syntax) is
-stable enough to build on, but this is a `0.x` release and breaking changes will happen in
-minor versions until `1.0.0`.
+Status: **stable**. `1.0.0` fixes the public surface — plugin options, fence metadata flags,
+the `data-*` attributes, and the shape of the rendered markup. Breaking changes to any of them
+require a major version.
+
+Explicitly **not** covered by that promise: the generated CSS-module class names, the exact SVG
+`@plantuml/core` produces, and the renderer, queue and cache internals — which is why none of
+them are exported.
 
 | Requirement     | Supported                                                                              |
 | --------------- | -------------------------------------------------------------------------------------- |
@@ -204,6 +211,7 @@ props untouched. Existing code-block behaviour (highlighting, line numbers, titl
 | `showSourceOnError` | `boolean`                         | `true`                 | Include the diagram source in a `<details>` block on the error panel.                                                      |
 | `renderTimeoutMs`   | `number`                          | `20000`                | Abort a single render (and the runtime load) after this many milliseconds. Integer, `100`–`600000`.                        |
 | `cacheMaxEntries`   | `number`                          | `50`                   | Upper bound on cached SVG entries. Positive integer.                                                                       |
+| `zoom`              | `boolean`                         | `true`                 | Let readers zoom and pan diagrams. Adds a control toolbar and a focusable viewport. Override per fence with `zoom=false`.  |
 | `id`                | `string`                          | `'default'`            | Docusaurus plugin instance id; only relevant if you register the plugin more than once.                                    |
 
 Options are validated during the Docusaurus configuration phase, before anything is built.
@@ -213,7 +221,7 @@ would otherwise silently disable the option you meant to set:
 ```text
 [docusaurus-plugin-plantuml-client] Unknown option 'sanitiseSvg'. Supported options:
 'languages', 'theme', 'lazy', 'cache', 'sanitizeSvg', 'showSourceOnError',
-'renderTimeoutMs', 'cacheMaxEntries'.
+'renderTimeoutMs', 'cacheMaxEntries', 'zoom'.
 ```
 
 `PlantUmlPluginOptions`, `ResolvedPlantUmlOptions`, `CacheMode`, `DiagramTheme`,
@@ -235,6 +243,88 @@ theme.
 
 The current mode is exposed on the wrapper as `data-plantuml-theme="light|dark"`.
 
+## Zoom and pan
+
+Large diagrams are unreadable at column width. Rendered diagrams are therefore zoomable and
+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   |
+
+`Cmd` + wheel is deliberately **not** intercepted: on macOS that is the browser's own page
+zoom, and taking it over would fight the platform.
+
+### Keyboard
+
+The diagram viewport is focusable. Once focused:
+
+| Key                | Action                      |
+| ------------------ | --------------------------- |
+| `+` or `=`         | Zoom in                     |
+| `-` or `_`         | Zoom out                    |
+| `0`                | Reset to 100%               |
+| Arrow keys         | Pan                         |
+| Shift + arrow keys | Pan by most of the viewport |
+
+Keys with Ctrl, Cmd or Alt held are left to the browser, so shortcuts such as Ctrl + 0 keep
+working, and `Tab` always moves on — the diagram is never a keyboard trap.
+
+Scale is limited to 0.25×–8×, and the view resets to 100% whenever the diagram source or the
+site colour mode changes.
+
+### 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.
+
+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
+`::backdrop` sits outside the element so the page shows through behind the diagram. An overlay
+has neither problem, behaves identically in every browser, and needs no capability detection —
+so the control also works on iOS Safari, which has no element fullscreen at all.
+
+### Turning it off
+
+Globally:
+
+```ts
+['@matfsw/docusaurus-plantuml-plugin', {zoom: false}];
+```
+
+Or for a single fence, which overrides the option either way:
+
+````markdown
+```plantuml title="Small diagram" zoom=false
+@startuml
+Alice -> Bob : Hello
+@enduml
+```
+````
+
+### Why it is on by default, and what that costs
+
+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.
+- 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.
+- Each diagram costs one non-passive `wheel` listener and one `ResizeObserver`, and only in the
+  `ready` state.
+
+Setting `zoom: false` restores the previous markup exactly.
+
 ## Lazy loading
 
 With `lazy: true` (the default), a diagram is not rendered until it scrolls within 300 px of
@@ -278,7 +368,7 @@ in-memory cache for the rest of the session. A storage failure never breaks rend
 
 ## Accessibility
 
-Each diagram renders as:
+With `zoom: false`, a diagram renders as:
 
 ```html
 <figure
@@ -293,6 +383,32 @@ Each diagram renders as:
 </figure>
 ```
 
+With zoom enabled (the default), the same `role="img"` element is wrapped by a viewport and a
+transform layer, and a control group is added beside it:
+
+```html
+<figure
+  data-plantuml-diagram="plantuml"
+  data-plantuml-status="ready"
+  data-plantuml-theme="light"
+  data-plantuml-interactive="true"
+>
+  <div class="stage">
+    <div class="viewport" tabindex="0" aria-describedby="…" data-plantuml-zoom="1">
+      <div class="layer">
+        <div role="img" aria-label="Authentication sequence"><svg>…</svg></div>
+      </div>
+    </div>
+    <div role="group" aria-label="Authentication sequence zoom controls">…buttons…</div>
+  </div>
+  <p class="visuallyHidden" id="…">Zoomable diagram. Use the zoom controls, …</p>
+  <figcaption>Authentication sequence</figcaption>
+  <noscript><pre>@startuml …</pre></noscript>
+</figure>
+```
+
+`div[role="img"] > svg` holds in both shapes, so a selector written against it keeps working.
+
 - The fence `title="..."` becomes the `<figcaption>` and the `aria-label`. Without a title,
   the accessible label falls back to **`PlantUML diagram`**.
 - Progress is conveyed with `aria-busy` on the `<figure>`, deliberately **not** with an
@@ -303,18 +419,31 @@ Each diagram renders as:
   a ⚠ glyph in addition to the danger colouring, so it survives colour-blindness and
   forced-colours mode.
 - Readers without JavaScript get the diagram source in a `<noscript>` block.
-- The spinner animation is disabled under `prefers-reduced-motion: reduce`.
+- The spinner animation is disabled under `prefers-reduced-motion: reduce`, as is the easing of
+  discrete zoom steps. Dragging and wheel zooming stay instantaneous either way, because direct
+  manipulation is not decoration.
+- Zoom controls live **outside** the `role="img"` element. That role makes its whole subtree
+  opaque to assistive technology, so a button placed inside would be invisible to screen-reader
+  users.
+- The control group is `role="group"`, not `role="toolbar"`: the toolbar role obliges arrow-key
+  navigation between its buttons, and the arrow keys already pan the diagram.
+- Button labels are static and the zoom percentage is `aria-hidden`. A live percentage would
+  announce on every wheel tick.
+- Keyboard instructions are attached to the viewport with `aria-describedby` rather than being
+  announced on focus repeatedly.
 
 ### `data-*` contract
 
 These attributes are part of the public surface; write your own end-to-end tests against
 them.
 
-| Attribute               | Values                                                     |
-| ----------------------- | ---------------------------------------------------------- |
-| `data-plantuml-diagram` | the fence language that matched, e.g. `plantuml` or `puml` |
-| `data-plantuml-status`  | `idle` \| `loading` \| `rendering` \| `ready` \| `error`   |
-| `data-plantuml-theme`   | `light` \| `dark`                                          |
+| Attribute                   | Values                                                     |
+| --------------------------- | ---------------------------------------------------------- |
+| `data-plantuml-diagram`     | the fence language that matched, e.g. `plantuml` or `puml` |
+| `data-plantuml-status`      | `idle` \| `loading` \| `rendering` \| `ready` \| `error`   |
+| `data-plantuml-theme`       | `light` \| `dark`                                          |
+| `data-plantuml-interactive` | `true`, on the `<figure>`, only when zoom is enabled       |
+| `data-plantuml-zoom`        | current scale on the viewport, e.g. `1`, `2.5`             |
 
 ## SVG sanitization and security model
 
@@ -408,6 +537,9 @@ The runtime requires:
 - `MutationObserver`
 - `IntersectionObserver` — optional; a graceful fallback renders immediately when it is absent
 - `sessionStorage` — optional; only for `cache: 'session'`, which degrades to memory without it
+- Pointer Events — required for drag-to-pan when `zoom` is enabled
+- `ResizeObserver` — optional; without it zoom still works, but the view is not re-clamped when
+  the column is resized
 
 That is modern evergreen Chrome, Edge, Firefox and Safari. Internet Explorer is not
 supported and will not be.
@@ -525,7 +657,10 @@ Four layers, all deterministic and none of them calling an external PlantUML ser
    retry, FIFO queue ordering, queue continuation after failure, timeouts, unmount during
    render, light/dark cache separation, memory cache eviction, `sessionStorage` failure and
    corruption handling, SVG sanitization against synthetic malicious input, the loading/ready/
-   error UI, SSR without browser globals, and the `IntersectionObserver` fallback.
+   error UI, SSR without browser globals, the `IntersectionObserver` fallback, and the zoom
+   layer: focal-point and clamping geometry as pure functions, the wheel policy (plain wheel
+   ignored, Ctrl honoured, Cmd ignored), keyboard handling, both reset triggers, and listener
+   teardown.
    Docusaurus `@theme/*` and `@docusaurus/*` aliases only exist inside a real Docusaurus
    webpack build, so the Vitest config points them at local stubs.
 2. **Package verification** (`npm run pack:check`). Runs `npm pack --dry-run --json`, prints
@@ -537,7 +672,11 @@ Four layers, all deterministic and none of them calling an external PlantUML ser
    fixture in a temporary directory, runs a full `docusaurus build`, and serves it. This is
    what proves the package works as consumers actually install it.
 4. **Browser end-to-end** (`npm run test:e2e`, Playwright against the served production
-   build). Asserts that real `<svg>` elements appear inside the expected container with the
+   build). Asserts that zooming magnifies the diagram without changing the figure's height,
+   that a plain wheel scrolls the page while Ctrl + wheel zooms without scrolling, that the
+   focal point stays under the cursor, that panning is clamped so an edge never comes inside
+   the viewport, and that `touch-action` stays `pan-y pinch-zoom`. It also asserts that real
+   `<svg>` elements appear inside the expected container with the
    expected diagram labels, that multiple diagrams render on one page, that `.md` and `.mdx`
    both work, that ordinary code blocks are untouched, that an invalid diagram produces the
    documented error state, that toggling dark mode re-renders, that client-side navigation
@@ -639,6 +778,12 @@ package.
   8 MB download is subject to the same budget as a render.
 - **Consuming the plugin through a `file:` link needs a webpack tweak.** See the entry in
   Troubleshooting below.
+- **No pinch-to-zoom of the diagram itself on touchscreens.** Two-finger pinch is deliberately
+  left to the browser's own page zoom, so a full-width diagram can never become a scroll trap
+  and page zoom is never taken away. Trackpad pinch on a laptop does zoom the diagram, because
+  the browser reports it as Ctrl + wheel.
+- **Zoom state is not persisted.** Navigating away and back, or switching colour mode, returns
+  the diagram to 100%.
 
 ## Troubleshooting
 

package/dist/constants.d.ts

@@ -19,4 +19,13 @@ export declare const DATA_ATTR: {
     readonly diagram: "data-plantuml-diagram";
     readonly status: "data-plantuml-status";
     readonly theme: "data-plantuml-theme";
+    /** `"true"` on the figure when the diagram is zoomable. */
+    readonly interactive: "data-plantuml-interactive";
+    /**
+     * Current scale, on the viewport rather than the figure. Keeping it off the figure means
+     * the imperative zoom writes can never race React's attribute diffing.
+     */
+    readonly zoom: "data-plantuml-zoom";
+    /** `"true"` on the figure while the diagram fills the browser viewport. */
+    readonly maximized: "data-plantuml-maximized";
 };

package/dist/constants.js

@@ -21,4 +21,13 @@ export const DATA_ATTR = {
     diagram: 'data-plantuml-diagram',
     status: 'data-plantuml-status',
     theme: 'data-plantuml-theme',
+    /** `"true"` on the figure when the diagram is zoomable. */
+    interactive: 'data-plantuml-interactive',
+    /**
+     * Current scale, on the viewport rather than the figure. Keeping it off the figure means
+     * the imperative zoom writes can never race React's attribute diffing.
+     */
+    zoom: 'data-plantuml-zoom',
+    /** `"true"` on the figure while the diagram fills the browser viewport. */
+    maximized: 'data-plantuml-maximized',
 };

package/dist/index.cjs

@@ -99,7 +99,8 @@ var DEFAULT_OPTIONS = {
   sanitizeSvg: true,
   showSourceOnError: true,
   renderTimeoutMs: 2e4,
-  cacheMaxEntries: 50
+  cacheMaxEntries: 50,
+  zoom: true
 };
 var CACHE_MODES = ["none", "memory", "session"];
 var THEMES = ["auto", "light", "dark"];
@@ -187,6 +188,7 @@ function resolveOptions(rawOptions) {
     "showSourceOnError",
     "renderTimeoutMs",
     "cacheMaxEntries",
+    "zoom",
     // Docusaurus injects `id` for multi-instance plugins.
     "id"
   ]);
@@ -221,7 +223,8 @@ function resolveOptions(rawOptions) {
       DEFAULT_OPTIONS.showSourceOnError
     ),
     renderTimeoutMs: validateRenderTimeout(rawOptions.renderTimeoutMs),
-    cacheMaxEntries: validateCacheMaxEntries(rawOptions.cacheMaxEntries)
+    cacheMaxEntries: validateCacheMaxEntries(rawOptions.cacheMaxEntries),
+    zoom: validateBoolean(rawOptions.zoom, "zoom", DEFAULT_OPTIONS.zoom)
   };
 }
 

package/dist/index.d.cts

@@ -27,6 +27,11 @@ interface PlantUmlPluginOptions {
     renderTimeoutMs?: number;
     /** Maximum number of cached SVG entries kept per browsing session. */
     cacheMaxEntries?: number;
+    /**
+     * Let readers zoom and pan rendered diagrams, with a small control toolbar.
+     * Override for a single fence with `zoom` or `zoom=false` in its metastring.
+     */
+    zoom?: boolean;
     /** Docusaurus plugin instance id, used when the plugin is registered more than once. */
     id?: string;
 }

package/dist/options.d.ts

@@ -24,6 +24,11 @@ export interface PlantUmlPluginOptions {
     renderTimeoutMs?: number;
     /** Maximum number of cached SVG entries kept per browsing session. */
     cacheMaxEntries?: number;
+    /**
+     * Let readers zoom and pan rendered diagrams, with a small control toolbar.
+     * Override for a single fence with `zoom` or `zoom=false` in its metastring.
+     */
+    zoom?: boolean;
     /** Docusaurus plugin instance id, used when the plugin is registered more than once. */
     id?: string;
 }

package/dist/options.js

@@ -8,6 +8,7 @@ export const DEFAULT_OPTIONS = {
     showSourceOnError: true,
     renderTimeoutMs: 20_000,
     cacheMaxEntries: 50,
+    zoom: true,
 };
 const CACHE_MODES = ['none', 'memory', 'session'];
 const THEMES = ['auto', 'light', 'dark'];
@@ -103,6 +104,7 @@ export function resolveOptions(rawOptions) {
         'showSourceOnError',
         'renderTimeoutMs',
         'cacheMaxEntries',
+        'zoom',
         // Docusaurus injects `id` for multi-instance plugins.
         'id',
     ]);
@@ -127,5 +129,6 @@ export function resolveOptions(rawOptions) {
         showSourceOnError: validateBoolean(rawOptions.showSourceOnError, 'showSourceOnError', DEFAULT_OPTIONS.showSourceOnError),
         renderTimeoutMs: validateRenderTimeout(rawOptions.renderTimeoutMs),
         cacheMaxEntries: validateCacheMaxEntries(rawOptions.cacheMaxEntries),
+        zoom: validateBoolean(rawOptions.zoom, 'zoom', DEFAULT_OPTIONS.zoom),
     };
 }

package/dist/theme/MDXComponents/Code/index.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import OriginalCode from '@theme-init/MDXComponents/Code';
 import PlantUmlDiagram from '@theme/PlantUmlDiagram';
-import { extractLanguage, extractSource, parseTitle, } from '../../codeBlockMeta.js';
+import { extractLanguage, extractSource, parseBooleanMeta, parseTitle, } from '../../codeBlockMeta.js';
 import { usePlantUmlConfig } from '../../usePlantUmlConfig.js';
 /**
  * Wraps Docusaurus' `MDXComponents/Code` extension point.
@@ -24,5 +24,5 @@ export default function Code(props) {
     if (!isPlantUml || source === null) {
         return _jsx(OriginalCode, { ...props });
     }
-    return _jsx(PlantUmlDiagram, { source: source, title: parseTitle(props), language: language });
+    return (_jsx(PlantUmlDiagram, { source: source, title: parseTitle(props), language: language, zoom: parseBooleanMeta(props, 'zoom') }));
 }

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

@@ -6,6 +6,11 @@ export interface PlantUmlDiagramProps {
     title?: string;
     /** The fence language that matched, e.g. `plantuml` or `puml`. */
     language?: string;
+    /**
+     * Overrides the `zoom` plugin option for this diagram. `undefined` follows the option.
+     * Set from the fence metastring: `zoom` or `zoom=false`.
+     */
+    zoom?: boolean;
 }
 /**
  * Renders one PlantUML diagram in the browser.
@@ -13,4 +18,4 @@ export interface PlantUmlDiagramProps {
  * Nothing happens during server-side rendering: the markup emitted on the server is the
  * same deferred placeholder the client renders first, so hydration never mismatches.
  */
-export default function PlantUmlDiagram({ source, title, language, }: PlantUmlDiagramProps): ReactNode;
+export default function PlantUmlDiagram({ source, title, language, zoom: zoomProp, }: PlantUmlDiagramProps): ReactNode;

package/dist/theme/PlantUmlDiagram/index.js

@@ -1,11 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useId, useRef, useState } from 'react';
 import { useColorMode } from '@docusaurus/theme-common';
 import { DATA_ATTR } from '../../constants.js';
 import { getSharedCache } from '../../runtime/cache.js';
 import { PlantUmlError } from '../../runtime/errors.js';
 import { renderDiagram } from '../../runtime/renderer.js';
 import { usePlantUmlConfig } from '../usePlantUmlConfig.js';
+import { useZoomPan } from './useZoomPan.js';
 import styles from './styles.module.css';
 const DEFAULT_LABEL = 'PlantUML diagram';
 /** Margin large enough that a diagram is usually ready by the time it is scrolled into view. */
@@ -31,15 +32,23 @@ function messageFor(error) {
  * Nothing happens during server-side rendering: the markup emitted on the server is the
  * same deferred placeholder the client renders first, so hydration never mismatches.
  */
-export default function PlantUmlDiagram({ source, title, language, }) {
+export default function PlantUmlDiagram({ source, title, language, zoom: zoomProp, }) {
     const config = usePlantUmlConfig();
     const { colorMode } = useColorMode();
     const containerRef = useRef(null);
+    const hintId = useId();
     const themeOption = config?.options.theme ?? 'auto';
     const dark = themeOption === 'auto' ? colorMode === 'dark' : themeOption === 'dark';
     const lazy = config?.options.lazy ?? true;
+    // A fence flag wins over the plugin option, which in turn wins over the built-in default.
+    const interactive = zoomProp ?? config?.options.zoom ?? true;
     const [state, setState] = useState(INITIAL_STATE);
     const [inView, setInView] = useState(!lazy);
+    // Called unconditionally, as hooks must be; it attaches nothing when not interactive.
+    const zoom = useZoomPan({
+        enabled: interactive && state.status === 'ready',
+        resetKey: `${source}|${dark ? 'dark' : 'light'}`,
+    });
     useEffect(() => {
         if (!lazy || inView)
             return undefined;
@@ -121,11 +130,16 @@ export default function PlantUmlDiagram({ source, title, language, }) {
     ]);
     const label = title ?? DEFAULT_LABEL;
     const busy = state.status === 'loading' || state.status === 'rendering';
+    // 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: styles.canvas, role: "img", "aria-label": label, 
+        // Sanitized above unless `sanitizeSvg: false` was explicitly opted into.
+        dangerouslySetInnerHTML: { __html: state.svg } }));
     return (_jsxs("figure", { ref: containerRef, className: styles.figure, "aria-busy": busy || undefined, [DATA_ATTR.diagram]: language ?? 'plantuml',
         [DATA_ATTR.status]: state.status,
-        [DATA_ATTR.theme]: dark ? 'dark' : 'light', children: [state.status === 'ready' && state.svg !== null && (_jsx("div", { className: styles.canvas, role: "img", "aria-label": label, 
-                // Sanitized above unless `sanitizeSvg: false` was explicitly opted into.
-                dangerouslySetInnerHTML: { __html: state.svg } })), state.status !== 'ready' && state.status !== 'error' && (
+        [DATA_ATTR.theme]: dark ? 'dark' : 'light',
+        ...(interactive ? { [DATA_ATTR.interactive]: 'true' } : {}),
+        ...(zoom.maximized ? { [DATA_ATTR.maximized]: 'true' } : {}), children: [state.status === 'ready' && state.svg !== null && !interactive && canvas, state.status === 'ready' && state.svg !== null && interactive && (_jsxs("div", { ref: zoom.stageRef, className: zoom.maximized ? `${styles.stage} ${styles.maximized}` : styles.stage, children: [_jsx("div", { ref: zoom.viewportRef, className: styles.viewport, tabIndex: 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 }) }), _jsxs("div", { className: styles.toolbar, role: "group", "aria-label": `${label} zoom controls`, children: [_jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Zoom out", onClick: zoom.zoomOut, children: _jsx("span", { "aria-hidden": "true", children: "\u2212" }) }), _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Zoom in", onClick: zoom.zoomIn, children: _jsx("span", { "aria-hidden": "true", children: "+" }) }), _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Reset zoom", onClick: zoom.reset, children: _jsx("span", { "aria-hidden": "true", children: "\u27F2" }) }), _jsx("button", { type: "button", className: styles.toolbarButton, "aria-label": "Maximize diagram", "aria-pressed": zoom.maximized, onClick: zoom.toggleMaximize, children: _jsx("span", { "aria-hidden": "true", children: zoom.maximized ? '✕' : '⛶' }) }), _jsx("span", { ref: zoom.readoutRef, className: 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' && (
             // `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 PlantUML 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" }), _jsx("span", { children: "Error: PlantUML 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: {

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

@@ -14,6 +14,153 @@
   height: auto;
 }
 
+/*
+ * Zoom and pan.
+ *
+ * The transform is applied to `.layer`, never to the SVG. Transforms do not affect layout, so
+ * the figure keeps the exact height it has at 100% no matter how far the reader zooms in, and
+ * `max-width: 100%` on the SVG keeps constraining the base size as it always did.
+ */
+.stage {
+  position: relative;
+}
+
+.viewport {
+  /* `clip` also prevents find-in-page from silently scrolling this box. */
+  overflow: hidden;
+  overflow: clip;
+  max-height: var(--plantuml-zoom-max-height, none);
+  /*
+   * One finger scrolls the page and two fingers are the browser's own pinch zoom, so a
+   * full-width diagram can never become a scroll trap on a phone.
+   */
+  touch-action: pan-y pinch-zoom;
+  cursor: grab;
+  outline-offset: 2px;
+}
+
+.viewport[data-plantuml-dragging='true'] {
+  cursor: grabbing;
+  user-select: none;
+}
+
+/* Inside the viewport the SVG must not be clipped by the old scroll container. */
+.viewport .canvas {
+  display: block;
+  overflow: visible;
+}
+
+.layer {
+  transform-origin: 0 0;
+  transition: transform var(--plantuml-zoom-transition, 150ms) ease-out;
+}
+
+/* Direct manipulation must never lag behind the finger, so gestures suppress the easing. */
+.layer[data-plantuml-continuous='true'] {
+  transition: none;
+}
+
+.toolbar {
+  position: absolute;
+  top: 0.5rem;
+  right: 0.5rem;
+  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;
+}
+
+.toolbarButton {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.75rem;
+  height: 1.75rem;
+  padding: 0;
+  border: 1px solid transparent;
+  border-radius: var(--ifm-global-radius);
+  background: transparent;
+  color: var(--ifm-font-color-base);
+  font-size: 1rem;
+  line-height: 1;
+  cursor: pointer;
+}
+
+.toolbarButton:hover {
+  background: var(--ifm-color-emphasis-200);
+}
+
+.toolbarButton:focus-visible {
+  outline: 2px solid var(--ifm-color-primary);
+  outline-offset: 1px;
+}
+
+.readout {
+  min-width: 3.25rem;
+  padding: 0 0.25rem;
+  color: var(--ifm-color-emphasis-700);
+  font-size: 0.75rem;
+  font-variant-numeric: tabular-nums;
+  text-align: right;
+}
+
+/*
+ * Maximized is an in-page overlay, not the Fullscreen API.
+ *
+ * `requestFullscreen()` took the whole browser window fullscreen in Firefox, and its
+ * `::backdrop` sits outside the element so the page showed through behind the diagram. A
+ * fixed overlay is fully opaque, behaves the same everywhere, and needs no capability check.
+ */
+.maximized {
+  position: fixed;
+  inset: 0;
+  z-index: var(--ifm-z-index-overlay, 400);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  /*
+   * `--ifm-background-surface-color`, not `--ifm-background-color`: Infima defines the latter
+   * as `#0000` in light mode, so the overlay would be transparent and the page would show
+   * through — which is the defect this overlay exists to fix. The surface colour is opaque in
+   * both colour modes (white / #242526), and a `var()` fallback would not have saved us here,
+   * because the variable is defined, just transparent.
+   */
+  background: var(--ifm-background-surface-color, #ffffff);
+}
+
+.maximized .viewport {
+  width: 100vw;
+  height: 100dvh;
+  max-height: none;
+}
+
+.visuallyHidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+@media (forced-colors: active) {
+  .toolbar {
+    border-color: ButtonBorder;
+  }
+
+  .toolbarButton {
+    border-color: ButtonBorder;
+    color: ButtonText;
+  }
+}
+
 .placeholder {
   display: flex;
   align-items: center;
@@ -45,6 +192,14 @@
   .spinner {
     animation: none;
   }
+
+  /*
+   * Only the easing of discrete zoom steps is decoration. Dragging and wheel zooming are
+   * direct manipulation and stay instantaneous either way.
+   */
+  .layer {
+    --plantuml-zoom-transition: 0s;
+  }
 }
 
 .caption {

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

@@ -0,0 +1,25 @@
+import { type KeyboardEvent as ReactKeyboardEvent, type MutableRefObject } from 'react';
+import { MAX_SCALE, MIN_SCALE } from './zoomMath.js';
+export interface ZoomPanHandle {
+    viewportRef: MutableRefObject<HTMLDivElement | null>;
+    layerRef: MutableRefObject<HTMLDivElement | null>;
+    readoutRef: MutableRefObject<HTMLSpanElement | null>;
+    stageRef: MutableRefObject<HTMLDivElement | null>;
+    zoomIn: () => void;
+    zoomOut: () => void;
+    reset: () => void;
+    toggleMaximize: () => void;
+    onKeyDown: (event: ReactKeyboardEvent<HTMLDivElement>) => void;
+    /** Whether the diagram currently fills the browser viewport. */
+    maximized: boolean;
+}
+export interface UseZoomPanParams {
+    enabled: boolean;
+    /**
+     * Changing this resets the view. Pass something that identifies the rendered picture, so a
+     * new diagram or a colour-mode switch starts from a clean 100% view.
+     */
+    resetKey: string;
+}
+export declare function useZoomPan({ enabled, resetKey }: UseZoomPanParams): ZoomPanHandle;
+export { MAX_SCALE, MIN_SCALE };

package/dist/theme/PlantUmlDiagram/useZoomPan.js

@@ -0,0 +1,313 @@
+import { useCallback, useEffect, useRef, useState, } from 'react';
+import { clampTransform, fitScale, formatPercent, formatZoom, IDENTITY, MAX_SCALE, MIN_SCALE, normalizeWheelDelta, panBy, PAN_STEP, SCALE_STEP, toCssTransform, wheelZoomFactor, zoomAbout, } from './zoomMath.js';
+/**
+ * Zoom, pan and maximize for one diagram.
+ *
+ * The transform lives in a ref and is written straight to the DOM, so panning and zooming
+ * never re-render the component. The single piece of React state is `maximized`, which changes
+ * only on an explicit click or Escape — it drives markup, so it belongs in React, and at one
+ * transition per user action it costs nothing.
+ */
+/** Distance the pointer must travel before a press becomes a drag rather than a click. */
+const DRAG_THRESHOLD_PX = 3;
+/** Fraction of the viewport a Shift+arrow press pans. */
+const PAGE_PAN_RATIO = 0.9;
+export function useZoomPan({ enabled, resetKey }) {
+    const stageRef = useRef(null);
+    const viewportRef = useRef(null);
+    const layerRef = useRef(null);
+    const readoutRef = useRef(null);
+    const [maximized, setMaximized] = useState(false);
+    const transformRef = useRef(IDENTITY);
+    /** The view to restore when the diagram is un-maximized. */
+    const beforeMaximizeRef = useRef(null);
+    const frameRef = useRef(null);
+    /**
+     * Layout sizes, never `getBoundingClientRect()`: the layer's rect includes the transform we
+     * are about to change, which would feed back into the next measurement.
+     */
+    const measure = useCallback(() => {
+        const viewport = viewportRef.current;
+        const layer = layerRef.current;
+        return {
+            viewportWidth: viewport?.clientWidth ?? 0,
+            viewportHeight: viewport?.clientHeight ?? 0,
+            contentWidth: layer?.offsetWidth ?? 0,
+            contentHeight: layer?.offsetHeight ?? 0,
+        };
+    }, []);
+    const write = useCallback((next) => {
+        transformRef.current = next;
+        const layer = layerRef.current;
+        const viewport = viewportRef.current;
+        if (layer)
+            layer.style.transform = toCssTransform(next);
+        if (viewport)
+            viewport.dataset['plantumlZoom'] = formatZoom(next.k);
+        const readout = readoutRef.current;
+        if (readout)
+            readout.textContent = formatPercent(next.k);
+    }, []);
+    const apply = useCallback((next) => {
+        write(clampTransform(next, measure()));
+    }, [measure, write]);
+    const reset = useCallback(() => {
+        apply(IDENTITY);
+    }, [apply]);
+    /** Zooms about the middle of the viewport, which is what buttons and keys should do. */
+    const zoomByStep = useCallback((factor) => {
+        const viewport = viewportRef.current;
+        const focalX = (viewport?.clientWidth ?? 0) / 2;
+        const focalY = (viewport?.clientHeight ?? 0) / 2;
+        apply(zoomAbout(transformRef.current, factor, focalX, focalY));
+    }, [apply]);
+    const zoomIn = useCallback(() => zoomByStep(SCALE_STEP), [zoomByStep]);
+    const zoomOut = useCallback(() => zoomByStep(1 / SCALE_STEP), [zoomByStep]);
+    const toggleMaximize = useCallback(() => {
+        setMaximized((previous) => !previous);
+    }, []);
+    const onKeyDown = useCallback((event) => {
+        if (!enabled)
+            return;
+        // Leave Ctrl+0, Cmd+Arrow and friends to the browser.
+        if (event.ctrlKey || event.metaKey || event.altKey)
+            return;
+        const viewport = viewportRef.current;
+        const pageX = (viewport?.clientWidth ?? 0) * PAGE_PAN_RATIO;
+        const pageY = (viewport?.clientHeight ?? 0) * PAGE_PAN_RATIO;
+        const stepX = event.shiftKey ? pageX : PAN_STEP;
+        const stepY = event.shiftKey ? pageY : PAN_STEP;
+        switch (event.key) {
+            case '+':
+            case '=':
+                zoomIn();
+                break;
+            case '-':
+            case '_':
+                zoomOut();
+                break;
+            case '0':
+                reset();
+                break;
+            case 'ArrowLeft':
+                apply(panBy(transformRef.current, stepX, 0));
+                break;
+            case 'ArrowRight':
+                apply(panBy(transformRef.current, -stepX, 0));
+                break;
+            case 'ArrowUp':
+                apply(panBy(transformRef.current, 0, stepY));
+                break;
+            case 'ArrowDown':
+                apply(panBy(transformRef.current, 0, -stepY));
+                break;
+            default:
+                // Not ours: let the key through, so Tab still escapes the diagram.
+                return;
+        }
+        event.preventDefault();
+    }, [apply, enabled, reset, zoomIn, zoomOut]);
+    // Everything imperative lives in this one effect, so one cleanup removes all of it.
+    useEffect(() => {
+        if (!enabled)
+            return undefined;
+        const viewport = viewportRef.current;
+        if (!viewport)
+            return undefined;
+        // The layer node is replaced whenever the rendered SVG changes; start from a clean view.
+        write(IDENTITY);
+        let dragging = false;
+        let pointerId = null;
+        let startX = 0;
+        let startY = 0;
+        let startTransform = IDENTITY;
+        let pendingX = 0;
+        let pendingY = 0;
+        let suppressClick = false;
+        const setContinuous = (on) => {
+            const layer = layerRef.current;
+            if (layer)
+                layer.dataset['plantumlContinuous'] = on ? 'true' : 'false';
+        };
+        const onWheel = (event) => {
+            // Plain wheel must keep scrolling the page. Only Ctrl zooms — Cmd is the browser's own
+            // page zoom on macOS, and trackpad pinch already arrives here as Ctrl+wheel.
+            if (!event.ctrlKey)
+                return;
+            event.preventDefault();
+            const rect = viewport.getBoundingClientRect();
+            const factor = wheelZoomFactor(normalizeWheelDelta(event.deltaY, event.deltaMode));
+            setContinuous(true);
+            apply(zoomAbout(transformRef.current, factor, event.clientX - rect.left, event.clientY - rect.top));
+        };
+        const flushPan = () => {
+            frameRef.current = null;
+            apply(panBy(startTransform, pendingX, pendingY));
+        };
+        const onPointerDown = (event) => {
+            if (!event.isPrimary || event.button !== 0)
+                return;
+            // Deliberately no preventDefault: it would kill focus and text selection, and links
+            // inside a diagram must still be clickable.
+            pointerId = event.pointerId;
+            startX = event.clientX;
+            startY = event.clientY;
+            startTransform = transformRef.current;
+            pendingX = 0;
+            pendingY = 0;
+        };
+        const onPointerMove = (event) => {
+            if (pointerId === null || event.pointerId !== pointerId)
+                return;
+            pendingX = event.clientX - startX;
+            pendingY = event.clientY - startY;
+            if (!dragging) {
+                if (Math.hypot(pendingX, pendingY) < DRAG_THRESHOLD_PX)
+                    return;
+                dragging = true;
+                suppressClick = true;
+                viewport.dataset['plantumlDragging'] = 'true';
+                setContinuous(true);
+                try {
+                    viewport.setPointerCapture(pointerId);
+                }
+                catch {
+                    // Capture is unavailable in some environments; dragging still works without it.
+                }
+            }
+            event.preventDefault();
+            if (frameRef.current === null) {
+                frameRef.current = requestAnimationFrame(flushPan);
+            }
+        };
+        const endDrag = (event) => {
+            if (pointerId === null || event.pointerId !== pointerId)
+                return;
+            if (frameRef.current !== null) {
+                cancelAnimationFrame(frameRef.current);
+                frameRef.current = null;
+                flushPan();
+            }
+            try {
+                if (viewport.hasPointerCapture(pointerId))
+                    viewport.releasePointerCapture(pointerId);
+            }
+            catch {
+                // Nothing to release.
+            }
+            pointerId = null;
+            dragging = false;
+            delete viewport.dataset['plantumlDragging'];
+            setContinuous(false);
+        };
+        // A drag that ends over a link must not activate it.
+        const onClickCapture = (event) => {
+            if (!suppressClick)
+                return;
+            suppressClick = false;
+            event.preventDefault();
+            event.stopPropagation();
+        };
+        viewport.addEventListener('wheel', onWheel, { passive: false });
+        viewport.addEventListener('pointerdown', onPointerDown);
+        viewport.addEventListener('pointermove', onPointerMove);
+        viewport.addEventListener('pointerup', endDrag);
+        viewport.addEventListener('pointercancel', endDrag);
+        viewport.addEventListener('lostpointercapture', endDrag);
+        viewport.addEventListener('click', onClickCapture, true);
+        // Re-clamp when the column width changes (window resize, sidebar collapse), so a panned
+        // diagram cannot end up stranded outside a narrower viewport.
+        const observer = typeof ResizeObserver === 'undefined'
+            ? null
+            : new ResizeObserver(() => apply(transformRef.current));
+        observer?.observe(viewport);
+        return () => {
+            viewport.removeEventListener('wheel', onWheel);
+            viewport.removeEventListener('pointerdown', onPointerDown);
+            viewport.removeEventListener('pointermove', onPointerMove);
+            viewport.removeEventListener('pointerup', endDrag);
+            viewport.removeEventListener('pointercancel', endDrag);
+            viewport.removeEventListener('lostpointercapture', endDrag);
+            viewport.removeEventListener('click', onClickCapture, true);
+            observer?.disconnect();
+            if (frameRef.current !== null) {
+                cancelAnimationFrame(frameRef.current);
+                frameRef.current = null;
+            }
+            if (pointerId !== null) {
+                try {
+                    if (viewport.hasPointerCapture(pointerId))
+                        viewport.releasePointerCapture(pointerId);
+                }
+                catch {
+                    // Already gone.
+                }
+            }
+        };
+        // `resetKey` is a dependency so a re-render of the same node with new content re-arms
+        // the listeners against a clean view.
+    }, [apply, enabled, measure, resetKey, write]);
+    /**
+     * A cache hit resolves before any phase is reported, so a colour-mode toggle can go
+     * `ready -> ready` without ever unmounting the layer. The effect above would not re-run in
+     * that case, which is why the reset is also driven directly by `resetKey`.
+     */
+    useEffect(() => {
+        if (!enabled)
+            return;
+        write(IDENTITY);
+    }, [enabled, resetKey, write]);
+    /**
+     * Maximizing is done in the page, not with the Fullscreen API.
+     *
+     * `requestFullscreen()` gave two problems it cannot solve: Firefox takes the whole browser
+     * window fullscreen rather than presenting the element, and the `::backdrop` is outside the
+     * element so the page behind it shows through. A fixed-position overlay we own has neither
+     * issue, works identically in every browser, and needs no capability detection — which also
+     * restores the control on iOS Safari, where element fullscreen does not exist.
+     */
+    useEffect(() => {
+        if (!enabled || !maximized)
+            return undefined;
+        beforeMaximizeRef.current = transformRef.current;
+        // The overlay covers the viewport; scrolling the page underneath it would be confusing.
+        const body = document.body;
+        const previousOverflow = body.style.overflow;
+        body.style.overflow = 'hidden';
+        // The layout is already committed by the time an effect runs, so the viewport now
+        // reports its maximized size and the diagram can be fitted to it.
+        apply({ ...IDENTITY, k: fitScale(measure()) });
+        viewportRef.current?.focus();
+        const onKeyDownDocument = (event) => {
+            if (event.key !== 'Escape')
+                return;
+            event.preventDefault();
+            setMaximized(false);
+        };
+        document.addEventListener('keydown', onKeyDownDocument);
+        return () => {
+            document.removeEventListener('keydown', onKeyDownDocument);
+            body.style.overflow = previousOverflow;
+            apply(beforeMaximizeRef.current ?? IDENTITY);
+            beforeMaximizeRef.current = null;
+        };
+    }, [apply, enabled, maximized, measure]);
+    // A diagram that is re-rendered or unmounted must not leave the page scroll-locked.
+    useEffect(() => {
+        if (!enabled)
+            setMaximized(false);
+    }, [enabled]);
+    return {
+        stageRef,
+        viewportRef,
+        layerRef,
+        readoutRef,
+        zoomIn,
+        zoomOut,
+        reset,
+        toggleMaximize,
+        onKeyDown,
+        maximized,
+    };
+}
+export { MAX_SCALE, MIN_SCALE };

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

@@ -0,0 +1,75 @@
+/**
+ * Geometry for zooming and panning a diagram.
+ *
+ * Every function here is pure and DOM-free, which is what makes the interaction testable:
+ * jsdom reports every element as zero-sized, so the maths cannot be verified through the
+ * component. It is verified directly instead, and the component tests only check wiring.
+ */
+export interface Transform {
+    /** Scale factor. */
+    k: number;
+    /** Horizontal translation in CSS pixels, applied before scaling (`transform-origin: 0 0`). */
+    x: number;
+    /** Vertical translation in CSS pixels. */
+    y: number;
+}
+export interface Bounds {
+    viewportWidth: number;
+    viewportHeight: number;
+    /** Layout size of the content at scale 1 — never a `getBoundingClientRect()` measurement. */
+    contentWidth: number;
+    contentHeight: number;
+}
+export declare const IDENTITY: Transform;
+/** Smallest and largest scale a reader can reach, and the discrete step for buttons and keys. */
+export declare const MIN_SCALE = 0.25;
+export declare const MAX_SCALE = 8;
+export declare const SCALE_STEP = 1.25;
+/** Arrow-key pan distance, in CSS pixels. */
+export declare const PAN_STEP = 48;
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Scales about a focal point expressed in viewport coordinates, keeping the content under
+ * that point fixed.
+ *
+ * With `transform-origin: 0 0`, a content point `p` maps to `v = p * k + t`. Solving for the
+ * translation that leaves `v` unchanged at the new scale gives `t' = f - (f - t) * (k'/k)`.
+ *
+ * The ratio is deliberately computed from the *achieved* scale rather than the requested
+ * factor: at the min or max limit the two differ, and using the requested factor there would
+ * drift the diagram sideways on every further wheel tick.
+ */
+export declare function zoomAbout(transform: Transform, factor: number, focalX: number, focalY: number, min?: number, max?: number): Transform;
+export declare function panBy(transform: Transform, dx: number, dy: number): Transform;
+/**
+ * Keeps the diagram reachable: an edge can never be dragged inside the viewport, and content
+ * that fits is left-aligned — matching the `justify-content: flex-start` behaviour diagrams
+ * had before they became zoomable.
+ *
+ * The axes are clamped independently, so a wide, short diagram pans horizontally while staying
+ * pinned vertically.
+ */
+export declare function clampTransform(transform: Transform, bounds: Bounds): Transform;
+/**
+ * Normalizes wheel deltas to pixels.
+ *
+ * Firefox reports line-based deltas for a mouse wheel, so an un-normalized `deltaY` zooms
+ * roughly sixteen times slower there than in Chromium.
+ */
+export declare function normalizeWheelDelta(deltaY: number, deltaMode: number): number;
+/** Converts a normalized wheel delta into a multiplicative scale factor. */
+export declare function wheelZoomFactor(normalizedDelta: number): number;
+/**
+ * Largest scale at which the whole diagram still fits inside the given viewport.
+ *
+ * Used when maximizing. Small diagrams are magnified rather than left stranded in
+ * the middle of a large screen — the output is vector, so it stays crisp — but never beyond
+ * `max`, and never below {@link MIN_SCALE}.
+ */
+export declare function fitScale(bounds: Bounds, max?: number): number;
+export declare function toCssTransform(transform: Transform): string;
+/** Machine-readable scale for `data-plantuml-zoom`, used by tests and author CSS. */
+export declare function formatZoom(scale: number): string;
+/** Human-readable scale for the toolbar readout. */
+export declare function formatPercent(scale: number): string;
+export declare function isIdentity(transform: Transform): boolean;

package/dist/theme/PlantUmlDiagram/zoomMath.js

@@ -0,0 +1,114 @@
+/**
+ * Geometry for zooming and panning a diagram.
+ *
+ * Every function here is pure and DOM-free, which is what makes the interaction testable:
+ * jsdom reports every element as zero-sized, so the maths cannot be verified through the
+ * component. It is verified directly instead, and the component tests only check wiring.
+ */
+export const IDENTITY = { k: 1, x: 0, y: 0 };
+/** Smallest and largest scale a reader can reach, and the discrete step for buttons and keys. */
+export const MIN_SCALE = 0.25;
+export const MAX_SCALE = 8;
+export const SCALE_STEP = 1.25;
+/** Arrow-key pan distance, in CSS pixels. */
+export const PAN_STEP = 48;
+export function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+/**
+ * Scales about a focal point expressed in viewport coordinates, keeping the content under
+ * that point fixed.
+ *
+ * With `transform-origin: 0 0`, a content point `p` maps to `v = p * k + t`. Solving for the
+ * translation that leaves `v` unchanged at the new scale gives `t' = f - (f - t) * (k'/k)`.
+ *
+ * The ratio is deliberately computed from the *achieved* scale rather than the requested
+ * factor: at the min or max limit the two differ, and using the requested factor there would
+ * drift the diagram sideways on every further wheel tick.
+ */
+export function zoomAbout(transform, factor, focalX, focalY, min = MIN_SCALE, max = MAX_SCALE) {
+    const k = clamp(transform.k * factor, min, max);
+    const ratio = k / transform.k;
+    return {
+        k,
+        x: focalX - (focalX - transform.x) * ratio,
+        y: focalY - (focalY - transform.y) * ratio,
+    };
+}
+export function panBy(transform, dx, dy) {
+    return { k: transform.k, x: transform.x + dx, y: transform.y + dy };
+}
+/**
+ * Keeps the diagram reachable: an edge can never be dragged inside the viewport, and content
+ * that fits is left-aligned — matching the `justify-content: flex-start` behaviour diagrams
+ * had before they became zoomable.
+ *
+ * The axes are clamped independently, so a wide, short diagram pans horizontally while staying
+ * pinned vertically.
+ */
+export function clampTransform(transform, bounds) {
+    const scaledWidth = bounds.contentWidth * transform.k;
+    const scaledHeight = bounds.contentHeight * transform.k;
+    const x = scaledWidth <= bounds.viewportWidth
+        ? 0
+        : clamp(transform.x, bounds.viewportWidth - scaledWidth, 0);
+    const y = scaledHeight <= bounds.viewportHeight
+        ? 0
+        : clamp(transform.y, bounds.viewportHeight - scaledHeight, 0);
+    return { k: transform.k, x, y };
+}
+/** `WheelEvent.deltaMode` constants, which jsdom does not define. */
+const DELTA_PIXEL = 0;
+const DELTA_LINE = 1;
+const LINE_HEIGHT_PX = 16;
+const PAGE_HEIGHT_PX = 400;
+/**
+ * Normalizes wheel deltas to pixels.
+ *
+ * Firefox reports line-based deltas for a mouse wheel, so an un-normalized `deltaY` zooms
+ * roughly sixteen times slower there than in Chromium.
+ */
+export function normalizeWheelDelta(deltaY, deltaMode) {
+    if (deltaMode === DELTA_PIXEL)
+        return deltaY;
+    if (deltaMode === DELTA_LINE)
+        return deltaY * LINE_HEIGHT_PX;
+    return deltaY * PAGE_HEIGHT_PX;
+}
+/** Converts a normalized wheel delta into a multiplicative scale factor. */
+export function wheelZoomFactor(normalizedDelta) {
+    return Math.exp(-normalizedDelta * 0.002);
+}
+/**
+ * Largest scale at which the whole diagram still fits inside the given viewport.
+ *
+ * Used when maximizing. Small diagrams are magnified rather than left stranded in
+ * the middle of a large screen — the output is vector, so it stays crisp — but never beyond
+ * `max`, and never below {@link MIN_SCALE}.
+ */
+export function fitScale(bounds, max = MAX_SCALE) {
+    if (bounds.contentWidth <= 0 || bounds.contentHeight <= 0)
+        return 1;
+    const scale = Math.min(bounds.viewportWidth / bounds.contentWidth, bounds.viewportHeight / bounds.contentHeight);
+    if (!Number.isFinite(scale) || scale <= 0)
+        return 1;
+    return clamp(scale, MIN_SCALE, max);
+}
+/** Rounds away floating-point noise so repeated zoom in/out returns to exactly 1. */
+function tidy(value) {
+    return Math.abs(value) < 1e-6 ? 0 : Math.round(value * 1e6) / 1e6;
+}
+export function toCssTransform(transform) {
+    return `translate(${tidy(transform.x)}px, ${tidy(transform.y)}px) scale(${tidy(transform.k)})`;
+}
+/** Machine-readable scale for `data-plantuml-zoom`, used by tests and author CSS. */
+export function formatZoom(scale) {
+    return String(tidy(Math.round(scale * 1000) / 1000));
+}
+/** Human-readable scale for the toolbar readout. */
+export function formatPercent(scale) {
+    return `${Math.round(scale * 100)}%`;
+}
+export function isIdentity(transform) {
+    return tidy(transform.k) === 1 && tidy(transform.x) === 0 && tidy(transform.y) === 0;
+}

package/dist/theme/codeBlockMeta.d.ts

@@ -23,5 +23,14 @@ export declare function isPlantUmlLanguage(props: CodeBlockProps, languages: rea
  * than being rendered from a partially-known source string.
  */
 export declare function extractSource(children: ReactNode): string | null;
+/**
+ * Reads a boolean flag from the fence metastring: either bare (`zoom`) or explicit
+ * (`zoom=true` / `zoom=false`).
+ *
+ * Returns `undefined` when the flag is absent or malformed, which the caller reads as "fall
+ * back to the plugin option". A fence metastring is authored prose, not configuration, so an
+ * unrecognized value is ignored rather than failing the site build.
+ */
+export declare function parseBooleanMeta(props: CodeBlockProps, key: string): boolean | undefined;
 /** Reads `title="..."` (or `title='...'`) from the fence metastring. */
 export declare function parseTitle(props: CodeBlockProps): string | undefined;

package/dist/theme/codeBlockMeta.js

@@ -48,6 +48,39 @@ export function extractSource(children) {
     // MDX always terminates a fence with a newline that is not part of the diagram.
     return source.replace(/\n$/, '');
 }
+/**
+ * Quoted segments, removed before flag matching so that a value such as
+ * `title="zoom=false"` can never be mistaken for a flag.
+ */
+const QUOTED_SEGMENT = /(["'])(?:\\.|(?!\1).)*\1/g;
+/**
+ * Reads a boolean flag from the fence metastring: either bare (`zoom`) or explicit
+ * (`zoom=true` / `zoom=false`).
+ *
+ * Returns `undefined` when the flag is absent or malformed, which the caller reads as "fall
+ * back to the plugin option". A fence metastring is authored prose, not configuration, so an
+ * unrecognized value is ignored rather than failing the site build.
+ */
+export function parseBooleanMeta(props, key) {
+    const metastring = props.metastring;
+    if (typeof metastring !== 'string' || metastring === '')
+        return undefined;
+    const withoutQuoted = metastring.replace(QUOTED_SEGMENT, ' ');
+    // Word boundaries by hand: `nozoom` and `zoomed` must not match `zoom`.
+    const pattern = new RegExp(`(?:^|\\s)${key}(?:=(\\S+))?(?=\\s|$)`, 'i');
+    const match = pattern.exec(withoutQuoted);
+    if (!match)
+        return undefined;
+    const value = match[1];
+    if (value === undefined)
+        return true;
+    const normalized = value.toLowerCase();
+    if (normalized === 'true')
+        return true;
+    if (normalized === 'false')
+        return false;
+    return undefined;
+}
 /** Reads `title="..."` (or `title='...'`) from the fence metastring. */
 export function parseTitle(props) {
     if (typeof props.title === 'string' && props.title !== '')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matfsw/docusaurus-plantuml-plugin",
-  "version": "0.1.0",
+  "version": "1.0.1",
   "description": "Render PlantUML diagrams in Docusaurus 3 entirely in the browser - no Java, no PlantUML server, no CDN.",
   "keywords": [
     "docusaurus",