@miragon/modeler-api 1.1.0 → 1.3.0

package/README.md

@@ -31,15 +31,15 @@ modeler's build — not a downstream integration review.
 import type { CollaborativeModeler } from "@miragon/modeler-api";
 ```
 
-| Law | Requirement                                                                                                                                                                                                               |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| L1  | `importText` is **silent**: no change events, undo history erased without emitting — also over existing history and foreign content; an interaction open during an import (a label editor with typed input) never commits |
-| L2  | `exportText` is **canonical**: deterministic, a byte fixpoint on canonical input, idempotent otherwise                                                                                                                    |
-| L3  | `onContentChanged` fires for **every** user-visible change — element commands, config/axis/title edits, undo/redo — and nothing else; inside a listener `exportText()` already returns the new document                   |
-| L4  | undo directly after an import is a defined **no-op** — never a stale-history mutation                                                                                                                                     |
-| L5  | view state survives a re-import; an import leaves the view **fitted** to the content; the readback may be a normalised form of what was set                                                                               |
-| L6  | `exportText` is total after a successful import; foreign content is **preserved** through import → export, never dropped, never a throw                                                                                   |
-| L7  | EVERY rejected import leaves no trace — previous document still rendered and exported, no events, undo history untouched — and the modeler **stays usable**                                                               |
+| Law | Requirement                                                                                                                                                                                                                     |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| L1  | `importText` is **silent**: no change events, undo history erased without emitting — also over existing history and foreign content; an interaction open during an import (a label editor with typed input) never commits       |
+| L2  | `exportText` is **canonical**: deterministic, a byte fixpoint on canonical input, idempotent otherwise                                                                                                                          |
+| L3  | `onContentChanged` fires for **every** user-visible change — element commands, config/axis/title edits, undo/redo — and nothing else; inside a listener `exportText()` already returns the new document                         |
+| L4  | undo directly after an import is a defined **no-op** — never a stale-history mutation                                                                                                                                           |
+| L5  | view state survives a re-import; an import leaves the view **fitted** to the content; the readback may be a normalised form of what was set; a host's view change (`setViewState`, a fit) never **commits** an open interaction |
+| L6  | `exportText` is total after a successful import; foreign content is **preserved** through import → export, never dropped, never a throw                                                                                         |
+| L7  | EVERY rejected import leaves no trace — previous document still rendered and exported, no events, undo history untouched — and the modeler **stays usable**                                                                     |
 
 View state is never part of the document: `setViewState` fires no change
 events and `exportText` is independent of it.
@@ -71,6 +71,35 @@ per-instance counter such as `event_1`. An id derived from the content (OWM's
 `component_<slug>`) collides only when both users create the same content,
 which the merge has to reconcile anyway.
 
+Optional `elements.bounds(id)` (1.2) gives the element's box in DIAGRAM
+coordinates (`{ x, y, width, height }`, the canvas's own space, which zoom and
+scroll leave alone), or `undefined` for an id `list()` does not report. Hosts
+feature-detect it (`typeof modeler.elements?.bounds === "function"`) for
+presence outlines and todo markers instead of reaching into the engine. It
+reads the live canvas: an element created, moved, resized or renamed in the
+session has its current box at once, not the one of the last import. The box
+is the element's own shape (a connection: the box around its waypoints),
+without an external label.
+
+Optional `contentBounds()` (1.3) gives the box of the CONTENT in diagram
+coordinates: what a host fits the view to when it fits itself
+(`fitOnImport: false`, the modeler shell's viewport), or `undefined` while
+there is nothing to fit (an empty diagram). Hosts feature-detect it
+(`typeof modeler.contentBounds === "function"`) instead of reaching into a
+renderer's services (Wardley's `panConstraint`). The content is everything the
+canvas draws of the document: the box covers every `elements.bounds` box and
+whatever the notation always draws (Wardley's plot with its axes, so a map
+without components still has a box and `undefined` is no emptiness test). It
+is tight, with no padding of its own: a host's fit adds its margins. Like
+`elements.bounds` it ignores zoom and scroll, reads the live canvas, and before
+the first import returns `undefined` or a box without throwing. A browser
+measures SVG text differently at each zoom (Chromium lays it out at the scaled
+font size), so a renderer computes the box from its model, or measures it once
+per content change and keeps it across view changes. A viewer that exposes it
+follows the same rules. It sits on the modeler next to the view state rather
+than on `elements`: a fit frames the whole canvas, and a notation without
+addressable elements still has content to fit.
+
 An interaction in progress during an import (an open label editor, a popup
 with typed input) never commits during or because of it (L1): no change
 event, nothing in the imported document or on its undo history, nothing
@@ -78,6 +107,68 @@ applied to an element the import removed. RECOMMENDED: keep the typed input
 and reopen the interaction on the element with the same id when it is still
 there — hosts re-import remote states while the user is typing.
 
+A view change the HOST makes — `setViewState`, or a fit its chrome applies to
+the canvas — never commits an interaction in progress either (L5, since 1.2):
+no change event, the export unchanged. Hosts restore the viewport after every
+remote re-import and refit when their chrome changes; a modeler that completes
+its label editor on every viewbox change (diagram-js's direct-editing pattern,
+which every renderer built against contract 1.1 follows) writes the half-typed
+label into the shared document for every peer. RECOMMENDED: the interaction
+stays open with its typed input, so the user's commit afterwards writes what it
+would have written without the view change.
+
+## Factory options
+
+`CollaborativeModelerOptions` (1.2) names the options a host has to feed a
+renderer's contract factory (`createCollaborativeModeler`,
+`createCollaborativeViewer`), the same for every notation, so a host can pass
+every notation one object. The contract defines them; each renderer adopts
+them in its own release, next to its own options (diagram-js
+`additionalModules`). Adopting them is part of moving a renderer to contract
+1.2: `meta.apiVersion` follows the `@miragon/modeler-api` version the renderer
+pins, and no kit case checks the options (the harness's `create()` builds the
+instance), so a renderer that reports 1.2.0 without them silently ignores a
+host's aligned options.
+
+| Option         | Meaning                                                                                                                                                                                                                                                           | Default             |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
+| `freeArea`     | the part of the canvas no host chrome covers — `{ insets }` (px from the container's edges, e.g. `shell.fitInsets()`) or `{ center }` (diagram coordinates, e.g. `viewport.freeRectCenter()`), each a function, never both; keyboard creation lands in its centre | the whole container |
+| `fitOnImport`  | fit the content after every import (the fitted view of L5), into the free rectangle or with the renderer's own padding (see below); `false` when the host's chrome fits it itself                                                                                 | `true`              |
+| `undoRedoKeys` | bind Cmd/Ctrl+Z, Cmd/Ctrl+Shift+Z and Cmd/Ctrl+Y to the canvas history; `false` when the host owns the document's history (VS Code)                                                                                                                               | `true`              |
+
+```ts
+import type { CollaborativeModelerOptions } from "@miragon/modeler-api";
+
+const options: CollaborativeModelerOptions = {
+  freeArea: { insets: () => shell.fitInsets() }, // or { center: () => viewport.freeRectCenter() }
+  fitOnImport: false, // the shell's viewport fits after every import
+  undoRedoKeys: false, // VS Code owns the history
+};
+```
+
+Until a renderer ships the aligned names, a host keeps passing that
+renderer's own names, or passes both: a renderer that accepts the aligned
+names takes them over its own. Its own names then stay accepted as DEPRECATED
+aliases for one minor release of that renderer, then go: `freeRectInsets`
+(Wardley, Event Storming, Context Maps) is `freeArea: { insets }`,
+`freeRectCenter` (Team Topologies, Value Chain) is `freeArea: { center }`, and
+Wardley's `keyboard: { undoRedo }` is `undoRedoKeys`. A renderer given only
+`center` that needs the rectangle itself (a pan constraint) works there as it
+does without the option: no host chrome, with whatever margins of its own it
+uses then. A viewer factory takes the same type and ignores `undoRedoKeys`.
+The kit's `create()` keeps `fitOnImport` at its default: L5 checks the
+modeler's own fit.
+
+The post-import fit (`fitOnImport`, L5's fitted view) MAY use the free area:
+given `insets` a renderer may fit into the free rectangle (Wardley, Context
+Maps) or keep its own fit (Event Storming, Team Topologies, Value Chain), and
+given only `center`, which names no rectangle, it MAY fit as it does without
+the option, keeping the padding it uses then (Context Maps keeps the room its
+palette needs, and a test pins it). All five published renderers conform to
+this reading; no kit case checks it, since `create()` takes no options. A host
+whose first view must leave its chrome free passes `fitOnImport: false` and
+fits itself, to `contentBounds()` where the renderer has it.
+
 ## The conformance kit
 
 ```ts
