umlimator 0.0.0-stage → 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zintaen <zintaen@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,159 @@
-# Temporary Holding Version
+# umlimator
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![check](https://github.com/zintaen/umlimator/actions/workflows/check.yml/badge.svg)](https://github.com/zintaen/umlimator/actions/workflows/check.yml)
+
+Layered architecture maps you can click through, from one JSON model: an ES module that any page embeds, and a CLI
+that writes a self-contained HTML page and still pictures (SVG, PNG) for documents that cannot run one.
+
+![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
+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.
+- **Reading**: animated flow, neighbours lit on selection, numbered steps, tours, minimap, light and dark themes.
+- **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.
+
+## Install
+
+```bash
+npm install umlimator
+```
+
+Or from GitHub, at a tag or any commit: `"umlimator": "github:zintaen/umlimator#v0.10.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
+
+```js
+import { render } from 'umlimator';   // one ES module, no dependencies, no build step
+import 'umlimator/theme.css';         // the default --um-* palette and fonts (or set the variables yourself)
+
+const map = render(document.getElementById('map'), model, {
+  on: { select: e => showDetails(e.target), open: e => { e.preventDefault(); router.push(e.view); } },
+});
+map.update(nextModel);                        // redraws only what changed; keeps the view, camera and selection
+const svg = map.toSVG({ scale: 2 });          // the current view as a stand-alone file
+const png = await map.toPNG({ view: 'api' }); // any view, without showing it
+map.destroy();
+```
+
+In React, mount once and pass new models to `update`:
+
+```jsx
+function MapView({ model, onSelect }) {
+  const el = useRef(null), map = useRef(null), cb = useRef(onSelect);
+  cb.current = onSelect;
+  useEffect(() => { map.current = render(el.current, model, { on: { select: e => cb.current?.(e.target) } }); return () => map.current.destroy(); }, []);
+  useEffect(() => { map.current?.update(model); }, [model]);
+  return <div ref={el} style={{ height: 600 }} />;
+}
+```
+
+- `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.
+- 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.
+- `editable: true` turns on editing gestures ([docs/editing.md](docs/editing.md); `examples/edit.html` is a working host).
+- `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`.
+
+## Model
+
+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.
+
+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:
+
+| On | Field | What it does |
+|---|---|---|
+| node | `badges` (`badge`) | tabs on the card, each a string or `{ text, tone }` |
+| node | `icon` | a logo or line icon from `icons/manifest.json` |
+| node | `noSub` | the name only; the description stays in the details panel |
+| node | `opensView`, `opensCount` | the view the card opens, which may not be loaded yet, and the ⤢ number for it |
+| node, 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 | `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 |
+| 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 |
+
+## Command line
+
+```bash
+python3 umlimator.py render examples/bookshop.json --out page.html   # the interactive page, then its layout check
+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
+```
+
+The page has breadcrumbs, a details panel per card, ⌘K search, deep links (`#view=<id>&node=<id>`) 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`.
+
+## Icons
+
+A node's `icon` names an entry in `icons/manifest.json`. Line icons ship in `icons/` and take the card's colour. Brand
+logos do not ship: they are their owners' trademarks. The manifest records each logo's official source and a sha256;
+the first render that needs one downloads it into `~/.cache/umlimator/icons` (or `$UMLIMATOR_ICON_CACHE`) and uses it
+only if the hash matches. A logo is never recoloured; follow each brand's guidelines for its use.
+
+```bash
+python3 -I tools/fetch_icons.py icons "name:slug"            # a brand logo: svgl, then devicon, then gilbarbara/logos
+python3 -I tools/fetch_icons.py icons "name=https://..."     # a brand's own official file
+python3 -I tools/fetch_icons.py icons "name:lucide/<icon>"   # a line icon
+python3 umlimator.py pin-icons                                # records each new logo's sha256
+```
+
+## Development
+
+```bash
+node --test                 # layout() in Node: the bench views' geometry and the layout rules
+python3 tests/embed.py      # render() in headless Chrome: events, keyboard, colours, contrast, editing
+python3 bench/bench.py --check-determinism --expect bench/expected.json --max-ms m50=2000
+```
+
+The bench lays out fixed models (10 to 69 cards, and 50 modules with 100 lines) in headless Chrome and reports the
+time per phase, the layout check's issues and a hash of the geometry. `--expect` fails on a view that no longer draws as
+recorded in `bench/expected.json`; a change that moves lines on purpose refreshes it with `--write-expected`. CI runs
+all of the above, and checks that the files copied from upstream (`engine/scripts`, `engine/references`,
+`tools/fetch_icons.py`) are unmodified.
+
+To release, bump `package.json`'s version in a PR and add that version's `## X.Y.Z: …` section to
+`docs/module-api.md`. When the PR is merged and the checks pass on `main`, CI tags `vX.Y.Z`, publishes a GitHub
+Release with that section as its notes, and publishes the package to npm (trusted publishing: no token is stored).
+CI also publishes the examples to GitHub Pages from `main`.
+
+```
+umlimator.py                 CLI: render, stills, check, pin-icons
+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
+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)
+```
+
+## Licence
+
+MIT (`LICENSE`). Third-party notices: `THIRD_PARTY_NOTICES.md`.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,215 @@
+# Third-party notices
+
+umlimator contains, or builds on, the work below. Each entry says what is used and under which licence.
+
+1. super-board `/visual` (MIT): the engine in `lib/` and `engine/`. Its own notices for BuilderIO/skills and archify follow,
+   kept as super-board wrote them, with one note added on archify's later licence change.
+2. caru-ini/stack-diagram (MIT): `tools/fetch_icons.py` and the rules for brand logos.
+3. Lucide (ISC, some icons MIT from Feather): the line icons in `icons/`.
+4. Brand logos: not distributed with umlimator (see the last section).
+
+## EricTechPro/super-board, `/visual` skill
+
+`lib/umlimator.js` and `engine/assets/template.html` derive from super-board's `skills/visual/assets/template.html`
+at commit `d0b7d5a` (29 Oct 2026), modified by umlimator (the changes are in its git history and `docs/module-api.md`);
+`engine/scripts/visual.py` and `engine/references/` are copied from that commit unmodified. Source:
+https://github.com/EricTechPro/super-board
+
+MIT License
+
+Copyright (c) 2026 Eric Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+super-board's own third-party notice for `/visual`, as it ships it:
+
+`/visual` adapts ideas from two MIT-licensed projects. No source file is copied
+whole; the borrowed parts are named below so the attribution is precise.
+
+## BuilderIO/skills (visual-recap, visual-plan)
+
+Adapted from BuilderIO/skills (MIT): the per-mode section list, the recap and
+plan quality bar, the grounding and secret-redaction rules, and the
+"Key changes" + file-tree layout. `references/sections.md` carries them. The
+hosted Agent-Native Plans app, MDX blocks, MCP connector, and `npx` tooling are
+not used.
+
+Source: https://github.com/BuilderIO/skills
+
+MIT License
+
+Copyright (c) 2026 Builder.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## tt-a1i/archify
+
+Diagram style adapted from Archify (MIT): the semantic node palette (dark and
+light values), the opaque-mask-under-translucent-fill node construction, the
+40px grid canvas, orthogonal rounded routes with arrowhead markers, and
+per-kind icons (the cloud, shield, and external-link icon paths follow
+Archify's semantic sigils). `assets/template.html` re-implements these as a small inline
+renderer.
+
+Viewer UX adapted from Archify's viewer (`viewer/viewer-camera.js`, `semantic-radar.js`,
+`focus.js`, `node-finder.js`, `export.js`): camera zoom and pan with fit and 100% presets
+and keyboard steps, reading depths that hide detail when zoomed out (map / read / full),
+a minimap with a draggable viewport, a node focus panel with upstream and downstream reach
+(Archify's "Semantic Passport"), dimming of unrelated nodes on focus, a node finder, SVG and
+PNG export, and the floating control-pill and toolbar look. These are re-implemented from
+scratch in `assets/template.html`; no Archify source file is copied. The edge router follows
+the approach of Archify's `renderers/shared/route-quality.mjs` (`shortestOrthogonalGridRoute`)
+and `renderers/architecture/routing.mjs`: one port per edge spread along the node side in the
+order of the far ends, a sparse orthogonal visibility grid built from node edges plus clearance
+and earlier routes plus separation, Dijkstra with a bend penalty over (cell, direction) states,
+no collinear reuse of earlier routes, and labels reserved as obstacles for later routes.
+Re-implemented, not copied. Drill-down views,
+breadcrumbs, deep links, and the overlap check are /visual's own. Archify's JSON-IR CLI,
+validators, viewer runtime, and embedded font are not bundled.
+
+Source: https://github.com/tt-a1i/archify
+
+Note added by umlimator (2 Nov 2026): archify moved to the Apache License 2.0 on 25 Oct 2026 (commit 9c306ee). Its
+NOTICE keeps code and contributions received under MIT through commit 25cf370 under their original terms, and keeps
+the historical MIT notice, reproduced below, in its LICENSE-MIT. archify itself originated from
+Cocoon-AI/architecture-diagram-generator (MIT), which is why Cocoon AI appears in that notice. super-board adapted
+ideas, not files, and umlimator copies none of archify's files.
+
+MIT License
+
+Copyright (c) 2026 tt-a1i (Archify)
+Copyright (c) 2025 Cocoon AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## caru-ini/stack-diagram
+
+`tools/fetch_icons.py` is copied unmodified from caru-ini/stack-diagram (commit `30cbbb7`). The rules umlimator follows
+for brand logos (official marks only, never recoloured, a white tile, a dark tile for a white mark, fetched rather than
+bundled) are stack-diagram's. stack-diagram's bundled fonts (SIL OFL 1.1) are not used. Source:
+https://github.com/caru-ini/stack-diagram
+
+MIT License
+
+Copyright (c) 2026 caru-ini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## Lucide icons
+
+The line icons in `icons/` (every manifest entry whose source is `lucide`) are from Lucide, fetched from the
+`lucide-static` package; `tools/fetch_icons.py` sets their stroke colour. Source: https://github.com/lucide-icons/lucide
+
+ISC License
+
+Copyright (c) 2026 Lucide Icons and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+Of the icons umlimator ships, clock, database, link, lock, server, terminal and trash-2 are derived from the Feather
+project, under this licence:
+
+The MIT License (MIT)
+
+Copyright (c) 2013-present Cole Bemis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## Brand logos (not distributed)
+
+umlimator does not ship any brand logo. `icons/manifest.json` records, for each one, where its official file is
+published and a sha256; `umlimator.py render` downloads it into the user's cache the first time a model names it.
+The logos are trademarks of their owners and keep their owners' terms: svgl (the project is MIT; the logos belong to
+their owners), devicon (MIT), gilbarbara/logos (CC0), Microsoft's Azure and Entra architecture icons (allowed in
+architecture diagrams, training material and documentation), and files published by the brands themselves. Their use
+in a diagram does not imply endorsement.

package/lib/umlimator-theme.css

@@ -0,0 +1,64 @@
+/* umlimator's default palette and fonts: light, and dark when the system asks or <html data-theme="dark">.
+   The canvas reads only these --um-* variables (it bakes in no colour and loads no font), so a host may use this file,
+   set the variables itself (e.g. --um-bg: var(--surface)), or switch light and dark by changing them on any ancestor
+   of the map. Fonts are the host's: --um-sans and --um-mono name families the page already has; nothing is fetched.
+   It meets WCAG AA in both themes (text 4.5:1 on its background, lines 3:1 on the stage): tests/contrast.html.
+   The tints (--um-<tone>-f) below are for page chrome: the map mixes its own from the tones and --um-panel in effect
+   where it is, so setting a tone on any ancestor of the map recolours its tint too. */
+/* Clean flowchart (GitHub Primer-like): light first, dark when the system or the toggle asks. */
+:root {
+  --um-stage-bg: #fbfcfd; --um-logo-tile: #ffffff; --um-logo-tile-dark: #1b1f23; --um-intake-mark: #1b1f23; --um-edited: #bf8700;
+  --um-bg: #ffffff; --um-bg-2: #f6f8fa; --um-panel: #ffffff; --um-panel-2: #f6f8fa; --um-border: #d8dee4; --um-border-2: #d1d9e0;
+  --um-text: #1f2328; --um-muted: #59636e; --um-dim: #818b98; --um-grid: rgba(31,35,40,.06); --um-mask: #ffffff; --um-arrow: #8c959f;
+  --um-shadow: 0 8px 24px rgba(31,35,40,.10); --um-dot: #e6eaef; --um-gridline: transparent; --um-chrome: rgba(255,255,255,.94);
+  --um-accent: #0969da; --um-accent-fg: #ffffff; --um-lane: rgba(31,35,40,.025);
+  --um-cyan: #0969da; --um-green: #1a7f37; --um-violet: #8250df; --um-amber: #9a6700; --um-rose: #cf222e; --um-orange: #bc4c00; --um-slate: #59636e; --um-fuchsia: #bf3989;
+  --um-k-public: #0969da; --um-k-lane: #0f766e; --um-k-ext: #8250df; --um-k-verb: #bf3989; --um-k-script: #6e7781; --um-k-hook: #cf222e; --um-k-board: #9a6700;
+  --um-w-calls: #424a53; --um-w-feeds: #0969da; --um-w-triggers: #8250df; --um-w-state: #868f99; --um-w-guard: #cf222e;
+  --um-add-bg: rgba(26,127,55,.10); --um-add-tx: #1a7f37; --um-del-bg: rgba(207,34,46,.08); --um-del-tx: #cf222e;
+  color-scheme: light;
+  --um-accent-f: color-mix(in srgb, var(--um-accent) 12%, var(--um-panel));
+  --um-cyan-f: color-mix(in srgb, var(--um-cyan) 9%, var(--um-panel));
+  --um-green-f: color-mix(in srgb, var(--um-green) 9%, var(--um-panel));
+  --um-violet-f: color-mix(in srgb, var(--um-violet) 9%, var(--um-panel));
+  --um-amber-f: color-mix(in srgb, var(--um-amber) 10%, var(--um-panel));
+  --um-rose-f: color-mix(in srgb, var(--um-rose) 8%, var(--um-panel));
+  --um-orange-f: color-mix(in srgb, var(--um-orange) 9%, var(--um-panel));
+  --um-slate-f: color-mix(in srgb, var(--um-slate) 8%, var(--um-panel));
+  --um-fuchsia-f: color-mix(in srgb, var(--um-fuchsia) 8%, var(--um-panel));
+  --um-k-public-f: color-mix(in srgb, var(--um-k-public) 8%, var(--um-panel));
+  --um-k-lane-f: color-mix(in srgb, var(--um-k-lane) 8%, var(--um-panel));
+  --um-k-ext-f: color-mix(in srgb, var(--um-k-ext) 7%, var(--um-panel));
+  --um-k-verb-f: color-mix(in srgb, var(--um-k-verb) 7%, var(--um-panel));
+  --um-k-script-f: color-mix(in srgb, var(--um-k-script) 5%, var(--um-panel));
+  --um-k-hook-f: color-mix(in srgb, var(--um-k-hook) 12%, var(--um-panel));
+  --um-k-board-f: color-mix(in srgb, var(--um-k-board) 9%, var(--um-panel));
+  --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;
+}
+@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-cyan: #4493f8; --um-green: #3fb950; --um-violet: #ab7df8; --um-amber: #d29922; --um-rose: #f85149; --um-orange: #db6d28; --um-slate: #9198a1; --um-fuchsia: #db61a2;
+  --um-k-public: #4493f8; --um-k-lane: #2dd4bf; --um-k-ext: #ab7df8; --um-k-verb: #f778ba; --um-k-script: #9198a1; --um-k-hook: #f85149; --um-k-board: #d29922;
+  --um-w-calls: #b7bdc8; --um-w-feeds: #4493f8; --um-w-triggers: #ab7df8; --um-w-state: #59626e; --um-w-guard: #f85149;
+  --um-add-bg: rgba(63,185,80,.13); --um-add-tx: #56d364; --um-del-bg: rgba(248,81,73,.12); --um-del-tx: #ff7b72;
+  color-scheme: dark;
+  }
+}
+:root[data-theme="dark"] {
+  --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-cyan: #4493f8; --um-green: #3fb950; --um-violet: #ab7df8; --um-amber: #d29922; --um-rose: #f85149; --um-orange: #db6d28; --um-slate: #9198a1; --um-fuchsia: #db61a2;
+  --um-k-public: #4493f8; --um-k-lane: #2dd4bf; --um-k-ext: #ab7df8; --um-k-verb: #f778ba; --um-k-script: #9198a1; --um-k-hook: #f85149; --um-k-board: #d29922;
+  --um-w-calls: #b7bdc8; --um-w-feeds: #4493f8; --um-w-triggers: #ab7df8; --um-w-state: #59626e; --um-w-guard: #f85149;
+  --um-add-bg: rgba(63,185,80,.13); --um-add-tx: #56d364; --um-del-bg: rgba(248,81,73,.12); --um-del-tx: #ff7b72;
+  color-scheme: dark;
+}

