@matfsw/docusaurus-plantuml-plugin 1.1.2 → 1.3.0

package/CHANGELOG.md

@@ -7,6 +7,106 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.0]
+
+### Added
+
+- **The PlantUML standard library.** `!include <C4/C4_Container>` now renders, with no
+  configuration and nothing to install. Eight namespaces ship with the plugin — `c4`,
+  `archimate`, `eip`, `k8s`, `kubernetes`, `azure`, `office` and `cloudinsight` — and a page
+  downloads only the ones its diagrams actually include. A C4 page costs 29 KB gzipped; a page
+  with no standard library include costs nothing.
+
+  Four details are worth knowing:
+  - **Bundles are served from your own `baseUrl`**, like every other asset. Left to itself the
+    engine resolves a namespace against the *current page* — `/docs/architecture/c4.min.js` —
+    which cannot exist, and pre-populating its global does not stop it. The plugin loads the
+    bundle from the assets directory and then tells the engine the work is done. See
+    [ADR 0005](docs/adr/0005-stdlib-bundles.md).
+  - **Includes the library makes of itself are resolved too**, from an index built when the
+    bundles are generated. `k8s/Common` needs `<c4/…>`, and the engine would only discover that
+    mid-render, with no chance to fetch it.
+  - **`!include <C4/C4_Container.puml>` works**, spelled with the extension. Upstream's own
+    bundles cannot resolve that spelling, even though C4-PlantUML's documentation uses it.
+  - **A missing namespace is explained, not dumped on the reader.** The panel names the
+    namespace and the option that adds it, instead of PlantUML's grey "Fatal parsing error".
+
+- `stdlib` plugin option: `stdlib: false` switches the feature off entirely; `stdlib.include`
+  plus `stdlib.source` add namespaces from a `plantuml-stdlib` checkout — including the icon
+  libraries that are far too large to vendor, such as `aws`, `ibm` and `tupadr3` — and
+  `stdlib.namespaces` narrows what a build emits.
+- `stdlib` error kind, for an include the site cannot resolve.
+- `npm run stdlib:update`, which regenerates the vendored bundles from a pinned
+  plantuml-stdlib commit. It is maintainer-only and never part of `npm run build`, so site
+  builds stay offline and hermetic.
+- `assets/stdlib/LICENSES.md`, recording the upstream project, version and licence of every
+  vendored namespace. Namespaces whose upstream declares no licence are deliberately not
+  vendored; `stdlib.include` remains available for anyone who wants them.
+
+### Fixed
+
+- **PlantUML's preprocessor failures are now reported as errors** rather than passed through as
+  successfully rendered pictures. Calling a macro the included library does not define
+  (`Function not found RelIndex`), naming a file that is not in a namespace
+  (`cannot include <C4/C4_Nope>`) and an include that could not be resolved at all
+  (`Fatal parsing error`) all produce an error card with no `Syntax Error?` marker on it, so
+  the existing detection missed all three. They are the likeliest ways a standard library
+  diagram goes wrong, which is how this surfaced. The panel shows the failure alone rather
+  than the thousands of macro-expanded lines it is buried in.
+- **Library files that are themselves whole `@startuml … @enduml` documents** are unwrapped when
+  the bundle is generated, the way PlantUML's file-based `!include` does. The standard library
+  lookup passes the markers through verbatim, and a nested `@startuml` fails the diagram — 81 of
+  `cloudinsight`'s 83 sprite files are written that way, so the namespace was unusable without
+  this. Files with more than one block are left alone.
+
+### Changed
+
+- A script asset that fails to load is now replaced rather than reused when a later diagram
+  retries, so one flaky response no longer disables the engine — or a standard library
+  namespace — for the rest of the page.
+- The render cache key includes the standard library revision, so refreshing it cannot serve a
+  picture rendered against the old one.
+- The published package grows from 77 KB to ~776 KB packed (245 KB to ~3.2 MB unpacked); the
+  difference is the vendored bundles. `verify-package.mjs` budgets them separately from the
+  plugin's own code, which keeps its own 400 KB ceiling.
+
+## [1.2.0]
+
+### Added
+
+- **A source view for every rendered diagram.** A `</>` control in the toolbar, beside the zoom
+  buttons, **flips the frame**: the source takes the diagram's place, in the same box. A
+  **Copy** button joins the same toolbar while the source is shown, so every control on a
+  diagram lives in one place. Enabled by default; turn it off with
+  `showSource: false`, or per fence with `showSource=false` in the metastring.
+
+  Four details are deliberate:
+  - **It shares the diagram's frame rather than sitting below it.** Below the diagram it had two
+    failure modes: a diagram taller than the window pushed it off-screen, and while maximized it
+    was painted behind the full-screen overlay. Sharing the frame removes both by construction.
+  - **The diagram is hidden, not unmounted**, so the frame keeps its height — nothing on the page
+    moves when you flip — and the reader's zoom and pan survive the round trip.
+  - The copy result is announced through a `role="status"` region rather than by renaming the
+    button, because a control whose accessible name changes is announced as a new control.
+  - A failed copy says so. `navigator.clipboard` is undefined outside a secure context, which a
+    docs site on plain HTTP genuinely is; the source is on screen either way, so the reader can
+    select the text.
+
+- `showSource` plugin option and the matching `showSource` / `showSource=false` fence flag.
+- `data-plantuml-source-open="true"` on the `<figure>` while the source is shown, part of the
+  documented `data-*` contract.
+
+### Changed
+
+- The zoom controls are hidden while the source is shown — they would act on a picture nobody
+  can see. **Maximize stays**, because it sizes the frame the source is read in and removing it
+  while maximized would leave Escape as the only way back out.
+
+- With `zoom: false` the source control gets its own row after the diagram, since there is no
+  zoom toolbar to join. `figure > div[role="img"]` remains the first child, so the shape the
+  pre-zoom markup has always had is unchanged. Setting both `zoom: false` and
+  `showSource: false` restores the bare markup exactly.
+
 ## [1.1.2]
 
 ### Fixed
