120 lines
6.4 KiB
Markdown
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.
|