refactor(library): harden routing integration

Author: FelixTJDietrich

.changeset/orthogonal-edge-routing.md

@@ -2,4 +2,4 @@
 "@tumaet/apollon": minor
 ---
 
-Edges now choose sides, ports, and orthogonal routes together to avoid unnecessary corners, crossings, overlaps, and off-centre attachments. Connections spread into balanced grid-aligned gaps, shared pinned junctions keep stable trunks, and required-interface sockets remain concentric and visually separated from neighbouring markers. Endpoint and bend customization stays live without jumping on release, while edge-dense diagrams route in the background to keep dragging responsive. Results remain deterministic across reloads and collaborators, and existing v3 and older v4 diagrams continue to open and upgrade automatically.
+Create cleaner diagrams with automatic edges that balance connection points, reduce collisions with nodes and nearby edges, and stay responsive while you drag, without losing pinned endpoints, hand-placed bends, aligned component interfaces, or compatibility with older diagrams; embedding apps can also normalize diagrams in server-side code through the new `@tumaet/apollon/model` entry.

.github/workflows/pr-health-checks.yml

@@ -393,18 +393,30 @@ jobs:
         run: pnpm --filter @tumaet/apollon run test
 
       - name: Verify ESM exports-map resolution
-        # The library is ESM-only. `import.meta.resolve` (sync, no side
-        # effects) validates every subpath in the exports map — actually
-        # evaluating the module would require jsdom.
+        # The library is ESM-only. `import.meta.resolve` validates every
+        # subpath in the exports map. The model-only entry is intentionally
+        # DOM-free; the follow-up check evaluates its complete runtime graph.
         working-directory: standalone/server
         run: |
           node --input-type=module -e '
             const root = import.meta.resolve("@tumaet/apollon");
             const internals = import.meta.resolve("@tumaet/apollon/internals");
             const exportEntry = import.meta.resolve("@tumaet/apollon/export");
+            const model = import.meta.resolve("@tumaet/apollon/model");
             const css = import.meta.resolve("@tumaet/apollon/style.css");
-            console.log({ root, internals, exportEntry, css });
+            const schema = import.meta.resolve("@tumaet/apollon/schema");
+            const packageJson = import.meta.resolve("@tumaet/apollon/package.json");
+            console.log({
+              root,
+              internals,
+              exportEntry,
+              model,
+              css,
+              schema,
+              packageJson,
+            });
           '
+          node ../../scripts/check-model-entry.mjs
 
       - name: Lint published package shape (publint)
         working-directory: library

docs/library/api/model-contract.md