@@ -247,7 +347,9 @@ Initial release.
   opt-out.
 - Plugin option validation that rejects unknown keys and out-of-range values at build time.
 
-[Unreleased]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.1.2...HEAD
+[Unreleased]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.1.2...v1.2.0
 [1.1.2]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.1.1...v1.1.2
 [1.1.1]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/matf/docusaurus-plantuml-plugin/compare/v1.0.3...v1.1.0

package/README.md

@@ -231,21 +231,23 @@ props untouched. Existing code-block behaviour (highlighting, line numbers, titl
 
 ## Options
 
-| Option              | Type                              | Default                | Description                                                                                                                |
-| ------------------- | --------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `languages`         | `string[]`                        | `['plantuml', 'puml']` | Fence languages treated as PlantUML. Matched case-insensitively; must contain at least one non-empty, non-duplicate entry. |
-| `theme`             | `'auto' \| 'light' \| 'dark'`     | `'auto'`               | Diagram colour scheme. `auto` follows the Docusaurus colour mode; `light`/`dark` pin it.                                   |
-| `lazy`              | `boolean`                         | `true`                 | Render a diagram only once it scrolls near the viewport (300 px root margin).                                              |
-| `cache`             | `'none' \| 'memory' \| 'session'` | `'memory'`             | Where rendered SVG is cached.                                                                                              |
-| `sanitizeSvg`       | `boolean`                         | `true`                 | Run rendered SVG through DOMPurify before inserting it. See [Security model](#svg-sanitization-and-security-model).        |
-| `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`.  |
-| `graphviz`          | `object`                          | see below              | Graphviz/DOT support. See [Graphviz options](#graphviz-options).                                                           |
-| `id`                | `string`                          | `'default'`            | Docusaurus plugin instance id; only relevant if you register the plugin more than once.                                    |
-
-Every option above except `graphviz` applies to **both** engines: `lazy`, `cache`,
+| Option              | Type                              | Default                | Description                                                                                                                         |
+| ------------------- | --------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `languages`         | `string[]`                        | `['plantuml', 'puml']` | Fence languages treated as PlantUML. Matched case-insensitively; must contain at least one non-empty, non-duplicate entry.          |
+| `theme`             | `'auto' \| 'light' \| 'dark'`     | `'auto'`               | Diagram colour scheme. `auto` follows the Docusaurus colour mode; `light`/`dark` pin it.                                            |
+| `lazy`              | `boolean`                         | `true`                 | Render a diagram only once it scrolls near the viewport (300 px root margin).                                                       |
+| `cache`             | `'none' \| 'memory' \| 'session'` | `'memory'`             | Where rendered SVG is cached.                                                                                                       |
+| `sanitizeSvg`       | `boolean`                         | `true`                 | Run rendered SVG through DOMPurify before inserting it. See [Security model](#svg-sanitization-and-security-model).                 |
+| `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`.           |
+| `showSource`        | `boolean`                         | `true`                 | Offer a toolbar control that reveals the diagram source and copies it to the clipboard. Override per fence with `showSource=false`. |
+| `graphviz`          | `object`                          | see below              | Graphviz/DOT support. See [Graphviz options](#graphviz-options).                                                                    |
+| `stdlib`            | `object \| false`                 | see below              | PlantUML standard library (`!include <C4/…>`). See [Standard library options](#standard-library-options).                           |
+| `id`                | `string`                          | `'default'`            | Docusaurus plugin instance id; only relevant if you register the plugin more than once.                                             |
+
+Every option above except `graphviz` and `stdlib` applies to **both** engines: `lazy`, `cache`,
 `sanitizeSvg`, `showSourceOnError`, `renderTimeoutMs`, `cacheMaxEntries` and `zoom` behave
 identically for a `dot` fence and a `plantuml` fence. `theme` is the exception — see
 [Light and dark mode](#light-and-dark-mode).
@@ -257,16 +259,17 @@ 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', 'zoom', 'graphviz'.
+'renderTimeoutMs', 'cacheMaxEntries', 'zoom', 'showSource', 'graphviz', 'stdlib'.
 ```
 
 The same is true one level deeper, so `graphviz: {enigne: 'neato'}` fails the build rather than
 quietly doing nothing.
 
 `PlantUmlPluginOptions`, `ResolvedPlantUmlOptions`, `GraphvizOptions`,
-`ResolvedGraphvizOptions`, `GraphvizEngine`, `GRAPHVIZ_ENGINES`, `CacheMode`, `DiagramTheme`,
-`DEFAULT_OPTIONS`, `DEFAULT_GRAPHVIZ_OPTIONS`, `resolveOptions` and `PlantUmlOptionsError` are
-exported from the package root. The renderer, queue and cache internals are deliberately not
+`ResolvedGraphvizOptions`, `GraphvizEngine`, `GRAPHVIZ_ENGINES`, `StdlibOptions`,
+`ResolvedStdlibOptions`, `CacheMode`, `DiagramTheme`, `DEFAULT_OPTIONS`,
+`DEFAULT_GRAPHVIZ_OPTIONS`, `resolveOptions` and `PlantUmlOptionsError` are exported from the
+package root. The renderer, queue and cache internals are deliberately not
 exported.
 
 ## Graphviz (DOT) diagrams
@@ -377,6 +380,115 @@ large, and expect the page to stall while they render.
 The check happens **before** the engine is downloaded, so refusing an oversized diagram is
 free.
 
+## PlantUML standard library
+
+`!include <C4/C4_Container>` works out of the box. Nothing to install, nothing to configure:
+
+````markdown
+```plantuml title="C4 container diagram"
+@startuml
+!include <C4/C4_Container>
+
+Person(user, "Reader", "Reads the documentation")
+Container(browser, "Browser", "JavaScript", "Renders diagrams locally")
+Rel(user, browser, "Opens a page")
+@enduml
+```
+````
+
+Both spellings of the include resolve — `<C4/C4_Container>` and `<C4/C4_Container.puml>` —
+and so do the includes the library makes of _itself_: `C4_Container` pulls in `C4_Context`,
+`k8s/Common` pulls in `<c4/…>`, and none of that has to be written in the fence.
+
+### What is included, and what it costs
+
+Namespaces are fetched **per page, on demand**. A page with a C4 diagram downloads 29 KB
+gzipped; a page with no standard library include downloads nothing at all. The bundles are
+served from your own `baseUrl` like every other asset — no CDN, no plantuml.com.
+
+| Namespace      | Library              | Transfer | Licence    |
+| -------------- | -------------------- | -------- | ---------- |
+| `c4`           | C4-PlantUML          | 29 KB    | MIT        |
+| `archimate`    | Archimate-PlantUML   | 34 KB    | MIT        |
+| `eip`          | EIP-PlantUML         | 21 KB    | MIT        |
+| `k8s`          | kubernetes-PlantUML  | 23 KB    | MIT        |
+| `kubernetes`   | kubernetes sprites   | 221 KB   | Apache-2.0 |
+| `azure`        | Azure-PlantUML       | 160 KB   | MIT        |
+| `office`       | plantuml-office      | 160 KB   | MIT        |
+| `cloudinsight` | cicon sprites        | 24 KB    | MIT        |
+| `domainstory`  | DomainStory-PlantUML | 5 KB     | MIT        |
+
+Transfer figures are gzipped, per namespace, once per browsing session.
+[`assets/stdlib/LICENSES.md`](assets/stdlib/LICENSES.md) records the exact upstream version and
+licence of each. The bundles are generated from a pinned
+[plantuml-stdlib](https://github.com/plantuml/plantuml-stdlib) commit by
+`npm run stdlib:update`.
+
+### Namespaces that are not included
+
+The standard library in full is **265 MB** of source (28 MB gzipped), most of it icon sets:
+`aws` alone is 114 MB, and `ibm`, `tupadr3`, `material7.4.47` and `awslib14`/`awslib20` account
+for most of the rest. Shipping that in an npm package is not reasonable, and several other
+namespaces — `classy`, `classy-c4`, `cloudogu`, `edgy`, `elastic`, `gcp`, `osa2` — declare no
+licence at all upstream, which makes redistributing them your call rather than this package's.
+`domainstory` is left out for a third reason: it is small and MIT licensed, but every element it
+draws resolves an icon out of `material2.1.19`, so it cannot render without 6.8 MB of icons
+beside it — use it with `include: ['domainstory', 'material2.1.19']`.
+
+Any of them can be added from your own checkout:
+
+```bash
+git clone --depth 1 https://github.com/plantuml/plantuml-stdlib vendor/plantuml-stdlib
+```
+
+```ts
+{
+  stdlib: {
+    include: ['aws', 'tupadr3'],
+    source: 'vendor/plantuml-stdlib/stdlib',
+  },
+}
+```
+
+Bundles for those namespaces are generated during the build and cached under `.docusaurus`, so
+only the first build pays for it. Naming a namespace that _is_ vendored replaces it with the
+copy from your checkout, which is also how you pin a newer C4 than the one shipped here.
+
+### Standard library options
+
+| Option       | Type                 | Default | Description                                                                                                                        |
+| ------------ | -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `enabled`    | `boolean`            | `true`  | Resolve `!include <namespace/…>` at all. `stdlib: false` is shorthand for `{enabled: false}`.                                      |
+| `include`    | `string[]`           | `[]`    | Extra namespaces to make available. Each must be found in `source`, or the build fails naming it.                                  |
+| `source`     | `string \| string[]` | `[]`    | `stdlib` directories of plantuml-stdlib checkouts, relative to the site directory or absolute. Required whenever `include` is set. |
+| `namespaces` | `string[]`           | all     | Narrow the vendored namespaces emitted into the build. Dependencies of the named ones are kept regardless.                         |
+
+Namespaces are matched case-insensitively, because the engine lower-cases `<C4/…>` before it
+looks anything up.
+
+### When a namespace is missing
+
+A diagram that includes a namespace the site does not provide gets the plugin's error panel,
+naming what is missing and how to add it — not PlantUML's grey "Fatal parsing error" picture:
+
+```text
+This diagram includes <aws/…>, but the 'aws' standard library namespace is not available on
+this site. Add it to the plugin's `stdlib.include` option and point `stdlib.source` at a
+plantuml-stdlib checkout that contains it.
+```
+
+### Turning it off
+
+```ts
+{
+  stdlib: false;
+}
+```
+
+Nothing is emitted into the build, and a diagram with a standard library include says so
+instead of failing inside the engine. See
+[ADR 0005](docs/adr/0005-stdlib-bundles.md) for why the bundles are loaded the way they are.
+
 ## Light and dark mode
 
 The two engines handle this differently, because PlantUML has a real dark theme and Graphviz
@@ -499,6 +611,58 @@ would mean most readers never discover it. The costs are real and worth knowing:
 
 Setting `zoom: false` restores the previous markup exactly.
 
+## Source view
+
+Every rendered diagram offers its own source. The `</>` control in the toolbar **flips the
+frame**: the source takes the diagram's place, in the same box. A **Copy** button appears beside
+it in the same toolbar while the source is shown. Press `</>` again to flip back.
+
+````markdown
+```plantuml title="Readers can copy this"
+@startuml
+Alice -> Bob : Hello
+@enduml
+```
+````
+
+Details worth knowing:
+
+- **The source shares the diagram's frame.** It was previously rendered _below_ the diagram,
+  which had two failure modes: a diagram taller than the window pushed it off-screen, so the
+  control looked broken; and while maximized it was painted behind the full-screen overlay, so
+  it was invisible however far you scrolled. In the frame it appears exactly where the picture
+  was.
+- **The diagram is hidden, not unmounted.** The frame keeps its height, so nothing on the page
+  moves when you flip, and your zoom and pan survive the round trip.
+- **The zoom controls step aside while the source is shown** — they would act on a picture
+  nobody can see. Maximize stays, because it sizes the frame the source is read in, and taking
+  it away while maximized would leave Escape as the only way out.
+- The source stays outside the `role="img"` subtree, which is opaque to assistive technology —
+  content inside it would be unreachable for screen-reader users.
+- **The copy result is announced through a `role="status"` region**, not by renaming the button.
+  A control whose accessible name changes is announced as a new control every time.
+- **A failed copy says so.** `navigator.clipboard` is undefined outside a secure context, which
+  a docs site served over plain HTTP genuinely is. The panel is open either way, so the reader
+  can select the text; the control never silently does nothing.
+- The panel shows the **authored source**, never the rendered SVG.
+
+Turn it off for a whole site with `showSource: false`, or for one fence:
+
+````markdown
+```plantuml showSource=false
+@startuml
+Alice -> Bob : Hello
+@enduml
+```
+````
+
+With `zoom: false` there is no zoom toolbar, so the control gets its own row after the diagram.
+Setting both `zoom: false` and `showSource: false` restores the bare markup the plugin produced
+before either feature existed.
+
+This is separate from `showSourceOnError`, which offers the source in the error panel when a
+diagram _fails_ to render.
+
 ## Lazy loading
 
 With `lazy: true` (the default), a diagram is not rendered until it scrolls within 300 px of
@@ -675,16 +839,17 @@ wrapper carries `data-plantuml-status="error"`.
 
 Failures are classified internally as one of:
 
-| Kind        | Cause                                                                                                                                                          |
-| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `load`      | `viz-global.js` or `plantuml.js` could not be fetched, timed out, or was not the expected module (usually a proxy or service worker returning the wrong file). |
-| `engine`    | The engine threw, or its output could not be used at all.                                                                                                      |
-| `diagram`   | The source is not valid PlantUML.                                                                                                                              |
-| `syntax`    | The source is not valid DOT. Carries Graphviz's own diagnostic, including the line number.                                                                     |
-| `too-large` | A DOT source exceeded `graphviz.maxSourceBytes`.                                                                                                               |
-| `timeout`   | One render exceeded `renderTimeoutMs`.                                                                                                                         |
-| `config`    | The plugin's global data is missing, or a fence named a layout engine this Graphviz build does not have.                                                       |
-| `aborted`   | The component unmounted or re-rendered; not surfaced to the reader.                                                                                            |
+| Kind        | Cause                                                                                                                                                                                  |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `load`      | `viz-global.js` or `plantuml.js` could not be fetched, timed out, or was not the expected module (usually a proxy or service worker returning the wrong file).                         |
+| `engine`    | The engine threw, or its output could not be used at all.                                                                                                                              |
+| `diagram`   | The source is not valid PlantUML.                                                                                                                                                      |
+| `syntax`    | The source is not valid DOT. Carries Graphviz's own diagnostic, including the line number.                                                                                             |
+| `too-large` | A DOT source exceeded `graphviz.maxSourceBytes`.                                                                                                                                       |
+| `stdlib`    | A `!include <namespace/…>` names a standard library namespace this site does not provide, or the standard library is switched off. See [Standard library](#plantuml-standard-library). |
+| `timeout`   | One render exceeded `renderTimeoutMs`.                                                                                                                                                 |
+| `config`    | The plugin's global data is missing, or a fence named a layout engine this Graphviz build does not have.                                                                               |
+| `aborted`   | The component unmounted or re-rendered; not surfaced to the reader.                                                                                                                    |
 
 The two engines report invalid source very differently:
 
@@ -692,6 +857,10 @@ The two engines report invalid source very differently:
   an "error picture" and reports success, so the rendered SVG is inspected for error markers
   before it is trusted. See [ADR 0002](docs/adr/0002-render-to-string.md) for the exact
   detection rules.
+- **Preprocessor failures carry no `Syntax Error?` marker at all** — `Function not found X`
+  after a macro that the included library version does not define, or `cannot include
+<C4/C4_Nope>` for a file that is not in the namespace. Both are detected by their own
+  signature, and the panel shows the failure rather than the expanded source it sits in.
 - **Invalid DOT is reported as structured data**, so the panel shows Graphviz's own message
   verbatim — `syntax error in line 3 near '}'` — with no heuristics involved.
 
@@ -745,6 +914,10 @@ The runtimes are large:
 | `viz-global.js` | ≈ 1.4 MB            | DOT fences, and PlantUML's own layout |
 | **Total**       | **≈ 8.2 MB**        |                                       |
 
+Standard library namespaces are separate again, and much smaller: one bundle per namespace, 5
+to 220 KB gzipped, fetched only by the pages whose diagrams include them. A C4 page adds 29 KB
+to the figures above; a page with no standard library include adds nothing.
+
 Crucially, **none of that is in your site's initial bundle**. The files are emitted as static
 assets, not imported into the webpack graph (the dynamic import is marked `webpackIgnore`), so:
 
@@ -760,9 +933,12 @@ assets, not imported into the webpack graph (the dynamic import is marked `webpa
 **Adding Graphviz support to a site that already renders PlantUML costs nothing**, because
 `viz-global.js` was already being emitted and loaded.
 
-The published npm package itself is small (the compiled plugin and theme components only);
-the 8 MB comes from the `@plantuml/core` dependency and lands in your build output, not in
-your JavaScript bundle. Budget for roughly 8 MB of extra static assets per deployed site.
+The published npm package is the compiled plugin, its theme components, and ~3 MB of vendored
+standard library bundles; the 8 MB engine comes from the `@plantuml/core` dependency. Both land
+in your build output rather than in your JavaScript bundle, so budget for roughly 11 MB of
+extra static assets per deployed site — of which a given reader downloads the 8 MB engine once
+and only the standard library namespaces their pages actually use. `stdlib.namespaces` narrows
+what is emitted if the build output size matters more to you than which diagrams keep working.
 
 Serve these assets with compression enabled — they are ordinary JavaScript and compress well.
 
@@ -1136,6 +1312,9 @@ Then rebuild. If it persists, remove `node_modules/.cache` and `.docusaurus/` by
   why zoom transforms a wrapper rather than the SVG.
 - [`docs/adr/0004-graphviz-engine-reuse.md`](docs/adr/0004-graphviz-engine-reuse.md) — why DOT
   is rendered with the Graphviz already inside `@plantuml/core`, and what that couples us to.
+- [`docs/adr/0005-stdlib-bundles.md`](docs/adr/0005-stdlib-bundles.md) — how `!include <C4/…>`
+  is resolved, why the engine's own loader has to be short-circuited, and how the vendored set
+  was chosen.
 - [`CONTRIBUTING.md`](CONTRIBUTING.md)
 - [`SECURITY.md`](SECURITY.md)
 

package/assets/stdlib/LICENSES.md

@@ -0,0 +1,21 @@
+# Vendored PlantUML standard library namespaces
+
+These bundles are generated from
+[plantuml/plantuml-stdlib](https://github.com/plantuml/plantuml-stdlib) at commit
+`bdbb819f76c75e7a23af582b2a63ea7dc43eed7c` by `npm run stdlib:update`. Each namespace keeps the licence of its
+own upstream project, listed below. plantuml-stdlib leaves the `license:` field of most
+namespace READMEs empty, so where that is the case the licence was read from the source
+repository and recorded in `scripts/update-stdlib.mjs`. Namespaces whose upstream declares
+no licence at all are not vendored. The MIT licence of this plugin covers the generator,
+not the library content.
+
+| Namespace | Library | Version | Licence | Upstream |
+| --- | --- | --- | --- | --- |
+| `c4` | C4 (C4-PlantUML) | 2.13.0 | MIT | <https://github.com/plantuml-stdlib/C4-PlantUML> |
+| `archimate` | Archimate | 3.2.2 | MIT | <https://github.com/plantuml-stdlib/Archimate-PlantUML> |
+| `azure` | Azure | 2.2.0 | MIT | <https://github.com/plantuml-stdlib/Azure-PlantUML> |
+| `cloudinsight` | Cloudinsight | 1.0.0 | MIT | <https://github.com/plantuml-stdlib/cicon-plantuml-sprites> |
+| `eip` | Eip | 1.0.0 | MIT | <https://github.com/plantuml-stdlib/EIP-PlantUML> |
+| `k8s` | K8s | 1.0.0 | MIT | <https://github.com/dcasati/kubernetes-PlantUML> |
+| `kubernetes` | Kubernetes | 5.3.45 | Apache-2.0 | <https://github.com/plantuml-stdlib/plantuml-kubernetes-sprites> |
+| `office` | Office | 1.0.0 | MIT | <https://github.com/Roemer/plantuml-office> |