diff --git a/app/lib/features/chat/conversation/composer_running_arc.dart b/app/lib/features/chat/conversation/composer_running_arc.dart new file mode 100644 index 00000000..62d931ce --- /dev/null +++ b/app/lib/features/chat/conversation/composer_running_arc.dart @@ -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 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 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 = []; + 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 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; +} diff --git a/app/lib/features/chat/conversation/composer_running_border.dart b/app/lib/features/chat/conversation/composer_running_border.dart index 07ecd216..713dcf23 100644 --- a/app/lib/features/chat/conversation/composer_running_border.dart +++ b/app/lib/features/chat/conversation/composer_running_border.dart @@ -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(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 diff --git a/app/notes/composer-running-border-arc.md b/app/notes/composer-running-border-arc.md new file mode 100644 index 00000000..291f0a3c --- /dev/null +++ b/app/notes/composer-running-border-arc.md @@ -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. diff --git a/app/test/features/chat/conversation/composer_running_arc_test.dart b/app/test/features/chat/conversation/composer_running_arc_test.dart new file mode 100644 index 00000000..c2d9a40d --- /dev/null +++ b/app/test/features/chat/conversation/composer_running_arc_test.dart @@ -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 _outline(Size size, {double radius = 24}) { + final path = RoundedRectangleBorder( + borderRadius: BorderRadius.circular(radius), + ).getOuterPath(Offset.zero & size); + return path.computeMetrics().toList(); +} + +double _length(List metrics) => + metrics.fold(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 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)); + }); +}