umlimator 0.20.0 → 0.22.0

package/README.md

@@ -22,11 +22,10 @@ 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)).
+- **Card shapes**: one style, the union of what the C4 model's tools and UML 2.5 draw: people, robots, browser apps,
+  phones, terminals, queues, packages, hosts, data stores, files and hooks, each by its card's kind, and a rounded box
+  where no shape says more. A card's own `shape` wins. Each shape keeps to its card's box, so the layout is the same
+  ([`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
@@ -66,8 +65,37 @@ drill-down, a data pipeline, an AI agent's skills, and host pages for embedding,
   [what it covers](docs/conformance/uml-communication.md)). Messages are inserted, moved in time, wrapped in a frame and
   deleted on the canvas, by pointer and by key, each gesture an `edit` event; checked by the types' rules; a sequence
   diagram is read from and written to Mermaid's `sequenceDiagram`, and an OpenTelemetry trace becomes one
-  (`umlimator.py trace --diagram uml.sequence`). The MCP server, the `map-repo` skill and the diff Action learn these
-  types in one package after 0.20.0; until then a reorder of a view's messages shows in a diff as changed, not moved.
+  (`umlimator.py trace --diagram uml.sequence`). A diff says "moves" for a reordered message, and `paths()` on a
+  sequence view runs in time order (0.22.0).
+- **UML use case, activity, state machine and interaction overview diagrams** (0.21.0): actors as stick figures, use
+  cases as ellipses with their extension points, a subject as a box holding its use cases, include, extend and
+  generalization ([`examples/shopping-use-cases.json`](examples/shopping-use-cases.json),
+  [what it covers](docs/conformance/uml-use-case.md)); actions, object nodes, data stores, send and accept actions, call
+  behaviour actions that open the activity they call, and the control nodes, in lanes (partitions, nested)
+  ([`examples/fulfil-activity.json`](examples/fulfil-activity.json), [what it covers](docs/conformance/uml-activity.md));
+  states with their entry, do and exit activities and internal transitions, composite states as boxes, orthogonal
+  regions with dashed dividers, every pseudostate, and transitions written `trigger [guard] / effect`
+  ([`examples/order-states.json`](examples/order-states.json), [what it covers](docs/conformance/uml-state-machine.md));
+  interaction uses and inline interactions, drawn with their sequence diagram inside, joined by the activity's control
+  nodes ([`examples/buy-book-overview.json`](examples/buy-book-overview.json),
+  [what it covers](docs/conformance/uml-interaction-overview.md)). Lines end on the outline of a circle, a diamond, a
+  bar or an ellipse. F2 edits a transition's or a flow's label through its parts; a drop changes a node's lane or a
+  state's region. A state machine is read from and written to Mermaid's `stateDiagram`. The MCP server's read tools and
+  the diff Action are tested on all four.
+- **UML component, deployment and composite structure diagrams** (0.22.0): components nested in components and
+  packages, ports on their borders, provided and required interfaces as a ball and socket or as a rectangle, assembly
+  and delegation connectors (a delegation runs from a box's port inward to the port of what it holds), artifacts and
+  their manifestations ([`examples/bookshop-components.json`](examples/bookshop-components.json),
+  [what it covers](docs/conformance/uml-component.md)); nodes, devices and execution environments drawn as cubes and
+  nested to any depth, artifacts deployed in them or by a «deploy» line, deployment specifications and communication
+  paths ([`examples/bookshop-deployment.json`](examples/bookshop-deployment.json),
+  [what it covers](docs/conformance/uml-deployment.md)); a class's parts and ports, each part showing its type's ports,
+  connectors through parts, open collaborations as dashed ellipses and collaboration uses with their role bindings
+  ([`examples/order-service-structure.json`](examples/order-service-structure.json),
+  [what it covers](docs/conformance/uml-composite-structure.md)). A port's side is chosen from where its lines go, or
+  pinned by a drag or Alt + arrows; `B` turns an interface into a ball and back; a port or a part is added as a row of
+  its owner. The MCP server's read tools and the diff Action are tested on all three, and the Bookshop atlas opens them
+  from the map's Hosts.
 - **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`).
@@ -90,7 +118,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.20.0"`. npm 12 refuses git
+Or from GitHub, at a tag or any commit: `"umlimator": "github:zintaen/umlimator#v0.22.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
@@ -135,17 +163,15 @@ 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).
-- `import { render, apply, history } from 'umlimator/all'` draws diagram types too: a class, object, package, sequence or communication diagram, whose gestures emit
+- `import { render, apply, history } from 'umlimator/all'` draws diagram types too: a class, object, package, sequence, communication, use case, activity, state machine, interaction overview, component, deployment or composite structure diagram, whose gestures emit
   `edit` transactions that `apply(model, e.commands)` turns into the next model (`examples/class-editor.html` is a
   working host). `umlimator` alone draws maps, and a typed view as plain cards with a warning.
 - `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.
+  and the views that show it (on a typed diagram, a reordered member or message reads "moves");
+  `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. `render()` can draw its pieces too, each on its own or
   any mix, inside the map's element; the host keeps its own header:
 
@@ -182,8 +208,7 @@ the map is drawn, and stay where scripts don't run ([`examples/element.html`](ex
 - **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. `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.
+  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.
@@ -218,8 +243,10 @@ path. The full schema is `engine/references/schema.md` (§ Map model); `examples
 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.
 `"schemaVersion": 2` marks a model that may hold typed elements and typed views (`docs/diagrams/model.md`). A view whose
-`diagram` is `"uml.class"`, `"uml.object"`, `"uml.package"`, `"uml.sequence"` or `"uml.communication"` is a UML class, object,
-package, sequence or communication diagram, drawn by `umlimator/all` and the CLI; a type not drawn yet shows its
+`diagram` is `"uml.class"`, `"uml.object"`, `"uml.package"`, `"uml.sequence"`, `"uml.communication"`, `"uml.use-case"`,
+`"uml.activity"`, `"uml.state-machine"`, `"uml.interaction-overview"`, `"uml.component"`, `"uml.deployment"` or
+`"uml.composite-structure"` is a UML class, object, package, sequence, communication, use case, activity, state machine,
+interaction overview, component, deployment or composite structure diagram, drawn by `umlimator/all` and the CLI; a type not drawn yet shows its
 nodes as plain cards, with a warning. A model with no `schemaVersion` is a map, as always, and a version newer than the
 module reads is an error.
 
@@ -233,7 +260,7 @@ 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 | `shape` | the card's own shape, over the one its kind draws: `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 |
@@ -249,9 +276,8 @@ 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) |
+| 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 |
 | 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 |
