@miragon/modeler-api 1.0.0 → 1.2.0

package/dist/index.d.cts

@@ -18,7 +18,15 @@
  *  release (release-please-config.json `extra-files`), and the kit's own
  *  test pins it to package.json exactly. Modelers pin the npm package; the
  *  constant is what travels in `meta`. */
-declare const MODELER_API_VERSION = "1.0.0";
+declare const MODELER_API_VERSION = "1.2.0";
+/**
+ * apiVersion compatibility: same major — and, while the contract is 0.x,
+ * the same minor too (pre-1.0 minors may break; bump-minor-pre-major).
+ * Hosts call it at bind time with `meta.apiVersion` and their own
+ * MODELER_API_VERSION; it lives in the package root so that check never
+ * pulls the conformance kit into a host bundle (`/conformance` re-exports it)
+ */
+declare function apiVersionsCompatible(a: string, b: string): boolean;
 interface ModelerMeta {
     /** stable notation id, e.g. "wardley", "team-topology", "event-storming" */
     readonly notation: string;
@@ -47,11 +55,32 @@ interface ElementInfo {
      * `?element=` deep links to it, so an id that renumbers when a line is
      * inserted above (positional edge ids) breaks every anchor below it. An
      * element without an id in the text gets one the serializer WRITES BACK.
+     *
+     * The id a session reports IS the element's id in the document: after
+     * `exportText()` → `importText()` — in this instance or in any other one
+     * (a peer, the viewer, the next session) — the element carries the same
+     * id. An id that lives only in memory anchors nothing: the todo or deep
+     * link a host stored against it points nowhere once the text travels.
+     *
+     * RECOMMENDED: when two peers create different elements at the same time,
+     * their ids do not collide. An id allocated regardless of the content —
+     * a per-instance counter (`event_1` on both peers) — does: once both edits
+     * merge into one document, two elements share one id; random or
+     * peer-scoped ids do not. 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.
      */
     id: string;
     /** human label, when the notation has one */
     name?: string;
 }
+/** an element's box in diagram coordinates, as `ElementsSurface.bounds` reports it */
+interface ElementBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
 /**
  * Optional element surface — what a host needs for anchored todos, `?element=`
  * deep links and the selection half of live presence. Absent = the notation
@@ -71,6 +100,22 @@ interface ElementsSurface {
     selection(): string[];
     /** selection changes as STABLE element ids; returns the unsubscribe */
     onSelection(cb: (ids: string[]) => void): () => void;
+    /**
+     * the element's box in DIAGRAM coordinates — the canvas's own coordinate
+     * space, which zoom and scroll leave alone (a host maps it to the screen
+     * with the current view, or draws in a layer that moves with the canvas) —
+     * or `undefined` for an id `list()` does not report. Optional (1.2): hosts
+     * feature-detect it 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 this session has its current box at once, not the one of the last
+     * import — a host outlining a peer's selection would otherwise draw it
+     * where the element was, or not at all, until the next import. The box is
+     * the element's own shape (a connection: the box around its waypoints); an
+     * external label is not part of it.
+     */
+    bounds?(id: string): ElementBounds | undefined;
 }
 /**
  * The collaborative-modeler contract. The LAWS (verified by the conformance
@@ -80,6 +125,14 @@ interface ElementsSurface {
  *     the undo history without emitting — also when history exists. Hosts
  *     re-import remote states on every sync; an import echo would re-export
  *     the canonical serialization over half-typed peer text.
+ *     An interaction in progress when an import runs (an open label editor,
+ *     a popup with typed input) never commits during or because of the
+ *     import: no change event comes from it, its input lands neither in the
+ *     imported document nor on its fresh undo history, and nothing is
+ *     applied to an element the import removed. RECOMMENDED: keep the typed
+ *     input and reopen the interaction on the element with the same id when
+ *     that element is still there after the import — a remote re-import
+ *     should not cost the user what they were typing.
  *  L2 CANONICAL FIXPOINT — `exportText` is deterministic, and for any text t:
  *     with c = exportText() after importText(t), importText(c) followed by
  *     exportText() returns c byte-for-byte. Canonicalization is idempotent;
@@ -104,6 +157,15 @@ interface ElementsSurface {
  *     readback may be a NORMALISED form of what was set (a diagram-js
  *     viewbox comes back rounded, with scale/inner/outer) — what must hold
  *     is that setting a readback yields that readback again.
+ *     A view change the HOST makes — `setViewState`, or a fit its chrome
+ *     applies to the canvas — never commits an interaction in progress (an
+ *     open label editor, a popup with typed input): no change event, the
+ *     export unchanged. Hosts restore the viewport after every remote
+ *     re-import and refit when their chrome changes; a commit there writes
+ *     the half-typed input into the shared document for every peer.
+ *     RECOMMENDED: the interaction stays open with its typed input, so the
+ *     user's own commit afterwards writes what it would have written without
+ *     the view change.
  *  L6 EXPORT IS TOTAL AFTER IMPORT — after a successful import (and any
  *     sequence of user commands and undos), `exportText` succeeds. Foreign or
  *     auxiliary content the modeler does not understand is PRESERVED through
@@ -111,9 +173,11 @@ interface ElementsSurface {
  *     rest), never dropped and never a reason to throw.
  *  L7 REJECTED IMPORTS LEAVE NO TRACE — `importText` on non-importable text
  *     REJECTS (resolve-with-warnings means "imported, with notes"; rejection
- *     means "nothing imported"): afterwards the previously imported document
- *     is still rendered with its elements, `exportText` still returns it, no
- *     change event has fired and the undo history is untouched.
+ *     means "nothing imported"). This holds for EVERY rejection, whatever
+ *     the input (a truncated or half-typed text included): afterwards the
+ *     previously imported document is still rendered with its elements,
+ *     `exportText` still returns it, no change event has fired and the undo
+ *     history is untouched.
  *     The modeler stays USABLE: the next valid import renders, the next user
  *     command applies. Hosts re-import half-typed peer text on every sync —
  *     "blank (or wedged) until healed" is not an acceptable failure mode.
@@ -125,10 +189,16 @@ interface CollaborativeModeler {
     readonly meta: ModelerMeta;
     /** mount the canvas into a host element (once, before the first import).
      *  The host must be attached to the document with a non-zero size — a
-     *  detached or 0×0 element gives diagram-js engines NaN viewboxes */
+     *  detached or 0×0 element gives diagram-js engines NaN viewboxes.
+     *  Calls made between mounting and the first import (`exportText()`, a
+     *  user command) return whatever the modeler defines, or throw (only
+     *  `getViewState` never does, L5), but they never wedge the instance:
+     *  the first `importText` still behaves exactly as specified */
     attachTo(host: Element): void;
     /** parse + render `text` — SILENT per L1, the view fitted to the content
-     *  per L5; resolves when rendered, REJECTS when nothing was imported (L7) */
+     *  per L5; resolves when rendered, REJECTS when nothing was imported (L7).
+     *  This holds for the first import too, whatever was called before it — a
+     *  host may export or route a command before its first document arrives */
     importText(text: string): Promise<ImportResult>;
     /** the canonical serialization of the current document (L2, L6) */
     exportText(): string;
