diff --git a/app/PARITY.md b/app/PARITY.md index 77fb6823..0625a956 100644 --- a/app/PARITY.md +++ b/app/PARITY.md @@ -24,7 +24,7 @@ or scratch servers only, never real operator sessions/runs/workflows. | Shared transport/settings connection | Preview | foreground recovery, persisted endpoint boot, protocol warning, complete refresh semantics | | Native shell/run URLs | Preview: full route vocabulary; pipeline/version/stage, template detail and run visit/stage links open their detail/pane | `?action=decide` opening the prompt, runs pipeline filter, native OS deep-link registration | | Pipeline list/filter/sort/detail/source/versions | Preview: recorded row metadata and miniature, pinned detail URLs, filter/sort | none outstanding on the list/detail read path | -| Definition graph | Preview: measured native canvas, pipeline Graph tab, pan/zoom, expanded view, stage definition pane, pipeline stage deep link | live activity pulse on the run graph (tracked below) | +| Definition graph | Preview: measured native canvas, pipeline Graph tab, pan/zoom, expanded view, stage definition pane, pipeline stage deep link | none outstanding on the definition graph read path | | Start a pipeline | Preview: native Run action, prompt/workspace/notify dialog, pinned run request, response-loss check/retry | Report format, recent-directory suggestions, pending intent across a reload | | Templates | Preview: gallery/detail/source, create-only dialog via Settings → Templates, list invalidated on create | run-detail template link, create refresh verified against a real server | | Runs list/filter/sort/live fold | Preview | full time/status/provenance filters, recency/day groups, shell live/attention state | @@ -33,7 +33,7 @@ or scratch servers only, never real operator sessions/runs/workflows. | Cancel run | Preview | exact confirm/server-accepted detail+list fold; production cancellation not tested | | Retry/restart | Preview controls in the run detail | accepted new-run navigation, stale/refusal handling verified in the app | | Human decisions | Preview waiting card/native prompt/exact accepted reply | attention/action URL entry; no production decision answered during tests | -| Run graph | Preview: Graph tab with legend, recorded-stage selection, canvas pan/zoom and an expanded view | live activity pulse | +| Run graph | Preview: Graph tab with legend, recorded-stage selection, canvas pan/zoom, an expanded view, and a live pulse on the recorded current stage while executing | rendered browser capture of the pulse; styling advisories tracked in `notes/graph-pulse.md` | | Timeline/recorded visit pane | Preview: selection opens the recorded facts with Input/Output/Artifacts/Session/Definition sections and exact absence wording | full per-visit session-repair choices (separate row); the export-only retry lives in Session | | Changes/diffs | Preview via run detail | settled-run aggregate gate, recorded file/diff/close/back verified in the real app; per-visit capture entry and paging remain | | Artifact groups | Preview: recorded groups in run detail, per-visit drill-down, turn documents (input/memory/output, session.html) in the run gallery | video/HTML preview remains external-only | diff --git a/app/lib/features/graph/widgets/graph_stage_node.dart b/app/lib/features/graph/widgets/graph_stage_node.dart index d28d4a26..1b0c91d0 100644 --- a/app/lib/features/graph/widgets/graph_stage_node.dart +++ b/app/lib/features/graph/widgets/graph_stage_node.dart @@ -15,6 +15,7 @@ class GraphStageNode extends StatelessWidget { required this.node, this.recordedStatus, this.selected = false, + this.active = false, required this.onSelected, }); @@ -26,6 +27,12 @@ class GraphStageNode extends StatelessWidget { /// Whether this definition node is the current graph selection. final bool selected; + /// Whether the run records this node as its current stage while executing. + /// + /// Set only from the run's recorded active-stage evidence; a finished run has + /// none, so an idle graph never shows live activity. + final bool active; + /// Reports [node.key] exactly as the definition recorded it. final ValueChanged onSelected; @@ -48,7 +55,7 @@ class GraphStageNode extends StatelessWidget { Widget build(BuildContext context) { final content = ExcludeSemantics(child: _content()); void onPressed() => onSelected(node.key); - return MergeSemantics( + final control = MergeSemantics( child: Semantics( button: true, selected: selected, @@ -58,6 +65,7 @@ class GraphStageNode extends StatelessWidget { : _materialCard(onPressed, content), ), ); + return active ? StageActivityHalo(child: control) : control; } /// A stock card, not a stock button: Material's button shape is a stadium, @@ -124,3 +132,113 @@ class GraphStageNode extends StatelessWidget { return buffer.toString(); } } + +/// The live-stage halo around a native node. +/// +/// It paints outside the node's measured box, so it never changes a node extent +/// or the layout, and it takes no pointer input. The ring pulses in the host's +/// primary colour and stays still when the platform asks for reduced motion. +class StageActivityHalo extends StatefulWidget { + const StageActivityHalo({super.key, required this.child}); + + final Widget child; + + /// One full pulse; slow enough to read as activity, not as a progress bar. + static const Duration period = Duration(milliseconds: 1600); + + @override + State createState() => _StageActivityHaloState(); +} + +class _StageActivityHaloState extends State + with SingleTickerProviderStateMixin { + late final AnimationController _controller = AnimationController( + vsync: this, + duration: StageActivityHalo.period, + ); + bool _reducedMotion = false; + + @override + void didChangeDependencies() { + super.didChangeDependencies(); + final reducedMotion = MediaQuery.maybeDisableAnimationsOf(context) ?? false; + if (reducedMotion == _reducedMotion && + (_controller.isAnimating || reducedMotion)) { + return; + } + _reducedMotion = reducedMotion; + if (reducedMotion) { + // A still ring still marks the current stage; only the animation stops. + _controller.stop(); + } else { + _controller.repeat(reverse: true); + } + } + + @override + void dispose() { + _controller.dispose(); + super.dispose(); + } + + @override + Widget build(BuildContext context) { + final cupertino = usesCupertinoHost(context); + final color = cupertino + ? CupertinoTheme.of(context).primaryColor + : Theme.of(context).colorScheme.primary; + return AnimatedBuilder( + animation: _controller, + builder: (context, child) => CustomPaint( + foregroundPainter: StageActivityHaloPainter( + color: color, + progress: _reducedMotion ? 0.5 : _controller.value, + ), + child: child, + ), + child: widget.child, + ); + } +} + +/// Paints the halo just outside a node's own box. +/// +/// [progress] runs 0..1 so the ring breathes outward and fades; the radius is +/// derived from the node's own size rather than a fixed corner value, because +/// the node keeps its host's stock shape. +class StageActivityHaloPainter extends CustomPainter { + const StageActivityHaloPainter({required this.color, required this.progress}); + + final Color color; + final double progress; + + static const double _baseSpread = 2; + static const double _pulseSpread = 5; + static const double _strokeWidth = 2; + static const double _blurSigma = 4; + + @override + void paint(Canvas canvas, Size size) { + if (size.isEmpty) return; + final rect = Offset.zero & size; + final spread = _baseSpread + _pulseSpread * progress; + final radius = Radius.circular(size.shortestSide * 0.25); + final paint = Paint() + ..style = PaintingStyle.stroke + ..strokeWidth = _strokeWidth + ..color = color.withValues(alpha: 0.55 - 0.3 * progress) + ..maskFilter = const MaskFilter.blur(BlurStyle.normal, _blurSigma); + canvas.drawRRect( + RRect.fromRectAndRadius(rect.inflate(spread), radius), + paint, + ); + } + + /// Like the node itself, the halo adds no hit target. + @override + bool hitTest(Offset position) => false; + + @override + bool shouldRepaint(StageActivityHaloPainter oldDelegate) => + oldDelegate.color != color || oldDelegate.progress != progress; +} diff --git a/app/lib/features/graph/widgets/run_graph_canvas.dart b/app/lib/features/graph/widgets/run_graph_canvas.dart index 68deaa50..7ab77677 100644 --- a/app/lib/features/graph/widgets/run_graph_canvas.dart +++ b/app/lib/features/graph/widgets/run_graph_canvas.dart @@ -199,6 +199,7 @@ class RunGraphCanvas extends StatelessWidget { } final executedIds = {for (final route in executed) route.id}; final size = Size(routing.width, routing.height); + final activeStage = state.activeStage; final cupertino = usesCupertinoHost(context); final executedColor = cupertino ? CupertinoTheme.of(context).primaryColor @@ -226,6 +227,7 @@ class RunGraphCanvas extends StatelessWidget { node: nodesByKey[box.key]!, recordedStatus: recordedStatuses[box.key], selected: box.key == selectedStage, + active: box.key == activeStage, opensVisit: !nodesByKey[box.key]!.terminal && state.isStageVisited(box.key), @@ -250,7 +252,9 @@ class RunGraphCanvas extends StatelessWidget { /// One placed run node. A visited stage is the native control with its recorded /// status; an unvisited node and a terminal are labels with no tap target or -/// button semantics, because neither owns a recorded visit to open. +/// button semantics, because neither owns a recorded visit to open. [active] +/// marks the run's recorded current stage while it executes; it only adds the +/// live halo, never a visit or a control. class RunGraphNode extends StatelessWidget { const RunGraphNode({ super.key, @@ -259,12 +263,14 @@ class RunGraphNode extends StatelessWidget { required this.opensVisit, required this.onSelected, this.selected = false, + this.active = false, }); final GraphNode node; final String? recordedStatus; final bool opensVisit; final bool selected; + final bool active; final ValueChanged onSelected; @override @@ -275,6 +281,7 @@ class RunGraphNode extends StatelessWidget { node: node, recordedStatus: status, selected: selected, + active: active, onSelected: onSelected, ); } @@ -286,6 +293,7 @@ class RunGraphNode extends StatelessWidget { child: GraphStageNode( node: node, recordedStatus: status, + active: active, onSelected: (_) {}, ), ), diff --git a/app/notes/graph-pulse.md b/app/notes/graph-pulse.md new file mode 100644 index 00000000..85001df5 --- /dev/null +++ b/app/notes/graph-pulse.md @@ -0,0 +1,44 @@ +# Run graph: live current-stage pulse + +The run graph marks the run's recorded current stage while the run executes. The +mark is a ring around the existing native node; nothing about the node's size, +label, tap target or semantics changed, and an idle or finished run shows no +live activity. + +## Landed + +- `GraphStageNode.active` (default `false`), set only from + `RunGraphState.activeStage`, which is non-null only while the run reports + `executing`. No second source of truth and no client-side inference. +- `StageActivityHalo` / `StageActivityHaloPainter` draw a primary-colour ring + with a foreground painter outside the node box. The painter's `hitTest` + returns `false` and it adds no measured extent; the node keeps the host's + stock Material card or Cupertino button. +- `MediaQuery.disableAnimations` keeps the ring still rather than animating it, + mirroring the web's `active` (always) vs `pulsing` (animations allowed) split. +- The halo is applied to both the interactive visited node and the + non-interactive unvisited/terminal node, because the current stage is run + evidence, not a visit. + +## Checks run at landing + +- `flutter analyze` — No issues found. +- `flutter test` — all tests passed (1511). +- `flutter build web` — built `build/web`. +- `dart format --output=none --set-exit-if-changed` on the four changed files — + 0 changed. +- Branch `flutter/graph-pulse` is based on `main`; merging `main` was a no-op + because the branch already contained it. + +## Limits + +- No real-browser interaction/capture of the pulse was taken in this run. The + behaviour is verified by widget tests (state, animation progress, reduced + motion, unchanged node extent) and by analysis/build, not by rendered + evidence. +- Android/iOS are unverified; no device, emulator or platform build was used. +- Advisory, not fixed here: one full breath is 3.2 s because the 1600 ms + controller repeats in reverse (web's is 1.6 s); the ring radius follows the + node's shortest side rather than the stock 12 px surface corner; the blur is + a soft glow where the web ring is crisp; the halo has no `RepaintBoundary` + of its own. diff --git a/app/test/features/graph/widgets/run_graph_pulse_test.dart b/app/test/features/graph/widgets/run_graph_pulse_test.dart new file mode 100644 index 00000000..4a335867 --- /dev/null +++ b/app/test/features/graph/widgets/run_graph_pulse_test.dart @@ -0,0 +1,185 @@ +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; + +import 'package:pipelines_app/features/graph/domain/graph_definition.dart'; +import 'package:pipelines_app/features/graph/widgets/graph_stage_node.dart'; +import 'package:pipelines_app/features/graph/widgets/run_graph_view.dart'; + +import '../domain/graph_fixtures.dart'; + +Map _run({required bool executing}) => { + 'id': 42, + 'steps': [ + step( + sequence: 1, + stage: 'plan', + status: 'completed', + outcome: 'success', + target: 'build', + ), + if (executing) + step( + sequence: 2, + stage: 'build', + status: 'running', + startedAt: '2026-10-21T10:00:00Z', + ) + else + step( + sequence: 2, + stage: 'build', + status: 'completed', + outcome: 'success', + target: 'ship', + ), + ], + 'current_stage': executing ? 'build' : '', + 'executing': executing, +}; + +Widget _host(Map run, {bool disableAnimations = false}) => + MaterialApp( + builder: (context, child) => MediaQuery( + data: MediaQuery.of( + context, + ).copyWith(disableAnimations: disableAnimations), + child: child!, + ), + home: Scaffold( + body: SizedBox( + width: 900, + height: 700, + child: RunGraphView( + graph: linearGraph(), + run: run, + onStageSelected: (_) {}, + ), + ), + ), + ); + +Finder _node(String key) => find.byWidgetPredicate( + (widget) => widget is GraphStageNode && widget.node.key == key, +); + +Finder _haloPainter() => find.byWidgetPredicate( + (widget) => + widget is CustomPaint && + widget.foregroundPainter is StageActivityHaloPainter, +); + +StageActivityHaloPainter _painter(WidgetTester tester) => + tester.widget(_haloPainter()).foregroundPainter! + as StageActivityHaloPainter; + +void main() { + testWidgets('only the recorded current stage pulses while executing', ( + tester, + ) async { + await tester.pumpWidget(_host(_run(executing: true))); + await tester.pump(); + await tester.pump(); + await tester.pump(); + + expect(tester.widget(_node('build')).active, isTrue); + for (final other in ['plan', 'ship', '#success', '#failure']) { + expect( + tester.widget(_node(other)).active, + isFalse, + reason: '$other is not the run current stage', + ); + } + expect(find.byType(StageActivityHalo), findsOneWidget); + expect( + find.descendant( + of: _node('build'), + matching: find.byType(StageActivityHalo), + ), + findsOneWidget, + ); + expect(tester.hasRunningAnimations, isTrue); + + final before = _painter(tester).progress; + await tester.pump(const Duration(milliseconds: 400)); + expect(_painter(tester).progress, isNot(closeTo(before, 0.01))); + expect(tester.hasRunningAnimations, isTrue); + expect(tester.takeException(), isNull); + }); + + testWidgets('a finished run shows no live activity', (tester) async { + await tester.pumpWidget(_host(_run(executing: false))); + await tester.pump(); + await tester.pump(); + await tester.pump(); + + for (final key in ['plan', 'build', 'ship']) { + expect(tester.widget(_node(key)).active, isFalse); + } + expect(find.byType(StageActivityHalo), findsNothing); + expect(tester.hasRunningAnimations, isFalse); + expect(tester.takeException(), isNull); + }); + + testWidgets('reduced motion keeps a still ring on the current stage', ( + tester, + ) async { + await tester.pumpWidget( + _host(_run(executing: true), disableAnimations: true), + ); + await tester.pump(); + await tester.pump(); + await tester.pump(); + + expect(tester.widget(_node('build')).active, isTrue); + expect(find.byType(StageActivityHalo), findsOneWidget); + expect(tester.hasRunningAnimations, isFalse); + final still = _painter(tester).progress; + await tester.pump(const Duration(milliseconds: 800)); + expect(_painter(tester).progress, still); + expect(tester.takeException(), isNull); + }); + + testWidgets('turning reduced motion on stops an existing pulse', ( + tester, + ) async { + await tester.pumpWidget(_host(_run(executing: true))); + await tester.pump(); + await tester.pump(); + await tester.pump(); + expect(tester.hasRunningAnimations, isTrue); + + await tester.pumpWidget( + _host(_run(executing: true), disableAnimations: true), + ); + await tester.pump(); + expect(tester.hasRunningAnimations, isFalse); + expect(find.byType(StageActivityHalo), findsOneWidget); + expect(tester.takeException(), isNull); + }); + + testWidgets('the halo never changes the node box the layout measured', ( + tester, + ) async { + const node = GraphNode(key: 'build', terminal: false, stageIndex: 1); + final sizes = []; + for (final active in [false, true]) { + await tester.pumpWidget( + MaterialApp( + home: Scaffold( + body: Center( + child: GraphStageNode( + node: node, + active: active, + onSelected: (_) {}, + ), + ), + ), + ), + ); + await tester.pump(); + sizes.add(tester.getSize(find.byType(GraphStageNode))); + } + expect(sizes[0], sizes[1]); + expect(tester.takeException(), isNull); + }); +} diff --git a/app/test/features/graph/widgets/run_graph_view_test.dart b/app/test/features/graph/widgets/run_graph_view_test.dart index cd14083d..30a12979 100644 --- a/app/test/features/graph/widgets/run_graph_view_test.dart +++ b/app/test/features/graph/widgets/run_graph_view_test.dart @@ -87,25 +87,26 @@ Widget _materialHost( double scale = 1, Size size = const Size(900, 700), DateTime Function()? now, + bool disableAnimations = false, }) { return MaterialApp( + builder: (context, child) => MediaQuery( + data: MediaQuery.of(context).copyWith( + textScaler: TextScaler.linear(scale), + disableAnimations: disableAnimations, + ), + child: child!, + ), home: Scaffold( - body: Builder( - builder: (context) => MediaQuery( - data: MediaQuery.of( - context, - ).copyWith(textScaler: TextScaler.linear(scale)), - child: SizedBox( - width: size.width, - height: size.height, - child: RunGraphView( - graph: graph, - run: run, - selectedStage: selected, - onStageSelected: onSelected ?? (_) {}, - now: now, - ), - ), + body: SizedBox( + width: size.width, + height: size.height, + child: RunGraphView( + graph: graph, + run: run, + selectedStage: selected, + onStageSelected: onSelected ?? (_) {}, + now: now, ), ), ), @@ -205,7 +206,9 @@ void main() { }); testWidgets('the expanded run graph keeps the route legend', (tester) async { - await tester.pumpWidget(_materialHost(linearGraph(), _runningRun())); + await tester.pumpWidget( + _materialHost(linearGraph(), _runningRun(), disableAnimations: true), + ); await _settle(tester); await tester.tap(find.byKey(const Key('graph-expand'))); await tester.pumpAndSettle();