umlimator 0.12.1 → 0.13.0

package/README.md

@@ -18,25 +18,40 @@ 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, each view
+  with its text, then the legend and 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 +59,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.13.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 +100,76 @@ 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"`, `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 +187,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 +196,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 +220,37 @@ 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, with its text, the legend, 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.
+`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, A4 across: a title page, then each view on a page of its own, as a
+vector picture with its `describe()` text, then the legend and each rule, holding or broken in the views printed
+([bike-share's](https://zintaen.github.io/umlimator/examples/bike-share.pdf), as CI builds it). It takes `--views` and
+`--theme`, as `stills` does.
+
+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). Needs Python
-3.9+ (standard library only), Google Chrome or Chromium for `stills`, `check` and `record`, and Node 18+ for `diff`
-and `drift`.
+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:
@@ -170,11 +271,39 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: zintaen/umlimator@v0.12.1
+      - uses: zintaen/umlimator@v0.13.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 highlight, the tour and the story off |
+
+- 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. Each tool says whether a page is connected, and gives the URL when none
+  is; a page that connects later shows the latest command, and a page drawn from an older model draws itself again.
+- 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 +332,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 +354,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,19 @@
+// 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 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. */
+  readonly map: Handle | null;
+}
+
+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,77 @@
+/* <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 or controls (controls="false" hides them) draws it again, and
+   removing the element destroys the map. 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 when it
+   can't be (its children show again). `el.map` is render()'s handle once drawn (toSVG(), highlight(), setView() ...),
+   else null. */
+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', 'height'];
+  map = null;
+  #drawn = 0; #due = false; #src = null; #model = null;
+
+  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>';
+  }
+  connectedCallback() { this.#soon(); }
+  disconnectedCallback() { this.#drop(); }
+  attributeChangedCallback(name, was, now) {
+    if (name === 'height') this.style.height = now == null ? '' : /^\d+(\.\d+)?$/.test(now) ? now + 'px' : now;
+    else this.#soon();
+  }
+  #soon() { // attributes set together draw once
+    if (this.#due) return;
+    this.#due = true;
+    queueMicrotask(() => { this.#due = false; if (this.isConnected) this.#draw(); });
+  }
+  #drop() {
+    this.map?.destroy(); this.map = null;
+    const [, slot, box] = this.shadowRoot.children; slot.hidden = false; box.hidden = true;
+  }
+  #fail(err) { this.#drop(); console.warn('<umlimator-map>:', err); this.dispatchEvent(new Event('error')); } // the children show again
+  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 || !this.isConnected) 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', on });
+    } catch (err) { return this.#fail(err); }
+    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, 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', '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;
 }

package/lib/umlimator.d.ts

@@ -13,6 +13,8 @@ export interface MapModel {
   rules?: Rule[];
   /** Narrated walk-throughs of the map (#69): handle.play(id), the standalone page's Stories menu, umlimator.py record. */
   stories?: Story[];
+  /** Saved ways to look at the map (#94): handle.lens(id), the standalone page's Lenses menu and #lens=<id>. */
+  lenses?: Lens[];
   [key: string]: unknown;
 }
 /** A badge: its text, and optionally a palette name for its colour (green, amber, rose, accent, violet ... : --um-<tone>). */
@@ -25,6 +27,8 @@ export interface MapNode {
   opensView?: string;
   /** The number on the ⤢ badge of a card whose view is not loaded yet (else ⤢ alone). A loaded view's cards are counted. */
   opensCount?: number;
+  /** Who owns the card (a team, say): selectors pick by it, and a lens with color 'owner' rings the card in its owner's tone. */
+  owner?: string;
   [key: string]: unknown;
 }
 /** What a line means, drawn as its colour: calls (the default), feeds (hands work on), triggers (suggests, offers, fires),
@@ -52,6 +56,10 @@ export interface MapEdge {
   change?: 'added' | 'removed' | 'changed';
   /** What drift() found: undrawn (traffic ran on it, nobody drew it) or idle (drawn, carried nothing). */
   drift?: 'undrawn' | 'idle';
+  /** Budgets (#95), which critical() sums along a path: how long the call takes, in ms, and what it costs, in any unit.
+   *  Not drawn. */
+  latency?: number;
+  cost?: number;
   [key: string]: unknown;
 }
 export interface MapView {
@@ -115,6 +123,20 @@ export interface RenderOptions {
   /** update() eases into the next model: moved cards glide, new ones fade in, removed ones fade out (#67). Default true;
    *  never under prefers-reduced-motion. false draws the next model at once. */
   ease?: boolean;
+  /** The standalone page's pieces (#99), each on its own or any mix, all off by default. They are drawn inside the map's
+   *  element, around the canvas, with the page's look, keys and --um-* colours; update() and destroy() keep them in step.
+   *  nav: the views list (Miller columns) left of the map, opened and shut by its ☰ button or O; picking a view shows it
+   *  (viewchange). It comes after the map in the tab order, so focus given to the map's element still lands on the map. */
+  nav?: boolean;
+  /** The kinds of cards and lines the view draws, in a box over the map, bottom left, that folds away. */
+  legend?: boolean;
+  /** A line over the map's foot: what the pointer does, and for a while what just happened (a polite live region). */
+  hints?: boolean;
+  /** The selected card's details under the map: its kind, actions and tabs (when, what, how, an example, what it comes
+   *  from and leads to), [ and ] between tabs. Open and Unfold here emit open and expand as the canvas does; → ← ⇄ light
+   *  what the card leads to, what leads to it, and every path between two selected cards (> < P); ⏱ ¤ the slowest and the
+   *  costliest path where the view's lines have latency or cost, and ⊘ what loses its way if the card goes down (#95). */
+  details?: boolean;
   on?: { [K in keyof Events]?: (e: Events[K]) => void };
 }
 
@@ -160,6 +182,11 @@ export interface Handle {
   /** The 'highlight' layer: these cards and lines lit, the rest dimmed (in place of the selection's dimming), or null to clear.
    *  A Ref's level (0 to 1), else its distance (as reach() gives it), fades it. A chip's or badge's Ref lights its card. */
   highlight(refs: Lit[] | null): void;
+  /** Puts one of the model's lenses on the map (#94), or none with null: the 'lens' layer lights what it picks and dims the
+   *  rest, on every view shown, and the view is not laid out again. With color 'owner', each lit card is ringed in its
+   *  owner's tone, and a legend over the controls names them. It stays across update() and setView(); a model without the
+   *  lens takes it off. False when the model has no lens `id`. */
+  lens(id: string | null): boolean;
   /** The tour dot rides the line between each pair of cards in turn (either way), through each card to its next line; a card
    *  it reaches flashes, and a pair with no line between them is skipped. Resolves true at the end, false when cut short (a
    *  new tour or replay, tour(null), a new picture of the view, destroy()). With reduced motion it resolves at once.
@@ -239,9 +266,16 @@ export interface CheckIssue { message: string; targets: Ref[] }
  *  it measures in the DOM (text overflowing its card, titles, edge labels on cards or each other). In Node, text widths
  *  are an estimate unless `measure` is given, so the layout, and what is found, can differ from a browser's. */
 export function check(model: MapModel, viewId: string, options?: { repair?: boolean; measure?: (text: string, px: number) => number; expand?: string[] }): CheckIssue[];
-/** Picks cards by id, kind (as the map draws it: "db" picks databases) or box (at any depth), each a value or a list;
- *  every key given must hold, and `not` turns a selector round. A line's end on a box is that box: in it, of no kind. */
-export interface Selector { id?: string | string[]; kind?: string | string[]; container?: string | string[]; not?: Selector }
+/** Picks cards by id, kind (as the map draws it: "db" picks databases), box (at any depth) or owner, each a value or a
+ *  list; every key given must hold, and `not` turns a selector round. A line's end on a box is that box: in it, of no kind
+ *  and no owner. */
+export interface Selector { id?: string | string[]; kind?: string | string[]; container?: string | string[]; owner?: string | string[]; not?: Selector }
+/** A lens's pick: a Selector, and `line`, line kinds. Without `line` it lights the cards it picks and the lines between two
+ *  of them; with `line`, the lines of those kinds between two cards the rest of it picks, and their ends. */
+export interface LensSelector extends Selector { line?: WireKind | WireKind[] }
+/** A saved way to look at the map (#94): what `pick` picks lit, the rest dimmed (a pick left out lights everything);
+ *  color 'owner' rings each lit card in its owner's tone, with a legend. */
+export interface Lens { id: string; title?: string; pick?: LensSelector; color?: 'owner' }
 /** What the model says must hold (`model.rules`): no line from the cards `from` picks to the cards `to` picks (a side left
  *  out picks every card), or, with noCycles, no boxes that reach each other through their lines (a line counts between
  *  the two boxes that hold its ends right under the box they share). A rule that names a box (a container, or a box's
@@ -261,6 +295,20 @@ export function reach(model: MapModel, viewId: string, from: string, options?: {
 export function describe(model: MapModel, viewId: string): string;
 /** The spans of an OpenTelemetry trace in OTLP JSON (resourceSpans), as replay() takes them. */
 export function otlpSpans(otlp: unknown): Span[];
+/** The path along a view's lines with the highest total of `by` (#95): latency (ms, the default) or cost, summed over its
+ *  lines (a line without one counts 0), from `from` to `to` (either left out: any card), never coming back to a card. Its
+ *  cards in order, then its lines, as Refs for highlight(); no refs and 0 when no line leads there. No browser needed. */
+export function critical(model: MapModel, viewId: string, options?: { from?: string; to?: string; by?: 'latency' | 'cost' }): { refs: Ref[]; total: number };
+/** What taking cards out of a view would cost (#95), with the model left as it is. unreachable: what loses its way to them
+ *  (backward, as reach() finds it: for calls, what depends on them), each with its distance from the nearest, the cards
+ *  themselves at 0. No rule breaks: rules only forbid lines and cycles, which taking cards out never adds. No browser needed. */
+export function whatIf(model: MapModel, viewId: string, options: { remove: string[] }): { unreachable: (Ref & { distance: number })[] };
+/** A trace kept as a numbered view (#96): `model` with a sequence view (render: "sequence") whose steps are the trace's calls
+ *  between cards (a span and its parent's), in time order, each line labelled with its span's name and its duration under
+ *  it. A span's service is a card as replay() matches it (match, else id, else label in any case); the caption names the
+ *  services with no card. The view (id `view`, default "trace") replaces one with that id, else comes last, under the
+ *  view that shows the most of its cards. The model passed in is not changed. */
+export function sequenceFromTrace(model: MapModel, spans: Span[], options?: { view?: string; match?: Record<string, string>; title?: string }): MapModel;
 /** What changed from one model to the next (#66), as one model to draw: `after`, with each card marked added, changed or
  *  removed (`change`: a NEW or CHANGED tab; REMOVED is faded, dashed and struck through) and each line likewise (`style`
  *  added or removed; a changed one `edited`); what left comes back in its views, boxes and places, and a card put into