@@ -98,9 +189,11 @@ registerConformance(
     configMutations: [{ name: "axis labels", run: (m) => renameEvolutionAxis(m) }], // [] if the notation has none
     undo: (m) => triggerUndo(m),
     redo: (m) => triggerRedo(m),
+    moveElement: (m) => dragFirstElement(m), // optional: move one element by its own commands, return its id
     probeTexts: [CUT_OFF_SAMPLE], // optional: damaged forms your parser meets, on top of the derived probes
     openInteraction: (m) => typeIntoLabelEditor(m, "typed, not committed"), // open an editor, type, do NOT commit
     interactionState: (m) => readOpenLabelEditor(m), // { elementId, text } | undefined
+    commitInteraction: (m) => pressEnterInLabelEditor(m), // optional: commit what openInteraction typed
     // engines that debounce change delivery: make this outlast the debounce
     settle: () => new Promise((r) => setTimeout(r, 50)),
   },
@@ -126,7 +219,14 @@ to route it) instead of passing. An explicit `[]` (`invalidTexts`,
 `foreignTexts`, `configMutations`, `looseTexts`) is a statement that the
 notation has no such form and skips nothing. Without `openInteraction` the
 L1 interaction case reports a skip; with `openInteraction` but without
-`interactionState` only its keep-and-reopen half does.
+`interactionState` only its keep-and-reopen half does. A modeler without
+`elements.bounds` skips the bounds case; with it, a harness without
+`moveElement` skips only its move half, one without `viewState` only its
+diagram-coordinates half. A modeler without `contentBounds` skips the
+content-bounds case; with it, a harness without `viewState` skips only its
+view half, and a modeler without `elements.bounds` only its covering half.
+Without `openInteraction` or `viewState` the L5 interaction case reports a
+skip; without `commitInteraction` only its commit halves do.
 
 **Every rejection is probed.** `invalidTexts` lists what MUST reject; the kit
 does not take `[]` on trust. The L7 probe case derives damaged forms from
@@ -155,19 +255,30 @@ requires no change event, the imported document as the export and an undo
 that changes nothing (L1, L4). `interactionState` lets it check the
 recommended keep-and-reopen on the same-document import.
 
+**Interactions open during a host's view change.** On a fresh import of
+`canonicalTexts[0]` the kit opens the interaction, commits it with
+`commitInteraction` and requires the export to change and to contain the typed
+input (`interactionState().text`) — proof the case can see a commit. It then
+re-imports, opens the interaction again and calls `setViewState(viewState)`:
+no change event, the export unchanged (L5), and the view really changed. The
+RECOMMENDED keep-open is an advisory: `interactionState` must still report the
+same element and input, and `commitInteraction` must then write the same
+document as without the view change — so `openInteraction` types the same
+input on every call.
+
 **Recommendations are advisories.** Where the contract only RECOMMENDS
