feat(app): pulse the run graph's recorded current stage

Mark the run's recorded current stage on the run graph while it executes. The
halo is a foreground painter outside the node box, so it adds no size, hit
target or semantics, and it is derived only from RunGraphState.activeStage,
which is non-null only while the run reports executing. Reduced motion keeps a
still ring instead of animating.

Widget tests cover the sole active node, a finished run with no halo or ticker,
reduced motion, toggling it at runtime and unchanged node extents.
This commit is contained in:
2026-10-22 17:17:39 +01:00
parent cf6da4acaa
commit 407551b8bb
6 changed files with 379 additions and 21 deletions
+2 -2
View File
@@ -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 |
@@ -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<String> 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<StageActivityHalo> createState() => _StageActivityHaloState();
}
class _StageActivityHaloState extends State<StageActivityHalo>
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;
}
@@ -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<String> 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: (_) {},
),
),
+44
View File
@@ -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.
@@ -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<String, dynamic> _run({required bool executing}) => <String, dynamic>{
'id': 42,
'steps': <dynamic>[
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<String, dynamic> 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<CustomPaint>(_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<GraphStageNode>(_node('build')).active, isTrue);
for (final other in ['plan', 'ship', '#success', '#failure']) {
expect(
tester.widget<GraphStageNode>(_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<GraphStageNode>(_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<GraphStageNode>(_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 = <Size>[];
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);
});
}
@@ -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();