Compact and harden devtools statecharts

.changeset/quiet-state-charts.md

@@ -0,0 +1,9 @@
+---
+"@typeonce/effect-machine-devtools": patch
+---
+
+Make statecharts denser by flowing states from top to bottom, replacing full initial-entry lanes with compact top-entry markers, and sizing state cards from their visible names and invocations.
+
+State values now appear as compact JSON-shaped type previews in the state inspector instead of occupying the topology. Transition labels sit directly on clear route segments when space permits, hierarchy-crossing routes avoid compound-state headers, and routes attach to their actual source and target before turning. Horizontally scrolling machine tabs also keep their position when selecting or live-reloading a machine.
+
+Charts remain available when every deterministic layout has only cosmetic label-to-route crossings. Structural failures such as detached edges, node crossings, and overlapping routes still prevent rendering.

packages/devtools/README.md

@@ -85,7 +85,7 @@ Run the devtools only against code you trust. The server has no authentication a
 
 ## Inspection and walkthroughs
 
-The visualizer shows topology as a read-only statechart with native horizontal and vertical scrolling, incremental zoom, and a fit-to-viewport overview. Machine tabs run across the top so the chart uses the rest of the viewport. States remain grouped inside their compound parents, while orthogonal routes connect each enabled transition without requiring a draggable canvas. State cards show projected value fields and invocations at a glance. A single click selects a state or transition, while a double click opens its dismissible inspector. State selection distinguishes incoming from outgoing relationships, and conditional branches with the same source and target share one topology edge while retaining their full details in the inspector.
+The visualizer shows topology as a read-only statechart with native horizontal and vertical scrolling, incremental zoom, and a fit-to-viewport overview. Machine tabs run across the top so the chart uses the rest of the viewport. The default flow runs from top to bottom, while parallel regions remain side by side and states stay grouped inside their compound parents. Orthogonal routes connect each enabled transition without requiring a draggable canvas. Compact state cards keep names and invocations visible at a glance; select a state to inspect its projected value fields. A single click selects a state or transition, while a double click opens its dismissible inspector. State selection distinguishes incoming from outgoing relationships, and conditional branches with the same source and target share one topology edge while retaining their full details in the inspector.
 
 The machine document includes projected value and output schemas for every state, plus the public machine and event input contracts. The browser renders those contracts as read-only field metadata: names, projected types, required or optional status, descriptions, ranges, lengths, patterns, and literal or enum values. It never asks for payload values merely to explore a static document.
 

packages/devtools/src/internal/browser/chart-layout-policy.ts

@@ -7,7 +7,7 @@ export interface ChartNodeLayoutPolicy {
   readonly staticPath: boolean
   readonly rank: number | null
   readonly order: number
-  readonly layerConstraint: "LAST" | null
+  readonly layerConstraint: "FIRST" | "LAST" | null
 }
 
 export interface ChartEdgeLayoutPolicy {
@@ -159,17 +159,17 @@ export const makeChartLayoutPolicy = (model: ChartModel): ChartLayoutPolicy => {
         staticPath: staticPaths.has(node.path),
         rank,
         order,
-        layerConstraint: node.type === "final" ? "LAST" : null
+        layerConstraint: rank === 0 ? "FIRST" : node.type === "final" ? "LAST" : null
       })
     })
   }
 
   const edgePolicy = (edge: ChartEdge): ChartEdgeLayoutPolicy => {
     if (edge.kind === "targetless" || edge.target === edge.source) {
-      return { direction: "self", sourceSide: "SOUTH", targetSide: "SOUTH" }
+      return { direction: "self", sourceSide: "EAST", targetSide: "EAST" }
     }
     if (edge.target === null) {
-      return { direction: "forward", sourceSide: "EAST", targetSide: "WEST" }
+      return { direction: "forward", sourceSide: "SOUTH", targetSide: "NORTH" }
     }
 
     const sourceLineage = lineage(edge.source, nodes)
@@ -182,20 +182,25 @@ export const makeChartLayoutPolicy = (model: ChartModel): ChartLayoutPolicy => {
       differentAt++
     }
     if (differentAt === sourceLineage.length) {
-      return { direction: "forward", sourceSide: "EAST", targetSide: "WEST" }
+      return { direction: "forward", sourceSide: "EAST", targetSide: "EAST" }
     }
     if (differentAt === targetLineage.length) {
-      return { direction: "backward", sourceSide: "WEST", targetSide: "EAST" }
+      return { direction: "backward", sourceSide: "WEST", targetSide: "WEST" }
     }
 
     const source = nodePolicies.get(sourceLineage[differentAt]!) ?? unreachableNode
     const target = nodePolicies.get(targetLineage[differentAt]!) ?? unreachableNode
     const backward = source.rank !== null && target.rank !== null
       ? target.rank < source.rank || target.rank === source.rank && target.order < source.order
       : target.order < source.order
+    if (nodes.get(edge.source)?.parent !== nodes.get(edge.target)?.parent) {
+      return backward
+        ? { direction: "backward", sourceSide: "WEST", targetSide: "WEST" }
+        : { direction: "forward", sourceSide: "EAST", targetSide: "EAST" }
+    }
     return backward
-      ? { direction: "backward", sourceSide: "WEST", targetSide: "EAST" }
-      : { direction: "forward", sourceSide: "EAST", targetSide: "WEST" }
+      ? { direction: "backward", sourceSide: "NORTH", targetSide: "SOUTH" }
+      : { direction: "forward", sourceSide: "SOUTH", targetSide: "NORTH" }
   }
 
   return {