umlimator 0.13.0 → 0.15.0

package/README.md

@@ -22,6 +22,11 @@ drill-down, a data pipeline, an AI agent's skills, and host pages for embedding,
   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.
+- **Card shapes**: three notations. `box` (the default) draws every card as a rounded box, as before. `c4` draws people,
+  browser apps, phones, databases, queues and files as the C4 model's tools do. `uml` draws UML 2.5's actors, nodes,
+  artifacts, packages and data stores, with UML's component icon on a box. A card's own `shape` wins in any notation.
+  The notation comes from the model, a view, `render()`, the page's toggle or the link; switching it draws the cards
+  again and lays nothing out ([`examples/notations.html`](examples/notations.html)).
 - **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
@@ -38,8 +43,9 @@ drill-down, a data pipeline, an AI agent's skills, and host pages for embedding,
 - **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; the whole map as one PDF, each view
-  with its text, then the legend and the rules (`umlimator.py pdf`).
+- **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.
@@ -59,7 +65,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.13.0"`. npm 12 refuses git
+Or from GitHub, at a tag or any commit: `"umlimator": "github:zintaen/umlimator#v0.15.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
@@ -94,7 +100,8 @@ function MapView({ model, onSelect }) {
 - `map.expand(id)` unfolds a stacked card in place and `map.collapse(id)` folds it; `layout(model, view, { expand })`
   draws the same in Node.
 - Colours are `--um-*` CSS variables, fonts are the host's (`--um-sans`, `--um-mono`), text is measured in that font,
-  and nothing is fetched.
+  and nothing is fetched. `--um-tint` sets how deep the cards' and the boxes' tints are: 1 by default, 0 for none, 2 for
+  twice as deep (a tint stops at 18% of its colour, so text on it keeps 4.5:1).
 - `layout(model, viewId)` returns a view's geometry without a DOM, in Node too; `check(model, viewId)` runs the layout
   check on it, and `validate(model)` finds dangling or repeated ids before anything is drawn. `rules(model)` lists every
   rule the model breaks, view by view.
@@ -103,6 +110,9 @@ function MapView({ model, onSelect }) {
 - `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.