@@ -142,5 +212,80 @@ interface CollaborativeModeler {
      *  behavior, but a second destroy() must not throw */
     destroy(): void;
 }
+/** px the host's chrome covers along the edges of the modeler's container */
+interface FreeAreaInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** a point in diagram coordinates */
+interface DiagramPoint {
+    x: number;
+    y: number;
+}
+/**
+ * The FREE AREA: the part of the canvas no host chrome covers (Miragon
+ * guide §5.9). Keyboard creation places a new element in its centre (§5.5)
+ * and a renderer that constrains panning keeps the content reachable around
+ * it, so both agree with a host that fits into the same rectangle. A host
+ * passes ONE of two forms, each a function the renderer reads whenever it
+ * needs it (the chrome changes when an inspector or a legend opens):
+ *
+ *  - `insets`: what the chrome covers, in px from the container's edges
+ *    (the modeler shell's `shell.fitInsets()`); the renderer computes the
+ *    centre itself, the way a fit does;
+ *  - `center`: the centre itself, in diagram coordinates, `undefined` while
+ *    there is none (a 0×0 container) — the shell's `viewport.freeRectCenter()`.
+ *
+ * A renderer accepts both. One that needs the rectangle itself (a pan
+ * constraint) and is given only `center` treats the whole container as
+ * free, as it does without the option.
+ */
+type FreeArea = {
+    insets: () => FreeAreaInsets;
+    center?: never;
+} | {
+    center: () => DiagramPoint | undefined;
+    insets?: never;
+};
+/**
+ * The options a renderer's contract factory takes under THESE names once it
+ * implements contract 1.2, so a host feeds every notation the same object
+ * instead of one spelling per renderer. A renderer extends the type with its
+ * own options (diagram-js `additionalModules`); the contract fixes names,
+ * meaning and defaults. A viewer factory takes the same type and ignores
+ * what has no meaning without editing (`undoRedoKeys`).
+ *
+ * Each renderer adopts them in its own release, as part of its move to 1.2:
+ * `meta.apiVersion` follows the pinned package and no kit case checks the
+ * options, so the version alone does not tell a host they are honoured.
+ * Until a renderer ships them, a host passes the renderer's own names, or
+ * both. Those 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`. Given both, the aligned name
+ * wins.
+ */
+interface CollaborativeModelerOptions {
+    /** where the host's chrome leaves the canvas free; default: the whole container */
+    freeArea?: FreeArea | undefined;
+    /**
+     * fit the content into the view after every import — default true, the
+     * fitted view L5 defines. A host whose chrome fits the content itself
+     * (the modeler shell's viewport fits into the free area) passes false:
+     * the post-import view is then the host's to set, and L5's fit is the
+     * host's fit. The conformance kit runs with the default
+     */
+    fitOnImport?: boolean | undefined;
+    /**
+     * bind Cmd/Ctrl+Z, Cmd/Ctrl+Shift+Z and Cmd/Ctrl+Y to the canvas history —
+     * default true. A host that owns the document's history (VS Code) passes
+     * false, and the keys reach it unprevented; text fields keep their own
+     * undo either way
+     */
+    undoRedoKeys?: boolean | undefined;
+}
 
