feat(library): improve automatic edge routing (#826)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: 3 people

.changeset/clear-signs-live.md

@@ -0,0 +1,5 @@
+---
+"@tumaet/webapp": patch
+---
+
+Start every bundled design-pattern template in a clean, visually balanced editing state, with stable shared hierarchy trunks and automatic routing preserved for associations.

.changeset/orthogonal-edge-routing.md

@@ -0,0 +1,5 @@
+---
+"@tumaet/apollon": minor
+---
+
+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)
 

knip.json

@@ -3,7 +3,12 @@
   "ignoreExportsUsedInFile": true,
   "workspaces": {
     "library": {
-      "entry": ["lib/index.tsx", "lib/internals.ts", "lib/export/index.ts"],
+      "entry": [
+        "lib/index.tsx",
+        "lib/internals.ts",
+        "lib/export/index.ts",
+        "lib/model.ts"
+      ],
       "project": ["lib/**/*.{ts,tsx}"],
       "ignoreBinaries": ["build", "run"]
     },
@@ -28,7 +33,6 @@
       "ignoreDependencies": [
         "@capacitor/file-transfer",
         "@capacitor/splash-screen",
-        "@capacitor/android",
         "tailwindcss",
         "jspdf",
         "svg2pdf.js",

library/lib/App.tsx

@@ -3,16 +3,20 @@ import {
   ReactFlowInstance,
   ConnectionMode,
   ReactFlow,
-  type Edge,
 } from "@xyflow/react"
-import { type MouseEvent as ReactMouseEvent, useCallback } from "react"
+import { useCallback } from "react"
 import {
   CustomBackground,
-  ReconnectConnectionLine,
   AssessmentSelectionDebug,
   ScrollOverlay,
   AlignmentGuides,
 } from "@/components"
+// Imported DIRECTLY, not via the `@/components` barrel: this component pulls in the
+// edge-geometry solver to preview the committed auto route, and the barrel is
+// imported by `constants.ts`, so routing it through the barrel forms a
+// `constants → components → solver → edgeAnchoring` import cycle that leaves module
+// constants undefined at init. The direct path keeps the solver out of the barrel.
+import { ConnectionPreviewLine } from "@/components/ConnectionPreviewLine"
 import { OverlayLayer } from "@/overlay/OverlayLayer"
 import "@xyflow/react/dist/style.css"
 // Shared, embed-safe @tumaet/ui primitives + --apollon-/--home- design tokens
@@ -26,6 +30,7 @@ import "@/styles/fonts.css"
 import "@/styles/app.css"
 import {
   useDiagramStore,
+  useEdgeGeometryStore,
   useMetadataStore,
   useOverlayStore,
 } from "./store/context"
@@ -36,7 +41,6 @@ import { diagramEdgeTypes } from "./edges"
 import {
   useNodeDragStop,
   useConnect,
-  useReconnect,
   useElementInteractions,
   useDragOver,
   useNodeDrag,
@@ -50,37 +54,30 @@ import {
   useRemoteDraggingNodes,
   applyDraggingOverlay,
 } from "./hooks/useRemoteDraggingNodes"
-import {
-  getConnectionLineType,
-  resolveReconnectPreviewBasePoints,
-} from "./utils/edgeUtils"
-import { IPoint } from "./edges/Connection"
+import { getConnectionLineType } from "./utils/edgeUtils"
 import {
   CollaborationLayer,
   type CollaborationAwarenessApi,
   type CollaborationLayerOptions,
 } from "@/components/collaboration/CollaborationLayer"
 import { TooltipProvider } from "@/components/ui"
+import { EdgeGeometrySolver } from "@/components/EdgeGeometrySolver"
 
 interface AppProps {
   onReactFlowInit: (instance: ReactFlowInstance) => void
   collaboration: CollaborationLayerOptions
   awareness: CollaborationAwarenessApi
+  /** Disabled by the off-screen export mount, which must materialize the whole
+   * model regardless of its synthetic viewport. */
+  onlyRenderVisibleElements?: boolean
 }
 const proOptions = { hideAttribution: true }
-const isPointArray = (value: unknown): value is IPoint[] =>
-  Array.isArray(value) &&
-  value.every(
-    (point) =>
-      typeof point === "object" &&
-      point !== null &&
-      "x" in point &&
-      "y" in point &&
-      typeof point.x === "number" &&
-      typeof point.y === "number"
-  )
-
-function App({ onReactFlowInit, collaboration, awareness }: AppProps) {
+function App({
+  onReactFlowInit,
+  collaboration,
+  awareness,
+  onlyRenderVisibleElements = true,
+}: AppProps) {
   useKeyboardShortcuts()
 
   const { nodes, onNodesChange, edges, onEdgesChange, diagramId, previewMode } =
@@ -102,8 +99,6 @@ function App({ onReactFlowInit, collaboration, awareness }: AppProps) {
     scrollEnabled,
     keyboardShortcuts,
     connectionGuidanceActive,
-    startReconnectPreview,
-    stopReconnectPreview,
   } = useMetadataStore(
     useShallow((state) => ({
       diagramType: state.diagramType,
@@ -112,8 +107,6 @@ function App({ onReactFlowInit, collaboration, awareness }: AppProps) {
       scrollEnabled: state.scrollEnabled,
       keyboardShortcuts: state.keyboardShortcuts,
       connectionGuidanceActive: state.connectionGuidanceActive,
-      startReconnectPreview: state.startReconnectPreview,
-      stopReconnectPreview: state.stopReconnectPreview,
     }))
   )
 
@@ -143,11 +136,11 @@ function App({ onReactFlowInit, collaboration, awareness }: AppProps) {
   const onDragOver = useDragOver()
   const { onConnect, onConnectEnd, onConnectStart, onEdgesDelete } =
     useConnect()
-  const onReconnect = useReconnect()
   const { onBeforeDelete, onNodeDoubleClick, onEdgeDoubleClick } =
     useElementInteractions()
   const { onPaneClicked } = usePaneClicked()
   const multiSelectionMode = useMultiSelectionMode()
+  const routingReady = useEdgeGeometryStore((state) => state.routingReady)
 
   const handleReactFlowInit = useCallback(
     (instance: ReactFlowInstance) => {
@@ -156,25 +149,6 @@ function App({ onReactFlowInit, collaboration, awareness }: AppProps) {
     [onReactFlowInit]
   )
 
-  const handleReconnectStart = useCallback(
-    (_event: ReactMouseEvent, edge: Edge, handleType: "source" | "target") => {
-      const storedPoints = isPointArray(edge.data?.points)
-        ? edge.data.points
-        : undefined
-
-      startReconnectPreview(
-        edge.id,
-        handleType,
-        resolveReconnectPreviewBasePoints(storedPoints, undefined, [])
-      )
-    },
-    [startReconnectPreview]
-  )
-
-  const handleReconnectEnd = useCallback(() => {
-    stopReconnectPreview()
-  }, [stopReconnectPreview])
-
   return (
     <TooltipProvider>
       <div
@@ -205,7 +179,20 @@ function App({ onReactFlowInit, collaboration, awareness }: AppProps) {
             nodeTypes={diagramNodeTypes}
             edgeTypes={diagramEdgeTypes}
             nodes={displayNodes}
-            edges={edges}
+            // The solver reads DiagramStore directly. Keep provisional React
+            // Flow edges unmounted until this model's first exact generation;
+            // nodes still mount below so their runtime handles can be measured.
+            edges={routingReady ? edges : []}
+            // React Flow's viewport culling keeps large off-screen diagrams out
+            // of the DOM while the central solver still optimizes every edge.
+            // This is purely a rendering boundary: export and exact geometry
+            // continue to use the complete diagram.
+            // Bootstrap one complete measurement pass before enabling viewport
+            // culling. Otherwise off-screen nodes never mount their handles and
+            // the holistic router cannot produce a stable first generation.
+            onlyRenderVisibleElements={
+              routingReady ? onlyRenderVisibleElements : false
+            }
             onDragOver={onDragOver}
             onNodesChange={onNodesChange}
             onEdgesChange={onEdgesChange}
@@ -216,11 +203,8 @@ function App({ onReactFlowInit, collaboration, awareness }: AppProps) {
             zoomOnDoubleClick={false}
             onNodeDrag={onNodeDrag}
             onNodeDragStop={onNodeDragStop}
-            onReconnect={onReconnect}
-            onReconnectStart={handleReconnectStart}
-            onReconnectEnd={handleReconnectEnd}
             connectionLineType={connectionLineType}
-            connectionLineComponent={ReconnectConnectionLine}
+            connectionLineComponent={ConnectionPreviewLine}
             connectionMode={ConnectionMode.Loose}
             // Lift the selected edge (and its bend/endpoint handles) above other
             // edges so an overlapping edge's interaction ribbon can't steal the
@@ -244,7 +228,7 @@ function App({ onReactFlowInit, collaboration, awareness }: AppProps) {
             onBeforeDelete={onBeforeDelete}
             onPaneClick={onPaneClicked}
             proOptions={proOptions}
-            edgesReconnectable={isDiagramModifiable}
+            edgesReconnectable={false}
             nodesConnectable={isDiagramModifiable}
             nodesDraggable={isDiagramModifiable}
             panOnScroll={!scrollLock || scrollEnabled}
@@ -278,6 +262,7 @@ function App({ onReactFlowInit, collaboration, awareness }: AppProps) {
             <CustomBackground />
             <AlignmentGuides />
             <AssessmentSelectionDebug />
+            <EdgeGeometrySolver />
             {/* Renders every registered control (built-in + host-injected) into
                 its region: header, rails, corners, on-canvas. The chrome itself is
                 registered at construction (imperative) or by the React wrapper. */}