@miragon/modeler-api 1.3.0 → 1.4.0

package/dist/index.cjs

@@ -24,7 +24,7 @@ __export(index_exports, {
   apiVersionsCompatible: () => apiVersionsCompatible
 });
 module.exports = __toCommonJS(index_exports);
-var MODELER_API_VERSION = "1.3.0";
+var MODELER_API_VERSION = "1.4.0";
 function apiVersionsCompatible(a, b) {
   const [aMajor = "", aMinor = ""] = a.split(".");
   const [bMajor = "", bMinor = ""] = b.split(".");

package/dist/index.cjs.map

@@ -1 +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":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;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":[]}
+{"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.4.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 *\n *  KEYS STAY ON THE CANVAS (1.4, RECOMMENDED) — a modeler acts on a key only\n *  while its CANVAS holds the focus: the key's target is the focusable\n *  element the modeler placed in the host to take its keys (diagram-js: the\n *  canvas `<svg>`, `tabindex=\"0\"`) or lies inside it. Every other key is the\n *  page's: one aimed at the host's chrome or at a host editor (a button, a\n *  text input, a select, a contenteditable, an EditContext or Monaco\n *  editor), beside the modeler's container, inside it or next to the canvas\n *  in a host's overlay, and one whose target is `<body>` (nothing focused:\n *  after a load, after a click on page text, while the host hides the canvas\n *  or makes it inert). The modeler leaves such a key alone: no command, no\n *  change of the document or the selection, no `preventDefault()` and no\n *  `stopPropagation()`, in the capture phase too. A keydown or keyup\n *  without a string `key` (browser autofill dispatches both) is ignored\n *  without an error. The rule holds for the viewer mount too. Hosts embed\n *  modelers next to their own editors and toolbars: a key the canvas takes\n *  from there deletes the selection while the user types, undoes the last\n *  edit from a toolbar button or swallows Cmd/Ctrl+C in a text field. The\n *  modeler's own chrome (its palette, context pad, label editor) handles its\n *  keys as it sees fit; a host that wants keyboard editing hands the canvas\n *  the focus (a click on it, Tab, or `focus()` on the canvas element).\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. RECOMMENDED\n   *  (1.4): the canvas placed here takes keys only while it holds the focus\n   *  (KEYS STAY ON THE CANVAS above) */\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":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;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/index.d.cts

@@ -18,7 +18,7 @@
  *  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.3.0";
+declare const MODELER_API_VERSION = "1.4.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).
@@ -187,6 +187,27 @@ interface ElementsSurface {
  *
  *  View state is NEVER part of the document: `setViewState` fires no change
  *  events and `exportText` is independent of it.
+ *
+ *  KEYS STAY ON THE CANVAS (1.4, RECOMMENDED) — a modeler acts on a key only
+ *  while its CANVAS holds the focus: the key's target is the focusable
+ *  element the modeler placed in the host to take its keys (diagram-js: the
+ *  canvas `<svg>`, `tabindex="0"`) or lies inside it. Every other key is the
+ *  page's: one aimed at the host's chrome or at a host editor (a button, a
+ *  text input, a select, a contenteditable, an EditContext or Monaco
+ *  editor), beside the modeler's container, inside it or next to the canvas
+ *  in a host's overlay, and one whose target is `<body>` (nothing focused:
+ *  after a load, after a click on page text, while the host hides the canvas
+ *  or makes it inert). The modeler leaves such a key alone: no command, no
+ *  change of the document or the selection, no `preventDefault()` and no
+ *  `stopPropagation()`, in the capture phase too. A keydown or keyup
+ *  without a string `key` (browser autofill dispatches both) is ignored
+ *  without an error. The rule holds for the viewer mount too. Hosts embed
+ *  modelers next to their own editors and toolbars: a key the canvas takes
+ *  from there deletes the selection while the user types, undoes the last
+ *  edit from a toolbar button or swallows Cmd/Ctrl+C in a text field. The
+ *  modeler's own chrome (its palette, context pad, label editor) handles its
+ *  keys as it sees fit; a host that wants keyboard editing hands the canvas
+ *  the focus (a click on it, Tab, or `focus()` on the canvas element).
  */
 interface CollaborativeModeler {
     readonly meta: ModelerMeta;
@@ -196,7 +217,9 @@ interface CollaborativeModeler {
      *  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 */
+     *  the first `importText` still behaves exactly as specified. RECOMMENDED
+     *  (1.4): the canvas placed here takes keys only while it holds the focus
+     *  (KEYS STAY ON THE CANVAS above) */
     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).
@@ -329,4 +352,5 @@ interface CollaborativeModelerOptions {
     undoRedoKeys?: boolean | undefined;
 }
 
-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 };
+export { MODELER_API_VERSION, apiVersionsCompatible };
+export type { CollaborativeModeler, CollaborativeModelerOptions, DiagramPoint, ElementBounds, ElementInfo, ElementsSurface, FreeArea, FreeAreaInsets, ImportResult, ModelerMeta };

package/dist/index.d.ts

@@ -18,7 +18,7 @@
  *  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.3.0";
+declare const MODELER_API_VERSION = "1.4.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).
@@ -187,6 +187,27 @@ interface ElementsSurface {
  *
  *  View state is NEVER part of the document: `setViewState` fires no change
  *  events and `exportText` is independent of it.
+ *
+ *  KEYS STAY ON THE CANVAS (1.4, RECOMMENDED) — a modeler acts on a key only
+ *  while its CANVAS holds the focus: the key's target is the focusable
+ *  element the modeler placed in the host to take its keys (diagram-js: the
+ *  canvas `<svg>`, `tabindex="0"`) or lies inside it. Every other key is the
+ *  page's: one aimed at the host's chrome or at a host editor (a button, a
+ *  text input, a select, a contenteditable, an EditContext or Monaco
+ *  editor), beside the modeler's container, inside it or next to the canvas
+ *  in a host's overlay, and one whose target is `<body>` (nothing focused:
+ *  after a load, after a click on page text, while the host hides the canvas
+ *  or makes it inert). The modeler leaves such a key alone: no command, no
+ *  change of the document or the selection, no `preventDefault()` and no
+ *  `stopPropagation()`, in the capture phase too. A keydown or keyup
+ *  without a string `key` (browser autofill dispatches both) is ignored
+ *  without an error. The rule holds for the viewer mount too. Hosts embed
+ *  modelers next to their own editors and toolbars: a key the canvas takes
+ *  from there deletes the selection while the user types, undoes the last
+ *  edit from a toolbar button or swallows Cmd/Ctrl+C in a text field. The
+ *  modeler's own chrome (its palette, context pad, label editor) handles its
+ *  keys as it sees fit; a host that wants keyboard editing hands the canvas
+ *  the focus (a click on it, Tab, or `focus()` on the canvas element).
  */
 interface CollaborativeModeler {
     readonly meta: ModelerMeta;
@@ -196,7 +217,9 @@ interface CollaborativeModeler {
      *  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 */
+     *  the first `importText` still behaves exactly as specified. RECOMMENDED
+     *  (1.4): the canvas placed here takes keys only while it holds the focus
+     *  (KEYS STAY ON THE CANVAS above) */
     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).
@@ -329,4 +352,5 @@ interface CollaborativeModelerOptions {
     undoRedoKeys?: boolean | undefined;
 }
 
-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 };
+export { MODELER_API_VERSION, apiVersionsCompatible };
+export type { CollaborativeModeler, CollaborativeModelerOptions, DiagramPoint, ElementBounds, ElementInfo, ElementsSurface, FreeArea, FreeAreaInsets, ImportResult, ModelerMeta };

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   MODELER_API_VERSION,
   apiVersionsCompatible
-} from "./chunk-JK23ZTVG.js";
+} from "./chunk-N4TQ7UHQ.js";
 export {
   MODELER_API_VERSION,
   apiVersionsCompatible

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@miragon/modeler-api",
-  "version": "1.3.0",
-  "description": "ONE interface every Miragon modeler implements — the collaborative-modeler contract and its conformance test kit.",
+  "version": "1.4.0",
+  "description": "ONE interface every Miragon modeler implements: the collaborative-modeler contract and its conformance test kit.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Miragon/modeler-api.git",
+    "url": "git+https://github.com/Miragon/modeler-suite.git",
     "directory": "packages/api"
   },
-  "homepage": "https://github.com/Miragon/modeler-api/tree/main/packages/api#readme",
-  "bugs": "https://github.com/Miragon/modeler-api/issues",
+  "homepage": "https://github.com/Miragon/modeler-suite/tree/main/packages/api#readme",
+  "bugs": "https://github.com/Miragon/modeler-suite/issues",
   "type": "module",
   "sideEffects": false,
   "exports": {