-(collision-free ids across peers, keep-and-reopen of an open interaction), the
-kit reports what it finds as an ADVISORY through `onAdvisory`
-(`console.warn` by default) and never fails: a recommendation becomes a law,
-with a failing case, only in a major release. The collision check imports the
-same canonical text into two fresh instances, runs `mutate` once on each and
-advises when both allocate the same id — unless both new elements carry the
-same name and the id spells it out (its letters and digits contain the
-name's, as `component_new_component` does for "New Component"). Such an id is
-derived from the content and collides for identical content by design, so
-the check reports a skip instead: let `mutate`'s elements differ in content
-(a counter the harness shares across instances, as the reference harness
-does).
+(collision-free ids across peers, keep-and-reopen of an open interaction across
+an import, keep-open across a host's view change), the kit reports what it
+finds as an ADVISORY through `onAdvisory` (`console.warn` by default) and never
+fails: a recommendation becomes a law, with a failing case, only in a major
+release. The collision check imports the same canonical text into two fresh
+instances, runs `mutate` once on each and advises when both allocate the same
+id — unless both new elements carry the same name and the id spells it out
+(its letters and digits contain the name's, as `component_new_component` does
+for "New Component"). Such an id is derived from the content and collides for
+identical content by design, so the check reports a skip instead: let
+`mutate`'s elements differ in content (a counter the harness shares across
+instances, as the reference harness does).
 
 **View state is compared by readback.** The kit never compares
 `getViewState()` with your `viewState` literal: it sets it, reads the
@@ -175,6 +286,24 @@ modeler's own (possibly normalised) state back, and requires that readback
 to survive a re-import — a diagram-js viewbox that comes back rounded with
 `scale`/`inner`/`outer` is fine.
 
+**Element boxes are verified live.** With `elements.bounds` present, every
+listed id must give a finite box with a non-negative size and an unknown id
+`undefined` — after an import, after `mutate` (the new element has its box at
+once) and after `moveElement` (the moved element's box changed position).
+`setViewState(viewState)` must leave every box as it was: they are diagram
+coordinates. A viewer that exposes `bounds` is held to the same listing rules.
+
+**The content box is verified around every element.** With `contentBounds`
+present, it must not throw and must give `undefined` or a finite box with a
+non-negative size before the first import; after importing each canonical text
+and after `mutate` it must give a finite box as soon as an element is listed,
+and that box must cover every element's finite `elements.bounds` box (the new
+element included, so a box measured at the last import fails), give or take
+what float32 rounding takes off a box measured on the live SVG (`getBBox`): a
+thousandth of a unit, or 2^-20 of the edge where that is more.
+`setViewState(viewState)` must leave it as it was. A viewer that exposes `contentBounds` is held to the
+same rules after an import.
+
 **Element identity is verified through names.** After an unrelated edit, and
 after an export → import into the same instance, a fresh instance and the
 viewer, every id the session reported must still exist and, where the
@@ -198,6 +327,16 @@ rewrites the constant on every release (`extra-files`) and a test pins it to
 `meta.apiVersion`; hosts match on the major (`apiVersionsCompatible`).
 Releases are tagged `modeler-api-vX.Y.Z`.
 
+Hosts bind from the package root, which carries no kit code (since 1.2;
+`@miragon/modeler-api/conformance` re-exports `apiVersionsCompatible`, so 1.1
+imports keep working):
+
+```ts
+import { apiVersionsCompatible, MODELER_API_VERSION } from "@miragon/modeler-api";
+
+if (!apiVersionsCompatible(modeler.meta.apiVersion, MODELER_API_VERSION)) refuseToMount(modeler);
+```
+
 The contract is first published as 1.0.0, never 0.x: under 0.x,
 `apiVersionsCompatible` matches on the minor too, which would turn every
 additive surface into a lockstep release across all modelers and their
@@ -226,6 +365,10 @@ Recommendations today, proposed as hard laws for the next major:
   during an import is reopened, with its typed input, on the element with the
   same id when that element is still there (today: L1 RECOMMENDED, advisory in
   the L1 interaction case).
+- **Keep an interaction open across a host's view change** — after
+  `setViewState` (or a host's fit) the interaction is still open with its typed
+  input, and the user's commit writes what it would have written without the
+  view change (today: L5 RECOMMENDED, advisory in the L5 interaction case).
 
 ## License
 

package/dist/chunk-JK23ZTVG.js

@@ -0,0 +1,14 @@
+// src/index.ts
+var MODELER_API_VERSION = "1.3.0";
+function apiVersionsCompatible(a, b) {
+  const [aMajor = "", aMinor = ""] = a.split(".");
+  const [bMajor = "", bMinor = ""] = b.split(".");
+  if (aMajor !== bMajor) return false;
+  return aMajor !== "0" || aMinor === bMinor;
+}
+
+export {
+  MODELER_API_VERSION,
+  apiVersionsCompatible
+};
+//# sourceMappingURL=chunk-JK23ZTVG.js.map

package/dist/chunk-JK23ZTVG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @miragon/modeler-api — ONE interface every Miragon modeler implements.\n *\n * The contract encodes, as REQUIREMENTS, the behavioral drift that had to be\n * discovered per modeler against engine internals before it existed:\n * an `importDSL` that emitted change events (rewriting hand-authored files on\n * open), an import that left the undo stack on stale removed shapes, a\n * serializer that was not a byte fixpoint. A host embedding a conforming\n * modeler needs no per-engine suppression tricks — the laws below hold.\n *\n * The conformance test kit (`@miragon/modeler-api/conformance`) turns each\n * law into an executable case the modeler repo runs in its own CI.\n */\n\n/** the semver of THIS contract — a modeler declares the version it implements\n *  in `meta.apiVersion`; hosts check compatibility with `apiVersionsCompatible`\n *  (same major; while 0.x, the same minor too). The constant IS the\n *  package version: release-please rewrites the literal below on every\n *  release (release-please-config.json `extra-files`), and the kit's own\n *  test pins it to package.json exactly. Modelers pin the npm package; the\n *  constant is what travels in `meta`. */\nexport const MODELER_API_VERSION = \"1.3.0\"; // x-release-please-version\n\n/**\n * apiVersion compatibility: same major — and, while the contract is 0.x,\n * the same minor too (pre-1.0 minors may break; bump-minor-pre-major).\n * Hosts call it at bind time with `meta.apiVersion` and their own\n * MODELER_API_VERSION; it lives in the package root so that check never\n * pulls the conformance kit into a host bundle (`/conformance` re-exports it)\n */\nexport function apiVersionsCompatible(a: string, b: string): boolean {\n  const [aMajor = \"\", aMinor = \"\"] = a.split(\".\");\n  const [bMajor = \"\", bMinor = \"\"] = b.split(\".\");\n  if (aMajor !== bMajor) return false;\n  return aMajor !== \"0\" || aMinor === bMinor;\n}\n\nexport interface ModelerMeta {\n  /** stable notation id, e.g. \"wardley\", \"team-topology\", \"event-storming\" */\n  readonly notation: string;\n  /** the MODELER_API_VERSION this modeler implements — compatible when the\n   *  major matches and, while the contract is 0.x, the minor too (pre-1.0\n   *  minors may break: bump-minor-pre-major) */\n  readonly apiVersion: string;\n  /**\n   * true on an editing mount (the package's Modeler), false on a VIEWER\n   * (its NavigatedViewer/Viewer): a viewer never fires `onContentChanged`,\n   * accepts no user commands, and still imports, exports, reveals and\n   * reports view state exactly like the editor — hosts mount it on\n   * read-only surfaces (an MCP-App widget in read-only mode) without\n   * per-package knowledge or a command-stack shim.\n   */\n  readonly editable: boolean;\n}\n\nexport interface ImportResult {\n  /** non-fatal notes from the import (unknown lines kept, migrations run) */\n  warnings: string[];\n}\n\nexport interface ElementInfo {\n  /**\n   * stable element id — identical across re-imports of the same text AND\n   * untouched by edits to OTHER elements: hosts anchor todos, presence and\n   * `?element=` deep links to it, so an id that renumbers when a line is\n   * inserted above (positional edge ids) breaks every anchor below it. An\n   * element without an id in the text gets one the serializer WRITES BACK.\n   *\n   * The id a session reports IS the element's id in the document: after\n   * `exportText()` → `importText()` — in this instance or in any other one\n   * (a peer, the viewer, the next session) — the element carries the same\n   * id. An id that lives only in memory anchors nothing: the todo or deep\n   * link a host stored against it points nowhere once the text travels.\n   *\n   * RECOMMENDED: when two peers create different elements at the same time,\n   * their ids do not collide. An id allocated regardless of the content —\n   * a per-instance counter (`event_1` on both peers) — does: once both edits\n   * merge into one document, two elements share one id; random or\n   * peer-scoped ids do not. An id derived from the content (OWM's\n   * `component_<slug>`) collides only when both users create the same\n   * content, which the merge has to reconcile anyway.\n   */\n  id: string;\n  /** human label, when the notation has one */\n  name?: string;\n}\n\n/** a box in diagram coordinates: an element's, as `ElementsSurface.bounds`\n *  reports it, or the content's, as `CollaborativeModeler.contentBounds` does */\nexport interface ElementBounds {\n  x: number;\n  y: number;\n  width: number;\n  height: number;\n}\n\n/**\n * Optional element surface — what a host needs for anchored todos, `?element=`\n * deep links and the selection half of live presence. Absent = the notation\n * has no addressable element identity. Ids are ELEMENT ids throughout: a\n * shape that only labels another element (diagram-js external labels) is\n * reported and revealed as its target, never under its own label id.\n */\nexport interface ElementsSurface {\n  /** every addressable element currently on the canvas */\n  list(): ElementInfo[];\n  /** select + scroll the element into view; false when the id is unknown.\n   *  Revealing is view behavior: it delivers a selection, never a change event */\n  reveal(id: string): boolean;\n  /** the current selection as stable element ids — synchronous, so a host\n   *  can read it at the moment of a click (a deep link carrying the\n   *  selection) without caching every delivery */\n  selection(): string[];\n  /** selection changes as STABLE element ids; returns the unsubscribe */\n  onSelection(cb: (ids: string[]) => void): () => void;\n  /**\n   * the element's box in DIAGRAM coordinates — the canvas's own coordinate\n   * space, which zoom and scroll leave alone (a host maps it to the screen\n   * with the current view, or draws in a layer that moves with the canvas) —\n   * or `undefined` for an id `list()` does not report. Optional (1.2): hosts\n   * feature-detect it for presence outlines and todo markers instead of\n   * reaching into the engine.\n   *\n   * It reads the LIVE canvas: an element created, moved, resized or renamed\n   * in this session has its current box at once, not the one of the last\n   * import — a host outlining a peer's selection would otherwise draw it\n   * where the element was, or not at all, until the next import. The box is\n   * the element's own shape (a connection: the box around its waypoints); an\n   * external label is not part of it.\n   */\n  bounds?(id: string): ElementBounds | undefined;\n}\n\n/**\n * The collaborative-modeler contract. The LAWS (verified by the conformance\n * kit) are part of the interface:\n *\n *  L1 SILENT IMPORT — `importText` never fires `onContentChanged` and erases\n *     the undo history without emitting — also when history exists. Hosts\n *     re-import remote states on every sync; an import echo would re-export\n *     the canonical serialization over half-typed peer text.\n *     An interaction in progress when an import runs (an open label editor,\n *     a popup with typed input) never commits during or because of the\n *     import: no change event comes from it, its input lands neither in the\n *     imported document nor on its fresh undo history, and nothing is\n *     applied to an element the import removed. RECOMMENDED: keep the typed\n *     input and reopen the interaction on the element with the same id when\n *     that element is still there after the import — a remote re-import\n *     should not cost the user what they were typing.\n *  L2 CANONICAL FIXPOINT — `exportText` is deterministic, and for any text t:\n *     with c = exportText() after importText(t), importText(c) followed by\n *     exportText() returns c byte-for-byte. Canonicalization is idempotent;\n *     opening a file never rewrites it.\n *  L3 ONE CHANGE EVENT — every user-visible atomic change (element commands\n *     AND config/axis/title/style edits that live in the document, AND\n *     undo/redo) fires `onContentChanged` at least once, and nothing else\n *     does: not `importText`, not undo-history housekeeping, not view or\n *     selection changes. When a listener runs, `exportText()` ALREADY\n *     returns the post-change serialization — hosts export inside the\n *     listener; an emit-before-apply would lose the last edit.\n *  L4 DEFINED UNDO ACROSS IMPORTS — undo directly after an `importText` is a\n *     no-op: it must never mutate or resurrect shapes from the pre-import\n *     document (id coincidence included).\n *  L5 VIEW-STATE ROUND-TRIP — `getViewState`/`setViewState` survive a\n *     re-import: snapshot before, restore after, viewport unchanged. An\n *     import leaves the view FITTED to the content (the defined post-import\n *     view, the same for the same document and host — a host that wants to\n *     keep the user's viewport across a remote re-import snapshots before\n *     and restores after, and one that fits the view itself passes\n *     `fitOnImport: false` and fits to `contentBounds()`, 1.3, where the\n *     modeler has it); before the first import `getViewState()` returns\n *     `undefined` or a state `setViewState` accepts, and never throws. The\n *     readback may be a NORMALISED form of what was set (a diagram-js\n *     viewbox comes back rounded, with scale/inner/outer) — what must hold\n *     is that setting a readback yields that readback again.\n *     A view change the HOST makes — `setViewState`, or a fit its chrome\n *     applies to the canvas — never commits an interaction in progress (an\n *     open label editor, a popup with typed input): no change event, the\n *     export unchanged. Hosts restore the viewport after every remote\n *     re-import and refit when their chrome changes; a commit there writes\n *     the half-typed input into the shared document for every peer.\n *     RECOMMENDED: the interaction stays open with its typed input, so the\n *     user's own commit afterwards writes what it would have written without\n *     the view change.\n *  L6 EXPORT IS TOTAL AFTER IMPORT — after a successful import (and any\n *     sequence of user commands and undos), `exportText` succeeds. Foreign or\n *     auxiliary content the modeler does not understand is PRESERVED through\n *     import → export (it comes back in the export, canonicalised like the\n *     rest), never dropped and never a reason to throw.\n *  L7 REJECTED IMPORTS LEAVE NO TRACE — `importText` on non-importable text\n *     REJECTS (resolve-with-warnings means \"imported, with notes\"; rejection\n *     means \"nothing imported\"). This holds for EVERY rejection, whatever\n *     the input (a truncated or half-typed text included): afterwards the\n *     previously imported document is still rendered with its elements,\n *     `exportText` still returns it, no change event has fired and the undo\n *     history is untouched.\n *     The modeler stays USABLE: the next valid import renders, the next user\n *     command applies. Hosts re-import half-typed peer text on every sync —\n *     \"blank (or wedged) until healed\" is not an acceptable failure mode.\n *\n *  View state is NEVER part of the document: `setViewState` fires no change\n *  events and `exportText` is independent of it.\n */\nexport interface CollaborativeModeler {\n  readonly meta: ModelerMeta;\n\n  /** mount the canvas into a host element (once, before the first import).\n   *  The host must be attached to the document with a non-zero size — a\n   *  detached or 0×0 element gives diagram-js engines NaN viewboxes.\n   *  Calls made between mounting and the first import (`exportText()`, a\n   *  user command) return whatever the modeler defines, or throw (only\n   *  `getViewState` never does, L5), but they never wedge the instance:\n   *  the first `importText` still behaves exactly as specified */\n  attachTo(host: Element): void;\n\n  /** parse + render `text` — SILENT per L1, the view fitted to the content\n   *  per L5; resolves when rendered, REJECTS when nothing was imported (L7).\n   *  This holds for the first import too, whatever was called before it — a\n   *  host may export or route a command before its first document arrives */\n  importText(text: string): Promise<ImportResult>;\n\n  /** the canonical serialization of the current document (L2, L6) */\n  exportText(): string;\n\n  /** subscribe to user-visible model changes (L3); returns the unsubscribe */\n  onContentChanged(cb: () => void): () => void;\n\n  /** opaque viewport snapshot (zoom/scroll) — JSON-serializable (L5) */\n  getViewState(): unknown;\n  setViewState(state: unknown): void;\n\n  /**\n   * the box of the CONTENT in diagram coordinates — what a host fits the\n   * view to when it fits itself (`fitOnImport: false`, the modeler shell's\n   * viewport) — or `undefined` while there is nothing to fit (an empty\n   * diagram). Optional (1.3): hosts feature-detect it (`typeof\n   * modeler.contentBounds === \"function\"`) instead of reaching into a\n   * renderer's services; a renderer's own fit stays its business (L5).\n   *\n   * The content is everything the canvas draws of the document: the box\n   * covers every box `elements.bounds` reports, and whatever the notation\n   * always draws (Wardley's plot with its axes — a map without components\n   * still has a box, so `undefined` is no emptiness test). It is tight: no\n   * padding and no room for chrome of its own, since a host's fit adds its\n   * margins (the shell's fit insets) on top. Like `elements.bounds` it is in\n   * the canvas's own coordinate space, which zoom and scroll leave alone,\n   * and it reads the LIVE canvas: an element created or moved in this\n   * session counts at once. A browser measures SVG text differently at each\n   * zoom (Chromium lays it out at the scaled font size), so a renderer\n   * computes the box from its model, or measures it once per content change\n   * and keeps it across view changes. Before the first import it returns\n   * `undefined` or a box, and never throws. A viewer that exposes it follows\n   * the same rules. It sits next to the view state rather than on `elements`: a fit\n   * frames the whole canvas, and a notation without addressable elements\n   * still has content to fit.\n   */\n  contentBounds?(): ElementBounds | undefined;\n\n  readonly elements?: ElementsSurface;\n\n  /** tear down DOM + listeners; further calls on the instance are undefined\n   *  behavior, but a second destroy() must not throw */\n  destroy(): void;\n}\n\n/** px the host's chrome covers along the edges of the modeler's container */\nexport interface FreeAreaInsets {\n  top: number;\n  right: number;\n  bottom: number;\n  left: number;\n}\n\n/** a point in diagram coordinates */\nexport interface DiagramPoint {\n  x: number;\n  y: number;\n}\n\n/**\n * The FREE AREA: the part of the canvas no host chrome covers (Miragon\n * guide §5.9). Keyboard creation places a new element in its centre (§5.5)\n * and a renderer that constrains panning keeps the content reachable around\n * it, so both agree with a host that fits into the same rectangle. A host\n * passes ONE of two forms, each a function the renderer reads whenever it\n * needs it (the chrome changes when an inspector or a legend opens):\n *\n *  - `insets`: what the chrome covers, in px from the container's edges\n *    (the modeler shell's `shell.fitInsets()`); the renderer computes the\n *    centre itself, the way a fit does;\n *  - `center`: the centre itself, in diagram coordinates, `undefined` while\n *    there is none (a 0×0 container) — the shell's `viewport.freeRectCenter()`.\n *\n * A renderer accepts both. One that needs the rectangle itself (a pan\n * constraint) and is given only `center` works there as it does without\n * the option: it assumes no host chrome, with whatever margins of its own\n * it uses then.\n *\n * The post-import fit (`fitOnImport`, L5's fitted view) MAY use the free\n * area: given `insets` a renderer may fit into the free rectangle or keep\n * its own fit, and given only `center`, which names no rectangle, it MAY fit\n * as it does without the option, keeping the padding it uses then (Context\n * Maps keeps the room its palette needs) — the reading all five published\n * renderers conform to, which no kit case checks; a host whose first view\n * must leave its chrome free passes `fitOnImport: false` and fits itself.\n */\nexport type FreeArea =\n  | { insets: () => FreeAreaInsets; center?: never }\n  | { center: () => DiagramPoint | undefined; insets?: never };\n\n/**\n * The options a renderer's contract factory takes under THESE names once it\n * implements contract 1.2, so a host feeds every notation the same object\n * instead of one spelling per renderer. A renderer extends the type with its\n * own options (diagram-js `additionalModules`); the contract fixes names,\n * meaning and defaults. A viewer factory takes the same type and ignores\n * what has no meaning without editing (`undoRedoKeys`).\n *\n * Each renderer adopts them in its own release, as part of its move to 1.2:\n * `meta.apiVersion` follows the pinned package and no kit case checks the\n * options, so the version alone does not tell a host they are honoured.\n * Until a renderer ships them, a host passes the renderer's own names, or\n * both. Those names then stay accepted as DEPRECATED aliases for one minor\n * release of that renderer, then go: `freeRectInsets` (Wardley, Event\n * Storming, Context Maps) is `freeArea: { insets }`, `freeRectCenter` (Team\n * Topologies, Value Chain) is `freeArea: { center }`, and Wardley's\n * `keyboard: { undoRedo }` is `undoRedoKeys`. Given both, the aligned name\n * wins.\n */\nexport interface CollaborativeModelerOptions {\n  /** where the host's chrome leaves the canvas free; default: the whole container */\n  freeArea?: FreeArea | undefined;\n  /**\n   * fit the content into the view after every import — default true, the\n   * fitted view L5 defines. A host whose chrome fits the content itself\n   * (the modeler shell's viewport fits into the free area) passes false:\n   * the post-import view is then the host's to set, and L5's fit is the\n   * host's fit. The conformance kit runs with the default. Whether the\n   * renderer's own fit uses `freeArea` is its choice (see `FreeArea`): with\n   * `insets` it may fit into the free rectangle, with only `center` it may\n   * keep the padding it uses without the option\n   */\n  fitOnImport?: boolean | undefined;\n  /**\n   * bind Cmd/Ctrl+Z, Cmd/Ctrl+Shift+Z and Cmd/Ctrl+Y to the canvas history —\n   * default true. A host that owns the document's history (VS Code) passes\n   * false, and the keys reach it unprevented; text fields keep their own\n   * undo either way\n   */\n  undoRedoKeys?: boolean | undefined;\n}\n"],"mappings":";AAqBO,IAAM,sBAAsB;AAS5B,SAAS,sBAAsB,GAAW,GAAoB;AACnE,QAAM,CAAC,SAAS,IAAI,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG;AAC9C,QAAM,CAAC,SAAS,IAAI,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG;AAC9C,MAAI,WAAW,OAAQ,QAAO;AAC9B,SAAO,WAAW,OAAO,WAAW;AACtC;","names":[]}