-export { type CollaborativeModeler, type ElementInfo, type ElementsSurface, type ImportResult, MODELER_API_VERSION, type ModelerMeta };
+export { type CollaborativeModeler, type CollaborativeModelerOptions, type DiagramPoint, type ElementBounds, type ElementInfo, type ElementsSurface, type FreeArea, type FreeAreaInsets, type ImportResult, MODELER_API_VERSION, type ModelerMeta, apiVersionsCompatible };

package/dist/index.d.ts

@@ -18,7 +18,15 @@
  *  release (release-please-config.json `extra-files`), and the kit's own
  *  test pins it to package.json exactly. Modelers pin the npm package; the
  *  constant is what travels in `meta`. */
-declare const MODELER_API_VERSION = "1.0.0";
+declare const MODELER_API_VERSION = "1.2.0";
+/**
+ * apiVersion compatibility: same major — and, while the contract is 0.x,
+ * the same minor too (pre-1.0 minors may break; bump-minor-pre-major).
+ * Hosts call it at bind time with `meta.apiVersion` and their own
+ * MODELER_API_VERSION; it lives in the package root so that check never
+ * pulls the conformance kit into a host bundle (`/conformance` re-exports it)
+ */
+declare function apiVersionsCompatible(a: string, b: string): boolean;
 interface ModelerMeta {
     /** stable notation id, e.g. "wardley", "team-topology", "event-storming" */
     readonly notation: string;
@@ -47,11 +55,32 @@ interface ElementInfo {
      * `?element=` deep links to it, so an id that renumbers when a line is
      * inserted above (positional edge ids) breaks every anchor below it. An
      * element without an id in the text gets one the serializer WRITES BACK.
+     *
+     * The id a session reports IS the element's id in the document: after
+     * `exportText()` → `importText()` — in this instance or in any other one
+     * (a peer, the viewer, the next session) — the element carries the same
+     * id. An id that lives only in memory anchors nothing: the todo or deep
+     * link a host stored against it points nowhere once the text travels.
+     *
+     * RECOMMENDED: when two peers create different elements at the same time,
+     * their ids do not collide. An id allocated regardless of the content —
+     * a per-instance counter (`event_1` on both peers) — does: once both edits
+     * merge into one document, two elements share one id; random or
+     * peer-scoped ids do not. 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.
      */
     id: string;
     /** human label, when the notation has one */
     name?: string;
 }
+/** an element's box in diagram coordinates, as `ElementsSurface.bounds` reports it */
+interface ElementBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
 /**
  * Optional element surface — what a host needs for anchored todos, `?element=`
  * deep links and the selection half of live presence. Absent = the notation
@@ -71,6 +100,22 @@ interface ElementsSurface {
     selection(): string[];
     /** selection changes as STABLE element ids; returns the unsubscribe */
     onSelection(cb: (ids: string[]) => void): () => void;
+    /**
+     * the element's box in DIAGRAM coordinates — the canvas's own coordinate
+     * space, which zoom and scroll leave alone (a host maps it to the screen
+     * with the current view, or draws in a layer that moves with the canvas) —
+     * or `undefined` for an id `list()` does not report. Optional (1.2): hosts
+     * feature-detect it 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 this session has its current box at once, not the one of the last
+     * import — a host outlining a peer's selection would otherwise draw it
+     * where the element was, or not at all, until the next import. The box is
+     * the element's own shape (a connection: the box around its waypoints); an
+     * external label is not part of it.
+     */
+    bounds?(id: string): ElementBounds | undefined;
 }
 /**
  * The collaborative-modeler contract. The LAWS (verified by the conformance
@@ -80,6 +125,14 @@ interface ElementsSurface {
  *     the undo history without emitting — also when history exists. Hosts
  *     re-import remote states on every sync; an import echo would re-export
  *     the canonical serialization over half-typed peer text.
+ *     An interaction in progress when an import runs (an open label editor,
+ *     a popup with typed input) never commits during or because of the
+ *     import: no change event comes from it, its input lands neither in the
+ *     imported document nor on its fresh undo history, and nothing is
+ *     applied to an element the import removed. RECOMMENDED: keep the typed
+ *     input and reopen the interaction on the element with the same id when
+ *     that element is still there after the import — a remote re-import
+ *     should not cost the user what they were typing.
  *  L2 CANONICAL FIXPOINT — `exportText` is deterministic, and for any text t:
  *     with c = exportText() after importText(t), importText(c) followed by
  *     exportText() returns c byte-for-byte. Canonicalization is idempotent;
@@ -104,6 +157,15 @@ interface ElementsSurface {
  *     readback may be a NORMALISED form of what was set (a diagram-js
  *     viewbox comes back rounded, with scale/inner/outer) — what must hold
  *     is that setting a readback yields that readback again.
+ *     A view change the HOST makes — `setViewState`, or a fit its chrome
+ *     applies to the canvas — never commits an interaction in progress (an
+ *     open label editor, a popup with typed input): no change event, the
+ *     export unchanged. Hosts restore the viewport after every remote
+ *     re-import and refit when their chrome changes; a commit there writes
+ *     the half-typed input into the shared document for every peer.
+ *     RECOMMENDED: the interaction stays open with its typed input, so the
+ *     user's own commit afterwards writes what it would have written without
+ *     the view change.
  *  L6 EXPORT IS TOTAL AFTER IMPORT — after a successful import (and any
  *     sequence of user commands and undos), `exportText` succeeds. Foreign or
  *     auxiliary content the modeler does not understand is PRESERVED through
@@ -111,9 +173,11 @@ interface ElementsSurface {
  *     rest), never dropped and never a reason to throw.
  *  L7 REJECTED IMPORTS LEAVE NO TRACE — `importText` on non-importable text
  *     REJECTS (resolve-with-warnings means "imported, with notes"; rejection
- *     means "nothing imported"): afterwards the previously imported document
- *     is still rendered with its elements, `exportText` still returns it, no
- *     change event has fired and the undo history is untouched.
+ *     means "nothing imported"). This holds for EVERY rejection, whatever
+ *     the input (a truncated or half-typed text included): afterwards the
+ *     previously imported document is still rendered with its elements,
+ *     `exportText` still returns it, no change event has fired and the undo
+ *     history is untouched.
  *     The modeler stays USABLE: the next valid import renders, the next user
  *     command applies. Hosts re-import half-typed peer text on every sync —
  *     "blank (or wedged) until healed" is not an acceptable failure mode.
@@ -125,10 +189,16 @@ interface CollaborativeModeler {
     readonly meta: ModelerMeta;
     /** mount the canvas into a host element (once, before the first import).
      *  The host must be attached to the document with a non-zero size — a
-     *  detached or 0×0 element gives diagram-js engines NaN viewboxes */
+     *  detached or 0×0 element gives diagram-js engines NaN viewboxes.
+     *  Calls made between mounting and the first import (`exportText()`, a
+     *  user command) return whatever the modeler defines, or throw (only
+     *  `getViewState` never does, L5), but they never wedge the instance:
+     *  the first `importText` still behaves exactly as specified */
     attachTo(host: Element): void;
     /** parse + render `text` — SILENT per L1, the view fitted to the content
-     *  per L5; resolves when rendered, REJECTS when nothing was imported (L7) */
+     *  per L5; resolves when rendered, REJECTS when nothing was imported (L7).
+     *  This holds for the first import too, whatever was called before it — a
+     *  host may export or route a command before its first document arrives */
     importText(text: string): Promise<ImportResult>;
     /** the canonical serialization of the current document (L2, L6) */
     exportText(): string;
