fix(library): reserve an endpoint zone so no bend handle ever starves a grip

My previous fix only covered lone straight edges; a short PINNED S-jog (diagram 79)
still starved both endpoint grips to 0px, because a bend handle on its terminal stub
AND one on its 5px inner jog sat right on top of the endpoints. The root cause is
universal: nothing kept bend handles clear of the endpoints, so on any short or
crowded edge a handle lands inside an endpoint's grip zone and the reconnect target
(drawn on top) caps the grip to nothing.

Generalise "endpoints first" to every segment: each endpoint reserves a run along the
edge (ENDPOINT_HANDLE_RESERVE_PX), and ANY bend handle — terminal, inner or lone —
whose position falls within that reserve of either endpoint is withheld. The endpoints
then own their ends; every handle that survives sits clear in the middle at a usable
size. This replaces the narrower lone-segment rule. A short terminal stub (~30px) no
longer exposes a bend handle — its handle only gave a ~7px grip anyway — so the
endpoint grip is legible instead.

Diagram 79 grips: 0px → visible; a long edge still keeps its centre bend handle.
Updated the bend-handle unit tests to the endpoint-reserve behaviour and the
consecutive-bend e2e to grab a reshaping handle (short stubs no longer expose one);
added the pinned-jog e2e case. 1519 unit, handle + fresh-bend + interaction e2e green,
gate 23/23.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: FelixTJDietrich

library/lib/constants.ts

