@miragon/modeler-api 1.0.0 → 1.1.0

package/README.md

@@ -31,19 +31,23 @@ modeler's build — not a downstream integration review.
 import type { CollaborativeModeler } from "@miragon/modeler-api";
 ```
 
-| Law | Requirement                                                                                                                                                                                             |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| L1  | `importText` is **silent**: no change events, undo history erased without emitting — also over existing history and foreign content                                                                     |
-| L2  | `exportText` is **canonical**: deterministic, a byte fixpoint on canonical input, idempotent otherwise                                                                                                  |
-| L3  | `onContentChanged` fires for **every** user-visible change — element commands, config/axis/title edits, undo/redo — and nothing else; inside a listener `exportText()` already returns the new document |
-| L4  | undo directly after an import is a defined **no-op** — never a stale-history mutation                                                                                                                   |
-| L5  | view state survives a re-import; an import leaves the view **fitted** to the content; the readback may be a normalised form of what was set                                                             |
-| L6  | `exportText` is total after a successful import; foreign content is **preserved** through import → export, never dropped, never a throw                                                                 |
-| L7  | a REJECTED import leaves no trace — previous document still rendered and exported, no events, undo history untouched — and the modeler **stays usable**                                                 |
+| Law | Requirement                                                                                                                                                                                                               |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| L1  | `importText` is **silent**: no change events, undo history erased without emitting — also over existing history and foreign content; an interaction open during an import (a label editor with typed input) never commits |
+| L2  | `exportText` is **canonical**: deterministic, a byte fixpoint on canonical input, idempotent otherwise                                                                                                                    |
+| L3  | `onContentChanged` fires for **every** user-visible change — element commands, config/axis/title edits, undo/redo — and nothing else; inside a listener `exportText()` already returns the new document                   |
+| L4  | undo directly after an import is a defined **no-op** — never a stale-history mutation                                                                                                                                     |
+| L5  | view state survives a re-import; an import leaves the view **fitted** to the content; the readback may be a normalised form of what was set                                                                               |
+| L6  | `exportText` is total after a successful import; foreign content is **preserved** through import → export, never dropped, never a throw                                                                                   |
+| L7  | EVERY rejected import leaves no trace — previous document still rendered and exported, no events, undo history untouched — and the modeler **stays usable**                                                               |
 
 View state is never part of the document: `setViewState` fires no change
 events and `exportText` is independent of it.
 
+Calls made before the first import (`exportText()`, a user command) may
+return or throw whatever the modeler defines, but never wedge the instance:
+the first `importText` still renders and resolves as specified.
+
 `meta.editable` tells a viewer mount from an editor: a package that ships a
 `NavigatedViewer`/`Viewer` exposes it under the same contract with
 `editable: false` — it imports, exports, reveals and reports view state like
@@ -57,7 +61,22 @@ and selection events) powers host features like anchored todos, `?element=`
 deep links and the selection half of live presence. Ids are ELEMENT ids
 (a label shape resolves to its target) and survive edits to other elements —
 positional ids that renumber when a line is inserted above break every anchor
-below.
+below. The id a session reports is the element's id in the DOCUMENT: after
+`exportText()` → `importText()`, in this instance or any other (a peer, the
+viewer, the next session), the element carries the same id — an element
+created in the session gets an id the serializer writes back, never one that
+lives only in memory. RECOMMENDED: when two peers create different elements
+at the same time, their ids do not collide — random or peer-scoped ids, not a
+per-instance counter such as `event_1`. An id derived from the content (OWM's
+`component_<slug>`) collides only when both users create the same content,
+which the merge has to reconcile anyway.
+
+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
 
@@ -79,10 +98,14 @@ registerConformance(
     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
 );
 ```
 
@@ -101,7 +124,50 @@ proves only that it agrees with itself.
 a SKIP (`console.warn` by default, `registerConformance(h, test, { onSkip })`
 to route it) instead of passing. An explicit `[]` (`invalidTexts`,
 `foreignTexts`, `configMutations`, `looseTexts`) is a statement that the
