@miragon/modeler-api 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miragon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,232 @@
-# Temporary Holding Version
+# @miragon/modeler-api
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+ONE interface every Miragon modeler implements — the collaborative-modeler
+contract and its conformance test kit.
+
+## Why
+
+Embedding a modeler in a collaborative host (a shared Y.Text, re-imports on
+every remote change) exposes behavioral details that are invisible in
+standalone use. Before this contract existed, each drift had to be discovered
+per modeler, against its engine internals:
+
+- an `importDSL` that ran `commandStack.clear()` **emitting** a change event —
+  unsuppressed, opening a hand-authored file re-exported the canonical
+  serialization over it;
+- an import that left the undo stack on stale, removed shapes — undo after a
+  co-editor's change silently no-op'd or deleted re-imported shapes by id
+  coincidence;
+- a serializer that was not a byte fixpoint of its own parser;
+- config/axis edits that fired their own event instead of the command stack —
+  a host observing only the stack lost them.
+
+This package turns those lessons into **laws** (see the JSDoc on
+`CollaborativeModeler`) and ships a **conformance kit** that makes every law
+an executable test the modeler repo runs in its own CI. Drift fails the
+modeler's build — not a downstream integration review.
+
+## The contract (1.x)
+
+```ts
+import type { CollaborativeModeler } from "@miragon/modeler-api";
+```
+
+| Law | Requirement                                                                                                                                                                                                               |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| L1  | `importText` is **silent**: no change events, undo history erased without emitting — also over existing history and foreign content; an interaction open during an import (a label editor with typed input) never commits |
+| L2  | `exportText` is **canonical**: deterministic, a byte fixpoint on canonical input, idempotent otherwise                                                                                                                    |
+| L3  | `onContentChanged` fires for **every** user-visible change — element commands, config/axis/title edits, undo/redo — and nothing else; inside a listener `exportText()` already returns the new document                   |
+| L4  | undo directly after an import is a defined **no-op** — never a stale-history mutation                                                                                                                                     |
+| L5  | view state survives a re-import; an import leaves the view **fitted** to the content; the readback may be a normalised form of what was set                                                                               |
+| L6  | `exportText` is total after a successful import; foreign content is **preserved** through import → export, never dropped, never a throw                                                                                   |
+| L7  | EVERY rejected import leaves no trace — previous document still rendered and exported, no events, undo history untouched — and the modeler **stays usable**                                                               |
+
+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
+the editor and never fires `onContentChanged`, so hosts mount it on read-only
+surfaces without per-package knowledge. A viewer must import without a
+command stack of its own, or register one: the kit's viewer case fails a
+`NavigatedViewer` whose import clears a stack it never registered.
+
+Optional `elements` surface (stable ids, `reveal`, a synchronous `selection()`
+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. 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.
+
+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.
+
+## The conformance kit
+
+```ts
+// e.g. test/conformance.browser.test.ts in a modeler repo (any (name, fn) runner)
+import { attachedHost, registerConformance } from "@miragon/modeler-api/conformance";
+import { test } from "vitest";
+
+registerConformance(
+  {
+    create: async () => mountMyModeler(attachedHost()), // IN the document, sized — see below
+    createReadonly: async () => mountMyViewer(attachedHost()), // the viewer mount, if the package ships one
+    canonicalTexts: [CANONICAL_SAMPLE_A, CANONICAL_SAMPLE_B], // two DISTINCT, REVIEWED ones — the undo law needs them
+    looseTexts: [HAND_AUTHORED_SAMPLE],
+    invalidTexts: [HALF_TYPED_SAMPLE], // [] if NOTHING is non-importable (a lenient line DSL)
+    foreignTexts: [{ text: SAMPLE_WITH_VENDOR_EXTENSION, mustSurvive: ["x-vendor: keep-me"] }],
+    viewState: { x: 120, y: 80, width: 640, height: 480 }, // a panned/zoomed viewport, not the fitted one (the kit compares readbacks, never this literal)
+    mutate: (m) => addOneElement(m), // undoable; adds — never renames or deletes
+    configMutations: [{ name: "axis labels", run: (m) => renameEvolutionAxis(m) }], // [] if the notation has none
+    undo: (m) => triggerUndo(m),
+    redo: (m) => triggerRedo(m),
+    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
+    // 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
+);
+```
+
+**Run it in a real browser.** diagram-js engines compute viewboxes from the
+host's client size and use `getBBox`, which jsdom lacks and a detached or 0×0
+element turns into NaN: mount into `attachedHost()` (a sized element appended
+to `document.body`) under vitest browser mode / Playwright — the modeler
+repos' `test:browser` project — not under the unit project.
+
+**Canonical texts are yours to vouch for.** L2 proves `exportText` is a
+fixpoint of the texts you provide. Obtain them by exporting a hand-authored
+document and reviewing the bytes; pasting whatever the current build prints
+proves only that it agrees with itself.
+
+**Nothing skips silently.** A case whose harness field is `undefined` reports
+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. Without `openInteraction` the
+L1 interaction case reports a skip; with `openInteraction` but without
+`interactionState` only its keep-and-reopen half does.
+
+**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.
+
+**Recommendations are advisories.** Where the contract only RECOMMENDS
+(collision-free ids across peers, keep-and-reopen of an open interaction), the
+kit reports what it finds as an ADVISORY through `onAdvisory`
+(`console.warn` by default) and never fails: a recommendation becomes a law,
+with a failing case, only in a major release. The collision check imports the
+same canonical text into two fresh instances, runs `mutate` once on each and
+advises when both allocate the same id — unless both new elements carry the
+same name and the id spells it out (its letters and digits contain the
+name's, as `component_new_component` does for "New Component"). Such an id is
+derived from the content and collides for identical content by design, so
+the check reports a skip instead: let `mutate`'s elements differ in content
+(a counter the harness shares across instances, as the reference harness
+does).
+
+**View state is compared by readback.** The kit never compares
+`getViewState()` with your `viewState` literal: it sets it, reads the
+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, 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 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
+
+One identity: `MODELER_API_VERSION` IS the npm package version — release-please
+rewrites the constant on every release (`extra-files`) and a test pins it to
+`package.json` exactly. Modelers pin the package and put the constant into
+`meta.apiVersion`; hosts match on the major (`apiVersionsCompatible`).
+Releases are tagged `modeler-api-vX.Y.Z`.
+
+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. 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).
+
+## License
+
+MIT

package/dist/chunk-32BMH76T.js

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

package/dist/chunk-32BMH76T.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.1.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   * 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/**\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 *     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 *  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"],"mappings":";AAqBO,IAAM,sBAAsB;","names":[]}