@@ -287,6 +313,38 @@ and a communication diagram (`examples/checkout-communication.json`,
 | view | `edges` | a sequence view's messages and interaction uses (`uml.InteractionUse`, `props.covers`), inline and in time order; a communication view's connectors, then its messages, by id, in order. Bars and numbers are derived |
 | view | `fragments` | a sequence view's combined fragments (`uml.CombinedFragment`, `props.operator`), each with its operands as `members` (`label` the guard); a message's or fragment's `parent` is its operand |
 
+A use case diagram, an activity diagram, a state machine diagram and an interaction overview diagram
+(`examples/shopping-use-cases.json`, `fulfil-activity.json`, `order-states.json` and `buy-book-overview.json`; each
+type's note in [`docs/conformance/`](docs/conformance/)), from 0.21.0:
+
+| On | Field | What it does |
+|---|---|---|
+| node, member, edge | `type` | use case: `uml.Actor`, `uml.UseCase` (members `uml.ExtensionPoint`), `uml.Subject`; lines `uml.Association`, `uml.Include`, `uml.Extend`, `uml.Generalization` |
+| node, edge | `type` | activity: `uml.Action`, `uml.CallBehaviorAction`, `uml.SendSignalAction`, `uml.AcceptEventAction`, `uml.ObjectNode`, `uml.DataStoreNode`, `uml.InitialNode`, `uml.ActivityFinalNode`, `uml.FlowFinalNode`, `uml.DecisionNode`, `uml.MergeNode`, `uml.ForkNode`, `uml.JoinNode`, `uml.ActivityPartition`; lines `uml.ControlFlow`, `uml.ObjectFlow` |
+| node, member, edge | `type` | state machine: `uml.State` (members `uml.Region`, `uml.InternalTransition`), `uml.Pseudostate`, `uml.FinalState`; lines `uml.Transition` |
+| node, edge | `type` | interaction overview: the activity's control nodes, `uml.InteractionUse`, `uml.Interaction` (an inline interaction); lines `uml.ControlFlow` |
+| node | `parent` | a use case's subject; an activity node's partition (its lane), a partition's enclosing partition; a substate's state or region |
+| node | `opensView` | the activity a call behaviour action calls; the sequence view an interaction use or inline interaction shows |
+| node | `props` | a state's `entry`, `do`, `exit`; a pseudostate's `kind` (`initial`, `choice`, `junction`, `fork`, `join`, `shallowHistory`, `deepHistory`, `terminate`) |
+| edge, member | `props` | an extend's `extensionPoints` (ids) and `condition`; a flow's `guard` (its `label` is its name); a transition's or internal transition's `trigger`, `guard` and `effect`, drawn `trigger [guard] / effect` |
+| view | `diagram` | `"uml.use-case"`, `"uml.activity"`, `"uml.state-machine"` or `"uml.interaction-overview"` |
+
+A component diagram, a deployment diagram and a composite structure diagram (`examples/bookshop-components.json`,
+`bookshop-deployment.json` and `order-service-structure.json`; each type's note in
+[`docs/conformance/`](docs/conformance/)), from 0.22.0:
+
+| On | Field | What it does |
+|---|---|---|
+| node, member, edge | `type` | component: `uml.Component` (members `uml.Port`), `uml.Interface`, `uml.Artifact`, `uml.Package`; lines `uml.InterfaceRealization`, `uml.Usage`, `uml.ComponentRealization`, `uml.Connector`, `uml.Dependency`, `uml.Manifestation` |
+| node, edge | `type` | deployment: `uml.Node`, `uml.Device`, `uml.ExecutionEnvironment`, `uml.Artifact`, `uml.DeploymentSpecification`, `uml.Component`; lines `uml.Deployment`, `uml.Manifestation`, `uml.CommunicationPath`, `uml.Dependency` |
+| node, member, edge | `type` | composite structure: the subject (`uml.Class`, `uml.Component` or `uml.Collaboration`) with its parts (`uml.Property`) and ports (`uml.Port`), `uml.Collaboration` (its roles `uml.Property`), `uml.CollaborationUse`; lines `uml.Connector`, `uml.RoleBinding` (its `label` the role) |
+| node | `parent` | a component's component or package; an artifact's target (deployed by nesting); a target's target (any depth); a collaboration use's subject |
+| node, member | `props` | a port's `valueType`; a part's `valueType` (the class or component whose ports it shows, by label), `multiplicity` and `aggregation` (`shared` is dashed); a collaboration use's `collaboration` |
+| edge | `props` | a connector's `kind` (`assembly`, `delegation`); an end through a part, `ends.from.part` or `ends.to.part` (UML's `partWithPort`) |
+| view | `subject` | a composite structure view's class, component or collaboration, listed in `nodeIds` |
+| view | `present` | an interface drawn as a ball (`{ "as": "ball" }`); a port's side (`{ "side": "left" }`); on a part, `{ "ports": { "<port>": { "side": "top" } } }` |
+| view | `diagram` | `"uml.component"`, `"uml.deployment"` or `"uml.composite-structure"` |
+
 ## Command line
 
 ```bash
@@ -303,6 +361,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
 python3 umlimator.py import classes.mmd --out classes.json            # a Mermaid classDiagram, as a UML class diagram (needs Node)
 python3 umlimator.py import checkout.mmd --out checkout.json          # a Mermaid sequenceDiagram, as a UML sequence diagram (needs Node)
+python3 umlimator.py import order.mmd --out order.json                # a Mermaid stateDiagram, as a UML state machine diagram (needs Node)
 python3 umlimator.py render examples/sales-classes.json --out classes.html   # a class diagram's page; stills, check and pdf take it too
 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
@@ -316,14 +375,14 @@ python3 umlimator.py mcp model.json                                    # an MCP
 
 `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`; a `classDiagram` becomes a UML class diagram and a `sequenceDiagram` a UML sequence
-diagram, each read through Node), and the JSON of `docker compose config` (services, `depends_on`, networks) and of
+`C4Container` or `C4Component`; a `classDiagram` becomes a UML class diagram, a `sequenceDiagram` a UML sequence
+diagram and a `stateDiagram` a UML state machine diagram, each read through Node), 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). 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
+doesn't read is listed on stderr with its line (in JSON, its path). A Structurizr, C4-PlantUML or Mermaid C4 source's
+people are people (`person`, or `user` outside the system), and its phone apps 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`.
 
@@ -337,8 +396,8 @@ the title and "page N of M". It takes `--views` and `--theme`, as `stills` does,
 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, `#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
+(`#view=<id>&node=<id>`, `#story=<id>&step=<n>` for a story's step, `#lens=<id>`), stories, lenses, a
+light and dark toggle (◐), and export. For
 scripts and tests, it keeps its map's handle on `window.umlimatorMap`: the `Handle` that `render()` returns (`setView()`,
 `highlight()`, `tour()`, `play()` ...).
 `stills` skips a view whose inputs have not changed since its last export (`--all` exports every view), and exits 1,
