@miragon/modeler-api 1.2.0 → 1.3.0

package/README.md

@@ -81,6 +81,25 @@ 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
@@ -114,7 +133,7 @@ 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); `false` when the host's chrome fits it itself                                                                                                                                                         | `true`              |
+| `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
@@ -134,10 +153,21 @@ 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) treats the whole
-container as free. 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.
+`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
 
@@ -192,9 +222,11 @@ L1 interaction case reports a skip; with `openInteraction` but without
 `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. Without `openInteraction` or `viewState` the L5
-interaction case reports a skip; without `commitInteraction` only its commit
-halves do.
+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
@@ -261,6 +293,17 @@ 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

package/dist/{chunk-E6KJB7QH.js → chunk-JK23ZTVG.js}

@@ -1,5 +1,5 @@
 // src/index.ts
-var MODELER_API_VERSION = "1.2.0";
+var MODELER_API_VERSION = "1.3.0";
 function apiVersionsCompatible(a, b) {
   const [aMajor = "", aMinor = ""] = a.split(".");
   const [bMajor = "", bMinor = ""] = b.split(".");
@@ -11,4 +11,4 @@ export {
   MODELER_API_VERSION,
   apiVersionsCompatible
 };
-//# sourceMappingURL=chunk-E6KJB7QH.js.map
+//# 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,7 @@ __export(conformance_exports, {
 module.exports = __toCommonJS(conformance_exports);
 
 // src/index.ts
-var MODELER_API_VERSION = "1.2.0";
+var MODELER_API_VERSION = "1.3.0";
 function apiVersionsCompatible(a, b) {
   const [aMajor = "", aMinor = ""] = a.split(".");
   const [bMajor = "", bMinor = ""] = b.split(".");
@@ -61,6 +61,52 @@ 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()) {
@@ -936,6 +982,58 @@ ${out}`;
         }
       }
     },
+    {
+      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) {