@@ -300,6 +300,13 @@ export const EDGES = Object.freeze({
    * (on-top) target never abuts or buries the handle. Small — just enough to separate
    * them cleanly at the handle's rounded corner. */
   ENDPOINT_HANDLE_CLEARANCE_PX: 4,
+  /** Run along the edge each ENDPOINT reserves for its own grip + reconnect target. A
+   * bend handle landing within this of either endpoint is withheld, so the endpoints —
+   * the primary, universal edge interaction — are never starved by a handle crowding
+   * their end. Sized so the grip clears the nearest kept handle at a usable length: the
+   * grip needs ~14px of run, and a handle eats its rendered half (≥9) plus the clearance
+   * (4), so ~27px keeps the grip legible; rounded to a grid multiple. */
+  ENDPOINT_HANDLE_RESERVE_PX: 30,
   /** Grid step a dragged bend snaps to; matches the canvas grid so bends line
    * up with grid-snapped node handles. */
   BEND_SNAP_GRID_PX: CANVAS.SNAP_TO_GRID_PX,

library/lib/utils/geometry/bendHandles.ts

@@ -125,12 +125,23 @@ export function getBendableSegments(
   if (collapsed.length < 2) return []
 
   const lastSegment = collapsed.length - 2
+  // Total routed length and the running distance to each segment's start, so a handle can
+  // be measured by how far ALONG THE EDGE it sits from either endpoint.
+  const segLen = (a: IPoint, b: IPoint) =>
+    Math.abs(b.x - a.x) + Math.abs(b.y - a.y)
+  let totalLength = 0
+  for (let i = 0; i <= lastSegment; i++)
+    totalLength += segLen(collapsed[i], collapsed[i + 1])
+
   const handles: BendHandle[] = []
+  let distToSegStart = 0
   for (let i = 0; i <= lastSegment; i++) {
     const start = collapsed[i]
     const end = collapsed[i + 1]
     const rawLength = Math.abs(end.x - start.x) + Math.abs(end.y - start.y)
     if (rawLength <= 0) continue
+    const segStartDist = distToSegStart
+    distToSegStart += rawLength
 
     // Reserve the near-endpoint portion of a TERMINAL segment for that endpoint's
     // reconnect target, which is drawn on top and would swallow a handle placed
@@ -150,22 +161,28 @@ export function getBendableSegments(
     if (isTerminal && !isLoneSegment && rawLength < terminalBendFloorPx()) {
       continue
     }
-    // A LONE segment has an endpoint at BOTH ends, each of which owns its half for
-    // reconnecting and repositioning — the primary edge interactions, present on every
-    // edge. A centred bend handle between them starves both to nothing on a short edge
-    // (the reconnect targets, drawn on top, cap against it). So the endpoints win: the
-    // lone handle is withheld unless the region left BETWEEN the two endpoint reserves is
-    // big enough for a usable, non-overlapping handle. A longer lone edge keeps its
-    // handle in the clear middle; a short one is fully owned by its two grips.
-    if (isLoneSegment && bendRegion < EDGES.BEND_HANDLE_MIN_SCREEN_LENGTH_PX) {
-      continue
-    }
 
     const fitsPastSafeArea = bendRegion > 0
     const centreFromStart = fitsPastSafeArea
       ? reserveStart + bendRegion / 2
       : rawLength / 2
 
+    // ENDPOINTS FIRST. The two endpoint handles — reconnect to another node, reposition
+    // along the side — are the primary interaction on every edge. A bend handle placed
+    // within an endpoint's reserve (measured ALONG THE EDGE) starves that endpoint's grip
+    // to nothing, because the reconnect target, drawn on top, caps against it. So any
+    // handle — terminal OR inner — that would land inside either endpoint's reserve is
+    // withheld and the endpoint owns that run. A short edge is thus all grips, no bend
+    // handles; a longer one keeps every handle that sits clear in the middle.
+    const distFromSource = centreFromStart + segStartDist
+    const distFromTarget = totalLength - distFromSource
+    if (
+      Math.min(distFromSource, distFromTarget) <
+      EDGES.ENDPOINT_HANDLE_RESERVE_PX
+    ) {
+      continue
+    }
+
     const t = centreFromStart / rawLength
     handles.push({
       segmentIndex: i,

library/tests/unit/bendHandles.test.ts

@@ -95,9 +95,9 @@ describe("bend handle utilities", () => {
     expect(longHandle.position).toEqual({ x: 60, y: 0 })
 
     // Multi-bend route with SHORT terminal segments (10px source stub, 12px target
-    // stub): both terminals are pinned to a port and cannot bend cleanly at that
-    // length, so they get no handle — the endpoint reconnect target owns them. Only
-    // the two INNER segments keep a handle (inner segments bend cleanly at any length).
+    // stub): both terminals — AND the 8px inner segment tucked against the source — sit
+    // inside an endpoint's reserve, so they are withheld and the endpoints own those
+    // runs. Only the long middle inner segment, clear of both ends, keeps a handle.
     const shortTerminals = [
       { x: 0, y: 0 },
       { x: 10, y: 0 },
@@ -109,7 +109,7 @@ describe("bend handle utilities", () => {
       shortTerminals,
       EDGES.BEND_HANDLE_SAFE_AREA_PX
     )
-    expect(shortHandles.map((h) => h.kind)).toEqual(["inner", "inner"])
+    expect(shortHandles.map((h) => h.kind)).toEqual(["inner"])
 
     // The SAME route with LONG terminal segments (60px each) keeps all four handles:
     // a terminal long enough to bend without cramping its stub is bendable.
@@ -127,49 +127,46 @@ describe("bend handle utilities", () => {
     ).toEqual(["source-terminal", "inner", "inner", "target-terminal"])
   })
 
-  it("gates a terminal handle on the segment's full length, not its reserved bend region (regression)", () => {
+  it("withholds a bend handle inside an endpoint's reserve so the grip is never starved", () => {
     const safeArea = EDGES.BEND_HANDLE_SAFE_AREA_PX
-    // The user's repro: a 30px target terminal stub. Its reserved bend region is only
-    // 30 - min(safeArea, 30/2) = 15px, but `computeTerminalJogCoordinate` bends the
-    // FULL 30px segment cleanly, so the handle must be shown. Gating on the reserved
-    // region (15 < 20) wrongly withheld it — which also uncapped the endpoint target so
-    // it swallowed the neighbouring inner handle.
-    const repro = [
+    const reserve = EDGES.ENDPOINT_HANDLE_RESERVE_PX
+    // A SHORT terminal (30px) puts its handle ~15px from the endpoint — inside the
+    // reserve — where it starves that endpoint's grip. The endpoint owns the stub
+    // instead; the two LONG middle segments keep their handles, clear of both ends.
+    const shortTargetStub = [
       { x: 440, y: -265 },
-      { x: 440, y: -405 }, // seg0 V 140px  → source-terminal
-      { x: 495, y: -405 }, // seg1 H 55px   → inner
-      { x: 495, y: -345 }, // seg2 V 60px   → inner
-      { x: 525, y: -345 }, // seg3 H 30px   → target-terminal (was wrongly withheld)
+      { x: 440, y: -405 }, // seg0 V 140px → source-terminal (handle ~45px from source)
+      { x: 495, y: -405 }, // seg1 H 55px  → inner
+      { x: 495, y: -345 }, // seg2 V 60px  → inner
+      { x: 525, y: -345 }, // seg3 H 30px  → target-terminal, ~15px in → withheld
     ]
-    expect(getBendableSegments(repro, safeArea).map((h) => h.kind)).toEqual([
-      "source-terminal",
-      "inner",
-      "inner",
-      "target-terminal",
-    ])
+    expect(
+      getBendableSegments(shortTargetStub, safeArea).map((h) => h.kind)
+    ).toEqual(["source-terminal", "inner", "inner"])
 
-    // Boundary: MIN_STUB_LENGTH + armFloor. A terminal AT the floor (20px) bends
-    // cleanly and keeps its handle; one below it (15px) degenerates and is withheld.
-    const atFloor = [
+    // A terminal LONG enough to seat its handle clear of the reserve keeps it: a 140px
+    // source stub's handle sits well past the reserve from the source.
+    const longStubs = [
       { x: 0, y: 0 },
-      { x: 20, y: 0 }, // 20px source terminal — bendable
-      { x: 20, y: 200 }, // long inner
-      { x: 300, y: 200 }, // 280px target terminal — bendable
+      { x: 140, y: 0 }, // 140px source terminal — handle clear of the reserve
+      { x: 140, y: 200 }, // long inner
+      { x: 340, y: 200 }, // 200px target terminal — handle clear of the reserve
     ]
-    expect(getBendableSegments(atFloor, safeArea).map((h) => h.kind)).toEqual([
+    const kept = getBendableSegments(longStubs, safeArea)
+    expect(kept.map((h) => h.kind)).toEqual([
       "source-terminal",
       "inner",
       "target-terminal",
     ])
-    const belowFloor = [
-      { x: 0, y: 0 },
-      { x: 15, y: 0 }, // 15px source terminal — spike, withheld
-      { x: 15, y: 200 },
-      { x: 300, y: 200 },
-    ]
-    expect(
-      getBendableSegments(belowFloor, safeArea).map((h) => h.kind)
-    ).toEqual(["inner", "target-terminal"])
+    // Every kept handle sits at least `reserve` along this monotonic edge from either end
+    // (Manhattan distance from the source corner equals path distance here).
+    const total = 140 + 200 + 200
+    for (const h of kept) {
+      const fromSource = h.position.x + h.position.y
+      expect(Math.min(fromSource, total - fromSource)).toBeGreaterThanOrEqual(
+        reserve
+      )
+    }
   })
 
   it("reports the room each handle has, so the renderer can size it", () => {

standalone/webapp/tests/e2e/edge-fresh-bend.spec.ts

@@ -86,6 +86,24 @@ async function drawStraightEdge(page: Page): Promise<Locator> {
  * auto-selects, so its handle is already present — dragging it is the user's
  * "grab the middle and drag" gesture with no separate select-click. Using the
  * handle locator (not the path bbox) stays robust once the edge is bent. */
+/** The centre of a HORIZONTAL bend handle (wider than tall) on the edge — one a
+ * vertical drag actually reshapes. After the edge bends, `.first()` may be a vertical
+ * stub handle a vertical drag cannot move. */
+async function pickHorizontalBendHandle(
+  page: Page,
+  edge: Locator
+): Promise<{ cx: number; cy: number }> {
+  const handles = edge.locator(".edge-bend-handle")
+  const count = await handles.count()
+  for (let i = 0; i < count; i++) {
+    const box = await handles.nth(i).boundingBox()
+    if (box && box.width > box.height) {
+      return { cx: box.x + box.width / 2, cy: box.y + box.height / 2 }
+    }
+  }
+  throw new Error("no horizontal bend handle to drag")
+}
+
 async function dragFirstHandle(
   page: Page,
   edge: Locator,
@@ -202,13 +220,20 @@ test.describe("Fresh-edge first bend — drawn edge", () => {
   }) => {
     const edge = await drawStraightEdge(page)
     const seen: string[] = []
-    // Each drag RESHAPES the bend (all pull the same way, by different amounts).
-    // We deliberately do not drag a bend flat here: once the edge is bent,
-    // `.first()` is the source-TERMINAL handle, and pulling it back across the
-    // straight line legitimately returns a shallow edge to its auto-route
-    // (data.points = []) — a separate gesture, not a snap-back to regress.
-    for (const dy of [-40, -30, -50]) {
-      await dragFirstHandle(page, edge, dy)
+    // The first drag bends the (horizontal) straight edge via its centre handle. Each
+    // FURTHER drag RESHAPES the bend by pulling the top HORIZONTAL segment (a vertical
+    // drag on it moves the lane); we grab a horizontal handle rather than `.first()`,
+    // which after bending is a vertical stub handle a vertical drag cannot move. The
+    // short terminal stubs no longer expose a handle at all — the endpoints own them.
+    await dragFirstHandle(page, edge, -40)
+    seen.push(JSON.stringify(await persistedPoints(page)))
+    for (const dy of [-30, -50]) {
+      const handle = await pickHorizontalBendHandle(page, edge)
+      await page.mouse.move(handle.cx, handle.cy)
+      await page.mouse.down()
+      await page.mouse.move(handle.cx, handle.cy + dy, { steps: 12 })
+      await page.mouse.up()
+      await page.waitForTimeout(350)
       const points = await persistedPoints(page)
       expect(
         isStraightOrEmpty(points),

standalone/webapp/tests/e2e/short-edge-endpoint-handles.spec.ts

@@ -53,3 +53,38 @@ test("a short straight edge keeps usable endpoint grips (not starved by a bend h
     expect(Math.min(hit!.w, hit!.h)).toBeGreaterThanOrEqual(12)
   }
 })
+
+test("a short pinned S-jog edge also keeps usable endpoint grips (no bend handle crowds them)", async ({
+  page,
+}) => {
+  const fx = JSON.parse(
+    fs.readFileSync(
+      path.join(__d, "..", "fixtures", "short-edge-pinned-jog.json"),
+      "utf-8"
+    )
+  )
+  await openFixtureInLocalEditor(page, fx)
+  await waitForCanvasReady(page)
+  await page.waitForTimeout(300)
+  await page.locator(".react-flow__edge").first().click({ force: true })
+  await page.waitForTimeout(300)
+
+  const info = await page.evaluate(() => {
+    const m = (sel: string) => {
+      const el = document.querySelector(sel)
+      if (!el) return null
+      const r = el.getBoundingClientRect()
+      return { w: Math.round(r.width), h: Math.round(r.height) }
+    }
+    return {
+      bendHandles: document.querySelectorAll(".edge-bend-handle").length,
+      sg: m(".edge-endpoint-grip--source"),
+      tg: m(".edge-endpoint-grip--target"),
+    }
+  })
+  // No bend handle crowds this short edge; both grips are visible and usable (was 0px).
+  for (const grip of [info.sg, info.tg]) {
+    expect(grip).not.toBeNull()
+    expect(Math.max(grip!.w, grip!.h)).toBeGreaterThanOrEqual(10)
+  }
+})

standalone/webapp/tests/fixtures/short-edge-pinned-jog.json

@@ -0,0 +1,88 @@
+{
+  "id": "e243b057-3904-4787-9718-2324379be5b4",
+  "version": "4.1.0",
+  "title": "",
+  "type": "ClassDiagram",
+  "nodes": [
+    {
+      "id": "b717899c-aa84-40ba-9cc1-786d722f15c0",
+      "width": 160,
+      "height": 100,
+      "type": "class",
+      "position": {
+        "x": 520,
+        "y": 290
+      },
+      "data": {
+        "name": "Class",
+        "methods": [
+          {
+            "id": "d0fed8cd-8305-4e3c-8b73-958a007fbd5b",
+            "name": "+ method()"
+          }
+        ],
+        "attributes": [
+          {
+            "id": "232bc354-1126-413d-96f0-6e8d4a220e37",
+            "name": "+ attribute: Type"
+          }
+        ]
+      },
+      "measured": {
+        "width": 160,
+        "height": 100
+      }
+    },
+    {
+      "id": "3ece7475-efe8-4097-b9af-2184ac36246e",
+      "width": 160,
+      "height": 100,
+      "type": "class",
+      "position": {
+        "x": 520,
+        "y": 425
+      },
+      "data": {
+        "name": "Class",
+        "methods": [
+          {
+            "id": "44056373-0e97-4003-9b8b-9db813aaaa65",
+            "name": "+ method()"
+          }
+        ],
+        "attributes": [
+          {
+            "id": "ecce6c5d-4ede-4aad-a6d1-65cd1c3a2bfe",
+            "name": "+ attribute: Type"
+          }
+        ]
+      },
+      "measured": {
+        "width": 160,
+        "height": 100
+      }
+    }
+  ],
+  "edges": [
+    {
+      "id": "1b015227-3e36-4ad2-915e-febe1df31335",
+      "source": "b717899c-aa84-40ba-9cc1-786d722f15c0",
+      "target": "3ece7475-efe8-4097-b9af-2184ac36246e",
+      "type": "ClassUnidirectional",
+      "sourceHandle": "bottom",
+      "targetHandle": "top-between-mid-left-center",
+      "data": {
+        "sourceAnchor": {
+          "side": "bottom",
+          "ratio": 0.46875
+        },
+        "targetAnchor": {
+          "side": "top",
+          "ratio": 0.5
+        },
+        "points": []
+      }
+    }
+  ],
+  "assessments": {}
+}