-notation has no such form and skips nothing.
+notation has no such form and skips nothing. Without `openInteraction` the
+L1 interaction case reports a skip; with `openInteraction` but without
+`interactionState` only its keep-and-reopen half does.
+
+**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
@@ -109,18 +175,20 @@ modeler's own (possibly normalised) state back, and requires that readback
 to survive a re-import — a diagram-js viewbox that comes back rounded with
 `scale`/`inner`/`outer` is fine.
 
-**Element identity is verified through names.** After an unrelated edit every
-id must still exist and, where the notation has names, still name the same
-element; a notation whose elements carry no names is verified for id
-existence only.
+**Element identity is verified through names.** After an unrelated edit, and
+after an export → import into the same instance, a fresh instance and the
+viewer, every id the session reported must still exist and, where the
+notation has names, still name the same element; a notation whose elements
+carry no names is verified for id existence only.
 
 The kit throws plain `Error`s — no assertion-library or runner dependency.
 Its own CI proves it bites: a conforming reference modeler
 ([`test/reference-modeler.ts`](test/reference-modeler.ts) — also the model
-for a harness) passes every case, and one deliberately broken variant per
-historical drift AND per kit case fails exactly the case set that encodes
-the violated law (not every individual assertion has a saboteur; every case
-does).
+for a harness) passes every case and advises nothing, one deliberately broken
+variant per historical drift AND per kit case fails exactly the case set that
+encodes the violated law (not every individual assertion has a saboteur;
+every case does), and one variant per recommendation fails nothing and
+advises exactly once.
 
 ## Versioning
 
@@ -135,7 +203,29 @@ The contract is first published as 1.0.0, never 0.x: under 0.x,
 additive surface into a lockstep release across all modelers and their
 hosts. A new optional surface (a structured snapshot lane alongside the text
 lane, richer element info) is a minor, and hosts feature-detect it. A new
