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

120 lines
6.4 KiB
Markdown

# 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
```dart
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
`EdgeLabelBox`es); 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.