+- `shapes: 'box' | 'c4' | 'uml'` draws every view in that notation, over each view's own (and the model's).
+  `map.shapes` reads the notation shown and sets another (`null`: each view's own again); the cards are drawn again from
+  the geometry they have, with the camera, selection and marks kept, and nothing is laid out.
 - `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
@@ -141,9 +151,11 @@ the map is drawn, and stay where scripts don't run ([`examples/element.html`](ex
 
 - **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)
+- **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.
+  again, and removing the element destroys it. `shapes` (`box`, `c4` or `uml`) is the notation; changing it draws the
+  cards again in the map drawn, with nothing loaded or laid out again.
 - **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.
@@ -188,9 +200,11 @@ kinds such as `public`, `lane`, `script`, `hook` and `board` work too). Fields b
 | 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 | `shape` | the card's own shape in every notation: `box`, `person`, `browser`, `mobile`, `cylinder`, `pipe`, `document`, `hexagon`, `robot`, `terminal`, `window`, `folder` or `node` |
 | 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 |
+| edge | `step` | a number (2, or 2.1) or text of up to 3 characters (2a), in a circle on the line in any view (a pill for 2 or 3 characters): the order things happen, shown as written in the line's name and title. A numbered view numbers its lines in run order instead |
 | edge | `sublabel` | a second, smaller line under the label |
 | edge | `fromSide`, `toSide` | the card sides the line uses |
 | edge | `from`, `to` | may name a container of the view: the line ends on its box |
@@ -202,7 +216,9 @@ kinds such as `public`, `lane`, `script`, `hook` and `board` work too). Fields b
 | 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 |
+| view, model | `shapes` | the notation the cards are drawn in: `box` (default), `c4` or `uml`; a view's wins over the model's ([what each draws](docs/module-api.md#card-shapes-box-c4-and-uml)) |
 | container | `badges` | tabs on the box's border |
+| container | `tone` | a palette name, as a badge's: the region behind the box tinted in it, its border dashed and its title in the tone (in `c4`, every box is dashed) |
 | 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 |
@@ -223,7 +239,7 @@ python3 umlimator.py record bike-share.html --story ride --out ride.png   # bike
 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 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)
 ```
@@ -237,18 +253,28 @@ views), C4-PlantUML (its element, relationship and boundary macros), Mermaid (`f
 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.
+doesn't read is listed on stderr with its line (in JSON, its path). A Structurizr, C4-PlantUML or Mermaid C4 source is
+drawn in the `c4` notation: its people as people (`person`, or `user` outside the system), its phone apps as phones. A
+Structurizr workspace's `styles` give its elements their shapes (`shape Person`, `Cylinder`, `WebBrowser`, ...), in
+Structurizr's own order; a shape the map has no counterpart for is listed in `notImported`.
+
+`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
+(`#view=<id>&node=<id>`, `#story=<id>&step=<n>` for a story's step, `#lens=<id>` and `#shapes=c4`), stories, lenses, a
+card shapes toggle next to ◐ (box, c4, uml; the page keeps the reader's choice), 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
+`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`.
 
@@ -261,17 +287,19 @@ 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.13.0
+      - uses: zintaen/umlimator@v0.15.0
         with:
           models: "docs/*.json"   # optional: where the models are (default: every .json that is a map model)
 ```
@@ -296,12 +324,18 @@ claude mcp add umlimator -- python3 /path/to/umlimator.py mcp /path/to/model.jso
 | `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 |
+| `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. 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.
+  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

package/lib/umlimator-element.d.ts

@@ -1,11 +1,13 @@
 // 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
+/** <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. */
+  /** 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 {

package/lib/umlimator-element.js

@@ -6,45 +6,57 @@
 
    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:
+   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 when it
-   can't be (its children show again). `el.map` is render()'s handle once drawn (toSVG(), highlight(), setView() ...),
-   else null. */
+   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).
+   shapes: "box", "c4" or "uml", the notation every view is drawn in (0.15.0; without it each view's own); changing it
+   draws the cards again in the map drawn, with nothing laid out 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', 'height'];
+  static observedAttributes = ['src', 'view', 'minimap', 'controls', 'wheel', 'height', 'shapes'];
   map = null;
-  #drawn = 0; #due = false; #src = null; #model = 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.#drop(); }
+  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 if (name === 'shapes' && this.map && !this.#loading) this.map.shapes = now || null; // the map drawn, in another notation: no new draw
     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(); });
+    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) { this.#drop(); console.warn('<umlimator-map>:', err); this.dispatchEvent(new Event('error')); } // the children show again
+  #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;
@@ -59,7 +71,8 @@ export class UmlimatorMap extends Base {
         model = JSON.parse(json.textContent);
       }
     } catch (err) { if (n === this.#drawn) this.#fail(err); return; }
-    if (n !== this.#drawn || !this.isConnected) 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;
@@ -68,8 +81,10 @@ export class UmlimatorMap extends Base {
       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 });
+      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', shapes: get('shapes') || undefined, 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'));
   }
 }

package/lib/umlimator-markdown-it.js

@@ -6,11 +6,11 @@
      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'];
+   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) {

package/lib/umlimator-theme.css

@@ -39,13 +39,17 @@
   --um-sans: Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif;
   --um-mono: "JetBrains Mono", ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
 }
+/* How deep the map's tints are, in either theme: a card's kind colour, and a box's tone (containers[].tone). 1 is as
+   drawn here, 0 is none (plain panels), 2 twice as deep. The map stops a tint at 18% of its colour, where a card's
+   sub-line would fall below 4.5:1. Set it on the map or any ancestor; on :root only, so a map's own setting wins. */
+:root { --um-tint: 1; }
 @media (prefers-color-scheme: dark) {
   :root:not([data-theme="light"]) {
   --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;
   --um-shadow: 0 10px 30px rgba(1,4,9,.55); --um-dot: #161b22; --um-gridline: transparent; --um-chrome: rgba(13,17,23,.92);
-  --um-accent: #4493f8; --um-accent-fg: #ffffff; --um-lane: rgba(240,246,252,.025);
+  --um-accent: #4493f8; --um-accent-fg: #0d1117; --um-lane: rgba(240,246,252,.025);
   --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;
@@ -59,7 +63,7 @@
   --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;
   --um-shadow: 0 10px 30px rgba(1,4,9,.55); --um-dot: #161b22; --um-gridline: transparent; --um-chrome: rgba(13,17,23,.92);
-  --um-accent: #4493f8; --um-accent-fg: #ffffff; --um-lane: rgba(240,246,252,.025);
+  --um-accent: #4493f8; --um-accent-fg: #0d1117; --um-lane: rgba(240,246,252,.025);
   --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;

package/lib/umlimator.d.ts

@@ -15,8 +15,16 @@ export interface MapModel {
   stories?: Story[];
   /** Saved ways to look at the map (#94): handle.lens(id), the standalone page's Lenses menu and #lens=<id>. */
   lenses?: Lens[];
+  /** The notation every view's cards are drawn in (0.15.0; a view's own `shapes` wins). Default 'box'. */
+  shapes?: Notation;
   [key: string]: unknown;
 }
+/** How cards are drawn (0.15.0): box (every card a rounded box, the default), c4 (people, browser apps, phones, databases,
+ *  queues and files as the C4 model's tools draw them) or uml (UML 2.5's actor, node, artifact, package and data store,
+ *  and the component icon on a box). Each shape keeps to its card's box: the layout is the same in every notation. */
+export type Notation = 'box' | 'c4' | 'uml';
+/** A card's shape (0.15.0). */
+export type Shape = 'box' | 'person' | 'browser' | 'mobile' | 'cylinder' | 'pipe' | 'document' | 'hexagon' | 'robot' | 'terminal' | 'window' | 'folder' | 'node';
 /** A badge: its text, and optionally a palette name for its colour (green, amber, rose, accent, violet ... : --um-<tone>). */
 export type Badge = string | { text: string; tone?: string };
 export interface MapNode {
@@ -29,6 +37,8 @@ export interface MapNode {
   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;
+  /** The card's own shape, in every notation (0.15.0); without it, the notation draws the card by its kind. */
+  shape?: Shape;
   [key: string]: unknown;
 }
 /** What a line means, drawn as its colour: calls (the default), feeds (hands work on), triggers (suggests, offers, fires),
@@ -45,6 +55,13 @@ export interface MapEdge {
    *  hit line growing with it. The host picks the bucket (say under 10, under 100, 100 or more relations); anything else is 1.
    *  A line that stands for several edges takes the largest. */
   weight?: 1 | 2 | 3;
+  /** Its place in the order things happen, drawn in a circle on the line before its label, as a numbered view draws its
+   *  steps, in any view: 2, 2.1 for a step within step 2, or text of up to 3 characters such as "2a" (a pill for 2 or 3
+   *  characters). The line's name and title say it as written ("Step 2a: …"); in order, 2 < 2a < 2b < 3. A numbered view
+   *  (`render: 'sequence'`) numbers its lines in run order instead. A line that stands for several edges shows the first
+   *  one's step (a view's `keepPairs` draws each edge as its own line). A step on a model edge shows in every view that
+   *  draws the edge; a view's own edge numbers it in that view only. */
+  step?: number | string;
   /** A second, smaller line under the label (a technology, say), placed with it and counted in the room left for labels.
    *  Shown only with a label. A line that stands for several edges shows each of their sublabels, joined by " / ". */
   sublabel?: string;
@@ -71,7 +88,11 @@ export interface MapView {
   /** Guess a line's kind from the words of its label ("reads" is state, "triggers" is triggers ...) when its edges name
    *  none. Off in render() and layout(), which draw no legend; the standalone page (mountPage) always guesses. */
   kindsFromLabels?: boolean;
-  containers?: { id: string; label?: string; nodeIds?: string[]; parent?: string; badges?: Badge[] }[];   // badges: tabs on the box's border
+  /** Boxes: badges are tabs on the box's border; tone, a palette name as a badge's (--um-<tone>), tints the region behind the
+   *  box (as deep as --um-tint makes the cards), with its border dashed and its title in the tone. */
+  containers?: { id: string; label?: string; nodeIds?: string[]; parent?: string; badges?: Badge[]; tone?: string }[];
+  /** The notation this view's cards are drawn in (0.15.0): it wins over the model's. */
+  shapes?: Notation;
   [key: string]: unknown;
 }
 
@@ -92,14 +113,48 @@ export interface Events {
   change: Change;                                           // only with `editable`
   /** E or Alt + click on a stacked card, or the ⤡ tab of the box it unfolded into (#71): before the card unfolds in place
    *  (expanded: true) or folds back (false). view: the card's inner view, which may not be in the model yet; the card
-   *  unfolds once it is (the host loads it and calls update() right here, or later expand()). preventDefault(): no change. */
+   *  unfolds once it is: the update() that brings it unfolds the card (here or later), or expand(). preventDefault(): no change. */
   expand: { target: Extract<Ref, { type: 'node' }>; view: string; expanded: boolean; preventDefault(): void };
-  story: { story: string; step: number | null; steps: number };   // a story shows its step (0-based); step null: it ended
+  /** A story changed: it shows a step (0-based), it was paused or resumed (playing), or it ended (step null, on destroy()
+   *  too). playing (0.14.0): it goes on by itself. */
+  story: { story: string; step: number | null; steps: number; playing: boolean };
+  /** The map's state changed (0.14.0): at most once a frame, with the keys that changed since the last state event. The
+   *  camera is the exception: a pan, zoom, glide or drag is one event, once it comes to rest, and until then the event's
+   *  camera is where it last rested (handle.state reads it live). The last event, on destroy(), has destroyed: true. */
+  state: { state: MapState; changed: (keyof MapState)[] };
+  /** The lens on the map changed: lens(), or an update() whose model lacks the lens shown (lens: null). */
+  lens: { lens: string | null };
+}
+
+/** The map's state, for hosts and agents (0.14.0): handle.state, the state event, the standalone page's
+ *  window.umlimatorMap.state and <umlimator-map>'s el.map.state. Fresh on every read, frozen, and plain JSON. */
+export interface MapState {
+  view: string | null;            // shown now (null: the model has no views)
+  navigating: string | null;      // the view a move under way is going to
+  selection: Ref[];               // as `selected`
+  expanded: string[];             // as `expanded`
+  lens: string | null;
+  overlays: string[];             // the layers on the map, in stack order ('lens', 'highlight', 'replay', 'story', 'tour', a host's)
+  story: { id: string; step: number; steps: number; playing: boolean } | null;   // playing: the player's own (it goes on by itself)
+  tour: boolean;                  // a tour's dot is on the map, riding or held (by paused, or by its story's pause); a path lit at rest: false
+  replay: { playing: boolean } | null;   // a replay under way: playing, or paused by its own pause()
+  /** The standalone page's ❚❚ is on (0.15.0): it holds every clock (a tour's or a replay's dot, a story's step, the flow)
+   *  and leaves each one's own state as it is, so story.playing or replay.playing true under it means "would play, held". */
+  paused: boolean;
+  camera: { x: number; y: number; zoom: number };   // the centre in map units, and the zoom (1: actual size); a state event's: at rest
+  flow: boolean;
+  shapes: Notation;               // the notation the view shown is drawn in (0.15.0)
+  motion: 'full' | 'reduced' | 'instant';
+  gesture: 'idle' | 'dragging' | 'connecting' | 'naming';   // an edit in progress (editable maps)
+  destroyed: boolean;
 }
 
 /** Where the user dropped or placed something: a point in the view and, on a column view, its column and row. */
 export interface Hint { x: number; y: number; col?: number; row?: number }
-/** An edit the user asked for. Nothing changes until the host applies it and calls update(). */
+/** An edit the user asked for. Nothing changes until the host applies it and calls update(). The places it hints (a card
+ *  moved, reordered or added) are used only if that update's model shows the edit: the card in its new box, a new card
+ *  with its name, or, for a place alone, the card's `layout` entry written or the model unchanged. Any other update drops
+ *  them. An update back to the model before an applied move, or after it (undo, redo), puts the cards back as they were. */
 export type Change = { id: string; view: string; hint?: Hint } & (
   | { op: 'add'; kind: 'node'; label: string; container?: string }
   | { op: 'add'; kind: 'edge'; from: string; to: string; label?: string }
@@ -112,8 +167,13 @@ export interface RenderOptions {
   view?: string;                 // default: model.root, else the view with no parent
   select?: Ref | null;
   controls?: boolean;            // up / zoom / fit / 1:1 / flow buttons (default true)
+  /** 'zoom' (the default): the wheel zooms the map, and a trackpad pans it. 'ctrl': only Ctrl or ⌘ with the wheel (and a
+   *  trackpad's pinch) zooms, and the wheel otherwise scrolls the page, as a map in a document should. */
+  wheel?: 'zoom' | 'ctrl';
   minimap?: boolean;             // default false
   flow?: boolean;                // animated flow along lines (default: on unless prefers-reduced-motion)
+  /** The notation every view is drawn in (0.15.0), over each view's and the model's own. */
+  shapes?: Notation;
   /** Text widths: default the host's font (--um-sans, measured on a canvas); false: a font-independent estimate. */
   measure?: false | ((text: string, px: number) => number);
   /** Edit gestures that emit `change` events: all of them, or only those set true. Off by default. */
@@ -148,6 +208,9 @@ export interface Handle {
    *  where it was; none of it with the option `ease: false` or under prefers-reduced-motion, and an export at any point
    *  draws where things end up. */
   update(model: MapModel): void;
+  /** Shows a view, zooming in or out as a drill-down does. A request during a move takes the move to its own view (the
+   *  latest wins). Resolves true once the view shows; false for a view the model lacks (with a console warning), when a
+   *  later request supersedes it, or on destroy(). */
   setView(id: string): Promise<void> | void;
   select(ref: Ref | null): void;
   fit(): void;
@@ -175,13 +238,32 @@ export interface Handle {
   readonly view: string | null;
   readonly selection: Ref | null;   // the latest selected
   readonly selected: Ref[];          // every selected thing (Shift / Cmd / Ctrl + click adds cards), the latest last
+  /** The map's state as one snapshot (0.14.0): fresh, frozen and JSON-serializable on every read. */
+  readonly state: MapState;
+  /** The view a move is going to, while one is under way (setView(), a drill-down, up); else null. */
+  readonly navigating: string | null;
+  /** True once destroy() has run: calls then do nothing, and every promise has settled. */
+  readonly destroyed: boolean;
+  /** The animated flow along lines (the ≋ button and F), to read or set. */
+  flow: boolean;
+  /** The notation the view shown is drawn in (0.15.0). Set it to draw every view in one (null: each view's own): the
+   *  cards are drawn again from the geometry they have, with the camera, selection, lens and marks; nothing is laid out. */
+  get shapes(): Notation;
+  set shapes(notation: Notation | null);
+  /** How this map moves: 'instant' (drawn without animation, as the page's #check, #still and #shot are), 'reduced' (the
+   *  reader's setting), else 'full'. */
+  readonly motion: 'full' | 'reduced' | 'instant';
+  /** The player of the story shown, whoever started it (play(), the standalone page's Stories menu or a link), else null. */
+  readonly story: StoryPlayer | null;
   /** Sets (or, with null, removes) a named layer of marks, drawn over the picture without touching the model. Layers stack
    *  in the order first set: each property comes from the latest layer that sets it, and a card or line is as lit as its
    *  lowest level. They survive update() and setView(); ids the view doesn't show are ignored. toSVG() and toPNG() draw them. */
   overlay(name: string, layer: Overlay | null): void;
   /** 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;
+   *  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.
+   *  layer (0.14.0): draw them as a layer of that name instead, so two owners never clear each other's (the MCP page's
+   *  assistant uses 'mcp'); null clears that layer only. */
+  highlight(refs: Lit[] | null, options?: { layer?: string }): 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
@@ -189,8 +271,9 @@ export interface Handle {
   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.
-   *  speed: map units a second (default 240). */
+   *  new tour or replay, tour(null), Esc on the map, a new picture of the view, destroy()). With reduced motion no dot rides:
+   *  it resolves at once, and the path is lit at rest (its cards ringed and numbered in turn, its lines glowing: the 'tour'
+   *  layer) and said, until the next tour or replay, tour(null), Esc or a new picture. speed: map units a second (default 240). */
   tour(path: string[] | null, options?: { speed?: number }): Promise<boolean>;
   /** Plays a trace: each call from one card to another (a span and its parent's) runs along their line at the trace's relative
    *  time; the line glows while the call lasts and keeps its duration as a label (the 'replay' layer, until stop() or the next
@@ -200,8 +283,11 @@ export interface Handle {
   /** Tells one of the model's stories (#69): each step in turn sets the view, camera, selection, highlight and caption
    *  (drawn in a bar on the map and said to screen readers), then plays its tour. auto (default true): the next step
    *  follows once a step's duration is up and its tour has ended. step: where to start (0-based). The bar and the keys
-   *  (← → PageUp PageDown, Esc) step through and stop it. null when the model has no story `id` with steps. */
-  play(id: string, options?: { step?: number; auto?: boolean }): StoryPlayer | null;
+   *  (← → PageUp PageDown, Esc) step through and stop it. The reader taking the map (a press, a key, a view or a selection
+   *  the story didn't make) pauses it, and a pause holds the step's tour too, until resume(). A step folds back the cards
+   *  unfolded on its view first, and its highlight is its own 'story' layer, which dims alone while the step shows.
+   *  null when the model has no story `id` with steps, and the story shown, if any, plays on; play(null) stops it. */
+  play(id: string | null, options?: { step?: number; auto?: boolean }): StoryPlayer | null;
   destroy(): void;
 }
 
@@ -215,9 +301,11 @@ export interface StoryStep {
   camera?: 'fit' | { x: number; y: number; zoom?: number } | { card: string; zoom?: number }; duration?: number;
 }
 /** A story being told. step: the one shown (0-based). next() past the last step ends it (done: true); stop() closes it
- *  (done: false). */
+ *  (done: false). state (0.14.0): entering a step (its view, camera, selection and highlight on their way), playing or paused
+ *  on it, then ended or stopped. */
 export interface StoryPlayer {
   readonly story: string; readonly step: number; readonly steps: number; readonly playing: boolean; readonly done: Promise<boolean>;
+  readonly state: 'entering' | 'playing' | 'paused' | 'ended' | 'stopped';
   next(): void; prev(): void; pause(): void; resume(): void; stop(): void;
 }