fix(library): preserve legacy diagram imports

Author: FelixTJDietrich

.changeset/orthogonal-edge-routing.md

@@ -2,4 +2,4 @@
 "@tumaet/apollon": minor
 ---
 
-Edges now route themselves far more cleanly. They avoid unnecessary corners and crossings, run straight when two boxes line up, leave a node from a suitable side, and divide each available node side into balanced grid-aligned stretches — one edge centres itself, two edges make three even gaps, and larger groups spread the same way — instead of piling into a corner, stepping when they could be straight, or looping around another edge. Dragging an endpoint preserves its attachment while the route remains eligible for layout; dragging a bend preserves the route you authored. In both cases, neighbouring edges adapt without jumping on release, and node dragging remains substantially more responsive in edge-dense diagrams. Automatic results are deterministic, so every collaborator and a reloaded page see the same picture.
+Edges now route themselves far more cleanly. They avoid unnecessary corners and crossings, run straight when two boxes line up, leave a node from a suitable side, and divide each available node side into balanced grid-aligned stretches — one edge centres itself, two edges make three even gaps, and larger groups spread the same way — instead of piling into a corner, stepping when they could be straight, or looping around another edge. Dragging an endpoint preserves its attachment while the route remains eligible for layout; dragging a bend preserves the route you authored. In both cases, neighbouring edges adapt without jumping on release, and node dragging remains substantially more responsive in edge-dense diagrams. Automatic results are deterministic, so every collaborator and a reloaded page see the same picture. Existing v3 diagrams and older v4 files with pre-routing edge data continue to open and are upgraded automatically.

library/lib/services/migration/EdgeTransformer.ts

@@ -10,7 +10,8 @@ import type { ApollonEdge, UMLModel, OrthogonalEdgeData } from "@/typings"
 
 /**
  * Returns a new edge whose data is free of stale runtime geometry. Does NOT
- * mutate the input. A null/absent `data` is normalized to an empty object.
+ * mutate the input. Null/absent legacy data and points are normalized to the
+ * canonical empty point list.
  */
 export function hydrateEdgeData(edge: ApollonEdge): ApollonEdge {
   // Legacy/malformed payloads can carry a null or absent `data`; treat it as
@@ -22,13 +23,18 @@ export function hydrateEdgeData(edge: ApollonEdge): ApollonEdge {
     "computedSegments"
   )
 
-  // Already a clean object with nothing to strip — leave it untouched.
-  if (edge.data != null && !hasComputedSegments) {
+  // Already a clean object with nothing to strip or hydrate — leave it untouched.
+  if (
+    edge.data != null &&
+    Array.isArray(sourceData.points) &&
+    !hasComputedSegments
+  ) {
     return edge
   }
 
   const data = { ...sourceData } as OrthogonalEdgeData & Record<string, unknown>
   delete data.computedSegments
+  if (!Array.isArray(data.points)) data.points = []
 
   return { ...edge, data }
 }

library/lib/utils/versionConverter.ts

@@ -906,8 +906,8 @@ export function isV4Format(data: any): data is UMLModel {
       (edge: unknown) =>
         edge != null &&
         typeof edge === "object" &&
-        (edge as { data?: unknown }).data != null &&
-        typeof (edge as { data: unknown }).data === "object"
+        ((edge as { data?: unknown }).data == null ||
+          typeof (edge as { data: unknown }).data === "object")
     )
   )
 }
@@ -964,13 +964,58 @@ export function normalizeElementTags(model: UMLModel): UMLModel {
   return model
 }
 