@@ -142,5 +212,80 @@ interface CollaborativeModeler {
      *  behavior, but a second destroy() must not throw */
     destroy(): void;
 }
+/** px the host's chrome covers along the edges of the modeler's container */
+interface FreeAreaInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** a point in diagram coordinates */
+interface DiagramPoint {
+    x: number;
+    y: number;
+}
+/**
+ * The FREE AREA: the part of the canvas no host chrome covers (Miragon
+ * guide §5.9). Keyboard creation places a new element in its centre (§5.5)
+ * and a renderer that constrains panning keeps the content reachable around
+ * it, so both agree with a host that fits into the same rectangle. A host
+ * passes ONE of two forms, each a function the renderer reads whenever it
+ * needs it (the chrome changes when an inspector or a legend opens):
+ *
+ *  - `insets`: what the chrome covers, in px from the container's edges
+ *    (the modeler shell's `shell.fitInsets()`); the renderer computes the
+ *    centre itself, the way a fit does;
+ *  - `center`: the centre itself, in diagram coordinates, `undefined` while
+ *    there is none (a 0×0 container) — the shell's `viewport.freeRectCenter()`.
+ *
+ * A renderer accepts both. One that needs the rectangle itself (a pan
+ * constraint) and is given only `center` treats the whole container as
+ * free, as it does without the option.
+ */
+type FreeArea = {
+    insets: () => FreeAreaInsets;
+    center?: never;
+} | {
+    center: () => DiagramPoint | undefined;
+    insets?: never;
+};
+/**
+ * The options a renderer's contract factory takes under THESE names once it
+ * implements contract 1.2, so a host feeds every notation the same object
+ * instead of one spelling per renderer. A renderer extends the type with its
+ * own options (diagram-js `additionalModules`); the contract fixes names,
+ * meaning and defaults. A viewer factory takes the same type and ignores
+ * what has no meaning without editing (`undoRedoKeys`).
+ *
+ * Each renderer adopts them in its own release, as part of its move to 1.2:
+ * `meta.apiVersion` follows the pinned package and no kit case checks the
+ * options, so the version alone does not tell a host they are honoured.
+ * Until a renderer ships them, a host passes the renderer's own names, or
+ * both. Those 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`. Given both, the aligned name
+ * wins.
+ */
+interface CollaborativeModelerOptions {
+    /** where the host's chrome leaves the canvas free; default: the whole container */
+    freeArea?: FreeArea | undefined;
+    /**
+     * fit the content into the view after every import — default true, the
+     * fitted view L5 defines. A host whose chrome fits the content itself
+     * (the modeler shell's viewport fits into the free area) passes false:
+     * the post-import view is then the host's to set, and L5's fit is the
+     * host's fit. The conformance kit runs with the default
+     */
+    fitOnImport?: boolean | undefined;
+    /**
+     * bind Cmd/Ctrl+Z, Cmd/Ctrl+Shift+Z and Cmd/Ctrl+Y to the canvas history —
+     * default true. A host that owns the document's history (VS Code) passes
+     * false, and the keys reach it unprevented; text fields keep their own
+     * undo either way
+     */
+    undoRedoKeys?: boolean | undefined;
+}
 
