From 835f16c0bf7aa45b2b273dc73b56050c6a441944 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Wed, 21 Oct 2026 18:31:38 +0100 Subject: [PATCH 1/5] 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. --- .../graph/painting/graph_edge_layer.dart | 161 ++++++++++++ app/notes/P2-edge.md | 116 +++++++++ .../graph/painting/edge_layer_fixtures.dart | 41 +++ .../painting/graph_edge_geometry_test.dart | 240 ++++++++++++++++++ .../graph/painting/graph_edge_layer_test.dart | 190 ++++++++++++++ app/tool/graph_edge_probe.dart | 182 +++++++++++++ 6 files changed, 930 insertions(+) create mode 100644 app/lib/features/graph/painting/graph_edge_layer.dart create mode 100644 app/notes/P2-edge.md create mode 100644 app/test/features/graph/painting/edge_layer_fixtures.dart create mode 100644 app/test/features/graph/painting/graph_edge_geometry_test.dart create mode 100644 app/test/features/graph/painting/graph_edge_layer_test.dart create mode 100644 app/tool/graph_edge_probe.dart diff --git a/app/lib/features/graph/painting/graph_edge_layer.dart b/app/lib/features/graph/painting/graph_edge_layer.dart new file mode 100644 index 00000000..418eb492 --- /dev/null +++ b/app/lib/features/graph/painting/graph_edge_layer.dart @@ -0,0 +1,161 @@ +import 'package:flutter/foundation.dart' show listEquals; +import 'package:flutter/material.dart'; + +import '../routing/route_models.dart'; + +/// A passive canvas for already-routed graph edges. +/// +/// Paints exactly the supplied [routes] at their graph coordinates on a +/// [canvasSize] canvas. The caller owns every measurement: routes come from the +/// routing library, and [color] plus [strokeWidth] come from its native theme. +/// No node is invented or resized and no layout runs here. +/// +/// The layer is transparent to pointer input: it covers the canvas but never +/// takes a hit, so node buttons, labels and other siblings keep their own +/// gestures. Labels are composed separately as native widgets; this layer never +/// paints text and never handles pointer, focus or semantics input. +class GraphEdgeLayer extends StatelessWidget { + const GraphEdgeLayer({ + super.key, + required this.routes, + required this.canvasSize, + required this.color, + required this.strokeWidth, + }) : assert(strokeWidth > 0); + + /// Orthogonal routes in graph space, with each arrow entering its target port. + final List routes; + + /// The graph-space canvas the caller reserved for the drawing. + final Size canvasSize; + + /// The caller's native edge/label color. + final Color color; + + /// The caller's native stroke width; the arrow scales with it. + final double strokeWidth; + + @override + Widget build(BuildContext context) { + return CustomPaint( + size: canvasSize, + painter: GraphEdgePainter( + routes: routes, + color: color, + strokeWidth: strokeWidth, + ), + ); + } +} + +/// Paints [GraphEdgeLayer] routes as a polyline plus a filled direction arrow. +/// +/// The painter is public so a renderer and its tests share the exact path and +/// arrow geometry. It clips to the size `CustomPaint` supplies and reports every +/// point as a miss, matching the layer's passive contract. +class GraphEdgePainter extends CustomPainter { + GraphEdgePainter({ + required this.routes, + required this.color, + required this.strokeWidth, + }) : assert(strokeWidth > 0), + _line = Paint() + ..color = color + ..strokeWidth = strokeWidth + ..style = PaintingStyle.stroke + ..strokeJoin = StrokeJoin.round, + _arrow = Paint() + ..color = color + ..style = PaintingStyle.fill; + + final List routes; + final Color color; + final double strokeWidth; + final Paint _line; + final Paint _arrow; + + /// Arrow length and half base width, as multiples of the caller's stroke. + static const double _arrowLength = 6; + static const double _arrowHalfWidth = 2; + + @override + void paint(Canvas canvas, Size size) { + if (routes.isEmpty) return; + canvas.save(); + canvas.clipRect(Offset.zero & size); + for (final route in routes) { + if (route.points.length < 2) continue; + assert( + route.points.last == route.targetPort.point, + 'EdgeRoute ${route.id} must end at its target port; the router ' + 'guarantees points.last == targetPort.point.', + ); + canvas.drawPath(linePath(route), _line); + } + for (final route in routes) { + if (route.points.length < 2) continue; + canvas.drawPath(arrowPath(route), _arrow); + } + canvas.restore(); + } + + /// The orthogonally joined polyline for [route], in painter coordinates. + Path linePath(EdgeRoute route) { + final path = Path(); + final points = route.points; + if (points.isEmpty) return path; + path.moveTo(points.first.x, points.first.y); + for (var index = 1; index < points.length; index += 1) { + path.lineTo(points[index].x, points[index].y); + } + return path; + } + + /// A filled triangle whose tip is exactly [EdgeRoute.targetPort]. + /// + /// The direction follows the route's last segment, so forward, backward, + /// same-rank and self-loop edges keep their honest arrival direction. A + /// degenerate tail falls back to the target port's inward normal. + Path arrowPath(EdgeRoute route) { + final points = route.points; + if (points.length < 2) return Path(); + final tip = Offset(route.targetPort.point.x, route.targetPort.point.y); + final direction = _arrivalDirection(route); + final length = strokeWidth * _arrowLength; + final halfWidth = strokeWidth * _arrowHalfWidth; + final baseX = tip.dx - direction.dx * length; + final baseY = tip.dy - direction.dy * length; + final normalX = -direction.dy * halfWidth; + final normalY = direction.dx * halfWidth; + return Path() + ..moveTo(tip.dx, tip.dy) + ..lineTo(baseX + normalX, baseY + normalY) + ..lineTo(baseX - normalX, baseY - normalY) + ..close(); + } + + Offset _arrivalDirection(EdgeRoute route) { + final tip = route.targetPort.point; + for (var index = route.points.length - 1; index >= 0; index -= 1) { + final point = route.points[index]; + final delta = Offset(tip.x - point.x, tip.y - point.y); + if (delta != Offset.zero) return delta / delta.distance; + } + return switch (route.targetPort.side) { + RoutePortSide.top => const Offset(0, 1), + RoutePortSide.right => const Offset(-1, 0), + RoutePortSide.bottom => const Offset(0, -1), + RoutePortSide.left => const Offset(1, 0), + }; + } + + /// The layer is passive: every point misses so siblings keep their gestures. + @override + bool hitTest(Offset position) => false; + + @override + bool shouldRepaint(GraphEdgePainter oldDelegate) => + oldDelegate.color != color || + oldDelegate.strokeWidth != strokeWidth || + !listEquals(oldDelegate.routes, routes); +} diff --git a/app/notes/P2-edge.md b/app/notes/P2-edge.md new file mode 100644 index 00000000..7e02849d --- /dev/null +++ b/app/notes/P2-edge.md @@ -0,0 +1,116 @@ +# 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 + +```dart +GraphEdgeLayer( + routes: List, // 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 + `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. +- **No commit, push or deployment.** The candidate stays in the worktree. diff --git a/app/test/features/graph/painting/edge_layer_fixtures.dart b/app/test/features/graph/painting/edge_layer_fixtures.dart new file mode 100644 index 00000000..50cc9d00 --- /dev/null +++ b/app/test/features/graph/painting/edge_layer_fixtures.dart @@ -0,0 +1,41 @@ +import 'package:flutter/material.dart'; +import 'package:pipelines_app/features/graph/routing/route_models.dart'; + +/// Shared hand-built routes for the edge-layer painting tests. + +EdgeRoute edgeRoute({ + required List points, + RouteKind kind = RouteKind.forward, + RoutePortSide targetSide = RoutePortSide.left, + double portX = 0, + double portY = 0, +}) { + final start = points.isEmpty ? RoutePoint(portX, portY) : points.first; + final end = points.isEmpty ? RoutePoint(portX, portY) : points.last; + return EdgeRoute( + id: 1, + source: 'a', + outcome: 'success', + target: 'b', + label: 'success', + fallback: false, + kind: kind, + straight: false, + sourcePort: RoutePort(side: RoutePortSide.right, point: start), + targetPort: RoutePort(side: targetSide, point: end), + points: points, + ); +} + +Offset routeOffset(RoutePoint point) => Offset(point.x, point.y); + +/// The direction of the route's last non-degenerate segment. +Offset arrival(EdgeRoute route) { + final points = route.points; + final end = points.last; + for (var index = points.length - 2; index >= 0; index -= 1) { + final delta = Offset(end.x - points[index].x, end.y - points[index].y); + if (delta != Offset.zero) return delta / delta.distance; + } + return Offset.zero; +} diff --git a/app/test/features/graph/painting/graph_edge_geometry_test.dart b/app/test/features/graph/painting/graph_edge_geometry_test.dart new file mode 100644 index 00000000..18ef42de --- /dev/null +++ b/app/test/features/graph/painting/graph_edge_geometry_test.dart @@ -0,0 +1,240 @@ +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/features/graph/painting/graph_edge_layer.dart'; +import 'package:pipelines_app/features/graph/routing/route_models.dart'; + +import '../routing/routing_fixtures.dart'; +import 'edge_layer_fixtures.dart'; + +void main() { + const color = Colors.black87; + final straight = edgeRoute( + points: const [RoutePoint(10, 20), RoutePoint(90, 20)], + ); + final wrapping = edgeRoute( + points: const [ + RoutePoint(10, 20), + RoutePoint(40, 20), + RoutePoint(40, 60), + RoutePoint(80, 60), + RoutePoint(80, 50), + ], + ); + + group('path', () { + test('keeps every orthogonal vertex of the supplied route', () { + final painter = GraphEdgePainter( + routes: [wrapping], + color: color, + strokeWidth: 2, + ); + final path = painter.linePath(wrapping); + final metric = path.computeMetrics().single; + expect(metric.length, closeTo(30 + 40 + 40 + 10, 0.001)); + expect( + metric.getTangentForOffset(0)!.position, + routeOffset(wrapping.points.first), + ); + expect( + metric.getTangentForOffset(metric.length)!.position, + routeOffset(wrapping.points.last), + ); + expect(path.getBounds(), const Rect.fromLTRB(10, 20, 80, 60)); + }); + + test('a straight route is the exact port-to-port segment', () { + final painter = GraphEdgePainter( + routes: [straight], + color: color, + strokeWidth: 1, + ); + final metric = painter.linePath(straight).computeMetrics().single; + expect(metric.length, 80); + expect(metric.getTangentForOffset(40)!.vector, const Offset(1, 0)); + }); + + test('zero- and one-point routes produce an empty path', () { + final painter = GraphEdgePainter( + routes: const [], + color: color, + strokeWidth: 1, + ); + final empty = edgeRoute(points: const []); + final single = edgeRoute(points: const [RoutePoint(5, 5)]); + for (final route in [empty, single]) { + final path = painter.linePath(route); + expect(path.getBounds().isEmpty, isTrue); + expect(path.computeMetrics().isEmpty, isTrue); + } + }); + }); + + group('arrow', () { + test('points into a forward target port', () { + final painter = GraphEdgePainter( + routes: [straight], + color: color, + strokeWidth: 2, + ); + final arrow = painter.arrowPath(straight); + final tip = routeOffset(straight.points.last); + expect( + arrow.computeMetrics().first.getTangentForOffset(0)!.position, + tip, + ); + // 12 long and 8 wide for a 2px stroke, pointing right. + expect(arrow.getBounds(), const Rect.fromLTRB(78, 16, 90, 24)); + expect(arrow.contains(tip.translate(-5, 0)), isTrue); + expect(arrow.contains(tip.translate(2, 0)), isFalse); + expect(arrow.contains(tip.translate(-14, 0)), isFalse); + }); + + test('follows self-loop arrival instead of assuming a rightward edge', () { + final routing = routeFor(selfLoopGraphFixture()); + final loop = routing.routes.singleWhere( + (route) => route.kind == RouteKind.selfLoop, + ); + final painter = GraphEdgePainter( + routes: routing.routes, + color: color, + strokeWidth: 2, + ); + final direction = arrival(loop); + final tip = routeOffset(loop.points.last); + final arrow = painter.arrowPath(loop); + + expect(loop.targetPort.side, RoutePortSide.right); + expect(direction.dx, -1); + expect(arrow.getBounds().left, tip.dx); + expect(arrow.contains(tip.translate(5, 0)), isTrue); + expect(arrow.contains(tip.translate(-2, 0)), isFalse); + }); + + test('a backward route keeps its leftward arrival into a right port', () { + final back = edgeRoute( + kind: RouteKind.back, + targetSide: RoutePortSide.right, + points: const [ + RoutePoint(120, 20), + RoutePoint(140, 20), + RoutePoint(140, 60), + RoutePoint(80, 60), + ], + ); + final painter = GraphEdgePainter( + routes: [back], + color: color, + strokeWidth: 2, + ); + final arrow = painter.arrowPath(back); + final tip = routeOffset(back.points.last); + + expect(back.kind, RouteKind.back); + expect(arrow.getBounds().left, tip.dx); + expect(arrow.contains(tip.translate(5, 0)), isTrue); + expect(arrow.contains(tip.translate(-2, 0)), isFalse); + }); + + test('keeps the routed arrival direction for every cycle edge', () { + final routing = routeFor(cycleGraphFixture()); + final painter = GraphEdgePainter( + routes: routing.routes, + color: color, + strokeWidth: 2, + ); + expect(routing.routes, isNotEmpty); + for (final route in routing.routes) { + final direction = arrival(route); + final tip = routeOffset(route.points.last); + final arrow = painter.arrowPath(route); + expect( + arrow.computeMetrics().first.getTangentForOffset(0)!.position, + tip, + ); + expect(arrow.contains(tip - direction * 5), isTrue); + expect(arrow.contains(tip + direction * 2), isFalse); + } + }); + + test('a routed forward edge ends exactly at its target port', () { + final routing = routeFor(chainGraphFixture()); + final painter = GraphEdgePainter( + routes: routing.routes, + color: color, + strokeWidth: 2, + ); + expect(routing.routes, isNotEmpty); + for (final route in routing.routes) { + expect(route.points.last, route.targetPort.point); + final arrow = painter.arrowPath(route); + expect( + arrow.computeMetrics().first.getTangentForOffset(0)!.position, + routeOffset(route.targetPort.point), + ); + } + }); + + test('anchors the tip at the target port, not the last route point', () { + final route = EdgeRoute( + id: 7, + source: 'a', + outcome: 'success', + target: 'b', + label: 'success', + fallback: false, + kind: RouteKind.forward, + straight: true, + sourcePort: const RoutePort( + side: RoutePortSide.right, + point: RoutePoint(10, 20), + ), + targetPort: const RoutePort( + side: RoutePortSide.left, + point: RoutePoint(85, 20), + ), + points: const [RoutePoint(10, 20), RoutePoint(80, 20)], + ); + final arrow = GraphEdgePainter( + routes: [route], + color: color, + strokeWidth: 2, + ).arrowPath(route); + expect( + arrow.computeMetrics().first.getTangentForOffset(0)!.position, + const Offset(85, 20), + ); + }); + + test('scales with the caller stroke width', () { + final small = GraphEdgePainter( + routes: [straight], + color: color, + strokeWidth: 1, + ).arrowPath(straight); + final large = GraphEdgePainter( + routes: [straight], + color: color, + strokeWidth: 4, + ).arrowPath(straight); + expect(small.getBounds().width, 6); + expect(small.getBounds().height, 4); + expect(large.getBounds().width, 24); + expect(large.getBounds().height, 16); + }); + + test('falls back to the port inward normal for a degenerate tail', () { + final route = edgeRoute( + points: const [RoutePoint(50, 50), RoutePoint(50, 50)], + targetSide: RoutePortSide.top, + ); + final arrow = GraphEdgePainter( + routes: [route], + color: color, + strokeWidth: 2, + ).arrowPath(route); + final tip = routeOffset(route.points.last); + expect(arrow.getBounds(), const Rect.fromLTRB(46, 38, 54, 50)); + expect(arrow.contains(tip.translate(0, -5)), isTrue); + }); + }); +} diff --git a/app/test/features/graph/painting/graph_edge_layer_test.dart b/app/test/features/graph/painting/graph_edge_layer_test.dart new file mode 100644 index 00000000..aa46bfad --- /dev/null +++ b/app/test/features/graph/painting/graph_edge_layer_test.dart @@ -0,0 +1,190 @@ +import 'dart:ui' as ui; + +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/features/graph/painting/graph_edge_layer.dart'; +import 'package:pipelines_app/features/graph/routing/route_models.dart'; + +import 'edge_layer_fixtures.dart'; + +void main() { + const color = Colors.black87; + final straight = edgeRoute( + points: const [RoutePoint(10, 20), RoutePoint(90, 20)], + ); + final wrapping = edgeRoute( + points: const [ + RoutePoint(10, 20), + RoutePoint(40, 20), + RoutePoint(40, 60), + RoutePoint(80, 60), + RoutePoint(80, 50), + ], + ); + + test('draws one stroke and one filled arrow per route, clipped', () { + final canvas = TestRecordingCanvas(); + GraphEdgePainter( + routes: [straight, wrapping], + color: color, + strokeWidth: 2, + ).paint(canvas, const Size(120, 80)); + + final calls = canvas.invocations + .where((call) => call.invocation.memberName == #drawPath) + .toList(); + expect(calls.length, 4); + final paints = [ + for (final call in calls) + call.invocation.positionalArguments.last as Paint, + ]; + expect(paints[0].style, PaintingStyle.stroke); + expect(paints[1].style, PaintingStyle.stroke); + expect(paints[2].style, PaintingStyle.fill); + expect(paints[3].style, PaintingStyle.fill); + expect( + paints.every((paint) => paint.color.toARGB32() == color.toARGB32()), + isTrue, + ); + + final clip = canvas.invocations.singleWhere( + (call) => call.invocation.memberName == #clipRect, + ); + expect( + clip.invocation.positionalArguments.first, + const Rect.fromLTWH(0, 0, 120, 80), + ); + }); + + test('paints nothing for an empty route list', () { + final canvas = TestRecordingCanvas(); + GraphEdgePainter( + routes: const [], + color: color, + strokeWidth: 2, + ).paint(canvas, const Size(120, 80)); + expect(canvas.invocations, isEmpty); + }); + + test('reports every canvas point as a miss', () { + final painter = GraphEdgePainter( + routes: [straight], + color: color, + strokeWidth: 2, + ); + expect(painter.hitTest(const Offset(50, 20)), isFalse); + expect(painter.hitTest(const Offset(500, 500)), isFalse); + }); + + testWidgets('clips painted geometry to the canvas bounds', (tester) async { + final recorder = ui.PictureRecorder(); + GraphEdgePainter( + routes: [ + edgeRoute(points: const [RoutePoint(-30, 10), RoutePoint(60, 10)]), + ], + color: Colors.black, + strokeWidth: 6, + ).paint(Canvas(recorder), const Size(20, 20)); + final data = await tester.runAsync(() async { + final image = await recorder.endRecording().toImage(80, 40); + final bytes = await image.toByteData(format: ui.ImageByteFormat.rawRgba); + image.dispose(); + return bytes; + }); + expect(data, isNotNull); + final bytes = data!.buffer.asUint8List(); + int alphaAt(int x, int y) => bytes[(y * 80 + x) * 4 + 3]; + expect(alphaAt(10, 10), 255, reason: 'inside the clip is painted'); + expect(alphaAt(40, 10), 0, reason: 'the route continues past the clip'); + expect(alphaAt(10, 35), 0, reason: 'below the canvas stays empty'); + }); + + testWidgets('lets taps through to a sibling below the canvas', ( + tester, + ) async { + var taps = 0; + Widget harness(List routes) => MaterialApp( + home: Center( + child: SizedBox( + width: 200, + height: 100, + child: Stack( + children: [ + Positioned.fill( + child: GestureDetector( + behavior: HitTestBehavior.opaque, + onTap: () => taps += 1, + ), + ), + GraphEdgeLayer( + routes: routes, + canvasSize: const Size(200, 100), + color: color, + strokeWidth: 2, + ), + ], + ), + ), + ), + ); + for (final routes in >[ + const [], + [straight], + ]) { + await tester.pumpWidget(harness(routes)); + final origin = tester.getTopLeft(find.byType(GraphEdgeLayer)); + final before = taps; + await tester.tapAt(origin + const Offset(50, 20)); + await tester.tapAt(origin + const Offset(150, 80)); + expect(taps, before + 2, reason: 'routes=$routes'); + } + }); + + test('repaints on route, color or stroke changes only', () { + final painter = GraphEdgePainter( + routes: [straight], + color: color, + strokeWidth: 2, + ); + GraphEdgePainter copy({ + List? routes, + Color? color, + double? strokeWidth, + }) => GraphEdgePainter( + routes: routes ?? [straight], + color: color ?? Colors.black87, + strokeWidth: strokeWidth ?? 2, + ); + + expect(painter.shouldRepaint(copy()), isFalse); + expect(painter.shouldRepaint(copy(color: Colors.red)), isTrue); + expect(painter.shouldRepaint(copy(strokeWidth: 3)), isTrue); + expect( + painter.shouldRepaint( + copy( + routes: [ + edgeRoute(points: const [RoutePoint(10, 20), RoutePoint(90, 30)]), + ], + ), + ), + isTrue, + ); + }); + + testWidgets('lays out at the supplied canvas size', (tester) async { + await tester.pumpWidget( + MaterialApp( + home: Center( + child: GraphEdgeLayer( + routes: [wrapping], + canvasSize: const Size(120, 80), + color: color, + strokeWidth: 2, + ), + ), + ), + ); + expect(tester.getSize(find.byType(GraphEdgeLayer)), const Size(120, 80)); + expect(tester.takeException(), isNull); + }); +} diff --git a/app/tool/graph_edge_probe.dart b/app/tool/graph_edge_probe.dart new file mode 100644 index 00000000..42687e2d --- /dev/null +++ b/app/tool/graph_edge_probe.dart @@ -0,0 +1,182 @@ +import 'package:flutter/material.dart'; +import 'package:pipelines_app/features/graph/domain/graph_definition.dart'; +import 'package:pipelines_app/features/graph/domain/graph_protocol.dart'; +import 'package:pipelines_app/features/graph/layout/graph_node_layout.dart'; +import 'package:pipelines_app/features/graph/layout/layout_models.dart'; +import 'package:pipelines_app/features/graph/painting/graph_edge_layer.dart'; +import 'package:pipelines_app/features/graph/routing/graph_edge_routing.dart'; +import 'package:pipelines_app/features/graph/routing/route_models.dart'; + +/// Browser-capture fixture for `GraphEdgeLayer` only. +/// +/// It composes caller-measured cards, the landed node layout, the landed +/// orthogonal router and the edge layer. It is not wired into `main.dart`; the +/// app shell, a real pipeline and any server stay untouched. Query parameter +/// `theme=dark` selects the dark native theme and `case=same-rank` swaps in a +/// two-node cycle that exercises same-rank edges between distinct nodes. +void main() => runApp(const GraphEdgeProbeApp()); + +const Map _definition = { + 'stages': [ + { + 'key': 'ingest', + 'edges': {'success': 'build', 'error': '#failure'}, + }, + { + 'key': 'build', + 'edges': {'success': 'verify', 'retry': 'build'}, + }, + { + 'key': 'verify', + 'edges': {'success': '#success', 'rework': 'ingest'}, + }, + ], +}; + +/// A two-node cycle: both nodes share one rank and both edges are same-rank +/// without being self loops. +const Map _sameRankDefinition = { + 'stages': [ + { + 'key': 'review', + 'edges': {'success': 'approve'}, + }, + { + 'key': 'approve', + 'edges': {'success': 'review'}, + }, + ], +}; + +class GraphEdgeProbeApp extends StatelessWidget { + const GraphEdgeProbeApp({super.key}); + + @override + Widget build(BuildContext context) { + final dark = Uri.base.queryParameters['theme'] == 'dark'; + return MaterialApp( + title: 'Graph edge layer probe', + theme: ThemeData( + brightness: dark ? Brightness.dark : Brightness.light, + colorScheme: ColorScheme.fromSeed( + seedColor: Colors.indigo, + brightness: dark ? Brightness.dark : Brightness.light, + ), + ), + home: const _ProbePage(), + ); + } +} + +class _ProbePage extends StatelessWidget { + const _ProbePage(); + + @override + Widget build(BuildContext context) { + final theme = Theme.of(context); + final scaler = MediaQuery.textScalerOf(context); + final sameRankCase = Uri.base.queryParameters['case'] == 'same-rank'; + final definition = sameRankCase ? _sameRankDefinition : _definition; + final nodes = graphNodes(definition); + final edges = graphEdges(definition); + final layout = layoutGraphNodes( + nodes: nodes, + edges: edges, + extents: { + for (final node in nodes) + node.key: _nodeExtent(theme.textTheme.bodyMedium, node.label, scaler), + }, + config: GraphLayoutConfig(columnGap: 120, rowGap: 24, padding: 16), + ); + final routing = routeGraphEdges( + layout: layout, + edges: edges, + labelExtents: { + for (final edge in edges) + edge.id: _labelExtent(theme.textTheme.labelSmall, edge.label, scaler), + }, + config: RoutingConfig( + nodeClearance: 8, + laneSpacing: 28, + corridorSpacing: 20, + portSpacing: 12, + labelGap: 4, + boundsPadding: 8, + ), + ); + final size = Size(routing.width, routing.height); + + return Scaffold( + appBar: AppBar(title: const Text('Graph edge layer')), + body: SingleChildScrollView( + padding: const EdgeInsets.all(16), + child: Column( + crossAxisAlignment: CrossAxisAlignment.start, + children: [ + Text( + sameRankCase + ? 'A two-node cycle in one rank: both arrows are same-rank ' + 'and neither is a self loop.' + : 'Measured cards and routed edges: same-rank cycle edges, ' + 'forward edges to the terminals and a self loop, in the ' + 'native outline color and stroke.', + style: theme.textTheme.bodySmall, + ), + const SizedBox(height: 16), + SingleChildScrollView( + scrollDirection: Axis.horizontal, + child: SizedBox.fromSize( + size: size, + child: Stack( + clipBehavior: Clip.none, + children: [ + GraphEdgeLayer( + routes: routing.routes, + canvasSize: size, + color: theme.colorScheme.outline, + strokeWidth: theme.dividerTheme.thickness ?? 1, + ), + for (final node in layout.nodes) + Positioned( + left: node.x, + top: node.y, + width: node.width, + height: node.height, + child: Card( + margin: EdgeInsets.zero, + child: Center( + child: Text( + nodeDisplayLabel(node.key), + style: theme.textTheme.bodyMedium, + ), + ), + ), + ), + ], + ), + ), + ), + ], + ), + ), + ); + } +} + +NodeExtent _nodeExtent(TextStyle? style, String text, TextScaler scaler) { + final painter = TextPainter( + text: TextSpan(text: text, style: style), + textDirection: TextDirection.ltr, + textScaler: scaler, + )..layout(); + return NodeExtent(width: painter.width + 32, height: painter.height + 20); +} + +LabelExtent _labelExtent(TextStyle? style, String text, TextScaler scaler) { + final painter = TextPainter( + text: TextSpan(text: text, style: style), + textDirection: TextDirection.ltr, + textScaler: scaler, + )..layout(); + return LabelExtent(width: painter.width + 8, height: painter.height + 4); +} From fb27886b44a4d3948cbdd1af42c28f420b121563 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Wed, 21 Oct 2026 18:33:24 +0100 Subject: [PATCH 2/5] docs(app): keep the graph edge layer within its 160-line budget Join two doc-comment lines without changing the painter; the file is now 160 lines, matching the item's stated source budget. --- app/lib/features/graph/painting/graph_edge_layer.dart | 5 ++--- app/notes/P2-edge.md | 2 +- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/app/lib/features/graph/painting/graph_edge_layer.dart b/app/lib/features/graph/painting/graph_edge_layer.dart index 418eb492..3ce7d053 100644 --- a/app/lib/features/graph/painting/graph_edge_layer.dart +++ b/app/lib/features/graph/painting/graph_edge_layer.dart @@ -111,9 +111,8 @@ class GraphEdgePainter extends CustomPainter { return path; } - /// A filled triangle whose tip is exactly [EdgeRoute.targetPort]. - /// - /// The direction follows the route's last segment, so forward, backward, + /// A filled triangle whose tip is exactly [EdgeRoute.targetPort]. The + /// direction follows the route's last segment, so forward, backward, /// same-rank and self-loop edges keep their honest arrival direction. A /// degenerate tail falls back to the target port's inward normal. Path arrowPath(EdgeRoute route) { diff --git a/app/notes/P2-edge.md b/app/notes/P2-edge.md index 7e02849d..78c69953 100644 --- a/app/notes/P2-edge.md +++ b/app/notes/P2-edge.md @@ -8,7 +8,7 @@ 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 | +| `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 | From 1f44107f6a62276c5bce2b3672adfdd904c82644 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Wed, 21 Oct 2026 18:34:23 +0100 Subject: [PATCH 3/5] docs(app): point the edge note at the landed diff --- app/notes/P2-edge.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/app/notes/P2-edge.md b/app/notes/P2-edge.md index 78c69953..d44e3821 100644 --- a/app/notes/P2-edge.md +++ b/app/notes/P2-edge.md @@ -72,8 +72,9 @@ 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. +`public/P2-edge.patch` is the reviewed new-file diff. `public/P2-edge-land.patch` +is the landed diff and also carries the landing caption correction and the +160-line trim; it applies cleanly to the merged tree. ## Rendered evidence From b61db0230301ee2f4ba848fc5352486fb7a86de0 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Wed, 21 Oct 2026 18:34:33 +0100 Subject: [PATCH 4/5] docs(app): record the edge candidate's committed state --- app/notes/P2-edge.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/app/notes/P2-edge.md b/app/notes/P2-edge.md index d44e3821..2961894a 100644 --- a/app/notes/P2-edge.md +++ b/app/notes/P2-edge.md @@ -114,4 +114,6 @@ evidence for the rendered layout. 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. +- **Committed, not delivered.** The candidate is committed locally on + `flutter/p2-edge-layer` with `main` merged. Nothing was pushed, deployed or + installed. From c001c5349303de58d474883a2e5db20bc7c040a2 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Wed, 21 Oct 2026 18:34:42 +0100 Subject: [PATCH 5/5] docs(app): describe the landed edge patch precisely --- app/notes/P2-edge.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/app/notes/P2-edge.md b/app/notes/P2-edge.md index 2961894a..6775deb9 100644 --- a/app/notes/P2-edge.md +++ b/app/notes/P2-edge.md @@ -73,8 +73,8 @@ 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 diff and also carries the landing caption correction and the -160-line trim; it applies cleanly to the merged tree. +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