umlimator 0.10.0 → 0.12.0

package/README.md

@@ -7,22 +7,36 @@ that writes a self-contained HTML page and still pictures (SVG, PNG) for documen
 
 ![The example model's overview: a made-up bookshop with logos, line icons and a numbered flow behind the API card](examples/stills/overview.png)
 
-**Examples:** [live on GitHub Pages](https://zintaen.github.io/umlimator/), and [what each one shows](examples/README.md): a C4-style
+**Examples:** [live on GitHub Pages](https://zintaen.github.io/umlimator/), a [playground](https://zintaen.github.io/umlimator/examples/playground.html)
+to try a model in, and [what each one shows](examples/README.md): a C4-style
 drill-down, a data pipeline, an AI agent's skills, and host pages for embedding, live updates and editing.
 
 ## What it does
 
 - **Layers**: a view per level (system, containers, components, flows). A stacked card opens its inner view, which the
   host may load only when asked.
-- **Layout and routing**: columns in reading order, each ordered so the lines between columns cross as little as they
-  can; 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.
+- **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.
 - **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()`).
+- **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.
 - **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.
 - **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.
 
 ## Install
 
@@ -30,7 +44,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.10.0"`. npm 12 refuses git
+Or from GitHub, at a tag or any commit: `"umlimator": "github:zintaen/umlimator#v0.12.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
@@ -61,11 +75,21 @@ function MapView({ model, onSelect }) {
 ```
 
 - `render` draws one view at a time into a shadow root (give the element a height), with pan, zoom and drill-down.
-  Events (`click`, `select`, `open`, `viewchange`, `change`) name what they are about by ids from the model.
+  Events (`click`, `select`, `open`, `viewchange`, `change`, `expand`) name what they are about by ids from the model.
+- `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.
-- `layout(model, viewId)` returns a view's geometry without a DOM, in Node too.
+- `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.
+- `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.
 - `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.
 
 The API, its types and the decisions behind it: [docs/module-api.md](docs/module-api.md) and `lib/umlimator.d.ts`.
@@ -75,6 +99,8 @@ The API, its types and the decisions behind it: [docs/module-api.md](docs/module
 A model has shared `nodes` and `edges`, and `views` that each show a subset, with optional `containers` (boxes),
 `layout` (`[col, row]` per card), `render: "sequence"` for numbered run-order views and `tour` for a dot that rides a
 path. The full schema is `engine/references/schema.md` (§ Map model); `examples/bookshop.json` uses most of it.
+A model file that starts with `"$schema": "<path to>/umlimator.schema.json"` (exported as `umlimator/schema.json`)
+gets completion and checks in editors, and `validate(model)` lists its errors and warnings, each with where it is.
 
 Card kinds: `frontend`, `backend`, `ai`, `database`, `queue`, `security`, `cloud`, `external` and `file` (skill-map
 kinds such as `public`, `lane`, `script`, `hook` and `board` work too). Fields beyond the schema:
@@ -91,12 +117,16 @@ kinds such as `public`, `lane`, `script`, `hook` and `board` work too). Fields b
 | 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 |
+| 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` |
 | 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 | `stories` | walk-throughs: steps that each set the view, camera, selection, highlight, tour and caption |
 
 ## Command line
 
@@ -105,11 +135,59 @@ python3 umlimator.py render examples/bookshop.json --out page.html   # the inter
 python3 umlimator.py stills page.html --out stills/                   # every view as SVG and PNG
 python3 umlimator.py stills page.html --out stills/ --views overview,api --scale 1.5 --theme light
 python3 umlimator.py check page.html --views 'pic-*'                   # the layout check on chosen views
+python3 umlimator.py diff before.json after.json --out diff.html --stills diff/   # what changed, marked and in words
+python3 umlimator.py diff --base origin/main --out diff/              # every model changed since a ref, and a summary.md
+python3 umlimator.py drift model.json traffic.json --out drift.html   # drawn vs. seen (a Jaeger or Tempo dependency list)
+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, a frame per step
 ```
 
-The page has breadcrumbs, a details panel per card, ⌘K search, deep links (`#view=<id>&node=<id>`) and export.
+`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), and Google Chrome or Chromium for `stills` and `check`.
+3.9+ (standard library only), Google Chrome or Chromium for `stills`, `check` and `record`, and Node 18+ for `diff`
+and `drift`.
+
+`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:
+
+```bash
+ffmpeg -f apng -i ride.png -vf "split[a][b];[a]palettegen[p];[b][p]paletteuse" ride.gif
+ffmpeg -f apng -i ride.png -vf "scale=trunc(iw/2)*2:trunc(ih/2)*2" -pix_fmt yuv420p ride.mp4
+```
+
+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.
+
+```yaml
+on: pull_request
+permissions: { contents: read, pull-requests: write }
+jobs:
+  maps:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: zintaen/umlimator@v0.12.0
+        with:
+          models: "docs/*.json"   # optional: where the models are (default: every .json that is a map model)
+```
+
+## 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
+and stills, and fixes what the layout check reports. Install it, then ask Claude Code to map the repository:
+
+```
+/plugin marketplace add zintaen/umlimator
+/plugin install umlimator@umlimator
+```
+
+On Claude Code 2.1.275 or later, `/plugin install umlimator --marketplace zintaen/umlimator` does both in one step. The
+skill needs git, Python 3.9+ and Chrome; on first use it fetches the CLI of one pinned release into
+`~/.cache/umlimator/cli`.
 
 ## Icons
 
@@ -145,13 +223,15 @@ 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, pin-icons
+umlimator.py                 CLI: render, stills, check, record, pin-icons, diff, drift, timelapse
+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
-engine/                      the page template the CLI inlines the module into; the upstream renderer and schema
+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
 icons/                       line icons and the logo manifest (sources and hashes only)
 examples/                    made-up systems: models, host pages and a Node script (live: zintaen.github.io/umlimator)
+.claude-plugin/, plugins/    the Claude Code marketplace and its map-repo skill
 ```
 
 ## Licence

package/lib/umlimator.d.ts

@@ -9,6 +9,10 @@ export interface MapModel {
   views: MapView[];
   icons?: Record<string, { g?: string; src?: string; dark?: boolean }>;
   authors?: Record<string, { name?: string; url?: string; avatar?: string }>;
+  /** What must hold: rules() lists what breaks them, the map marks it, and umlimator.py check fails on it. */
+  rules?: Rule[];
+  /** Narrated walk-throughs of the map (#69): handle.play(id), the standalone page's Stories menu, umlimator.py record. */
+  stories?: Story[];
   [key: string]: unknown;
 }
 /** A badge: its text, and optionally a palette name for its colour (green, amber, rose, accent, violet ... : --um-<tone>). */
@@ -40,6 +44,14 @@ export interface MapEdge {
   /** 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;
+  /** A style that wins over the kind's colour: emphasis (green), added (green, flowing), dashed or async (violet),
+   *  security (rose, dashed), removed (rose, dashed, faded) or faded (its kind's colour, faint, with no flow). */
+  style?: 'emphasis' | 'added' | 'dashed' | 'async' | 'security' | 'removed' | 'faded';
+  /** A change mark: added and removed draw only with the matching `style` on a map; diff() sets both, and marks a
+   *  changed line `edited`. */
+  change?: 'added' | 'removed' | 'changed';
+  /** What drift() found: undrawn (traffic ran on it, nobody drew it) or idle (drawn, carried nothing). */
+  drift?: 'undrawn' | 'idle';
   [key: string]: unknown;
 }
 export interface MapView {
@@ -70,6 +82,11 @@ export interface Events {
   open: { target: Ref; view: string; preventDefault(): void };   // view: the one the card opens, which may not be in the model yet
   viewchange: { view: string; from: string };
   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. */
+  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
 }
 
 /** Where the user dropped or placed something: a point in the view and, on a column view, its column and row. */
@@ -95,12 +112,19 @@ export interface RenderOptions {
   editable?: boolean | { add?: boolean; rename?: boolean; move?: boolean; delete?: boolean; reorder?: boolean };
   /** Cards keep their places across update() (in this handle only, never in the model). Default true. */
   stableLayout?: boolean;
+  /** 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;
   on?: { [K in keyof Events]?: (e: Events[K]) => void };
 }
 
 export interface ExportOptions { view?: string; scale?: number; fontCSS?: string }
 
 export interface Handle {
+  /** Draws the next model, redrawing only what changed and keeping the view, camera and selection. With motion it eases
+   *  in (#67): moved cards glide from where they were, new cards and rerouted lines fade in, and what left fades out
+   *  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;
   setView(id: string): Promise<void> | void;
   select(ref: Ref | null): void;
@@ -117,12 +141,74 @@ export interface Handle {
    *  the selected card or line. */
   focus(ref?: Ref | null): void;
   on<K extends keyof Events>(type: K, fn: (e: Events[K]) => void): () => void;
+  /** Unfolds a stacked card of the view shown into a box in place (#71): its inner view's own cards inside, this view's
+   *  lines to it moved onto them, the rest of the picture in its order. In this handle only, never in the model; kept per
+   *  view across update(). False when it can't: no loaded inner view, nothing of its own inside, a numbered (sequence)
+   *  view in or opened, an editable map. No expand event: that is for gestures. */
+  expand(id: string): boolean;
+  /** Folds an unfolded card back (and anything unfolded inside it). False when it was not unfolded. */
+  collapse(id: string): boolean;
+  readonly expanded: string[];       // the cards unfolded on the view shown, in the order they were
   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
+  /** 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;
+  /** 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). */
+  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
+   *  replay). A span's service names its card: through `match`, else as a card's id, else as its label (any case).
+   *  duration: the whole trace's playing time in ms (default 6000). With reduced motion the labels appear at once. */
+  replay(spans: Span[], options?: { match?: Record<string, string>; duration?: number }): Replay;
+  /** 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;
   destroy(): void;
 }
 
+/** A walk-through: its steps, in order. */
+export interface Story { id: string; title?: string; steps: StoryStep[] }
+/** What one step shows. select: a card id, a line id, or a Ref. highlight: card ids, line ids or Lits; the lines between
+ *  two cards it names light too. tour: card ids, the dot's path. camera: 'fit' (the default), a point and zoom, or a card
+ *  to frame. duration: the step's time in ms when playing (default 4000; its tour runs to its end first). */
+export interface StoryStep {
+  view: string; caption?: string; select?: string | Ref; highlight?: (string | Lit)[]; tour?: string[];
+  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). */
+export interface StoryPlayer {
+  readonly story: string; readonly step: number; readonly steps: number; readonly playing: boolean; readonly done: Promise<boolean>;
+  next(): void; prev(): void; pause(): void; resume(): void; stop(): void;
+}
+
+/** A mark on a card. tone: a palette name (--um-<tone>), drawn as a ring; badge: a tab after the card's own; level: 0 to 1. */
+export interface CardMark { tone?: string; badge?: Badge; pulse?: boolean; level?: number }
+/** A mark on a line. speed: its flow's speed, as a factor (0 stops it); tone: a glow under it; label: a pill under its own;
+ *  dash: drawn dashed; level: 0 to 1. A drawn line that stands for several edges takes the strongest of their marks. */
+export interface LineMark { tone?: string; speed?: number; pulse?: boolean; label?: string; level?: number; dash?: boolean }
+/** A layer of marks: cards by node id, lines by edge id ("<from>-><to>#<n>" for an edge without one, as Refs name it).
+ *  dim: what the layer doesn't name fades. */
+export interface Overlay { nodes?: Record<string, CardMark>; edges?: Record<string, LineMark>; dim?: boolean }
+/** A Ref for highlight(), with how lit it is: level (0 to 1), else distance (each step out a little fainter). */
+export type Lit = Ref & { level?: number; distance?: number };
+/** A span of a trace: start and end in milliseconds; service names the card it ran in; parent is its caller's span id. */
+export interface Span { id: string; parent?: string | null; service: string; start: number; end: number; name?: string }
+/** A replay in progress. hops: the calls it plays; skipped: spans whose service has no card on the view, or whose call has
+ *  no line there. done: true when it played to the end, false when stopped or cut short. */
+export interface Replay { readonly hops: number; readonly skipped: number; readonly done: Promise<boolean>; pause(): void; resume(): void; stop(): void }
+
 export interface Geometry {
   nodes: { id: string; x: number; y: number; w: number; h: number; [key: string]: unknown }[];
   edges: { from: string; to: string; ids: string[]; pts: [number, number][]; weight: 1 | 2 | 3; wk: WireKind;
@@ -135,6 +221,62 @@ export function render(container: HTMLElement, model: MapModel, options?: Render
 /** Undo for a host: it pushes each model it applies, and hands undo() / redo() results to handle.update(). */
 export interface History { readonly model: MapModel; readonly canUndo: boolean; readonly canRedo: boolean; push(m: MapModel): MapModel; undo(): MapModel; redo(): MapModel }
 export function history(model: MapModel, limit?: number): History;
-export function layout(model: MapModel, viewId: string, options?: { repair?: boolean; measure?: (text: string, px: number) => number }): Geometry;
+/** expand: cards of the view unfolded in place (#71), as handle.expand() draws them; the geometry's `unfolded` lists those
+ *  that did (one inside another after it), and its `families` the boxes they became (`unfolds`: the inner view). */
+export function layout(model: MapModel, viewId: string, options?: { repair?: boolean; measure?: (text: string, px: number) => number; expand?: string[] }): Geometry & { unfolded?: string[] };
+/** A model's own problem. path says where: "views[2].nodeIds[4]". Errors draw as holes or not at all (missing,
+ *  repeated or dangling ids, a box inside itself); warnings draw other than they say (an unknown kind, weight or side,
+ *  a view a card opens that the host has not loaded yet). The JSON Schema is umlimator/schema.json. */
+export interface Problem { level: 'error' | 'warning'; path: string; message: string }
+export function validate(model: MapModel): Problem[];
+/** One issue of the layout check: its message, as the page's check words it, and the cards, lines and boxes it is about
+ *  (exactly those, even where two cards share a label). */
+export interface CheckIssue { message: string; targets: Ref[] }
+/** The layout check's geometry for one view, on layout()'s geometry: no browser needed. The page's check (CLI) adds what
+ *  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 }
+/** 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
+ *  id, in from, to or a not) holds only in the views that draw one of the boxes it names; any other, in every view.
+ *  `views` narrows that further. */
+export interface Rule { id: string; title?: string; views?: string[]; from?: Selector; to?: Selector; noCycles?: boolean }
+/** A rule broken in a view: its message (as umlimator.py check prints it), and the lines, and for a cycle the boxes, it is
+ *  about. The map draws those lines rose, with a mark that names the rule. */
+export interface RuleBreak { rule: string; view: string; message: string; targets: Ref[] }
+/** Every rule the model breaks, view by view. No browser needed. */
+export function rules(model: MapModel): RuleBreak[];
+/** Every card and line on a path from one card to another along the view's lines, as Refs ([] when none joins them). */
+export function paths(model: MapModel, viewId: string, from: string, to: string): Ref[];
+/** What a card's lines lead to, or (backward) what leads to it, as Refs with their distance in lines; the card first, at 0. */
+export function reach(model: MapModel, viewId: string, from: string, options?: { backward?: boolean; depth?: number }): (Ref & { distance: number })[];
+/** A view in plain sentences: cards and kinds, boxes, what each card's lines do, cards with no line. Deterministic. */
+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[];
+/** 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
+ *  or taken out of a view is marked in that view only (`nodeOverrides`). Cards and lines match by id (a line without one
+ *  by its ends, as a Ref names it). `summary`: what changed in words, in model order ("adds Payments queue between
+ *  Trip service and Payment provider"); `views`: those that show a change. The marks are the model's own fields, so a
+ *  page or still the CLI makes shows them. Neither input is changed. */
+export interface DiffResult { model: MapModel; summary: string[]; views: string[] }
+export function diff(before: MapModel | null, after: MapModel | null): DiffResult;
+/** A call between two services as traffic showed it: { from, to, count }, or a Jaeger or Tempo dependency. */
+export type Observed = { from: string; to: string; count?: number } | { parent: string; child: string; callCount?: number };
+/** The map against the traffic seen (#68). A line that ran but is not drawn comes in (`drift: 'undrawn'`: rose, dashed,
+ *  labelled "not drawn" with its calls); a drawn line between two cards traffic reached, that carried none, fades
+ *  (`drift: 'idle'`, style `faded`); other lines are left as they are. A service is the card `match` names, else the one
+ *  with its id, else with its label (case aside). `counts`: lines that carried traffic, came in, are idle, or could not
+ *  be judged (an end traffic never reached), and the services with no card; `views`: those that show drift. The counts
+ *  are of model edges, not drawn lines: a line that stands for several edges (A→B and B→A) fades only when every one of
+ *  them is idle, so a map can show fewer faded lines than `idle` counts. */
+export interface DriftResult { model: MapModel; counts: { carried: number; undrawn: number; idle: number; unknown: number; unmatched: string[] }; views: string[] }
+export function drift(model: MapModel, observed: Observed[] | { data: Observed[] }, options?: { match?: Record<string, string> }): DriftResult;
 /** The whole standalone viewer (top bar, views list, details panel, search, export) that umlimator.py writes. */
 export function mountPage(container: HTMLElement, model: MapModel, options?: { params?: URLSearchParams; instant?: boolean }): Handle;