Files
pipelines/app/notes/P2-edge.md
T

6.4 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 160 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.

public/P2-edge.patch is the reviewed new-file diff. public/P2-edge-land.patch is the landed git diff main..HEAD, which also carries the landing caption correction and the 160-line trim; it reverse-applies cleanly to the merged tree.

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.
  • Committed, not delivered. The candidate is committed locally on flutter/p2-edge-layer with main merged. Nothing was pushed, deployed or installed.