@@ -97,6 +97,14 @@ import { importDiagram } from "@tumaet/apollon"
 editor.model = importDiagram(maybeV2OrV3Json) // → guaranteed v4
 ```
 
+Server code that only needs to normalize model JSON can use the DOM-free entry:
+
+```ts
+import { importDiagram } from "@tumaet/apollon/model"
+
+export const normalizeDiagram = (data: unknown) => importDiagram(data)
+```
+
 The v2 / v3 detectors and converters live behind `@tumaet/apollon/internals`
 and are **not** part of the stability guarantee — only `importDiagram` is.
 

docs/library/embedding/react.md

@@ -244,9 +244,16 @@ export default function Page() {
 
 Remix and Nuxt have equivalent client-only loading.
 
-`@tumaet/apollon` is a client module in its entirety (`"use client"`), so its
-pure helpers (`importDiagram`, `createApollonTheme`, …) are client-only too —
-import them from client components, not Server Components.
+`@tumaet/apollon` is a client module in its entirety (`"use client"`), so
+import the editor and theme helpers from client components, not Server
+Components. Model migration is the exception: server code can import the
+DOM-free entry directly.
+
+```ts
+import { importDiagram } from "@tumaet/apollon/model"
+
+export const normalizeDiagram = (data: unknown) => importDiagram(data)
+```
 
 Non-React hosts that want imperative control mount `ApollonEditor` directly —
 see [Vanilla JS / CDN](/library/embedding/vanilla).

docs/library/upgrading.md

@@ -66,11 +66,14 @@ to React 19 before upgrading Apollon — on React 18 the install fails with an
 
 ## `"use client"` / RSC
 
-The main entry is now a client module (`"use client"`) in its entirety, so its
-pure helpers (`importDiagram`, `createApollonTheme`, …) are client-only too.
-React Server Components must treat `@tumaet/apollon` as client-only: import it
-from client components, not Server Components. See
-[SSR](/library/embedding/react#ssr-nextjs-remix-nuxt-sveltekit).
+The main entry is now a client module (`"use client"`) in its entirety. React
+Server Components must therefore treat `@tumaet/apollon` as client-only and
+import it from client components, not Server Components.
+
+Model migration is also available from the DOM-free
+`@tumaet/apollon/model` entry. Server code that only needs to normalize a
+diagram can import `importDiagram` from that subpath without loading the
+editor. See [SSR](/library/embedding/react#ssr-nextjs-remix-nuxt-sveltekit).
 
 ## Removed deep imports (CDN caveat)
 

library/lib/components/toolbars/NodeToolbar.tsx

@@ -30,15 +30,12 @@ export const NodeToolbar: FC<Props> = ({ elementId, showEdit = true }) => {
       align="end"
       offset={10}
       className="apollon-element-toolbar-host"
-      style={{ pointerEvents: "none" }}
     >
       <ButtonGroup
         aria-label={t.selectionActions}
         orientation="vertical"
         className="apollon-element-toolbar nodrag nopan"
         onPointerDownCapture={(event) => event.stopPropagation()}
-        onMouseDownCapture={(event) => event.stopPropagation()}
-        onTouchStartCapture={(event) => event.stopPropagation()}
       >
         <IconButton
           ariaLabel={t.deleteElement}

library/lib/edges/GenericEdge.tsx

@@ -278,8 +278,6 @@ export const EdgeEndpointMarkers = ({
   onEndpointPointerDown,
   straight = false,
   bendHandles,
-  sourcePinned = false,
-  targetPinned = false,
 }: {
   sourcePoint: IPoint
   targetPoint: IPoint
@@ -297,11 +295,6 @@ export const EdgeEndpointMarkers = ({
   // The edge's bend handles, so a reconnect target can cap its outward reach at
   // this end's terminal bend handle instead of painting over it.
   bendHandles?: BendHandle[]
-  // Whether each end is USER-PINNED (a custom anchor) rather than auto-anchored.
-  // Kept as a prop/class for the reset affordance and tests; the grip itself looks the
-  // same either way (a clean white handle), so nothing clutters the endpoint.
-  sourcePinned?: boolean
-  targetPinned?: boolean
 }) => {
   const screenScale = useHandleScreenScale()
 
@@ -385,9 +378,7 @@ export const EdgeEndpointMarkers = ({
       {showEndpointGrips && (
         <>
           <rect
-            className={`edge-circle edge-endpoint-grip edge-endpoint-grip--source${
-              sourcePinned ? " edge-endpoint-grip--pinned" : ""
-            }`}
+            className="edge-circle edge-endpoint-grip edge-endpoint-grip--source"
             x={sourceGrip.x}
             y={sourceGrip.y}
             width={sourceGrip.width}
@@ -399,9 +390,7 @@ export const EdgeEndpointMarkers = ({
             pointerEvents="none"
           />
           <rect
-            className={`edge-circle edge-endpoint-grip edge-endpoint-grip--target${
-              targetPinned ? " edge-endpoint-grip--pinned" : ""
-            }`}
+            className="edge-circle edge-endpoint-grip edge-endpoint-grip--target"
             x={targetGrip.x}
             y={targetGrip.y}
             width={targetGrip.width}
@@ -568,19 +557,6 @@ export const StepEdgeBody = ({
   ) => void
   children?: ReactNode
 }) => {
-  // Which ends the user has PINNED (a custom anchor) vs left to the router. Two
-  // boolean selectors (not one object) so equality stays primitive and the edge
-  // only re-renders when a pin actually flips. Drives the filled "anchored" grip.
-  const sourcePinned = useDiagramStore((state) =>
-    isFreeformEdgeAnchor(
-      state.edges.find((edge) => edge.id === id)?.data?.sourceAnchor
-    )
-  )
-  const targetPinned = useDiagramStore((state) =>
-    isFreeformEdgeAnchor(
-      state.edges.find((edge) => edge.id === id)?.data?.targetAnchor
-    )
-  )
   return (
     <g className="edge-container">
       <BaseEdge
@@ -656,8 +632,6 @@ export const StepEdgeBody = ({
         canEditEndpoint={canEditEndpoint}
         onEndpointPointerDown={handleEndpointPointerDown}
         bendHandles={bendHandles}
-        sourcePinned={sourcePinned}
-        targetPinned={targetPinned}
       />
 
       {children}
@@ -667,6 +641,7 @@ export const StepEdgeBody = ({
 
 export const CommonEdgeElements = ({
   id,
+  data,
   pathMiddlePosition,
   toolbarPosition,
   isDiagramModifiable,
@@ -676,6 +651,7 @@ export const CommonEdgeElements = ({
   type,
 }: {
   id: string
+  data: BaseEdgeProps["data"]
   pathMiddlePosition: IPoint
   toolbarPosition?: IPoint
   isDiagramModifiable: boolean
@@ -691,15 +667,12 @@ export const CommonEdgeElements = ({
   const [anchorEl, anchorRef] = usePopoverAnchor<HTMLDivElement>()
 
   const setEdges = useDiagramStore((state) => state.setEdges)
-  const hasManualRoute = useDiagramStore((state) => {
-    const data = state.edges.find((edge) => edge.id === id)?.data
-    const points = data?.points
-    const hasManualPoints = Array.isArray(points) && points.length > 0
-    const hasPinnedAnchor =
-      isFreeformEdgeAnchor(data?.sourceAnchor) ||
-      isFreeformEdgeAnchor(data?.targetAnchor)
-    return hasManualPoints || hasPinnedAnchor
-  })
+  const points = data?.points
+  const hasManualPoints = Array.isArray(points) && points.length > 0
+  const hasPinnedAnchor =
+    isFreeformEdgeAnchor(data?.sourceAnchor) ||
+    isFreeformEdgeAnchor(data?.targetAnchor)
+  const hasManualRoute = hasManualPoints || hasPinnedAnchor
 
   const handleResetRouting = useCallback(() => {
     setEdges((edges) =>

library/lib/edges/edgeTypes/ActivityDiagramEdge.tsx

@@ -120,6 +120,7 @@ export const ActivityDiagramEdge = ({
 
         <CommonEdgeElements
           id={id}
+          data={data}
           pathMiddlePosition={edgeData.pathMiddlePosition}
           toolbarPosition={edgeData.toolbarPosition}
           isDiagramModifiable={isDiagramModifiable}

library/lib/edges/edgeTypes/BPMNDiagramEdge.tsx

@@ -128,6 +128,7 @@ export const BPMNDiagramEdge = ({
 
         <CommonEdgeElements
           id={id}
+          data={data}
           pathMiddlePosition={edgeData.pathMiddlePosition}
           toolbarPosition={edgeData.toolbarPosition}
           isDiagramModifiable={isDiagramModifiable}

library/lib/edges/edgeTypes/ClassDiagramEdge.tsx

@@ -132,6 +132,7 @@ export const ClassDiagramEdge = ({
 
         <CommonEdgeElements
           id={id}
+          data={data}
           pathMiddlePosition={edgeData.pathMiddlePosition}
           toolbarPosition={edgeData.toolbarPosition}
           isDiagramModifiable={isDiagramModifiable}