-export { type CollaborativeModeler, type ElementInfo, type ElementsSurface, type ImportResult, MODELER_API_VERSION, type ModelerMeta };
+export { type CollaborativeModeler, type CollaborativeModelerOptions, type DiagramPoint, type ElementBounds, type ElementInfo, type ElementsSurface, type FreeArea, type FreeAreaInsets, type ImportResult, MODELER_API_VERSION, type ModelerMeta, apiVersionsCompatible };

package/dist/index.js

@@ -1,7 +1,9 @@
 import {
-  MODELER_API_VERSION
-} from "./chunk-HWB2EYDZ.js";
+  MODELER_API_VERSION,
+  apiVersionsCompatible
+} from "./chunk-E6KJB7QH.js";
 export {
-  MODELER_API_VERSION
+  MODELER_API_VERSION,
+  apiVersionsCompatible
 };
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miragon/modeler-api",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "ONE interface every Miragon modeler implements — the collaborative-modeler contract and its conformance test kit.",
   "license": "MIT",
   "repository": {

package/dist/chunk-HWB2EYDZ.js

@@ -1,7 +0,0 @@
-// src/index.ts
-var MODELER_API_VERSION = "1.0.0";
-
-export {
-  MODELER_API_VERSION
-};
-//# sourceMappingURL=chunk-HWB2EYDZ.js.map

package/dist/chunk-HWB2EYDZ.js.map

@@ -1 +0,0 @@
-{"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.0.0\"; // x-release-please-version\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  id: string;\n  /** human label, when the notation has one */\n  name?: string;\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\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 *  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 *  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\"): afterwards the previously imported document\n *     is still rendered with its elements, `exportText` still returns it, no\n *     change event has fired and the undo 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  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  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"],"mappings":";AAqBO,IAAM,sBAAsB;","names":[]}