Animate composer border at constant arc speed

Lay the running highlight out by rounded-border arc length so it advances at a steady linear speed without a loop jump, while preserving the existing colours and reduced-motion border. Add focused geometry tests and implementation notes.
This commit is contained in:
2026-11-12 10:54:42 +00:00
parent 82418d31a7
commit d9ec43e607
4 changed files with 343 additions and 21 deletions
@@ -0,0 +1,113 @@
import 'dart:math' as math;
import 'dart:ui' show PathMetric;
import 'package:flutter/material.dart';
/// Arc-length geometry for the composer's running border.
///
/// The highlight is laid out by distance travelled along the outline, not by
/// angle around the centre, so equal time steps move it equal lengths around
/// a rounded rectangle: no racing along the long edges, no crawling at ends.
///
/// One lap is `progress` in [0, 1]; progress 1 is the same place as 0, so the
/// loop restarts without a jump.
/// The colour bands, as fractions of a lap measured forward from the origin.
/// They match the original sweep's stops and colours.
const List<double> runningHighlightStops = [0, .12, .24, .38, 1];
/// Half a device pixel of overlap so neighbouring segments leave no seam.
const double _seamOverlap = .5;
/// One piece of the outline and the highlight colour drawn over it.
class RunningArcSegment {
const RunningArcSegment({
required this.start,
required this.end,
required this.color,
});
/// Arc length from the outline's start where the piece begins.
final double start;
/// Arc length where the piece ends (exclusive, may overlap by a seam).
final double end;
final Color color;
}
/// The arc length of the highlight's origin along an outline of [length].
double runningHighlightOrigin(double progress, double length) {
final lap = progress - progress.floorToDouble();
return lap * length;
}
/// The highlight colour [fraction] of a lap ahead of its origin. Fractions
/// wrap, so `f` and `f + 1` are the same colour.
Color runningHighlightColorAt(double fraction, Color primary, Color tertiary) {
final colors = [
primary.withValues(alpha: 0),
primary,
tertiary,
tertiary.withValues(alpha: 0),
primary.withValues(alpha: 0),
];
final f = fraction - fraction.floorToDouble();
for (var i = 1; i < runningHighlightStops.length; i++) {
final stop = runningHighlightStops[i];
if (f <= stop) {
final from = runningHighlightStops[i - 1];
final t = (f - from) / (stop - from);
return Color.lerp(colors[i - 1], colors[i], t)!;
}
}
return colors.last;
}
/// Splits an outline of [length] into pieces about [step] long and colours
/// each by where it sits in the highlight at [progress]. Pieces with no
/// visible colour are left out.
List<RunningArcSegment> runningHighlightSegments({
required double progress,
required double length,
required Color primary,
required Color tertiary,
double step = 3,
}) {
if (length <= 0) return const [];
final count = math.max(1, (length / step).ceil());
final size = length / count;
final origin = runningHighlightOrigin(progress, length);
final segments = <RunningArcSegment>[];
for (var i = 0; i < count; i++) {
final mid = (i + .5) * size;
final color = runningHighlightColorAt(
(mid - origin) / length,
primary,
tertiary,
);
if (color.a == 0) continue;
segments.add(
RunningArcSegment(
start: math.max(0, i * size - _seamOverlap),
end: math.min(length, (i + 1) * size + _seamOverlap),
color: color,
),
);
}
return segments;
}
/// The part of an outline between arc lengths [start] and [end]. The outline
/// may be made of several contours, so the range is taken across all of them.
Path runningArcPath(List<PathMetric> metrics, double start, double end) {
final out = Path();
var offset = 0.0;
for (final metric in metrics) {
final from = math.max(start, offset) - offset;
final to = math.min(end, offset + metric.length) - offset;
if (to > from) out.addPath(metric.extractPath(from, to), Offset.zero);
offset += metric.length;
}
return out;
}
@@ -1,7 +1,7 @@
import 'dart:math' as math;
import 'package:flutter/material.dart';
import 'composer_running_arc.dart';
/// The composer's "agent is working" edge: a soft highlight that travels once
/// around the pill's rounded border in [primary] and [tertiary], with a faint
/// glow beneath it. Mount it only while a turn runs; disposing it stops the
@@ -22,8 +22,8 @@ class ComposerRunningBorder extends StatefulWidget {
final Color primary;
final Color tertiary;
/// One lap of the highlight around the border.
static const Duration period = Duration(seconds: 4);
/// One lap of the highlight around the border (about 2.5–3 s).
static const Duration period = Duration(milliseconds: 2750);
/// The stroke drawn just inside the pill's edge.
static const double strokeWidth = 2;
@@ -117,24 +117,29 @@ class _RunningBorderPainter extends CustomPainter {
);
glow.color = solid.withValues(alpha: solid.a * .4);
line.color = solid;
} else {
final shader = SweepGradient(
colors: [
primary.withValues(alpha: 0),
primary,
tertiary,
tertiary.withValues(alpha: 0),
primary.withValues(alpha: 0),
],
stops: const [0, .12, .24, .38, 1],
transform: GradientRotation(progress * 2 * math.pi),
).createShader(rect);
glow.shader = shader;
line.shader = shader;
canvas
..drawPath(path, glow)
..drawPath(path, line);
return;
}
// The highlight is laid along the outline by arc length, one piece at a
// time, so its speed is even around corners and straight edges alike.
final metrics = path.computeMetrics().toList();
final length = metrics.fold<double>(0, (sum, m) => sum + m.length);
final segments = runningHighlightSegments(
progress: progress,
length: length,
primary: primary,
tertiary: tertiary,
);
for (final segment in segments) {
final piece = runningArcPath(metrics, segment.start, segment.end);
glow.color = segment.color;
line.color = segment.color;
canvas
..drawPath(piece, glow)
..drawPath(piece, line);
}
canvas
..drawPath(path, glow)
..drawPath(path, line);
}
@override
+45
View File
@@ -0,0 +1,45 @@
# Composer running border: constant arc-length speed
## Change
- The highlight is now laid along the pill's outline by arc length instead of a
`SweepGradient` rotated by angle. Equal time steps move it equal distances
round the rounded rectangle: no racing along long edges, no crawling at ends.
- `lib/features/chat/conversation/composer_running_arc.dart` (new, pure helpers):
origin = fractional lap × outline length; colour bands at the original stops
(0, .12, .24, .38, 1) and colours; segments of ~3 px with a 0.5 px seam
overlap, transparent pieces omitted; `runningArcPath` extracts a piece of the
outline across contours.
- `lib/features/chat/conversation/composer_running_border.dart`: the painter
draws those segments with the same glow and line strokes. Reduced motion still
paints the static border and never ticks. Period (2.75 s), colours, stroke width
and linear lap curve are unchanged.
## Speed
- `ComposerRunningBorder.period` is now 2750 ms (one lap per 2.75 s, the midpoint
of the requested 2.5–3 s). It was 4 s; review rejected that as too slow.
## Focused results
- `tool/memwatch/full.sh 'test/features/chat/conversation/composer_running_arc_test.dart test/features/chat/conversation/chat_composer_running_test.dart'`
→ PASS 16 passed, 0 failed (peak ~977 MB, exit 0).
- `tool/analyze.sh` on the three changed files → clean.
- New tests (`test/features/chat/conversation/composer_running_arc_test.dart`):
perimeter measured by arc; origin advances equal arc per equal lap step;
origin and colours wrap (progress 1 == 0, f == f+1); colour shifts with
arc under time; visible band spans 0.38 of the lap on a long pill and a
square; segments are ordered and inside the outline; `runningArcPath`
extracts the requested arc.
- Existing widget tests in `chat_composer_running_test.dart` (border mount and
unmount, reduced motion static, no ticks at rest, /stop, Escape handling)
pass unchanged.
## Affected states (not captured)
- Running composer border: default and reduced motion. Not captured or
reviewed here (ui-review owns captures). Mobile and browser behaviour is
unverified.
## Limitations
- Each frame draws about 0.38 × perimeter / 3 px segments twice (blurred glow
and line). Not profiled on device.
- The time-to-lap mapping is `AnimationController`'s default linear curve; it is
tested through the pure origin mapping, not by a widget test reading the
controller.
@@ -0,0 +1,159 @@
import 'dart:math' as math;
import 'dart:ui';
import 'package:flutter/material.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:pipelines_app/features/chat/conversation/composer_running_arc.dart';
const _primary = Color(0xFF3366FF);
const _tertiary = Color(0xFFFF6633);
/// The pill outline as the painter builds it, measured by arc length.
List<PathMetric> _outline(Size size, {double radius = 24}) {
final path = RoundedRectangleBorder(
borderRadius: BorderRadius.circular(radius),
).getOuterPath(Offset.zero & size);
return path.computeMetrics().toList();
}
double _length(List<PathMetric> metrics) =>
metrics.fold<double>(0, (sum, m) => sum + m.length);
/// The arc the visible band covers: from its first piece to its last. The
/// pieces overlap by a seam each, so their own lengths would overcount.
double _visibleSpan(List<RunningArcSegment> segments) =>
segments.last.end - segments.first.start;
/// Colours that differ only by float rounding at a band edge still match.
void _expectSameColor(Color actual, Color expected, {required String reason}) {
expect(actual.a, closeTo(expected.a, 1e-6), reason: reason);
expect(actual.r, closeTo(expected.r, 1e-6), reason: reason);
expect(actual.g, closeTo(expected.g, 1e-6), reason: reason);
expect(actual.b, closeTo(expected.b, 1e-6), reason: reason);
}
void main() {
const size = Size(320, 48);
final metrics = _outline(size);
final length = _length(metrics);
test('the outline is measured by arc length, not by angle', () {
// A 320x48 pill with radius 24: two straights of 272 and four quarter
// corners that make one full circle of radius 24. Flutter's curve metrics
// are approximate, so allow about a pixel.
expect(length, closeTo(2 * 272 + 2 * math.pi * 24, 1));
expect(metrics, hasLength(1));
});
test('the origin advances by equal arc for equal lap steps', () {
// Curves.linear: the lap value is proportional to elapsed time, so equal
// time steps must give equal arc steps all the way round the outline.
const steps = 16;
final first = runningHighlightOrigin(0, length);
final stepArc = runningHighlightOrigin(1 / steps, length) - first;
expect(stepArc, closeTo(length / steps, 1e-9));
for (var k = 0; k < steps; k++) {
final origin = runningHighlightOrigin(k / steps, length);
expect(origin, closeTo(k * stepArc, 1e-9), reason: 'step $k');
}
});
test('the highlight wraps seamlessly at the end of a lap', () {
expect(runningHighlightOrigin(1, length), 0);
expect(
runningHighlightOrigin(0.9999, length),
closeTo(length, length * 1e-3),
);
expect(runningHighlightOrigin(1.25, length), closeTo(length * .25, 1e-9));
final start = runningHighlightSegments(
progress: 0,
length: length,
primary: _primary,
tertiary: _tertiary,
);
final end = runningHighlightSegments(
progress: 1,
length: length,
primary: _primary,
tertiary: _tertiary,
);
expect(end.length, start.length);
for (var i = 0; i < start.length; i++) {
expect(end[i].start, start[i].start);
expect(end[i].end, start[i].end);
_expectSameColor(end[i].color, start[i].color, reason: 'piece $i');
}
});
test('colours wrap: a fraction and its +1 are the same colour', () {
for (var f = 0.0; f < 1; f += .02) {
_expectSameColor(
runningHighlightColorAt(f + 1, _primary, _tertiary),
runningHighlightColorAt(f, _primary, _tertiary),
reason: 'f=$f',
);
}
expect(runningHighlightColorAt(0, _primary, _tertiary).a, 0);
});
test('the highlight travels by arc: a shift of one step shifts colours', () {
// The colour at a given arc point, one step later, equals the colour one
// step earlier at a point shifted back by the arc that step covers.
const dt = .1;
final arc = dt * length;
for (var x = 0.0; x < length; x += length / 40) {
final before = runningHighlightColorAt(
(x - runningHighlightOrigin(0, length)) / length,
_primary,
_tertiary,
);
final after = runningHighlightColorAt(
(x + arc - runningHighlightOrigin(dt, length)) / length,
_primary,
_tertiary,
);
_expectSameColor(after, before, reason: 'x=$x');
}
});
test('the visible band covers the same arc on a long and a square shape', () {
// The band is 38% of a lap. Measured along the outline it has the same
// length whatever the aspect, which an angle-based sweep would not give.
final long = _outline(const Size(320, 48));
final square = _outline(const Size(120, 120), radius: 12);
for (final shape in [long, square]) {
final len = _length(shape);
final segments = runningHighlightSegments(
progress: .3,
length: len,
primary: _primary,
tertiary: _tertiary,
);
expect(_visibleSpan(segments), closeTo(.38 * len, 2 * 3 + 1));
}
});
test('the visible segments tile the outline without gaps', () {
final segments = runningHighlightSegments(
progress: .6,
length: length,
primary: _primary,
tertiary: _tertiary,
);
expect(segments, isNotEmpty);
for (var i = 1; i < segments.length; i++) {
expect(segments[i].start, lessThanOrEqualTo(segments[i - 1].end));
expect(segments[i].start, greaterThanOrEqualTo(segments[i - 1].start));
}
expect(segments.first.start, greaterThanOrEqualTo(0));
expect(segments.last.end, lessThanOrEqualTo(length));
});
test('runningArcPath draws the requested arc of the outline', () {
final piece = runningArcPath(metrics, 10, 30);
final pieceMetrics = piece.computeMetrics().toList();
// Curve metrics are approximations; a fraction of a pixel is exact enough.
expect(_length(pieceMetrics), closeTo(20, .5));
});
}