+/**
+ * Remove React Flow interaction state that older exports and captured fixtures
+ * could persist. Imported models should contain only durable diagram data, not
+ * the selection or drag state of the editor that produced the file.
+ */
+function stripRuntimeInteractionState(model: UMLModel): UMLModel {
+  let changed = false
+
+  const nodes = model.nodes.map((node) => {
+    if (
+      !("selected" in node) &&
+      !("dragging" in node) &&
+      !("resizing" in node)
+    ) {
+      return node
+    }
+
+    changed = true
+    const persistentNode = { ...node } as ApollonNode & {
+      selected?: unknown
+      dragging?: unknown
+      resizing?: unknown
+    }
+    delete persistentNode.selected
+    delete persistentNode.dragging
+    delete persistentNode.resizing
+    return persistentNode
+  })
+
+  const edges = model.edges.map((edge) => {
+    if (!("selected" in edge)) return edge
+
+    changed = true
+    const persistentEdge = { ...edge } as ApollonEdge & {
+      selected?: unknown
+    }
+    delete persistentEdge.selected
+    return persistentEdge
+  })
+
+  return changed ? { ...model, nodes, edges } : model
+}
+
 /**
  * The single normalization pass every incoming model must pass through, whatever
  * its origin. Keep it idempotent and version-agnostic so already-saved `4.0.0`
  * files are repaired on load rather than gated behind a version check.
  */
 export function normalizeModel(model: UMLModel): UMLModel {
-  return normalizeElementTags(normalizeClassStereotypes(model))
+  return stripRuntimeInteractionState(
+    normalizeElementTags(normalizeClassStereotypes(model))
+  )
 }
 
 /**

library/tests/unit/EdgeTransformer.test.ts

@@ -69,13 +69,28 @@ describe("EdgeTransformer", () => {
       expect(edge.data).toHaveProperty("computedSegments")
     })
 
-    it("normalizes null/absent data to an empty object without throwing", () => {
+    it("normalizes null/absent data to canonical edge data without throwing", () => {
       const malformed = makeEdge({
         data: null as unknown as ApollonEdge["data"],
       })
 
       expect(() => hydrateEdgeData(malformed)).not.toThrow()
-      expect(hydrateEdgeData(malformed).data).toEqual({})
+      expect(hydrateEdgeData(malformed).data).toEqual({ points: [] })
+    })
+
+    it("hydrates missing or malformed legacy points", () => {
+      const missing = makeEdge({
+        data: { label: "legacy" } as ApollonEdge["data"],
+      })
+      const malformed = makeEdge({
+        data: { points: "legacy" } as unknown as ApollonEdge["data"],
+      })
+
+      expect(hydrateEdgeData(missing).data).toEqual({
+        label: "legacy",
+        points: [],
+      })
+      expect(hydrateEdgeData(malformed).data).toEqual({ points: [] })
     })
   })
 

library/tests/unit/modelSchema.test.ts

@@ -100,22 +100,25 @@ describe("published model JSON schema", () => {
   }, 60_000)
 })
 
-// Contract lock: every real diagram model the app round-trips must validate
-// after importDiagram. This is what proves the open `data` envelope is correct
-// — it guarantees no real submission is rejected, and guards against anyone
-// later tightening the schema in a way that would. (The assets/diagramTemplates
-// starter files are intentionally excluded: they carry edges without `data`, so
-// they aren't conformant v4 submission models — a separate, pre-existing matter.)
+// Contract lock: every real diagram model the app round-trips, including the
+// bundled starter templates, must validate after importDiagram. This proves the
+// open `data` envelope is correct, guarantees templates work through both the
+// preset and direct-file import paths, and guards against future schema drift.
 describe("schema accepts every real diagram model (fixtures)", () => {
-  const dir = join(
-    import.meta.dirname,
-    "../../../standalone/webapp/tests/fixtures"
+  const dirs = [
+    join(import.meta.dirname, "../../../standalone/webapp/tests/fixtures"),
+    join(
+      import.meta.dirname,
+      "../../../standalone/webapp/assets/diagramTemplates"
+    ),
+  ]
+  const models = dirs.flatMap((dir) =>
+    existsSync(dir)
+      ? readdirSync(dir)
+          .filter((f) => f.endsWith(".json"))
+          .map((f) => [f, join(dir, f)] as const)
+      : []
   )
-  const models = existsSync(dir)
-    ? readdirSync(dir)
-        .filter((f) => f.endsWith(".json"))
-        .map((f) => [f, join(dir, f)] as const)
-    : []
 
   it("found fixtures to validate", () => {
     expect(models.length).toBeGreaterThan(10)

library/tests/unit/versionConverter.test.ts

@@ -1221,6 +1221,22 @@ describe("isV4Format", () => {
     expect(isV4Format(makeV4Model({ version: "4.1.0" }))).toBe(true)
   })
 
+  it("accepts legacy V4 edges with absent or null data for migration", () => {
+    expect(
+      isV4Format(
+        makeV4Model({
+          edges: [{ id: "without-data" }, { id: "null-data", data: null }],
+        })
+      )
+    ).toBe(true)
+  })
+
+  it("rejects V4 edges with non-object data", () => {
+    expect(
+      isV4Format(makeV4Model({ edges: [{ id: "bad-data", data: "invalid" }] }))
+    ).toBe(false)
+  })
+
   it("returns false for V3 data", () => {
     expect(isV4Format(makeV3Model())).toBe(false)
   })
@@ -1262,6 +1278,38 @@ describe("importDiagram", () => {
     expect(result).toBe(v4) // Same reference
   })
 
+  it("hydrates legacy V4 edges with absent or null data", () => {
+    const result = importDiagram(
+      makeV4Model({
+        edges: [{ id: "without-data" }, { id: "null-data", data: null }],
+      })
+    )
+
+    expect(result.edges).toEqual([
+      { id: "without-data", data: { points: [] } },
+      { id: "null-data", data: { points: [] } },
+    ])
+  })
+
+  it("strips transient interaction state from imported V4 models", () => {
+    const result = importDiagram(
+      makeV4Model({
+        nodes: [
+          {
+            id: "node",
+            selected: false,
+            dragging: true,
+            resizing: false,
+          },
+        ],
+        edges: [{ id: "edge", selected: true, data: {} }],
+      })
+    )
+
+    expect(result.nodes[0]).toEqual({ id: "node" })
+    expect(result.edges[0]).toEqual({ id: "edge", data: { points: [] } })
+  })
+
   it("converts V3 wrapped format", () => {
     const v3 = makeV3Wrapped()
     const result = importDiagram(v3)

standalone/webapp/assets/diagramTemplates/Adapter.json

@@ -100,6 +100,7 @@
       "targetHandle": "left",
       "type": "ClassUnidirectional",
       "selected": false,
+      "data": { "points": [] },
       "id": "xy-edge__286257b1-ebd3-424f-b3e4-c1c2a722531bright-2eb1ceb2-266e-4669-89f1-c61e246cb10cleft"
     },
     {

standalone/webapp/assets/diagramTemplates/Bridge.json

@@ -141,6 +141,7 @@
       "targetHandle": "left",
       "type": "ClassBidirectional",
       "selected": false,
+      "data": { "points": [] },
       "id": "xy-edge__286257b1-ebd3-424f-b3e4-c1c2a722531bright-2eb1ceb2-266e-4669-89f1-c61e246cb10cleft"
     },
     {
@@ -206,7 +207,8 @@
       "targetHandle": "left",
       "id": "1737993220311-2eb1ceb2-266e-4669-89f1-c61e246cb10c-889cb1f6-175a-45c0-ae06-d1acab5dcbdc",
       "type": "ClassBidirectional",
-      "selected": false
+      "selected": false,
+      "data": { "points": [] }
     }
   ],
   "assessments": {}

standalone/webapp/assets/diagramTemplates/Command.json

@@ -107,7 +107,8 @@
       "targetHandle": "left",
       "id": "1737994716146-8acfa3c3-de5b-424a-a555-cb68855538d0-7351d563-b929-460e-a09d-e2b463bfceea",
       "type": "ClassUnidirectional",
-      "selected": false
+      "selected": false,
+      "data": { "points": [] }
     },
     {
       "source": "8acfa3c3-de5b-424a-a555-cb68855538d0",
@@ -116,7 +117,8 @@
       "targetHandle": "left",
       "id": "1737994722983-8acfa3c3-de5b-424a-a555-cb68855538d0-41a9495d-9993-449e-a3b5-a7a704130380",
       "type": "ClassUnidirectional",
-      "selected": false
+      "selected": false,
+      "data": { "points": [] }
     },
     {
       "source": "f235a28a-6d9b-482c-9e67-546dfd92e0d5",
@@ -139,7 +141,8 @@
       "targetHandle": "right",
       "id": "1737994981686-f235a28a-6d9b-482c-9e67-546dfd92e0d5-41a9495d-9993-449e-a3b5-a7a704130380",
       "type": "ClassUnidirectional",
-      "selected": false
+      "selected": false,
+      "data": { "points": [] }
     },
     {
       "source": "7351d563-b929-460e-a09d-e2b463bfceea",
@@ -148,7 +151,8 @@
       "targetHandle": "left",
       "id": "1737995015106-7351d563-b929-460e-a09d-e2b463bfceea-52e53f8b-cac0-4816-a70a-c2f154f3fb67",
       "type": "ClassUnidirectional",
-      "selected": false
+      "selected": false,
+      "data": { "points": [] }
     },
     {
       "source": "8acfa3c3-de5b-424a-a555-cb68855538d0",
@@ -157,7 +161,8 @@
       "targetHandle": "bottom",
       "id": "1737995032625-8acfa3c3-de5b-424a-a555-cb68855538d0-f235a28a-6d9b-482c-9e67-546dfd92e0d5",
       "type": "ClassDependency",
-      "selected": false
+      "selected": false,
+      "data": { "points": [] }
     }
   ],
   "assessments": {}

standalone/webapp/assets/diagramTemplates/Factory.json

@@ -124,6 +124,7 @@
       "targetHandle": "left",
       "type": "ClassBidirectional",
       "selected": false,
+      "data": { "points": [] },
       "id": "xy-edge__cfc9b781-debe-4ca3-903c-9a9e555f6812right-1c0330be-83dd-4d92-9bd1-d62a36e90c7bleft"
     },
     {