umlimator 0.12.1 → 0.14.0

package/README.md

@@ -18,25 +18,41 @@ drill-down, a data pipeline, an AI agent's skills, and host pages for embedding,
 - **Unfolding in place**: a stacked card can also open into a box on the map it is on (E, or Alt + click), its inner
   view's cards inside and the lines to it moved onto them, the rest of the picture in its order.
 - **Layout and routing**: columns in reading order, each ordered so the lines cross as little as they can, those that
-  skip columns included; each card level with the cards its lines come from, so lines run straight; orthogonal lines
-  that never run through a card, room for every label, containers kept apart, and cards with no lines in a row of their
-  own, under the view or at the bottom of their box. The same model gives the same picture.
+  skip columns included; each card level with the cards its lines come from, in its box or outside it, so lines run
+  straight; orthogonal lines that never run through a card, room for every label, containers kept apart, and cards with
+  no lines in a row of their own, under the view or at the bottom of their box. The same model gives the same picture.
 - **Reading**: animated flow, neighbours lit on selection, numbered steps, tours, minimap, light and dark themes.
 - **Exploring**: every path between two cards, or everything a card reaches, lit on the map; a view in plain sentences
   (`describe()`); a tour along any path the host names.
 - **Live data**: marks over the map without touching the model (`overlay()`): flow as fast as the traffic, errors that
-  pulse, slow hops that glow, labels and tabs; and an OpenTelemetry trace replayed along its lines (`replay()`).
+  pulse, slow hops that glow, labels and tabs; and an OpenTelemetry trace replayed along its lines (`replay()`), or kept
+  as a numbered view to review in a pull request (`umlimator.py trace`).
+- **Lenses**: saved ways to look at one map, by team or by data flow: what a lens picks lit and the rest dimmed, cards
+  ringed by owner with a legend, from the page's Lenses menu or a link. The view is never laid out again.
+- **Budgets**: lines' latency and cost; the slowest or costliest path lit with its total (`critical()`), and what loses
+  its way if a card goes down (`whatIf()`).
 - **Stories**: walk-throughs in the model, step by step (view, camera, selection, highlight, tour and a caption), played
   on the map (`play()`) or from the page's Stories menu, recorded from the page, and written as an animated PNG.
 - **Keyboard and screen readers**: cards, then lines, in the Tab order (a card's tabs and chips too, for a host that
   listens for click); arrows between cards; selections announced.
+- **The page's pieces, embedded**: the standalone page's views list, details panel, legend and hint line, each one a
+  `render()` option, around the map in the host's own page.
 - **Editing** (opt-in): gestures emit `change` events; the host applies them and calls `update()`.
-- **Export**: any view as a stand-alone SVG or PNG, in the browser or from the CLI.
+- **Export**: any view as a stand-alone SVG or PNG, in the browser or from the CLI; the whole map as one PDF to hand in
+  for a review: a cover with the contents, each view with its legend and tables of its cards, lines and boxes, then the
+  rules (`umlimator.py pdf`).
+- **In docs**: `<umlimator-map src="model.json">` in any page, and an `umlimator` fenced block in VitePress, Docusaurus,
+  MkDocs or any Markdown that allows HTML.
 - **A layout check**: crossings, shared lines, detours, labels on lines, text that overflows its card.
 - **Rules**: what the model says must hold ("apps never call a database directly", "no cycles between teams' boxes"),
   marked on the map where it breaks; `umlimator.py check` fails on a broken rule, so CI does.
 - **Change**: what a pull request changes, marked on the map and said in words (with a GitHub Action that posts it);
   a time-lapse of a model's history, where cards glide, fade in and fade out; and drift, the map against the traffic seen.
+- **Import**: a Structurizr workspace, a C4-PlantUML or Mermaid diagram, or what `docker compose config` and `kubectl get`
+  print as JSON, read into a model (`umlimator.py import`), with what it can't read listed line by line.
+- **An AI assistant on the map**: an MCP server (`umlimator.py mcp`) through which an assistant such as Claude Code reads
+  the model (a view in words, paths, what a card reaches, broken rules, problems, a diff) and drives its page in your
+  browser (a view, a highlight, a tour, a story).
 
 ## Install
 
