@miragon/modeler-api 1.0.0 → 1.1.0

package/dist/conformance.js

@@ -1,6 +1,6 @@
 import {
   MODELER_API_VERSION
-} from "./chunk-HWB2EYDZ.js";
+} from "./chunk-32BMH76T.js";
 
 // src/conformance.ts
 function attachedHost(width = 800, height = 600) {
@@ -42,6 +42,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;
@@ -58,12 +71,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);
@@ -89,6 +132,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) {
@@ -123,6 +216,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) {
@@ -445,6 +619,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) {
@@ -566,6 +844,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) {
@@ -673,10 +1029,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);
     });
   }
 }