-required member or a stricter law is a major.
+required member or a stricter law is a major. A minor may still add a case
+that enforces what the contract text already states; a requirement the text
+does not state yet ships as a RECOMMENDATION with an advisory, so no
+conforming modeler turns red in a minor. A case that needs a new optional
+harness field (`openInteraction`) reports a skip until the harness provides
+it, and a check the harness cannot feed conclusively (the collision check
+when both peers' new elements share a name their id spells out) reports a
+skip too; a suite whose `onSkip` throws, to keep every law verified, turns red on
+that upgrade by its own choice, and the skip names what to add or change.
+
+### Candidates for 2.0
+
+Recommendations today, proposed as hard laws for the next major:
+
+- **Collision-free element ids across peers** — two instances that import the
+  same document and each create a different element never allocate the same
+  id for them; ids derived from the content (OWM's `component_<slug>`) meet
+  this by construction and collide only for identical content (today:
+  `ElementInfo.id` RECOMMENDED, advisory in the elements collision case).
+- **Keep and reopen an interaction across an import** — an interaction open
+  during an import is reopened, with its typed input, on the element with the
+  same id when that element is still there (today: L1 RECOMMENDED, advisory in
+  the L1 interaction case).
 
 ## License
 

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":[]}

package/dist/conformance.cjs

@@ -28,7 +28,7 @@ __export(conformance_exports, {
 module.exports = __toCommonJS(conformance_exports);
 
 // src/index.ts
-var MODELER_API_VERSION = "1.0.0";
+var MODELER_API_VERSION = "1.1.0";
 
 // src/conformance.ts
 function attachedHost(width = 800, height = 600) {
@@ -70,6 +70,19 @@ function assertFinite(state, when) {
   }
 }
 var defaultSettle = () => new Promise((resolve) => setTimeout(resolve, 0));
+var PRE_IMPORT_CALL_BOUND_MS = 2e3;
+async function toleratedCall(action, ms) {
+  let timer;
+  const call = Promise.resolve().then(action).catch(() => void 0);
+  const bound = new Promise((resolve) => {
+    timer = setTimeout(resolve, ms);
+  });
+  try {
+    await Promise.race([call, bound]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
 async function changeEvents(harness, modeler, action) {
   const settle = harness.settle ?? defaultSettle;
   let calls = 0;
@@ -86,12 +99,42 @@ async function changeEvents(harness, modeler, action) {
   }
   return { calls, exportAtEmit };
 }
+var lettersAndDigits = (value) => value.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "");
 var secondText = (h) => h.canonicalTexts[1] ?? h.canonicalTexts[0] ?? "";
 var mutationsOf = (h) => [
   { name: "mutate (element command)", run: (m) => h.mutate(m) },
   ...h.configMutations ?? []
 ];
 var sortedIds = (m) => m.elements ? [...m.elements.list().map((e) => e.id)].sort() : void 0;
+var namesById = (m) => m.elements ? new Map(m.elements.list().map((e) => [e.id, e.name])) : void 0;
+async function importOrFail(m, text, failure) {
+  await m.importText(text).catch((e) => fail(`${failure}: ${String(e)}`));
+}
+var describeProbe = (probe) => {
+  const excerpt = probe.text.length > 40 ? `${probe.text.slice(0, 40)}\u2026` : probe.text;
+  return `${probe.label} (${JSON.stringify(excerpt)})`;
+};
+function probesOf(h) {
+  const probes = [];
+  h.canonicalTexts.forEach((text, index) => {
+    const source = `canonicalTexts[${index}]`;
+    const codePoints = Array.from(text);
+    const cut = (length) => codePoints.slice(0, length).join("");
+    probes.push(
+      { label: `the first half of ${source}`, text: cut(Math.floor(codePoints.length / 2)) },
+      { label: `the first third of ${source}`, text: cut(Math.floor(codePoints.length / 3)) },
+      { label: `${source} without its last character`, text: cut(codePoints.length - 1) },
+      { label: `${source} followed by a NUL character`, text: `${text}\0` }
+    );
+  });
+  (h.probeTexts ?? []).forEach((text, index) => probes.push({ label: `probeTexts[${index}]`, text }));
+  const seen = /* @__PURE__ */ new Set();
+  return probes.filter((probe) => {
+    if (seen.has(probe.text)) return false;
+    seen.add(probe.text);
+    return true;
+  });
+}
 async function importContentText(h, m) {
   for (const text of h.canonicalTexts) {
     await m.importText(text);
@@ -117,6 +160,56 @@ function conformanceCases() {
         }
       }
     },
+    {
+      name: "calls before the first import never wedge the instance",
+      async run(h) {
+        const m = await h.create();
+        let control;
+        try {
+          try {
+            m.exportText();
+          } catch {
+          }
+          await toleratedCall(() => h.mutate(m), PRE_IMPORT_CALL_BOUND_MS);
+          await (h.settle ?? defaultSettle)();
+          control = await h.create();
+          const texts = h.canonicalTexts.length > 0 ? h.canonicalTexts.slice(0, 2) : [""];
+          let last = "";
+          for (const [index, text] of texts.entries()) {
+            const source = `canonicalTexts[${index}]`;
+            await control.importText(text);
+            const expected = exportOrFail(control, `after importing ${source} into a fresh instance`);
+            await importOrFail(
+              m,
+              text,
+              `importText(${source}) rejected on an instance that ran exportText() and a user command before its first import (wedged)`
+            );
+            last = exportOrFail(m, `after importing ${source} into an instance used before its first import`);
+            if (last !== expected) {
+              fail(
+                `importText(${source}) on an instance that ran exportText() and a user command before its first import did not render that document:
+--- expected (a fresh instance's export)
+${expected}
+--- got
+${last}`
+              );
+            }
+          }
+          const { calls } = await changeEvents(h, m, () => h.mutate(m));
+          if (calls === 0) {
+            fail(
+              "a user mutation fired no onContentChanged on an instance used before its first import (wedged)"
+            );
+          }
+          if (exportOrFail(m, "after a user mutation on an instance used before its first import") === last) {
+            fail("a user mutation did not apply on an instance used before its first import (wedged)");
+          }
+        } finally {
+          m.destroy();
+          control?.destroy();
+        }
+      }
+    },
     {
       name: "L1: importText is silent (no change events, for canonical, loose and foreign inputs)",
       async run(h) {
@@ -151,6 +244,87 @@ function conformanceCases() {
         }
       }
     },
+    {
+      name: "L1: an interaction open during importText never commits",
+      async run(h) {
+        if (!h.openInteraction) {
+          return skip(
+            "openInteraction is undefined \u2014 an interaction open during an import (a label editor with typed input) was not verified"
+          );
+        }
+        const openInteraction = h.openInteraction;
+        const first = h.canonicalTexts[0] ?? "";
+        const second = h.canonicalTexts[1];
+        const m = await h.create();
+        try {
+          const legs = [];
+          if (second !== void 0) {
+            await m.importText(second);
+            const expected = exportOrFail(m, "after importing canonicalTexts[1]");
+            legs.push({ text: second, expected, what: "a different document (canonicalTexts[1])" });
+          }
+          await m.importText(first);
+          const firstExport = exportOrFail(m, "after importing canonicalTexts[0]");
+          legs.push({
+            text: first,
+            expected: firstExport,
+            what: "the same document again (canonicalTexts[0])"
+          });
+          let advice;
+          for (const [index, leg] of legs.entries()) {
+            await m.importText(first);
+            await openInteraction(m);
+            await (h.settle ?? defaultSettle)();
+            const opened = h.interactionState?.(m);
+            if (h.interactionState && opened === void 0) {
+              fail("interactionState reports no interaction after openInteraction \u2014 the case proves nothing");
+            }
+            const { calls } = await changeEvents(h, m, () => m.importText(leg.text).then(() => void 0));
+            if (calls > 0) {
+              fail(
+                `importing ${leg.what} over an open interaction fired onContentChanged ${calls}x \u2014 the interaction committed during or because of the import (if every import emits, see the L1 cases first)`
+              );
+            }
+            const reopened = h.interactionState?.(m);
+            if (exportOrFail(m, `after importing ${leg.what} over an open interaction`) !== leg.expected) {
+              fail(
+                `importing ${leg.what} over an open interaction did not leave that document \u2014 the interaction's input was applied to it`
+              );
+            }
+            if (h.undo) {
+              await h.undo(m);
+              await (h.settle ?? defaultSettle)();
+              if (exportOrFail(m, `after an undo that followed importing ${leg.what}`) !== leg.expected) {
+                fail(
+                  `undo after importing ${leg.what} over an open interaction changed the document \u2014 the interaction was committed onto the fresh undo history (L4)`
+                );
+              }
+            }
+            const sameDocument = index === legs.length - 1;
+            const kept = reopened?.elementId === opened?.elementId && reopened?.text === opened?.text;
+            if (sameDocument && opened !== void 0 && !kept) {
+              const input = opened.text === void 0 ? "" : ` with the input ${JSON.stringify(opened.text)}`;
+              const after = reopened === void 0 ? "closed it" : `left ${JSON.stringify(reopened)} open`;
+              advice = `an interaction on '${opened.elementId}'${input} did not survive a re-import of the same document (the import ${after}) \u2014 RECOMMENDED: keep the typed input and reopen the interaction on the element with the same id, so a remote re-import does not cost the user what they were typing`;
+            }
+          }
+          const unverified = [
+            ...second === void 0 ? [
+              "canonicalTexts holds one text \u2014 importing a DIFFERENT document over an open interaction was not verified (add a second canonical text)"
+            ] : [],
+            ...h.interactionState ? [] : [
+              "interactionState is undefined \u2014 the RECOMMENDED keep-and-reopen of an interaction across an import was not checked (pass interactionState to check it)"
+            ]
+          ];
+          return {
+            ...unverified.length > 0 ? { skipped: unverified.join("; ") } : {},
+            ...advice === void 0 ? {} : { advisories: [advice] }
+          };
+        } finally {
+          m.destroy();
+        }
+      }
+    },
     {
       name: "L2: canonical texts are byte fixpoints of import \u2192 export",
       async run(h) {
@@ -473,6 +647,110 @@ ${out}`);
         }
       }
     },
+    {
+      name: "elements (when present): ids and names survive export \u2192 import, in this and in a fresh instance",
+      async run(h) {
+        const m = await h.create();
+        const others = [];
+        try {
+          await m.importText(h.canonicalTexts[0] ?? "");
+          const elements = m.elements;
+          if (!elements)
+            return skip("the modeler exposes no elements surface (optional) \u2014 nothing to verify");
+          await h.mutate(m);
+          await (h.settle ?? defaultSettle)();
+          const session = new Map(elements.list().map((e) => [e.id, e.name]));
+          const exported = exportOrFail(m, "after a user mutation");
+          const expectSessionIds = (target, where) => {
+            const after = namesById(target);
+            if (!after) fail(`${where} exposes no elements surface \u2014 the editor does`);
+            for (const [id, name] of session) {
+              if (!after.has(id)) {
+                fail(
+                  `element id '${id}' is gone after export \u2192 import ${where} \u2014 the id a session reports must be the element's id in the document (write it back)`
+                );
+              }
+              if (name !== void 0 && (after.get(id) ?? "") !== name) {
+                fail(
+                  `element id '${id}' names a different element after export \u2192 import ${where} ('${name}' \u2192 '${String(after.get(id))}')`
+                );
+              }
+            }
+          };
+          await importOrFail(m, exported, "importText rejected the modeler's own export");
+          expectSessionIds(m, "into the same instance");
+          const fresh = await h.create();
+          others.push(fresh);
+          await importOrFail(fresh, exported, "a fresh instance rejected the modeler's own export");
+          expectSessionIds(fresh, "into a fresh instance");
+          if (h.createReadonly) {
+            const viewer = await h.createReadonly();
+            others.push(viewer);
+            await importOrFail(viewer, exported, "the viewer rejected the editor's export");
+            if (viewer.elements) expectSessionIds(viewer, "into the viewer");
+          }
+        } finally {
+          m.destroy();
+          for (const other of others) other.destroy();
+        }
+      }
+    },
+    {
+      name: "elements (when present, recommended): ids created on two peers at the same time do not collide",
+      async run(h) {
+        const text = h.canonicalTexts[0] ?? "";
+        const peers = [];
+        try {
+          const created = [];
+          for (let count = 0; count < 2; count += 1) {
+            const peer = await h.create();
+            peers.push(peer);
+            await peer.importText(text);
+            if (!peer.elements)
+              return skip("the modeler exposes no elements surface (optional) \u2014 nothing to verify");
+            const before = new Set(peer.elements.list().map((e) => e.id));
+            await h.mutate(peer);
+            await (h.settle ?? defaultSettle)();
+            const added = new Map(
+              peer.elements.list().filter((e) => !before.has(e.id)).map((e) => [e.id, e.name])
+            );
+            if (added.size === 0) {
+              fail(
+                "the harness mutate must ADD an element (the elements cases compare the ids two instances allocate)"
+              );
+            }
+            created.push(added);
+          }
+          const [
+            onFirst = /* @__PURE__ */ new Map(),
+            onSecond = /* @__PURE__ */ new Map()
+          ] = created;
+          const shared = [...onFirst.keys()].filter((id) => onSecond.has(id));
+          const derivedFromContent = (id) => {
+            const name = onFirst.get(id) ?? "";
+            if (name === "" || name !== (onSecond.get(id) ?? "")) return false;
+            const spelled = lettersAndDigits(name);
+            return spelled !== "" && lettersAndDigits(id).includes(spelled);
+          };
+          const allocated = shared.filter((id) => !derivedFromContent(id));
+          const quoted = (ids) => ids.map((id) => `'${id}'`).join(", ");
+          if (allocated.length > 0) {
+            return {
+              advisories: [
+                `two instances that imported the same document and each created one element, not of the same name, allocated the same id (${quoted(allocated)}) \u2014 RECOMMENDED: allocate ids for new elements that do not collide across peers (random or peer-scoped, not a per-instance counter); once both edits merge, two elements share one id`
+              ]
+            };
+          }
+          if (shared.length > 0) {
+            return skip(
+              `both instances created an element of the same name and allocated the same id, one derived from that name (${quoted(shared)}) \u2014 such ids collide for identical content by design, so the check is inconclusive: let mutate's elements differ in content (a counter the harness shares across instances)`
+            );
+          }
+        } finally {
+          for (const peer of peers) peer.destroy();
+        }
+      }
+    },
     {
       name: "L6: export is total after imports, user mutations and undo",
       async run(h) {
@@ -594,6 +872,84 @@ ${out}`);
         }
       }
     },
+    {
+      name: "L7: every rejection of a derived probe leaves no trace",
+      async run(h) {
+        const base = h.canonicalTexts[0] ?? "";
+        const m = await h.create();
+        try {
+          await m.importText(base);
+          const baseline = exportOrFail(m, "after importing canonicalTexts[0]");
+          const baseIds = sortedIds(m);
+          let previous;
+          const reimportBase = async () => {
+            if (previous === void 0) return;
+            const after = `after importing ${describeProbe(previous)}`;
+            await importOrFail(m, base, `the next valid import ${after} did not render`);
+            const doc = exportOrFail(m, `on the next valid import ${after}`);
+            if (doc !== baseline || baseIds && !same(baseIds, sortedIds(m))) {
+              fail(`the next valid import ${after} did not replace the document (wedged)`);
+            }
+          };
+          const mutateAndExpectApplied = async () => {
+            await h.mutate(m);
+            await (h.settle ?? defaultSettle)();
+            const doc = exportOrFail(m, "after a user mutation");
+            if (doc === baseline) {
+              fail(
+                previous === void 0 ? "the harness mutation did not change the export \u2014 the case proves nothing" : `a user mutation after importing ${describeProbe(previous)} did not apply (wedged)`
+              );
+            }
+            return doc;
+          };
+          for (const probe of probesOf(h)) {
+            await reimportBase();
+            const doc = await mutateAndExpectApplied();
+            const ids = sortedIds(m);
+            const what = `importText(${describeProbe(probe)})`;
+            let rejected = false;
+            const { calls } = await changeEvents(
+              h,
+              m,
+              () => m.importText(probe.text).then(
+                () => void 0,
+                () => {
+                  rejected = true;
+                }
+              )
+            );
+            if (rejected) {
+              if (calls > 0) fail(`a rejected ${what} fired onContentChanged ${calls}x (L7)`);
+              if (exportOrFail(m, `after a rejected ${what}`) !== doc) {
+                fail(`a rejected ${what} changed the document \u2014 the previous state must stay intact (L7)`);
+              }
+              if (ids && !same(ids, sortedIds(m))) {
+                fail(
+                  `a rejected ${what} changed the rendered elements \u2014 the canvas must keep the previous document (L7)`
+                );
+              }
+              if (h.undo) {
+                await h.undo(m);
+                if (exportOrFail(m, `after an undo that followed a rejected ${what}`) !== baseline) {
+                  fail(
+                    `a rejected ${what} erased the undo history \u2014 the previous document's history must stay intact (L7)`
+                  );
+                }
+              }
+            } else {
+              if (calls > 0)
+                fail(`${what} resolved and fired onContentChanged ${calls}x \u2014 an import is silent (L1)`);
+              exportOrFail(m, `after ${what} resolved (L6)`);
+            }
+            previous = probe;
+          }
+          await reimportBase();
+          await mutateAndExpectApplied();
+        } finally {
+          m.destroy();
+        }
+      }
+    },
     {
       name: "viewer (when shipped): read-only, silent, canonical, fits, reveals, keeps foreign content, unshaken by a rejected import",
       async run(h) {
@@ -701,10 +1057,14 @@ function registerConformance(harness, test, options = {}) {
   const onSkip = options.onSkip ?? ((name, reason) => {
     console.warn(`modeler-api conformance: SKIPPED "${name}" \u2014 ${reason}`);
   });
+  const onAdvisory = options.onAdvisory ?? ((name, advice) => {
+    console.warn(`modeler-api conformance: ADVISORY "${name}" \u2014 ${advice}`);
+  });
   for (const conformanceCase of conformanceCases()) {
     test(`conformance: ${conformanceCase.name}`, async () => {
       const outcome = await conformanceCase.run(harness);
       if (outcome?.skipped) onSkip(conformanceCase.name, outcome.skipped);
+      for (const advice of outcome?.advisories ?? []) onAdvisory(conformanceCase.name, advice);
     });
   }
 }