@@ -44,7 +60,7 @@ drill-down, a data pipeline, an AI agent's skills, and host pages for embedding,
 npm install umlimator
 ```
 
-Or from GitHub, at a tag or any commit: `"umlimator": "github:zintaen/umlimator#v0.12.1"`. npm 12 refuses git
+Or from GitHub, at a tag or any commit: `"umlimator": "github:zintaen/umlimator#v0.14.0"`. npm 12 refuses git
 dependencies unless the project opts in, so that also needs `allow-git=root` in the `.npmrc` next to `package.json`.
 
 ## Embed
@@ -85,15 +101,77 @@ function MapView({ model, onSelect }) {
   rule the model breaks, view by view.
 - `map.overlay(name, layer)`, `highlight(refs)`, `tour(path)` and `replay(spans)` put the host's marks, a tour and a
   trace on the map; `paths()`, `reach()` and `describe()` walk a view and put it in words, in Node too.
+- `map.lens(id)` puts one of the model's lenses on the map. `critical(model, view, { from, to, by })` finds the slowest
+  or costliest path, `whatIf(model, view, { remove })` what loses its way when cards go down, and
+  `sequenceFromTrace(model, spans, { view, match })` keeps a trace as a numbered view; all three in Node too.
 - `editable: true` turns on editing gestures ([docs/editing.md](docs/editing.md); `examples/edit.html` is a working host).
 - `diff(before, after)` returns `after` with each card and line marked added, changed or removed, what changed in words,
   and the views that show it; `drift(model, observed)` marks the lines traffic ran on that nobody drew, and the drawn ones
   that carried nothing. Both are models to draw, in Node too. `update()` eases into the next model (`examples/timelapse.html`);
   the option `ease: false` draws it at once.
-- `mountPage` is the whole standalone viewer that the CLI writes.
+- `mountPage` is the whole standalone viewer that the CLI writes. `render()` can draw its pieces too, each on its own or
+  any mix, inside the map's element; the host keeps its own header:
+
+  ```js
+  render(el, model, { nav: true, details: true, legend: true, hints: true });
+  ```
+
+  - `nav`: the views list left of the map, opened and shut by its ☰ button or O. Picking a view emits `viewchange`.
+  - `details`: the selected card's panel under the map, with its tabs (`[` and `]`). Its Open and Unfold here buttons
+    emit `open` and `expand`, as the canvas does, so a host can load a view first.
+  - `legend` and `hints`: the legend, and the line saying what the pointer does, over the map.
+
+  They share the page's code and look, take the `--um-*` colours (the theme adds `--um-mark` and `--um-scrim` for them),
+  and follow `update()` and `destroy()`. `examples/embed.html` uses them.
 
 The API, its types and the decisions behind it: [docs/module-api.md](docs/module-api.md) and `lib/umlimator.d.ts`.
 
+### In a page or a docs site, as an element
+
+`<umlimator-map>` (`umlimator/element`) loads a model and draws it, with no script of your own. Its children show until
+the map is drawn, and stay where scripts don't run ([`examples/element.html`](examples/element.html)):
+
+```html
+<link rel="stylesheet" href="node_modules/umlimator/lib/umlimator-theme.css">
+<script type="module" src="node_modules/umlimator/lib/umlimator-element.js"></script>
+
+<umlimator-map src="bookshop.json" view="api" minimap height="520">
+  <img src="stills/api.png" alt="An order, step by step">
+</umlimator-map>
+```
+
+- **The model**: `src`, a URL resolved as an `<img>`'s is (a `data:` URL too), or the model in a child
+  `<script type="application/json">`.
+- **Attributes**: `view`, `minimap`, `controls="false"`, `wheel="ctrl"` (the wheel zooms only with Ctrl or ⌘, and scrolls
+  the page otherwise, as a map in a document should), `height` (a number is pixels; 480 by default, or size it in CSS)
+  and `theme` (`light` or `dark`: theme.css's palette for that map, whatever the page's). Changing one draws the map
+  again, and removing the element destroys it.
+- **Events**: `umlimator:select`, `umlimator:open` (cancel it to stay) and `umlimator:viewchange`, the map's event as
+  `detail`; `load` once it is drawn, `error` when it can't be. `el.map` is the `render()` handle.
+- **Colours**: theme.css, as above, or your own `--um-*` variables. The element fetches nothing but its model.
+- **Dark mode**: without `theme`, the map follows the page, a docs site's dark mode included: VitePress's
+  `<html class="dark">` and Docusaurus's `<html data-theme="dark">`.
+
+In a docs site, a fenced block becomes the element. It names the model's `src`, with `view` or any other attribute, or
+holds the model in JSON:
+
+````markdown
+```umlimator
+src: /maps/bookshop.json
+view: api
+```
+````
+
+- **VitePress**: in `.vitepress/config`, `markdown: { config: md => md.use(umlimator) }` (`import umlimator from
+  'umlimator/markdown-it'`) and `vue: { template: { compilerOptions: { isCustomElement: t => t === 'umlimator-map' } } }`;
+  in `.vitepress/theme/index`, `import 'umlimator/element'` and `import 'umlimator/theme.css'`.
+- **Docusaurus**: `remarkPlugins: [umlimator]` (`import umlimator from 'umlimator/remark'`) in the docs preset's options,
+  and a client module (`clientModules: ['./src/umlimator.js']`) that imports `umlimator/element` and
+  `umlimator/theme.css`.
+- **MkDocs, or any site that allows HTML**: write the element itself in the Markdown. Copy `lib/umlimator.js`,
+  `lib/umlimator-element.js` and `lib/umlimator-theme.css` into `docs/js/`, and load them in `mkdocs.yml`:
+  `extra_javascript: [{ path: js/umlimator-element.js, type: module }]` and `extra_css: [js/umlimator-theme.css]`.
+
 ## Model
 
 A model has shared `nodes` and `edges`, and `views` that each show a subset, with optional `containers` (boxes),
@@ -111,6 +189,7 @@ kinds such as `public`, `lane`, `script`, `hook` and `board` work too). Fields b
 | node | `icon` | a logo or line icon from `icons/manifest.json` |
 | node | `noSub` | the name only; the description stays in the details panel |
 | node | `opensView`, `opensCount` | the view the card opens, which may not be loaded yet, and the ⤢ number for it |
+| node | `owner` | who owns the card (a team): rules and lenses pick by it, and a lens can ring cards by owner |
 | node, edge | `edited` | a marker on the card or line |
 | edge | `kind` | what the line means, drawn as its colour: `calls` (default), `feeds`, `triggers`, `state`, `guard` |
 | edge | `weight` | 1, 2 or 3: how much the line stands for, drawn as its width |
@@ -119,14 +198,16 @@ kinds such as `public`, `lane`, `script`, `hook` and `board` work too). Fields b
 | edge | `from`, `to` | may name a container of the view: the line ends on its box |
 | edge | `style: "faded"` | the line in its kind's colour, faint and with no flow (drift's idle lines) |
 | edge | `drift` | what `drift()` found: `undrawn` or `idle` |
+| edge | `latency`, `cost` | budgets, in ms and in any unit: `critical()` sums them along a path (not drawn) |
 | view | `gap`, `rgap` | the space between columns and between rows |
 | view | `keepPairs` | A→B and B→A drawn as two lines |
 | view | `repair: false` | no port repair |
 | view | `subAndChips` | cards 80 px tall that show their sub-line, then their chips |
 | view | `kindsFromLabels` | a line whose edges name no `kind` takes one guessed from its label |
 | container | `badges` | tabs on the box's border |
-| model | `rules` | what must hold: no line `from` some cards `to` others (picked by id, kind or box), or `noCycles` between boxes |
+| model | `rules` | what must hold: no line `from` some cards `to` others (picked by id, kind, box or owner), or `noCycles` between boxes |
 | model | `stories` | walk-throughs: steps that each set the view, camera, selection, highlight, tour and caption |
+| model | `lenses` | ways to look at the map: what `pick` picks (by id, kind, box, owner or `line` kind) lit, the rest dimmed; `color: "owner"` rings cards by owner |
 
 ## Command line
 
@@ -141,15 +222,43 @@ python3 umlimator.py drift model.json traffic.json --out drift.html   # drawn vs
 python3 umlimator.py timelapse model.json --out history.html          # the model's versions in git history, on a slider
 python3 umlimator.py check page.html --expand                          # also each view with each stacked card unfolded
 python3 umlimator.py record bike-share.html --story ride --out ride.png   # bike-share's story as an animated PNG, its tours riding
+python3 umlimator.py import workspace.dsl --out model.json            # a diagram you have already, as a model
+docker compose config --format json > compose.json && python3 umlimator.py import compose.json --out model.json
+kubectl get deploy,sts,svc,ing -A -o json > cluster.json && python3 umlimator.py import cluster.json --out model.json
+python3 umlimator.py pdf page.html --out map.pdf                       # every view in one PDF: a cover, each view with its tables, the rules
+python3 umlimator.py trace model.json trace.json --view ride-end --match match.json --out model.json   # an OTLP trace kept as a numbered view
+python3 umlimator.py mcp model.json                                    # an MCP server over stdio, for an AI assistant (below)
 ```
 
 `check` also reports each rule the model breaks, and then exits 1.
 