package/dist/conformance.cjs

@@ -28,7 +28,13 @@ __export(conformance_exports, {
 module.exports = __toCommonJS(conformance_exports);
 
 // src/index.ts
-var MODELER_API_VERSION = "1.1.0";
+var MODELER_API_VERSION = "1.3.0";
+function apiVersionsCompatible(a, b) {
+  const [aMajor = "", aMinor = ""] = a.split(".");
+  const [bMajor = "", bMinor = ""] = b.split(".");
+  if (aMajor !== bMajor) return false;
+  return aMajor !== "0" || aMinor === bMinor;
+}
 
 // src/conformance.ts
 function attachedHost(width = 800, height = 600) {
@@ -40,12 +46,6 @@ function attachedHost(width = 800, height = 600) {
   document.body.append(wrapper);
   return host;
 }
-function apiVersionsCompatible(a, b) {
-  const [aMajor = "", aMinor = ""] = a.split(".");
-  const [bMajor = "", bMinor = ""] = b.split(".");
-  if (aMajor !== bMajor) return false;
-  return aMajor !== "0" || aMinor === bMinor;
-}
 function fail(message) {
   throw new Error(`modeler-api conformance: ${message}`);
 }
@@ -58,6 +58,68 @@ function exportOrFail(modeler, when) {
   }
 }
 var same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+var hasBounds = (elements) => typeof elements.bounds === "function";
+var isFiniteBox = (box) => box !== void 0 && [box.x, box.y, box.width, box.height].every((n) => typeof n === "number" && Number.isFinite(n)) && box.width >= 0 && box.height >= 0;
+var describeBox = (box) => box === void 0 ? "undefined" : `{ x: ${box.x}, y: ${box.y}, width: ${box.width}, height: ${box.height} }`;
+var hasContentBounds = (m) => typeof m.contentBounds === "function";
+var edgeTolerance = (edge) => Math.max(1e-3, Math.abs(edge) * 2 ** -20);
+var covers = (outer, inner) => {
+  const right = outer.x + outer.width;
+  const bottom = outer.y + outer.height;
+  return inner.x >= outer.x - edgeTolerance(outer.x) && inner.y >= outer.y - edgeTolerance(outer.y) && inner.x + inner.width <= right + edgeTolerance(right) && inner.y + inner.height <= bottom + edgeTolerance(bottom);
+};
+function contentBoxOf(m, when) {
+  let box;
+  try {
+    box = m.contentBounds();
+  } catch (e) {
+    fail(`contentBounds() threw ${when}: ${String(e)}`);
+  }
+  if (box === void 0) return void 0;
+  if (!isFiniteBox(box)) {
+    fail(
+      `contentBounds() ${when} is ${describeBox(box)} \u2014 the content box must be finite with a non-negative size, or undefined when there is nothing to fit`
+    );
+  }
+  return { x: box.x, y: box.y, width: box.width, height: box.height };
+}
+function expectContentAroundElements(m, when) {
+  const box = contentBoxOf(m, when);
+  const listed = m.elements?.list() ?? [];
+  if (box === void 0) {
+    if (listed.length > 0) {
+      fail(
+        `contentBounds() ${when} is undefined while elements.list() reports ${listed.length} element(s) \u2014 undefined means there is nothing to fit`
+      );
+    }
+    return void 0;
+  }
+  if (m.elements && hasBounds(m.elements)) {
+    for (const { id } of listed) {
+      const element = m.elements.bounds(id);
+      if (!isFiniteBox(element)) continue;
+      if (!covers(box, element)) {
+        fail(
+          `contentBounds() ${when} is ${describeBox(box)}, which does not cover elements.bounds('${id}') = ${describeBox(element)} \u2014 the content box holds every element (and reads the live canvas)`
+        );
+      }
+    }
+  }
+  return box;
+}
+function boxesOf(elements, when) {
+  const boxes = /* @__PURE__ */ new Map();
+  for (const { id } of elements.list()) {
+    const box = elements.bounds(id);
+    if (!isFiniteBox(box)) {
+      fail(
+        `elements.bounds('${id}') ${when} is ${describeBox(box)} \u2014 every listed id must give a finite box with a non-negative size`
+      );
+    }
+    boxes.set(id, { x: box.x, y: box.y, width: box.width, height: box.height });
+  }
+  return boxes;
+}
 function assertFinite(state, when) {
   const json = JSON.stringify(
     state,
@@ -572,6 +634,97 @@ ${out}`);
         }
       }
     },
+    {
+      name: "L5: a host's view change never commits an open interaction",
+      async run(h) {
+        if (!h.openInteraction) {
+          return skip(
+            "openInteraction is undefined \u2014 a host's view change over an open interaction (a label editor with typed input) was not verified"
+          );
+        }
+        if (h.viewState === void 0) {
+          return skip(
+            "viewState is undefined \u2014 a host's view change over an open interaction was not verified (supply a panned/zoomed state)"
+          );
+        }
+        const openInteraction = h.openInteraction;
+        const commitInteraction = h.commitInteraction;
+        const viewState = h.viewState;
+        const settle = h.settle ?? defaultSettle;
+        const first = h.canonicalTexts[0] ?? "";
+        const m = await h.create();
+        try {
+          await m.importText(first);
+          const doc = exportOrFail(m, "after importing canonicalTexts[0]");
+          const open = async () => {
+            await openInteraction(m);
+            await settle();
+            const opened2 = h.interactionState?.(m);
+            if (h.interactionState && opened2 === void 0) {
+              fail("interactionState reports no interaction after openInteraction \u2014 the case proves nothing");
+            }
+            return opened2;
+          };
+          let committed;
+          if (commitInteraction) {
+            const typed = (await open())?.text;
+            await commitInteraction(m);
+            await settle();
+            committed = exportOrFail(m, "after committing the interaction");
+            if (committed === doc || typed && !committed.includes(typed)) {
+              fail(
+                "committing the interaction openInteraction opened did not write its typed input into the export \u2014 the case proves nothing (commitInteraction must commit the way a user does, openInteraction type input the serializer writes verbatim)"
+              );
+            }
+            await importOrFail(m, first, "re-importing canonicalTexts[0] after the commit rejected");
+          }
+          const opened = await open();
+          const view = m.getViewState();
+          const { calls } = await changeEvents(h, m, () => m.setViewState(viewState));
+          if (calls > 0) {
+            fail(
+              `setViewState over an open interaction fired onContentChanged ${calls}x \u2014 the host's view change committed it (L5; if every setViewState emits, see the L5 round-trip case first)`
+            );
+          }
+          if (exportOrFail(m, "after setViewState over an open interaction") !== doc) {
+            fail(
+              "setViewState over an open interaction changed the export \u2014 the host's view change committed it (L5)"
+            );
+          }
+          if (same(m.getViewState(), view)) {
+            fail(
+              "setViewState(viewState) had no effect over an open interaction \u2014 the case proves nothing (supply a state that differs from the fitted view)"
+            );
+          }
+          const after = h.interactionState?.(m);
+          let advice;
+          if (opened !== void 0 && (after?.elementId !== opened.elementId || after?.text !== opened.text)) {
+            const input = opened.text === void 0 ? "" : ` with the input ${JSON.stringify(opened.text)}`;
+            const what = after === void 0 ? "closed it" : `left ${JSON.stringify(after)} open`;
+            advice = `an interaction on '${opened.elementId}'${input} did not survive a host's view change (setViewState ${what}) \u2014 RECOMMENDED: keep it open with its typed input, so the user's commit afterwards writes what it would have written without the view change`;
+          } else if (commitInteraction && committed !== void 0) {
+            await commitInteraction(m);
+            await settle();
+            const out = exportOrFail(m, "after committing the interaction after a view change");
+            if (out !== committed) {
+              advice = `committing an interaction after a host's view change wrote another document than committing it without one \u2014 RECOMMENDED: keep it open with its typed input across a view change (if openInteraction types different input per call, this advice is the harness's):
+--- committed without a view change
+${committed}
+--- committed after setViewState
+${out}`;
+            }
+          }
+          return {
+            ...commitInteraction ? {} : {
+              skipped: "commitInteraction is undefined \u2014 that the typed input changes the document (without it the case may prove nothing) and that it still commits after the view change were not checked (pass commitInteraction to check both)"
+            },
+            ...advice === void 0 ? {} : { advisories: [advice] }
+          };
+        } finally {
+          m.destroy();
+        }
+      }
+    },
     {
       name: "elements (when present): stable ids across re-imports and unrelated edits, reveal and selection semantics",
       async run(h) {
@@ -751,6 +904,136 @@ ${out}`);
         }
       }
     },
+    {
+      name: "elements.bounds (when present): a finite box in diagram coordinates for every listed id, undefined for an unknown one, live after a new element and a move",
+      async run(h) {
+        const text = h.canonicalTexts[0] ?? "";
+        const settle = h.settle ?? defaultSettle;
+        const m = await h.create();
+        let viewer;
+        try {
+          await m.importText(text);
+          const elements = m.elements;
+          if (!elements)
+            return skip("the modeler exposes no elements surface (optional) \u2014 nothing to verify");
+          if (!hasBounds(elements))
+            return skip("the modeler exposes no elements.bounds (optional) \u2014 nothing to verify");
+          boxesOf(elements, "after an import");
+          if (elements.bounds("__modeler_api_no_such_id__") !== void 0)
+            fail("elements.bounds(unknown id) must return undefined");
+          const imported = new Set(elements.list().map((e) => e.id));
+          await h.mutate(m);
+          await settle();
+          for (const { id } of elements.list().filter((e) => !imported.has(e.id))) {
+            const box = elements.bounds(id);
+            if (!isFiniteBox(box)) {
+              fail(
+                `elements.bounds('${id}') of an element created in the session is ${describeBox(box)} \u2014 bounds must read the live canvas, not the last import`
+              );
+            }
+          }
+          const unverified = [];
+          if (h.moveElement) {
+            const before = boxesOf(elements, "before a move");
+            const movedId = await h.moveElement(m);
+            await settle();
+            const was = before.get(movedId);
+            if (was === void 0)
+              fail(`moveElement returned '${movedId}', an id elements.list() did not report before the move`);
+            const box = boxesOf(elements, "after a move").get(movedId);
+            if (box === void 0)
+              fail(`'${movedId}' is gone from elements.list() after moveElement moved it`);
+            if (box.x === was.x && box.y === was.y) {
+              fail(
+                `elements.bounds('${movedId}') did not follow a move made through the modeler's own commands (still ${describeBox(was)}) \u2014 bounds must read the live canvas, not the last import (or moveElement did not move the element)`
+              );
+            }
+          } else {
+            unverified.push("moveElement is undefined \u2014 that a box follows a move was not verified");
+          }
+          if (h.viewState !== void 0) {
+            const atRest = boxesOf(elements, "before a view change");
+            m.setViewState(h.viewState);
+            for (const [id, box] of boxesOf(elements, "after setViewState")) {
+              if (!same(box, atRest.get(id))) {
+                fail(
+                  `elements.bounds('${id}') changed with the view (${describeBox(atRest.get(id))} \u2192 ${describeBox(box)}) \u2014 boxes are in diagram coordinates, which zoom and scroll leave alone`
+                );
+              }
+            }
+          } else {
+            unverified.push(
+              "viewState is undefined \u2014 that boxes are independent of the view was not verified"
+            );
+          }
+          if (h.createReadonly) {
+            viewer = await h.createReadonly();
+            await importOrFail(viewer, text, "the viewer rejected canonicalTexts[0]");
+            if (viewer.elements && hasBounds(viewer.elements)) {
+              boxesOf(viewer.elements, "on the viewer after an import");
+              if (viewer.elements.bounds("__modeler_api_no_such_id__") !== void 0)
+                fail("the viewer's elements.bounds(unknown id) must return undefined");
+            }
+          }
+          if (unverified.length > 0) return skip(unverified.join("; "));
+        } finally {
+          m.destroy();
+          viewer?.destroy();
+        }
+      }
+    },
+    {
+      name: "contentBounds (when present): a finite box in diagram coordinates around every listed element, live after a new element, unchanged by zoom and scroll",
+      async run(h) {
+        const settle = h.settle ?? defaultSettle;
+        const m = await h.create();
+        let viewer;
+        try {
+          if (!hasContentBounds(m))
+            return skip("the modeler exposes no contentBounds (optional, 1.3) \u2014 nothing to verify");
+          contentBoxOf(m, "before the first import");
+          for (const [index, text] of h.canonicalTexts.entries()) {
+            await importOrFail(m, text, `importText(canonicalTexts[${index}]) rejected`);
+            expectContentAroundElements(m, `after importing canonicalTexts[${index}]`);
+          }
+          await importOrFail(m, h.canonicalTexts[0] ?? "", "importText(canonicalTexts[0]) rejected");
+          await h.mutate(m);
+          await settle();
+          const atRest = expectContentAroundElements(m, "after a user mutation added an element");
+          const unverified = [];
+          if (h.viewState !== void 0) {
+            m.setViewState(h.viewState);
+            const viewed = contentBoxOf(m, "after setViewState");
+            if (!same(viewed, atRest)) {
+              fail(
+                `contentBounds() changed with the view (${describeBox(atRest)} \u2192 ${describeBox(viewed)}) \u2014 the content box is in diagram coordinates, which zoom and scroll leave alone`
+              );
+            }
+          } else {
+            unverified.push(
+              "viewState is undefined \u2014 that the content box is independent of the view was not verified"
+            );
+          }
+          if (!m.elements || !hasBounds(m.elements)) {
+            unverified.push(
+              "the modeler exposes no elements.bounds \u2014 that the content box covers every element was not verified"
+            );
+          }
+          if (h.createReadonly) {
+            viewer = await h.createReadonly();
+            if (hasContentBounds(viewer)) {
+              contentBoxOf(viewer, "on the viewer before the first import");
+              await importOrFail(viewer, h.canonicalTexts[0] ?? "", "the viewer rejected canonicalTexts[0]");
+              expectContentAroundElements(viewer, "on the viewer after an import");
+            }
+          }
+          if (unverified.length > 0) return skip(unverified.join("; "));
+        } finally {
+          m.destroy();
+          viewer?.destroy();
+        }
+      }
+    },
     {
       name: "L6: export is total after imports, user mutations and undo",
       async run(h) {