fix(library): preserve waypoint compatibility

Author: FelixTJDietrich

docs/library/api/model-contract.md

@@ -43,7 +43,7 @@ A v4 model is:
 
 ```ts no-check
 type UMLModel = {
-  version: `4.${number}.${number}` // wire-format version, e.g. "4.0.0"
+  version: `4.${number}.${number}` // wire-format version, currently "4.2.0"
   id: string
   title: string
   type: UMLDiagramType // "ClassDiagram" | "BPMN" | … (13 values)
@@ -79,8 +79,16 @@ normalization rules and the addressing API.
 ## Versioning policy
 
 `version` tracks the **wire-format major line (4.x)** — _not_ the npm package
-version. `importDiagram` stamps `4.0.0` when it _converts_ a v2 / v3 payload;
-an already-v4 model passes through with its existing version string untouched.
+version. The current canonical model version is `4.2.0`. `importDiagram`
+accepts every supported v2, v3, and v4 payload, migrates it in place where
+necessary, and returns the current v4 representation.
+
+The 4.2 minor adds optional, interior-only waypoints to straight connections.
+When loading a 4.0 or 4.1 model, Apollon discards `data.points` only on those
+straight edge families: older releases used that field for inert full-route
+geometry, which must not become visible user-authored bends. Orthogonal edge
+waypoints and all other model data are preserved. Models from 4.2 and later keep
+their straight-edge waypoints unchanged.
 
 | Change                | Bump  | What you do                                       |
 | --------------------- | ----- | ------------------------------------------------- |

library/lib/edges/GenericEdge.tsx

@@ -573,7 +573,7 @@ export const EdgeWaypointHandles = ({
     className: string,
     key: string,
     onPointerDown: (event: ReactPointerEvent<SVGRectElement>) => void,
-    accessibleName: string,
+    accessibleName?: string,
     onDoubleClick?: () => void,
     onKeyDown?: (event: ReactKeyboardEvent<SVGRectElement>) => void
   ) => (
@@ -595,9 +595,9 @@ export const EdgeWaypointHandles = ({
         rx={hit / 2}
         ry={hit / 2}
         pointerEvents="all"
-        tabIndex={0}
-        role="button"
-        aria-label={accessibleName}
+        tabIndex={onKeyDown && accessibleName ? 0 : undefined}
+        role={onKeyDown && accessibleName ? "button" : undefined}
+        aria-label={onKeyDown ? accessibleName : undefined}
         style={{ cursor: "grab", fill: "transparent", zIndex: 9999 }}
         onPointerDown={onPointerDown}
         onDoubleClick={(event) => {
@@ -618,8 +618,7 @@ export const EdgeWaypointHandles = ({
           midpoint.position,
           "edge-circle edge-waypoint-handle edge-waypoint-handle--proposed",
           `midpoint-${midpoint.segmentIndex}`,
-          (event) => onGhostPointerDown(event, midpoint.segmentIndex),
-          t.addEdgeWaypoint
+          (event) => onGhostPointerDown(event, midpoint.segmentIndex)
         )
       )}
       {interior.map((waypoint, index) =>

library/lib/edges/edgeRoutingBehavior.ts

@@ -10,10 +10,10 @@
  */
 
 /**
- * Edge types rendered by the straight-path hook (`useStraightPathEdge`): a plain
- * two-point line between the adjusted endpoints, with no obstacle or neighbour
- * routing. Other (step) edges still route AROUND these lines — the solver emits
- * their two-point polylines into the shared route map for that reason.
+ * Edge types rendered by the straight-path hook (`useStraightPathEdge`): a direct
+ * line through any user-authored interior waypoints, with no automatic obstacle
+ * or neighbour routing. Other (step) edges still route AROUND these polylines —
+ * the solver emits their complete authored routes into the shared map.
  */
 export const STRAIGHT_HOOK_EDGE_TYPES: ReadonlySet<string> = new Set([
   "UseCaseAssociation",

library/lib/i18n/labels.ts

@@ -21,10 +21,12 @@ export interface ApollonLabels {
   redoHint: string
   multiSelection: string
   multiSelectionHint: string
-  /** Accessible name for a straight-edge segment midpoint create handle. */
-  addEdgeWaypoint: string
-  /** Accessible name for an authored straight-edge waypoint handle. */
-  moveEdgeWaypoint: string
+  /**
+   * Accessible name for an authored straight-edge waypoint handle.
+   * Optional so a complete dictionary written against an older library release
+   * remains assignable; {@link mergeLabels} always fills the English default.
+   */
+  moveEdgeWaypoint?: string
 
   // Minimap
   miniMap: string
@@ -297,8 +299,14 @@ function defaultNodeTypeLabel(nodeType?: string): string {
     .trim()
 }
 
+/**
+ * The fully resolved dictionary used inside the editor. Public host dictionaries
+ * may omit keys added in later minor releases; merging always restores them.
+ */
+export type ResolvedApollonLabels = Required<ApollonLabels>
+
 /** The shipped English strings — the fallback for any key a host doesn't override. */
-export const DEFAULT_LABELS: ApollonLabels = Object.freeze<ApollonLabels>({
+const RESOLVED_DEFAULT_LABELS: ResolvedApollonLabels = Object.freeze({
   zoomToolbar: "Zoom, history and selection controls",
   zoomIn: "Zoom in",
   zoomOut: "Zoom out",
@@ -311,7 +319,6 @@ export const DEFAULT_LABELS: ApollonLabels = Object.freeze<ApollonLabels>({
   redoHint: "Redo (Ctrl+Y or Ctrl+Shift+Z)",
   multiSelection: "Select multiple elements",
   multiSelectionHint: "Select multiple: click elements to add or remove",
-  addEdgeWaypoint: "Drag to add a waypoint",
   moveEdgeWaypoint:
     "Waypoint: drag to move, double-click or press Delete to remove",
   miniMap: "Mini map",
@@ -512,8 +519,17 @@ export const DEFAULT_LABELS: ApollonLabels = Object.freeze<ApollonLabels>({
   nodeWord: "node",
 })
 
+/**
+ * Publicly retain the historical `ApollonLabels` type. The value is fully
+ * populated, but consumers that used `typeof DEFAULT_LABELS` for a translation
+ * dictionary must not acquire new required keys in a minor release.
+ */
+export const DEFAULT_LABELS: ApollonLabels = RESOLVED_DEFAULT_LABELS
+
 /** Merge a host's partial overrides over the English defaults (shallow, per key). */
 export const mergeLabels = (
   overrides?: Partial<ApollonLabels>
-): ApollonLabels =>
-  overrides ? { ...DEFAULT_LABELS, ...overrides } : DEFAULT_LABELS
+): ResolvedApollonLabels =>
+  overrides
+    ? { ...RESOLVED_DEFAULT_LABELS, ...overrides }
+    : RESOLVED_DEFAULT_LABELS

library/lib/store/metadataStore.ts

@@ -6,7 +6,7 @@ import { getDiagramMetadata, STORE_ORIGIN } from "@/sync/ydoc"
 import { UMLDiagramType } from "@/types"
 import { ApollonMode, ApollonView } from "@/typings"
 import { IPoint } from "@/edges/Connection"
-import { DEFAULT_LABELS, type ApollonLabels } from "@/i18n/labels"
+import { mergeLabels, type ResolvedApollonLabels } from "@/i18n/labels"
 import type { Edge } from "@xyflow/react"
 import { DISABLED_TAG_CONFIG, type TagConfig } from "@/utils/tagUtils"
 
@@ -45,7 +45,7 @@ export type MetadataStore = {
   /** Whether the editor answers `APOLLON_SHORTCUTS` at all. */
   keyboardShortcuts: boolean
   /** User-facing strings for the editor's own chrome; host-overridable for i18n. */
-  labels: ApollonLabels
+  labels: ResolvedApollonLabels
   /** Element-tag authoring config; disabled until a host opts in. */
   tagConfig: TagConfig
   scrollEnabled: boolean
@@ -73,7 +73,7 @@ export type MetadataStore = {
   setScrollLock: (scrollLock: boolean) => void
   setMultiSelectionMode: (multiSelectionMode: boolean) => void
   setKeyboardShortcuts: (keyboardShortcuts: boolean) => void
-  setLabels: (labels: ApollonLabels) => void
+  setLabels: (labels: ResolvedApollonLabels) => void
   setTagConfig: (tagConfig: TagConfig) => void
   setScrollEnabled: (scrollEnabled: boolean) => void
   startConnectionGuidance: (
@@ -101,7 +101,7 @@ type InitialMetadataState = {
   scrollLock: boolean
   multiSelectionMode: boolean
   keyboardShortcuts: boolean
-  labels: ApollonLabels
+  labels: ResolvedApollonLabels
   tagConfig: TagConfig
   scrollEnabled: boolean
   connectionGuidanceActive: boolean
@@ -124,7 +124,7 @@ const initialMetadataState: InitialMetadataState = {
   scrollLock: false,
   multiSelectionMode: false,
   keyboardShortcuts: true,
-  labels: DEFAULT_LABELS,
+  labels: mergeLabels(),
   tagConfig: DISABLED_TAG_CONFIG,
   scrollEnabled: false,
   connectionGuidanceActive: false,

library/tests/unit/EdgeWaypointHandles.test.tsx

@@ -0,0 +1,66 @@
+import { render } from "@testing-library/react"
+import { ReactFlowProvider } from "@xyflow/react"
+import { describe, expect, it, vi } from "vitest"
+import * as Y from "yjs"
+import { EdgeWaypointHandles } from "@/edges/GenericEdge"
+import { MetadataStoreContext } from "@/store/context"
+import { createMetadataStore } from "@/store/metadataStore"
+
+const renderHandles = ({
+  route,
+  interior,
+}: {
+  route: { x: number; y: number }[]
+  interior: { x: number; y: number }[]
+}) =>
+  render(
+    <MetadataStoreContext value={createMetadataStore(new Y.Doc())}>
+      <ReactFlowProvider>
+        <svg>
+          <EdgeWaypointHandles
+            route={route}
+            interior={interior}
+            selectedWaypointIndex={null}
+            onWaypointPointerDown={vi.fn()}
+            onWaypointDoubleClick={vi.fn()}
+            onWaypointKeyDown={vi.fn()}
+            onGhostPointerDown={vi.fn()}
+          />
+        </svg>
+      </ReactFlowProvider>
+    </MetadataStoreContext>
+  )
+
+describe("EdgeWaypointHandles", () => {
+  it("keeps pointer-only midpoint handles out of the keyboard tab order", () => {
+    const { container } = renderHandles({
+      route: [
+        { x: 0, y: 0 },
+        { x: 100, y: 0 },
+      ],
+      interior: [],
+    })
+    const midpoint = container.querySelector(".edge-waypoint-hit-target")
+
+    expect(midpoint).not.toHaveAttribute("tabindex")
+    expect(midpoint).not.toHaveAttribute("role")
+    expect(midpoint).not.toHaveAttribute("aria-label")
+  })
+
+  it("keeps authored waypoints keyboard focusable and named", () => {
+    const waypoint = { x: 50, y: 40 }
+    const { container } = renderHandles({
+      route: [{ x: 0, y: 0 }, waypoint, { x: 100, y: 0 }],
+      interior: [waypoint],
+    })
+    const target = container.querySelector(
+      '.edge-waypoint-hit-target[role="button"]'
+    )
+
+    expect(target).toHaveAttribute("tabindex", "0")
+    expect(target).toHaveAttribute(
+      "aria-label",
+      "Waypoint: drag to move, double-click or press Delete to remove"
+    )
+  })
+})

library/tests/unit/labels.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest"
+import { DEFAULT_LABELS, mergeLabels } from "@/i18n/labels"
+
+describe("mergeLabels", () => {
+  it("fills labels introduced after a host's partial dictionary was written", () => {
+    const labels = mergeLabels({ zoomIn: "Vergrößern" })
+
+    expect(labels.zoomIn).toBe("Vergrößern")
+    expect(labels.moveEdgeWaypoint).toBe(DEFAULT_LABELS.moveEdgeWaypoint)
+  })
+})

library/tests/unit/versionConverter.test.ts

@@ -1564,6 +1564,24 @@ describe("normalizeStraightEdgeWaypoints", () => {
     )
   })
 
+  it("does not rewrite or discard waypoints from a future v4 minor", () => {
+    const model = makeV4Model({
+      version: "4.9.0",
+      edges: [
+        {
+          id: "straight",
+          type: "UseCaseAssociation",
+          data: { points: [...points] },
+        },
+      ],
+    })
+    normalizeStraightEdgeWaypoints(model)
+    expect(model.version).toBe("4.9.0")
+    expect((model.edges[0].data as { points: unknown[] }).points).toEqual(
+      points
+    )
+  })
+
   it("runs on the universal import path", () => {
     const model = makeV4Model({
       version: "4.0.0",

standalone/webapp/tests/e2e/straight-edge-waypoint-ux.spec.ts

@@ -34,6 +34,8 @@ fixture.nodes = fixture.nodes.slice(0, 2)
 fixture.edges = fixture.edges.slice(0, 1)
 
 const edgeId = fixture.edges[0].id
+const midpointHandleSelector =
+  ".edge-waypoint-handle--proposed + .edge-waypoint-hit-target"
 
 async function persistedPoints(page: Page): Promise<unknown[] | null> {
   return page.evaluate((id) => {
@@ -94,13 +96,34 @@ test.beforeEach(async ({ page }) => {
   await selectEdgeOnPath(page, edgeId)
 })
 
+test("legacy straight-edge route caches do not become visible bends", async ({
+  page,
+}) => {
+  const legacyFixture = structuredClone(fixture)
+  legacyFixture.version = "4.1.0"
+  legacyFixture.edges[0].data.points = [
+    { x: 40, y: 40 },
+    { x: 180, y: 220 },
+  ]
+
+  await openFixtureInLocalEditor(page, legacyFixture)
+  await waitForCanvasReady(page)
+  await selectEdgeOnPath(page, edgeId)
+
+  await expect.poll(() => persistedPoints(page)).toEqual([])
+  await expect.poll(() => pathExcessLength(page)).toBeLessThan(1)
+  await expect(
+    page
+      .locator(`.react-flow__edge[data-id="${edgeId}"]`)
+      .getByRole("button", { name: /^Waypoint:/ })
+  ).toHaveCount(0)
+})
+
 test("straight and step bend handles share one opaque visual state", async ({
   page,
 }) => {
   const edge = page.locator(`.react-flow__edge[data-id="${edgeId}"]`)
-  const createTarget = edge
-    .getByRole("button", { name: "Drag to add a waypoint" })
-    .first()
+  const createTarget = edge.locator(midpointHandleSelector).first()
   const createCircle = edge.locator(".edge-waypoint-handle--proposed").first()
 
   // Selection clicks the route midpoint, so the newly-mounted midpoint handle
@@ -117,12 +140,6 @@ test("straight and step bend handles share one opaque visual state", async ({
   await page.mouse.move(280, 680)
   await expect(createCircle).toHaveCSS("fill", straightFill)
 
-  // Keyboard users retain a clear darkened-circle focus state, but the browser
-  // must not draw a square/ring around the invisible hit rectangle.
-  await createTarget.focus()
-  await expect(createTarget).toHaveCSS("outline-style", "none")
-  await expect(createCircle).not.toHaveCSS("fill", straightFill)
-
   await openFixtureInLocalEditor(page, structuredClone(stepFixture))
   await waitForCanvasReady(page)
   const stepEdgeId = "edge-bidirectional-dog-imovable"
@@ -139,9 +156,7 @@ test("straight waypoints feel editable and collapse live back to a line", async
   page,
 }) => {
   const edge = page.locator(`.react-flow__edge[data-id="${edgeId}"]`)
-  const createHandle = edge.getByRole("button", {
-    name: "Drag to add a waypoint",
-  })
+  const createHandle = edge.locator(midpointHandleSelector)
   await expect(createHandle.first()).toBeVisible()
   await dragBy(page, createHandle.first(), 70, 70)
 
@@ -186,15 +201,13 @@ test("a focused waypoint can be removed with the keyboard", async ({
   page,
 }) => {
   const edge = page.locator(`.react-flow__edge[data-id="${edgeId}"]`)
-  await dragBy(
-    page,
-    edge.getByRole("button", { name: "Drag to add a waypoint" }).first(),
-    70,
-    70
-  )
+  await dragBy(page, edge.locator(midpointHandleSelector).first(), 70, 70)
 
   const waypoint = edge.getByRole("button", { name: /^Waypoint:/ })
   await waypoint.focus()
+  // Authored points are keyboard actions. Their circle provides the focus
+  // feedback; the invisible SVG hit rectangle must never acquire a square ring.
+  await expect(waypoint).toHaveCSS("outline-style", "none")
   await page.keyboard.press("Delete")
 
   await expect(waypoint).toHaveCount(0)
@@ -209,12 +222,7 @@ test("the edge toolbar never traps a waypoint underneath it", async ({
   await selectEdgeOnPath(page, edgeId)
 
   const edge = page.locator(`.react-flow__edge[data-id="${edgeId}"]`)
-  await dragBy(
-    page,
-    edge.getByRole("button", { name: "Drag to add a waypoint" }).first(),
-    -70,
-    -70
-  )
+  await dragBy(page, edge.locator(midpointHandleSelector).first(), -70, -70)
 
   const waypoint = edge.getByRole("button", { name: /^Waypoint:/ })
   await expect(waypoint).toHaveCount(1)