@@ -355,9 +414,9 @@ ffmpeg -f apng -i ride.png -vf "split[a][b];[a]palettegen[p];[b][p]paletteuse" r
 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. 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.
+On pull requests, the diff Action posts what they change in your maps and UML diagrams (every type above): one comment
+with the summary and a sketch, and 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
@@ -368,7 +427,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: zintaen/umlimator@v0.20.0
+      - uses: zintaen/umlimator@v0.22.0
         with:
           models: "docs/*.json"   # optional: where the models are (default: every .json that is a map model)
 ```
@@ -386,7 +445,7 @@ claude mcp add umlimator -- python3 /path/to/umlimator.py mcp /path/to/model.jso
 |---|---|
 | `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` |
+| `paths(view, from, to)` | every card and line on a path from one card to another (`paths()`; on a sequence view, in time order), 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()`) |
@@ -441,7 +500,7 @@ With `UMLIMATOR_OFFLINE=1` the CLI fetches nothing: a logo not in the cache keep
 
 ```bash
 npm run build               # src/ into lib/umlimator.js and lib/umlimator-all.js: edit the sources, commit all three
-node --test                 # layout() in Node: the bench views' geometry and the layout rules
+node --test                 # layout() in Node: the bench views' geometry and the layout rules; npm test runs the "(timed)" tests apart, one file at a time
 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
 ```