Files
pipelines/app/notes/P2-edge.md
T
alan 835f16c0bf feat(app): add passive routed graph edge layer
Paint the landed orthogonal EdgeRoutes on a caller-sized canvas: one polyline
per route, a filled arrow at the target port in the route's real arrival
direction, clipping, and value-based repaint. The layer is pointer transparent
so node widgets below it keep their gestures. Includes focused geometry,
painter and hit-test regressions, an isolated web probe with rendered evidence,
and a note recording the slice and its limits.
2026-10-21 18:31:38 +01:00

6.2 KiB

P2-edge — passive edge layer over landed routing

What changed

App-only, new files. No existing routing, layout, domain, shell, main.dart, pubspec, server, web client or platform source was edited. The Land stage committed the candidate on flutter/p2-edge-layer and merged main.

File Lines Responsibility
lib/features/graph/painting/graph_edge_layer.dart 161 GraphEdgeLayer widget + GraphEdgePainter path/arrow painting
test/features/graph/painting/edge_layer_fixtures.dart 41 hand-built routes and arrival helper for the tests
test/features/graph/painting/graph_edge_geometry_test.dart 240 path and arrow geometry, routed forward/self-loop/cycle edges, a hand-built backward route and an off-port tip case
test/features/graph/painting/graph_edge_layer_test.dart 190 draw calls, clip, hit-test transparency, style colors, repaint rules, widget size
tool/graph_edge_probe.dart 182 isolated browser-capture entry (not wired into the app)

Public API

GraphEdgeLayer(
  routes: List<EdgeRoute>,   // from routing/route_models.dart
  canvasSize: Size,          // graph-space canvas supplied by the caller
  color: Color,              // caller's native outline color
  strokeWidth: double,       // caller's native stroke width
)

GraphEdgePainter is public so a compositor and its tests share the exact geometry through linePath(route) and arrowPath(route).

Behavior

  • Passive and hit-test transparent: a single CustomPaint; no child, gesture, focus, semantics or label text. GraphEdgePainter.hitTest returns false for every point, so the layer never becomes a full-canvas hit sink and siblings below it keep their taps, including with routes: const [] and on a painted stroke. Default CustomPainter.hitTest returns null, which RenderCustomPaint.hitTestSelf treats as a hit; the explicit false is the fix and the regression covers it. Node boxes and measured extents are caller-owned and are never read or changed here.
  • Same coordinates: every RoutePoint is used verbatim. A route with fewer than two points draws nothing. Painting clips to the CustomPaint size.
  • Orthogonal paths: consecutive points are joined with straight segments, so the landed orthogonal routes keep every bend; no smoothing or re-routing.
  • Direction arrows: one filled triangle per route, tip exactly at targetPort.point. The router guarantees points.last == targetPort.point; paint asserts that invariant, while arrowPath reads the tip from the port so a caller-supplied mismatch cannot move the arrow off the port. Direction is the route's last non-degenerate segment, so forward, backward, same-rank and self-loop edges keep their real arrival direction; a degenerate tail falls back to the target port's inward normal.
  • Theme-owned style: the caller supplies color and stroke width; the arrow length is 6x and its half base 2x that stroke width, so it scales with the caller's native thickness. No absolute palette, font or dimension is hard-coded.
  • Repaint: shouldRepaint compares color, stroke width and routes by value (listEquals over EdgeRoute ==), so equal rebuilt lists do not repaint while a moved route, color or stroke change does.

Checks actually run

dart format lib/features/graph/painting test/features/graph/painting tool/graph_edge_probe.dart
flutter test test/features/graph/painting          # 18 passed
flutter test test/features/graph/painting test/features/graph/routing  # 38 passed
flutter test                                       # 466 passed
flutter analyze                                    # No issues found!
flutter build web -t tool/graph_edge_probe.dart -o build/graph_edge_probe
flutter build web                                  # ✓ Built build/web

The hit-test regression was confirmed to fail (taps stayed 0) when hitTest returned true, and pass with the shipped false.

Full new-file diff: public/P2-edge.patch; it applies cleanly to an empty git repo and cmp matches all six worktree files.

Rendered evidence

Three real Chrome captures of the isolated probe build, served from a temporary loopback server on an OS-assigned port with a throwaway profile. No Pipelines server, authentication, production data, device or preview service was touched.

File Bytes Shows
public/graph-edge-layer-web.png 90,739 light theme: three measured cards, Success/Failure terminals, same-rank cycle edges, forward terminal edges and a self-loop
public/graph-edge-layer-web-dark.png 85,431 the same graph in the native dark theme
public/graph-edge-layer-web-same-rank.png 69,601 ?case=same-rank: a two-node cycle, both edges same-rank between distinct nodes

All are 2700x2700 (900x900 CSS at 3x). Arrow tips land on target ports; the layer uses colorScheme.outline and dividerTheme.thickness.

The caption wording was corrected at landing to name the actual routes (same-rank cycle edges, forward terminal edges and a self-loop). Fresh captures of the rebuilt probe are public/land-edge-light.png, public/land-edge-dark.png and public/land-edge-same-rank.png. The earlier public/graph-edge-layer-*.png and public/ui-review-edge-*.png captures predate that text-only correction; their geometry is unchanged and remains valid evidence for the rendered layout.

Honest limits

  • No labels or nodes. Edge labels are deliberately excluded for later native widget composition (the router already returns measured EdgeLabelBoxes); this slice paints no text. The probe's cards are fixture-only, not a node widget and not shell registration.
  • One style per layer. color/strokeWidth are single values; the web run graph's per-outcome colors and dashed/dotted not-executed/fallback styles are not expressible yet. A run-graph compositor will need a per-route style input or several layers.
  • No interaction. Selection, focus, hover and semantics belong to callers. If per-wire hover is added later it needs stroke-only hit testing, not a canvas-wide sink.
  • Browser capture only on web. The probe ran in Chrome; mobile was not built, installed or verified.
  • No commit, push or deployment. The candidate stays in the worktree.