-The page has breadcrumbs, a details panel per card, ⌘K search, deep links (`#view=<id>&node=<id>`, and
-`#story=<id>&step=<n>` for a story's step), stories, and export.
-`stills` skips a view whose inputs have not changed since its last export (`--all` exports every view). Needs Python
-3.9+ (standard library only), Google Chrome or Chromium for `stills`, `check` and `record`, and Node 18+ for `diff`
-and `drift`.
+`import` reads Structurizr DSL (people, systems, containers and components, their relationships, and the workspace's
+views), C4-PlantUML (its element, relationship and boundary macros), Mermaid (`flowchart` or `graph`, and `C4Context`,
+`C4Container` or `C4Component`), and the JSON of `docker compose config` (services, `depends_on`, networks) and of
+`kubectl get` (workloads, Services, Ingresses). It tells the format from the content, then the extension; `--format`
+decides. Groups, boundaries, subgraphs, networks and namespaces become boxes; Structurizr's views stay views, a card
+opening the view below it; `examples/clinic.json` is `examples/clinic.dsl`, imported. What each element becomes, and
+what is left out: [docs/module-api.md § Import](docs/module-api.md#import-90). Whatever the file holds that `import`
+doesn't read is listed on stderr with its line (in JSON, its path).
+
+`pdf` prints the map through Chrome's own print, as a document to hand in for a review
+([bike-share's](https://zintaen.github.io/umlimator/examples/bike-share.pdf), as CI builds it). A cover has the title,
+the date, the model's file, a summary line and the contents with each view's page. Each view starts a page of its own,
+under its path ("Bike share › What runs"): its picture in vectors, as large as the page allows, the legend of what it
+draws, and tables of its cards, lines and boxes, which go on over the next pages with their header row when they are
+long. The rules follow as a table, when the model has any, each holding or broken in the views printed. Every page ends in
+the title and "page N of M". It takes `--views` and `--theme`, as `stills` does, and `--paper a4|letter` (A4 is the
+default; both across).
+
+The page has breadcrumbs, a details panel per card (with the slowest path from it and what-if), ⌘K search, deep links
+(`#view=<id>&node=<id>`, `#story=<id>&step=<n>` for a story's step, and `#lens=<id>`), stories, lenses, and export. For
+scripts and tests, it keeps its map's handle on `window.umlimatorMap`: the `Handle` that `render()` returns (`setView()`,
+`highlight()`, `tour()`, `play()` ...).
+`stills` skips a view whose inputs have not changed since its last export (`--all` exports every view), and exits 1,
+saying why, when a view can't be exported. In `stills`, `check` and `pdf`, `--views` takes view ids, and a trailing `*`
+is a prefix; a name that matches no view is an error. A command that fails leaves its previous output as it was. Needs Python
+3.9+ (standard library only), Google Chrome or Chromium for `stills`, `check`, `record` and `pdf`, and Node 18+ for
+`diff`, `drift`, `trace` and `mcp`.
 
 `record` writes an animated PNG, which browsers and GitHub show as it is. For a GIF or an MP4 (for chat or slides),
 convert it with ffmpeg:
@@ -160,21 +269,57 @@ ffmpeg -f apng -i ride.png -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2" -pix_fmt yuv4
 ```
 
 On pull requests, the diff Action posts what they change in your maps: one comment with the summary and a sketch, and
-the pictures as the run's artifact.
+the pictures as the run's artifact. The comment names the commit it describes, only the run for the pull request's
+latest commit writes it, and it says so when the diff fails.
 
 ```yaml
 on: pull_request
 permissions: { contents: read, pull-requests: write }
+concurrency: { group: "maps-${{ github.event.pull_request.number }}", cancel-in-progress: true }   # one run per pull request
 jobs:
   maps:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: zintaen/umlimator@v0.12.1
+      - uses: zintaen/umlimator@v0.14.0
         with:
           models: "docs/*.json"   # optional: where the models are (default: every .json that is a map model)
 ```
 
+## An AI assistant on the map (MCP)
+
+`umlimator.py mcp model.json` is a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio: an AI
+assistant reads the model, and shows you what it finds on the map in your browser. Add it to Claude Code:
+
+```bash
+claude mcp add umlimator -- python3 /path/to/umlimator.py mcp /path/to/model.json
+```
+
+| Tool | What it does |
+|---|---|
+| `list_views()` | the views (id, title, parent, number of cards) and the stories |
+| `describe_view(view)` | the view in sentences (`describe()`), then each card's id |
+| `paths(view, from, to)` | every card and line on a path from one card to another (`paths()`), as Refs for `highlight` |
+| `reach(view, card, backward?, depth?)` | what a card leads to, or what leads to it, with the distance of each (`reach()`) |
+| `broken_rules()`, `validate()` | each break of the model's `rules` (`rules()`), and its own problems (`validate()`) |
+| `diff(other_model_path)` | what changed from another model file to this one, in words, and the views that show it (`diff()`) |
+| `show_view(view)` | shows a view on the page |
+| `highlight(refs, view?)` | lights cards and lines (their ids, or the Refs `paths` and `reach` give) and dims the rest |
+| `tour(cards, view?)` | a dot rides the lines through these cards |
+| `play_story(id)`, `clear()` | plays one of the model's stories; takes the assistant's highlight, tour and story off |
+| `page_state()` | what each open page shows (its map's `state`: view, selection, layers, story, camera), and whether the model renders |
+
+- The read tools run the module's own functions in Node on the model file, read again at each call, so edits show up.
+- The page tools drive the map's page, which the server serves at `http://127.0.0.1:7391` (`--port N`, or another port
+  when that one is taken). Open it in a browser.
+  - A tool answers "shown" once a page has shown it, or says why none did: the page's own error, or a tab in the
+    background that didn't finish in time. With no page open, it gives the URL.
+  - A page that opens later shows what the assistant built: the view, with the highlight on it, and a tour or story
+    still under way.
+  - The assistant's highlight is a layer of its own (`mcp`): off on another view, back on its own.
+  - A model that stops rendering keeps the last page that did, and the tools and the page say why.
+- The server listens on 127.0.0.1 only and fetches nothing, so a logo not in the cache yet keeps its card's sigil.
+
 ## Map a repo with Claude Code
 
 The `map-repo` skill reads a codebase, writes a C4-style model (context, containers, components), renders it to a page
@@ -203,11 +348,13 @@ python3 -I tools/fetch_icons.py icons "name:lucide/<icon>"   # a line icon
 python3 umlimator.py pin-icons                                # records each new logo's sha256
 ```
 
+With `UMLIMATOR_OFFLINE=1` the CLI fetches nothing: a logo not in the cache keeps its card's sigil (`mcp` sets it).
+
 ## Development
 
 ```bash
 node --test                 # layout() in Node: the bench views' geometry and the layout rules
-python3 tests/embed.py      # render() in headless Chrome: events, keyboard, colours, contrast, editing
+python3 tests/embed.py      # render() in headless Chrome: events, keyboard, colours, contrast, editing, the element
 python3 bench/bench.py --check-determinism --expect bench/expected.json --max-ms m50=2000
 ```
 
@@ -223,9 +370,11 @@ Release with that section as its notes, and publishes the package to npm (truste
 CI also publishes the examples to GitHub Pages from `main`.
 
 ```
-umlimator.py                 CLI: render, stills, check, record, pin-icons, diff, drift, timelapse
+umlimator.py                 CLI: render, stills, check, record, pdf, pin-icons, diff, drift, timelapse, import, trace, mcp
+umlimator_import.py          import's readers: Structurizr DSL, C4-PlantUML, Mermaid, compose and Kubernetes JSON
+umlimator_mcp.py             the MCP server that `umlimator.py mcp` runs
 action.yml                   the diff Action: what a pull request changes in its maps, posted on it
-lib/                         the module (umlimator.js), its types and the default theme
+lib/                         the module (umlimator.js), its types, the default theme, <umlimator-map> and the docs plugins
 engine/                      the page templates the CLI inlines the module into; the upstream renderer and schema
 docs/                        the module's API and the editing design
 tests/, bench/               tests, benchmark models and results

package/lib/umlimator-element.d.ts

@@ -0,0 +1,21 @@
+// Types for lib/umlimator-element.js, `umlimator/element` (#92). Its header says what each attribute and event does.
+import type { Events, Handle } from './umlimator.js';
+
+/** <umlimator-map src view minimap controls wheel theme height>: the model from `src` (a URL) or a child
+ *  <script type="application/json">, drawn by render(); its other children show until the map is drawn. */
+export class UmlimatorMap extends HTMLElement {
+  /** render()'s handle once the map is drawn (each `load` event), else null. Its `state` is the map's MapState. */
+  readonly map: Handle | null;
+  /** True while a draw waits for its model (0.14.0); `map` is then still the map drawn last. `load` or `error` ends it. */
+  readonly loading: boolean;
+}
+
+declare global {
+  interface HTMLElementTagNameMap { 'umlimator-map': UmlimatorMap }
+  /** The map's events, re-dispatched on the element (they bubble); preventDefault() on umlimator:open keeps the view. */
+  interface HTMLElementEventMap {
+    'umlimator:select': CustomEvent<Events['select']>;
+    'umlimator:open': CustomEvent<Events['open']>;
+    'umlimator:viewchange': CustomEvent<Events['viewchange']>;
+  }
+}

package/lib/umlimator-element.js

@@ -0,0 +1,89 @@
+/* <umlimator-map> (#92): a map in any page from HTML alone, as `umlimator/element`.
+
+     <umlimator-map src="model.json" view="system" minimap height="560">
+       <img src="system.png" alt="The system view">
+     </umlimator-map>
+
+   The model comes from `src`, a URL (a data: URL too), or from a child <script type="application/json">, and render()
+   draws it in the element's shadow root. The element's other children (a still, say) show until the map is drawn, and stay
+   where scripts don't run. Changing src, view, minimap, controls (controls="false" hides them) or wheel draws it again,
+   and removing the element destroys the map. wheel="ctrl": the wheel zooms only with Ctrl or ⌘, and scrolls the page
+   otherwise, as a map in a document should. height: a number is pixels (default 480px; CSS may size it instead). theme:
+   "light" or "dark", that map's palette from lib/umlimator-theme.css, whatever the page's; without it the map follows the
+   page, a docs site's dark mode too (VitePress's html.dark, Docusaurus's html[data-theme="dark"]). The colours come from
+   that file or the host's own --um-* variables; the element fetches nothing but its model.
+   Events: the map's select, open and viewchange as umlimator:select, umlimator:open and umlimator:viewchange, the map's
+   event as `detail` (preventDefault() on umlimator:open keeps the view); load each time the map is drawn, error (an
+   ErrorEvent, whose message says why) when it can't be, a model with no view to draw too (its children show again).
+   `el.map` is render()'s handle once drawn (toSVG(), highlight(), setView(), state ...), else null; `el.loading` is true
+   while a draw waits for its model, when el.map is still the map drawn last. An attribute set to the value it has draws
+   nothing again. */
+import { render } from './umlimator.js';
+
+const Base = globalThis.HTMLElement || class {}; // importable where there is no DOM (a docs site's server render)
+
+export class UmlimatorMap extends Base {
+  static observedAttributes = ['src', 'view', 'minimap', 'controls', 'wheel', 'height'];
+  map = null;
+  #drawn = 0; #due = false; #src = null; #model = null; #loading = false;
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' }).innerHTML = '<style>:host { display: block; height: 480px; overflow: hidden; } ::slotted(img) { display: block; max-width: 100%; max-height: 100%; }</style>'
+      + '<slot></slot><div hidden style="height: 100%"></div>';
+  }
+  get loading() { return this.#loading; } // a draw under way, waiting for its model (0.14.0)
+  connectedCallback() { this.#soon(); }
+  disconnectedCallback() { this.#loading = false; this.#drop(); }
+  attributeChangedCallback(name, was, now) {
+    if (was === now) return; // set to the value it has: nothing to draw again (0.14.0)
+    if (name === 'height') this.style.height = now == null ? '' : /^\d+(\.\d+)?$/.test(now) ? now + 'px' : now;
+    else this.#soon();
+  }
+  #soon() { // attributes set together draw once
+    this.#loading = true;
+    if (this.#due) return;
+    this.#due = true;
+    queueMicrotask(() => { this.#due = false; if (this.isConnected) this.#draw(); else this.#loading = false; });
+  }
+  #drop() {
+    this.map?.destroy(); this.map = null;
+    const [, slot, box] = this.shadowRoot.children; slot.hidden = false; box.hidden = true;
+  }
+  #fail(err) { // the children show again, and the error event says why
+    this.#loading = false; this.#drop(); console.warn('<umlimator-map>:', err);
+    this.dispatchEvent(new ErrorEvent('error', { message: String((err && err.message) || err), error: err }));
+  }
+  async #draw() {
+    const n = ++this.#drawn, src = this.getAttribute('src'), get = a => this.getAttribute(a); // a later draw wins
+    let model = src && src === this.#src ? this.#model : null;
+    try {
+      if (src && !model) {
+        const r = await fetch(src);
+        if (!r.ok) throw new Error(`${src}: ${r.status} ${r.statusText}`);
+        model = await r.json();
+      } else if (!src) {
+        const json = this.querySelector(':scope > script[type="application/json"]');
+        if (!json) throw new Error('no src, and no <script type="application/json"> child');
+        model = JSON.parse(json.textContent);
+      }
+    } catch (err) { if (n === this.#drawn) this.#fail(err); return; }
+    if (n !== this.#drawn) return; // a later draw has the element
+    if (!this.isConnected) { this.#loading = false; return; }
+    if (src) { this.#src = src; this.#model = model; }
+    this.#drop();
+    const [, slot, box] = this.shadowRoot.children; slot.hidden = true; box.hidden = false;
+    // the map's events, as DOM events on the element; a host that cancels umlimator:open cancels the open
+    const on = Object.fromEntries(['select', 'open', 'viewchange'].map(t => [t, e => {
+      if (!this.dispatchEvent(new CustomEvent('umlimator:' + t, { detail: e, bubbles: true, composed: true, cancelable: t === 'open' }))) e.preventDefault();
+    }]));
+    try {
+      this.map = render(box, model, { view: get('view') || undefined, minimap: this.hasAttribute('minimap') && get('minimap') !== 'false', controls: get('controls') !== 'false', wheel: get('wheel') === 'ctrl' ? 'ctrl' : 'zoom', on });
+    } catch (err) { return this.#fail(err); }
+    if (this.map.view == null) return this.#fail(new Error(`${src || 'the inline model'}: the model has no view to draw`)); // drawn, with nothing to see: an error, not a load (0.14.0)
+    this.#loading = false;
+    this.dispatchEvent(new Event('load'));
+  }
+}
+
+if (globalThis.customElements && !customElements.get('umlimator-map')) customElements.define('umlimator-map', UmlimatorMap);

package/lib/umlimator-markdown-it.d.ts

@@ -0,0 +1,6 @@
+// Types for lib/umlimator-markdown-it.js, `umlimator/markdown-it` (#92).
+/** A markdown-it plugin: each ```umlimator fenced block becomes a <umlimator-map> element. md.use(umlimator) */
+export default function umlimator(md: any): void;
+/** A block's text as the element's attributes (src, view, minimap, controls, theme, height), an inline model as a data:
+ *  URL in src. Throws on a block the element can't use. */
+export function attrs(text: string): Record<string, string>;

package/lib/umlimator-markdown-it.js

@@ -0,0 +1,33 @@
+/* A markdown-it plugin (VitePress, or any markdown-it), as `umlimator/markdown-it` (#92): a ```umlimator fenced block
+   becomes a <umlimator-map> element, which `umlimator/element` draws in the browser. md.use(umlimator)
+
+     ```umlimator
+     src: /maps/shop.json
+     view: api
+     ```
+
+   The block's `key: value` lines are the element's attributes (src, view, minimap, controls, wheel, theme, height); after
+   them, or instead of src, it may hold a model in JSON. An inline model goes into src as a data: URL, since VitePress
+   compiles the page as a Vue template, which drops a <script> child. A block the element can't use fails the build,
+   where it is seen. */
+const KEYS = ['src', 'view', 'minimap', 'controls', 'wheel', 'theme', 'height'];
+
+/** A block's text as the element's attributes. */
+export function attrs(text) {
+  const at = text.search(/^\s*\{/m), out = {};
+  for (const line of (at < 0 ? text : text.slice(0, at)).split('\n').filter(l => l.trim())) {
+    const m = line.match(/^\s*([\w-]+)\s*:\s*(.*?)\s*$/);
+    if (!m || !KEYS.includes(m[1])) throw new Error(`umlimator block: "${line.trim()}" is not one of ${KEYS.map(k => k + ':').join(' ')} or a model in JSON`);
+    out[m[1]] = m[2];
+  }
+  if ((at >= 0) === !!out.src) throw new Error('umlimator block: give either src: (a model\'s URL) or a model in JSON');
+  if (at >= 0) out.src = 'data:application/json,' + encodeURIComponent(JSON.stringify(JSON.parse(text.slice(at)))); // minified; a broken model throws
+  return out;
+}
+
+const html = text => `<umlimator-map${Object.entries(attrs(text)).map(([k, v]) => ` ${k}="${v.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;')}"`).join('')}></umlimator-map>\n`;
+
+export default function umlimator(md) {
+  const fence = md.renderer.rules.fence;
+  md.renderer.rules.fence = (tokens, i, ...rest) => tokens[i].info.trim().split(/\s+/)[0] === 'umlimator' ? html(tokens[i].content) : fence(tokens, i, ...rest);
+}

package/lib/umlimator-remark.d.ts

@@ -0,0 +1,4 @@
+// Types for lib/umlimator-remark.js, `umlimator/remark` (#92).
+/** A remark plugin: each ```umlimator fenced block becomes a <umlimator-map> element (a node with data.hName, which MDX
+ *  and remark-rehype draw as it). remarkPlugins: [umlimator] */
+export default function umlimator(): (tree: any) => void;

package/lib/umlimator-remark.js

@@ -0,0 +1,13 @@
+/* A remark plugin (Docusaurus, MDX, or any remark-rehype pipeline), as `umlimator/remark` (#92): a ```umlimator fenced
+   block becomes a <umlimator-map> element, with the attributes umlimator/markdown-it gives it (its header says what a
+   block holds). The block's node becomes one that names the element (data.hName, data.hProperties), which MDX and
+   remark-rehype both turn into it. remarkPlugins: [umlimator] */
+import { attrs } from './umlimator-markdown-it.js';
+
+export default function umlimator() {
+  const walk = node => node.children?.forEach((c, i) => {
+    if (c.type === 'code' && c.lang === 'umlimator') node.children[i] = { type: 'umlimator', data: { hName: 'umlimator-map', hProperties: attrs(c.value) }, children: [] };
+    else walk(c);
+  });
+  return walk;
+}

package/lib/umlimator-theme.css

@@ -1,4 +1,6 @@
-/* umlimator's default palette and fonts: light, and dark when the system asks or <html data-theme="dark">.
+/* umlimator's default palette and fonts: light, and dark when the system asks or <html data-theme="dark">; a
+   <umlimator-map theme="light|dark"> takes that palette whatever the page's, and one without a theme is dark in a docs
+   site's dark mode too (VitePress's <html class="dark">, Docusaurus's <html data-theme="dark">).
    The canvas reads only these --um-* variables (it bakes in no colour and loads no font), so a host may use this file,
    set the variables itself (e.g. --um-bg: var(--surface)), or switch light and dark by changing them on any ancestor
    of the map. Fonts are the host's: --um-sans and --um-mono name families the page already has; nothing is fetched.
@@ -6,7 +8,7 @@
    The tints (--um-<tone>-f) below are for page chrome: the map mixes its own from the tones and --um-panel in effect
    where it is, so setting a tone on any ancestor of the map recolours its tint too. */
 /* Clean flowchart (GitHub Primer-like): light first, dark when the system or the toggle asks. */
-:root {
+:root, umlimator-map[theme="light"] {
   --um-stage-bg: #fbfcfd; --um-logo-tile: #ffffff; --um-logo-tile-dark: #1b1f23; --um-intake-mark: #1b1f23; --um-edited: #bf8700;
   --um-bg: #ffffff; --um-bg-2: #f6f8fa; --um-panel: #ffffff; --um-panel-2: #f6f8fa; --um-border: #d8dee4; --um-border-2: #d1d9e0;
   --um-text: #1f2328; --um-muted: #59636e; --um-dim: #818b98; --um-grid: rgba(31,35,40,.06); --um-mask: #ffffff; --um-arrow: #8c959f;
@@ -16,6 +18,7 @@
   --um-k-public: #0969da; --um-k-lane: #0f766e; --um-k-ext: #8250df; --um-k-verb: #bf3989; --um-k-script: #6e7781; --um-k-hook: #cf222e; --um-k-board: #9a6700;
   --um-w-calls: #424a53; --um-w-feeds: #0969da; --um-w-triggers: #8250df; --um-w-state: #868f99; --um-w-guard: #cf222e;
   --um-add-bg: rgba(26,127,55,.10); --um-add-tx: #1a7f37; --um-del-bg: rgba(207,34,46,.08); --um-del-tx: #cf222e;
+  --um-mark: #fff1a6; --um-scrim: rgba(15,18,22,.72); /* the details panel's ==highlighter==, and the dark behind an example shown full size */
   color-scheme: light;
   --um-accent-f: color-mix(in srgb, var(--um-accent) 12%, var(--um-panel));
   --um-cyan-f: color-mix(in srgb, var(--um-cyan) 9%, var(--um-panel));
@@ -46,11 +49,12 @@
   --um-cyan: #4493f8; --um-green: #3fb950; --um-violet: #ab7df8; --um-amber: #d29922; --um-rose: #f85149; --um-orange: #db6d28; --um-slate: #9198a1; --um-fuchsia: #db61a2;
   --um-k-public: #4493f8; --um-k-lane: #2dd4bf; --um-k-ext: #ab7df8; --um-k-verb: #f778ba; --um-k-script: #9198a1; --um-k-hook: #f85149; --um-k-board: #d29922;
   --um-w-calls: #b7bdc8; --um-w-feeds: #4493f8; --um-w-triggers: #ab7df8; --um-w-state: #59626e; --um-w-guard: #f85149;
-  --um-add-bg: rgba(63,185,80,.13); --um-add-tx: #56d364; --um-del-bg: rgba(248,81,73,.12); --um-del-tx: #ff7b72;
+  --um-add-bg: rgba(63,185,80,.13); --um-add-tx: #56d364; --um-del-bg: rgba(248,81,73,.12); --um-del-tx: #ff7b72; --um-mark: rgba(250,204,21,.32);
   color-scheme: dark;
   }
 }
-:root[data-theme="dark"] {
+/* the docs sites' dark mode: :where() weighs nothing, so a host's own --um-* on the element still win */
+:root[data-theme="dark"], umlimator-map[theme="dark"], :where(html.dark, html[data-theme="dark"]) :where(umlimator-map:not([theme])) {
   --um-stage-bg: var(--um-bg-2); --um-edited: #d29922;
   --um-bg: #0d1117; --um-bg-2: #010409; --um-panel: #0d1117; --um-panel-2: #151b23; --um-border: #262c36; --um-border-2: #3d444d;
   --um-text: #f0f6fc; --um-muted: #9198a1; --um-dim: #656c76; --um-grid: rgba(240,246,252,.05); --um-mask: #0d1117; --um-arrow: #656c76;
@@ -59,6 +63,6 @@
   --um-cyan: #4493f8; --um-green: #3fb950; --um-violet: #ab7df8; --um-amber: #d29922; --um-rose: #f85149; --um-orange: #db6d28; --um-slate: #9198a1; --um-fuchsia: #db61a2;
   --um-k-public: #4493f8; --um-k-lane: #2dd4bf; --um-k-ext: #ab7df8; --um-k-verb: #f778ba; --um-k-script: #9198a1; --um-k-hook: #f85149; --um-k-board: #d29922;
   --um-w-calls: #b7bdc8; --um-w-feeds: #4493f8; --um-w-triggers: #ab7df8; --um-w-state: #59626e; --um-w-guard: #f85149;
-  --um-add-bg: rgba(63,185,80,.13); --um-add-tx: #56d364; --um-del-bg: rgba(248,81,73,.12); --um-del-tx: #ff7b72;
+  --um-add-bg: rgba(63,185,80,.13); --um-add-tx: #56d364; --um-del-bg: rgba(248,81,73,.12); --um-del-tx: #ff7b72; --um-mark: rgba(250,204,21,.32);
   color-scheme: dark;
 }