package/lib/umlimator.d.ts

@@ -0,0 +1,140 @@
+// Types for lib/umlimator.js (hand-written; the module is plain JavaScript). docs/module-api.md explains the API.
+
+/** A map model: engine/references/schema.md § Map model, plus the README's umlimator fields. Never mutated. */
+export interface MapModel {
+  title?: string;
+  root?: string;
+  nodes: MapNode[];
+  edges?: MapEdge[];
+  views: MapView[];
+  icons?: Record<string, { g?: string; src?: string; dark?: boolean }>;
+  authors?: Record<string, { name?: string; url?: string; avatar?: string }>;
+  [key: string]: unknown;
+}
+/** 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 {
+  id: string; label?: string; kind?: string; sublabel?: string; badge?: string; badges?: Badge[]; edited?: boolean; icon?: string; verbs?: string[];
+  /** The view this card opens. It may name a view the host has not loaded yet: the card still looks stacked, and
+   *  double-click, Enter on the selected card and a click on its ⤢ badge emit `open` with that id; the map goes in once
+   *  the view is in the model (the host loads it, calls update(), then setView(), or calls update() in its open handler). */
+  opensView?: string;
+  /** The number on the ⤢ badge of a card whose view is not loaded yet (else ⤢ alone). A loaded view's cards are counted. */
+  opensCount?: number;
+  [key: string]: unknown;
+}
+/** What a line means, drawn as its colour: calls (the default), feeds (hands work on), triggers (suggests, offers, fires),
+ *  state (reads or writes a file, board or config: a thinner line, a muted label, no flow) and guard (a hook steps in).
+ *  Colours are --um-w-<kind>. An edge's `style` (emphasis, dashed, security) wins over its kind's colour. */
+export type WireKind = 'calls' | 'feeds' | 'triggers' | 'state' | 'guard';
+/** from / to: a card's id, or a container's id in the view (the line ends on its box's border). */
+export interface MapEdge {
+  id?: string; from: string; to: string; label?: string; edited?: boolean;
+  /** The line's kind (default calls). A line that stands for several edges (A→B and B→A, parallel edges) takes the first
+   *  kind they name, in model order. Nothing is guessed from the label unless the view has `kindsFromLabels`. */
+  kind?: WireKind;
+  /** How much the line stands for, drawn as its width: 1 (the default), 2 or 3 (about 1.8, 3.2 and 4.5 px), the arrowhead and
+   *  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;
+  /** 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;
+  [key: string]: unknown;
+}
+export interface MapView {
+  id: string; parent?: string | null; title?: string; nodeIds: string[];
+  edges?: (string | MapEdge)[]; layout?: Record<string, [number, number]>; repair?: boolean;
+  /** Cards 80 px tall that show their sub-line and then their chips (`verbs`) on a third line. Default: 64 px, and a card's
+   *  chips take its sub-line's place. A script card (no kind) shows no sub-line either way. */
+  subAndChips?: boolean;
+  /** 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
+  [key: string]: unknown;
+}
+
+/** What a click or selection is about, named by ids from the model. An edge without an id is "<from>-><to>#<n>". */
+export type Ref =
+  | { type: 'node'; id: string; view: string }
+  | { type: 'edge'; ids: string[]; view: string }          // one drawn line can stand for several model edges
+  | { type: 'container'; id: string; view: string }
+  | { type: 'chip'; node: string; index: number; value: string; view: string }
+  | { type: 'badge'; node: string; index: number; value: string; view: string }
+  | { type: 'badge'; container: string; index: number; value: string; view: string };   // a container's badge
+
+export interface Events {
+  click: { target: Ref; event: MouseEvent | KeyboardEvent; preventDefault(): void };   // preventDefault(): the selection stays as it was (no select); Enter on a focused tab or chip is a click (KeyboardEvent)
+  select: { target: Ref | null; targets: Ref[] };          // a chip or badge selects its card (a container's badge: its box); targets: every selected thing, the latest last
+  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`
+}
+
+/** 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(). */
+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 }
+  | { op: 'rename'; target: Ref; label: string }
+  | { op: 'move'; target: Extract<Ref, { type: 'node' }>; to: string | null }
+  | { op: 'delete'; target: Ref }
+  | { op: 'reorder'; target: Ref; index: number });
+
+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)
+  minimap?: boolean;             // default false
+  flow?: boolean;                // animated flow along lines (default: on unless prefers-reduced-motion)
+  /** 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. */
+  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;
+  on?: { [K in keyof Events]?: (e: Events[K]) => void };
+}
+
+export interface ExportOptions { view?: string; scale?: number; fontCSS?: string }
+
+export interface Handle {
+  update(model: MapModel): void;
+  setView(id: string): Promise<void> | void;
+  select(ref: Ref | null): void;
+  fit(): void;
+  /** A view (default: the one shown; another is drawn off screen) as a stand-alone SVG file: colours resolved from the
+   *  host's CSS, drawn at rest (no selection, hover, flow or edit handles), `scale` × its natural size (default 1).
+   *  `fontCSS`: the host's own @font-face rules (data: URLs) to carry into the file. No network, no headless browser.
+   *  '' for an unknown or empty view, or a destroyed handle. */
+  toSVG(options?: ExportOptions): string;
+  /** The same picture as a PNG Blob, drawn on a canvas in the browser (default scale 2). null when there is nothing to draw. */
+  toPNG(options?: ExportOptions): Promise<Blob | null>;
+  /** Puts keyboard focus on the card or line `ref` names (a chip or badge: its card), by default the selected one, else on
+   *  the map. The map's element delegates focus too: `host.focus()`, as a dialog does when it gives focus back, lands on
+   *  the selected card or line. */
+  focus(ref?: Ref | null): void;
+  on<K extends keyof Events>(type: K, fn: (e: Events[K]) => void): () => void;
+  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
+  destroy(): 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;
+    lbl: { x: number; y: number; w: number; h: number; text: string; sub?: string } | null; [key: string]: unknown }[];
+  bounds: { x: number; y: number; w: number; h: number };
+  [key: string]: unknown;
+}
+
+export function render(container: HTMLElement, model: MapModel, options?: RenderOptions): Handle;
+/** 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;
+/** 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;