@miragon/modeler-api 1.0.0 → 1.2.0

package/README.md

@@ -31,19 +31,23 @@ 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                                                                     |
-| 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  | a 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.
 
+Calls made before the first import (`exportText()`, a user command) may
+return or throw whatever the modeler defines, but never wedge the instance:
+the first `importText` still renders and resolves as specified.
+
 `meta.editable` tells a viewer mount from an editor: a package that ships a
 `NavigatedViewer`/`Viewer` exposes it under the same contract with
 `editable: false` — it imports, exports, reveals and reports view state like
@@ -57,7 +61,83 @@ and selection events) powers host features like anchored todos, `?element=`
 deep links and the selection half of live presence. Ids are ELEMENT ids
 (a label shape resolves to its target) and survive edits to other elements —
 positional ids that renumber when a line is inserted above break every anchor
-below.
+below. The id a session reports is the element's id in the DOCUMENT: after
+`exportText()` → `importText()`, in this instance or any other (a peer, the
+viewer, the next session), the element carries the same id — an element
+created in the session gets an id the serializer writes back, never one that
+lives only in memory. RECOMMENDED: when two peers create different elements
+at the same time, their ids do not collide — random or peer-scoped ids, not a
+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.
+
+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
+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); `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) 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.
 
 ## The conformance kit
 
@@ -79,10 +159,16 @@ 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)),
   },
   test,
+  { onSkip: reportSkip, onAdvisory: reportAdvisory }, // optional: both default to console.warn
 );
 ```
 
@@ -101,7 +187,66 @@ proves only that it agrees with itself.
 a SKIP (`console.warn` by default, `registerConformance(h, test, { onSkip })`
 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.
+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. 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.
+
+**Every rejection is probed.** `invalidTexts` lists what MUST reject; the kit
+does not take `[]` on trust. The L7 probe case derives damaged forms from
+every canonical text — its first half, its first third, the text without its
+last character, the text followed by a NUL character — plus your optional
+`probeTexts`, and imports each over a document with undo history. A probe may
+import or reject: one that imports must be silent (L1) with `exportText`
+total (L6); one that rejects must leave the document, its element ids, the
+change events and the undo history untouched (L7). After every probe the next
+valid import must render and the next user command must apply. The case runs
+for every harness and never skips.
+
+**Calls before the first import.** A fresh instance gets `exportText()` and
+one `mutate` before any document (throws tolerated — what they return is
+unspecified — and a `mutate` that never settles too: the kit waits 2 s for
+it, so a harness that waits for its command's change event still runs); then
+importing the first two canonical texts must render each exactly like a
+fresh instance does, and the next `mutate` must emit and apply.
+
+**Interactions open during an import.** `openInteraction` opens an editor on
+an element of `canonicalTexts[0]` and types without committing. The kit then
+imports over it twice — a different document (`canonicalTexts[1]`, the edited
+element is usually gone; a harness with one canonical text reports that leg
+as skipped) and the same document again (the element is still there) — and
+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 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
@@ -109,18 +254,27 @@ 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 identity is verified through names.** After an unrelated edit every
-id must still exist and, where the notation has names, still name the same
-element; a notation whose elements carry no names is verified for id
-existence only.
+**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.
+
+**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
+notation has names, still name the same element; a notation whose elements
+carry no names is verified for id existence only.
 
 The kit throws plain `Error`s — no assertion-library or runner dependency.
 Its own CI proves it bites: a conforming reference modeler
 ([`test/reference-modeler.ts`](test/reference-modeler.ts) — also the model
-for a harness) passes every case, and one deliberately broken variant per
-historical drift AND per kit case fails exactly the case set that encodes
-the violated law (not every individual assertion has a saboteur; every case
-does).
+for a harness) passes every case and advises nothing, one deliberately broken
+variant per historical drift AND per kit case fails exactly the case set that
+encodes the violated law (not every individual assertion has a saboteur;
+every case does), and one variant per recommendation fails nothing and
+advises exactly once.
 
 ## Versioning
 
@@ -130,12 +284,48 @@ 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
 hosts. A new optional surface (a structured snapshot lane alongside the text
 lane, richer element info) is a minor, and hosts feature-detect it. A new
-required member or a stricter law is a major.
+required member or a stricter law is a major. A minor may still add a case
+that enforces what the contract text already states; a requirement the text
+does not state yet ships as a RECOMMENDATION with an advisory, so no
+conforming modeler turns red in a minor. A case that needs a new optional
+harness field (`openInteraction`) reports a skip until the harness provides
+it, and a check the harness cannot feed conclusively (the collision check
+when both peers' new elements share a name their id spells out) reports a
+skip too; a suite whose `onSkip` throws, to keep every law verified, turns red on
+that upgrade by its own choice, and the skip names what to add or change.
+
+### Candidates for 2.0
+
+Recommendations today, proposed as hard laws for the next major:
+
+- **Collision-free element ids across peers** — two instances that import the
+  same document and each create a different element never allocate the same
+  id for them; ids derived from the content (OWM's `component_<slug>`) meet
+  this by construction and collide only for identical content (today:
+  `ElementInfo.id` RECOMMENDED, advisory in the elements collision case).
+- **Keep and reopen an interaction across an import** — an interaction open
+  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-E6KJB7QH.js

@@ -0,0 +1,14 @@
+// src/index.ts
+var MODELER_API_VERSION = "1.2.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-E6KJB7QH.js.map

package/dist/chunk-E6KJB7QH.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.2.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/** an element's box in diagram coordinates, as `ElementsSurface.bounds` reports it */\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); 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  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` treats the whole container as\n * free, as it does without the option.\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\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":[]}