feat: release-ready flutter_border_beam — API, features, tests, CI, docs, segments

[rehmatsg]

Summary

Turns the border-beam Flutter port into a release-ready open-source package, flutter_border_beam (the pub.dev name border_beam is taken by an unrelated package), owned by the SimplifyJobs org. The branch carries five phases: repository hygiene and a dependency-free core; stability (engine fixes, enforced saveLayer budget, lifecycle/boundary/property tests, wider goldens, pinned CI with a minimum-SDK gate and an OIDC release pipeline); a value-object API with app-wide theming; a large feature set (palettes, motion, painting options, interaction widgets, BeamSync, driven beams); docs, community files, a deployed playground, and a spec-parity harness against the upstream React library; and partial contours (BeamSegment) with corner-wrapping line travel. Every original golden is byte-identical — the defaults reproduce the source's rendering exactly.

Changes

• Package identity (pubspec.yaml, lib/flutter_border_beam.dart, LICENSE, screenshots/) — renamed to flutter_border_beam; canonical repo/issue/homepage/documentation URLs; pub.dev screenshots:; canonical MIT header with the upstream third-party notice preserved below it; the sprung dependency replaced by an in-package FadeSpringCurve (bit-identical oracle test) so the package depends on the Flutter SDK alone.
• Engine correctness (lib/src/animation/, lib/src/models/beam_colors.dart, lib/src/painting/ring_geometry.dart) — value-equal, value-memoized palettes; phase-continuous retiming on cycle changes; runtime reduced-motion toggling; sub-2px boxes no longer assert; staticFrame() is hue-neutral.
• Value-object API (lib/src/models/, lib/src/border_beam.dart, lib/src/border_beam_theme.dart) — BeamStyle / BeamShape / BeamTiming / BeamPlayback with nullable-inherit fields resolved widget → BorderBeamTheme → variant preset; colors/active/borderRadius shorthands; generic BorderBeam(variant:); per-corner BorderRadiusGeometry (RTL-aware), BeamShape.all/stadium; BeamConfig value equality; public BeamThemeConfig.
• Palettes (beam_colors.dart, constants/extra_palettes.dart) — custom(base:), fromSeed (four harmonies), fromScheme, lerp, scaleAlpha; seven Flutter-only presets (aurora, neon, candy, ember, ice, gold, holographic).
• Motion & playback (beam_phases.dart, beam_clock.dart, border_beam_controller.dart, beam_sync.dart) — cycleGap, speed, direction (forward/reverse/bounce), phaseOffset, beamCount, hueMode, custom hue/breathe/spike periods, repeat, four-way reducedMotion, pauseWhenOffscreen, fadeCurve (+ cssEase), debugFrozenAt; progress, follow, strengthListenable/speedListenable; BorderBeam.overlay; BeamSync (one clock for many beams); controller.pulse()/flash().
• Painting options (lib/src/painting/strategies/, constants/{rotate_stops,line_geometry,pulse_constants}.dart) — tailLength, glowSpread, comet, sparkle, segments, line edge, ringOffset, custom contour, innerSizeScale, renderScale, pulseOutsideStock; strategy-embedded constants moved into lib/src/constants/; every option folds into existing layers — the per-variant saveLayer table (rotate 4, small 3, line 4, pulseInside 4, pulseOutside 3) is measured and enforced by test/painting/save_layer_budget_test.dart.
• Partial contours (beam_segment.dart, ring_geometry.dart, all strategies) — BeamSegment with BeamAnchor perimeter fractions (top-center, clockwise), feathered endpoints via dstIn inside existing layers, presets for halves and edges; rotate/pulse masked, line travels the segment; wrapCorners bends the line streak around its edge's corner arcs while keeping the planar travel direction. Implemented on a PathMetrics-measured BeamPerimeter that works for rounded rects, superellipses, and custom contours.
• Widgets (lib/src/widgets/) — BeamDecoration, BeamFocusRing, BeamHover, BeamPress.
• Tests (test/) — 165 → 1167 tests: value objects, config equality, transitions, lifecycle/ticker leaks, boundaries, seeded property tests, saveLayer budget rows for every option, pixel probes for segments, and six golden families (beam_, palette_, motion_, surface_, widgets_, research_, segment_); spec_parity_test.dart asserts every transcribed constant against the vendored upstream beam-spec.json (134 checks, zero discrepancies).
• CI & release (.github/) — Flutter pinned to 3.44.2 (the goldens' renderer), macOS goldens with failure artifacts, a 3.35.0 minimum-SDK gate, Codecov (OIDC), pana floor, example web build; release.yaml publishes to pub.dev over OIDC from a vX.Y.Z tag and cuts the GitHub Release from the changelog; pages.yaml deploys the playground to simplifyjobs.github.io/flutter_border_beam; weekly upstream_drift.yaml alarms when the upstream spec or styles.ts changes; Dependabot.
• Docs & community (README.md, doc/, CHANGELOG.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, issue/PR templates, CODEOWNERS) — README rewritten with per-field tables and an animated hero; nine doc/ guides incl. an explicit parity list of deviations from the original; complete Keep-a-Changelog section; CLAUDE.md refreshed (architecture, hard rules incl. the measured budget table, release recipe).
• Example (example/) — the playground exposes every option with a compiling, copyable snippet and shareable URL state; gallery sections for palettes, surfaces, motion, driven progress, sync, and the half-phone segment look.

Testing

• dart format --output=none --set-exit-if-changed . — clean.
• flutter analyze — no issues (package and example; lints include public_member_api_docs).
• flutter test — 1167 passed, 0 skipped (goldens included, on macOS / Flutter 3.44.2); every pre-existing golden PNG is byte-identical to main.
• cd example && flutter test — 91 passed; flutter build web --release succeeds.
• dart pub publish --dry-run — 0 warnings on the clean tree.
• New workflows linted with actionlint; action tags verified against the GitHub API.
• Not run here: CI on this branch (first push), the Pages deploy, and the release workflow (needs the one-time pub.dev setup below).

Follow-ups that need a human decision

1. Contact address — CODE_OF_CONDUCT.md and SECURITY.md name opensource@simplify.jobs; confirm it routes to a person or change it.
2. CODEOWNERS is @rehmatsg; an org team would survive role changes.
3. Upstream version in public copy — the README says the port tracks border-beam 1.4.0 (npm package version); the spec's own visual baseline is 1.3.0 (identical rendering, lib/src/constants/upstream.dart records both).
4. First release — publish 0.2.0 manually once (flutter pub publish), then enable pub.dev Admin → Automated publishing for this repo with tag pattern v{{version}}; version: is still 0.1.0 and the changelog heading is Unreleased pending that decision.
5. vance re-pin — VanceBeam moves respectReducedMotion → reducedMotion and can collapse its variant switch to BorderBeam(variant:).

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

---

Summary by cubic

Prepares the Flutter port for its first release as flutter_border_beam; the old package:border_beam/border_beam.dart import becomes package:flutter_border_beam/flutter_border_beam.dart, sprung is removed, and default rendering remains unchanged.

API and rendering

• Adds nullable BeamStyle, BeamShape, BeamTiming, and BeamPlayback with widget, BorderBeamTheme, and variant inheritance.
• Adds palettes, motion and playback controls, interaction widgets, BeamSync, driven beams, custom contours, and segmented rendering.
• Enforces timing and palette invariants, including release-time errors for empty color tables.
• Snapshots mutable palette inputs, reverses unfinished synchronized fade-outs, preserves phase-offset and line breathe/spike continuity during cycle retiming, and clears timeline corrections on every clock restart, including replacement clocks from variant changes.
• Preserves follow hand-backs across config rebuilds and retimes.
• Keeps segmented and faded layers within the measured saveLayer budget.
• Expands the example into a shareable playground with generated snippets and public API coverage.

Release and adoption

• Adds pinned Flutter CI, minimum-SDK testing, parity and golden tests, pub.dev OIDC releases, Pages deployment, and contributor documentation; CI uses actions/checkout v5 for the Node 24 runtime.
• Restructures the README into a centered hero, layered sections, and a consolidated API reference.
• Excludes repository-only tests and fixtures from the pub archive, reducing the package to about 847 KB.
• Existing callers must update imports and rename VanceBeam.respectReducedMotion to reducedMotion.
• Before release, confirm the security contact and CODEOWNERS, publish the first version manually, then enable automated publishing for v{{version}} tags.

^{Written for commit 292bb4e. Summary will update on new commits.}

[cubic-dev-ai]

All reported issues were addressed

Not reviewed (too large): test/fixtures/beam-spec.json (~5,731 lines) - if these are generated or fixture files, add them to ignored paths to exclude them from future reviews.

<sub>Note: This PR contains a large number of files. cubic selects up to 200 of the highest-priority eligible files for this review, so some files may not have been reviewed.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 7 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 62 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="lib/src/painting/strategies/pulse_common.dart">

<violation number="1" location="lib/src/painting/strategies/pulse_common.dart:8">
P2: When `border` is empty in a release build (asserts stripped), `border[index % border.length]` throws IntegerDivisionByZeroException during paint. The non-empty guarantee comes only from the debug `assert(border.isNotEmpty, ...)` in `BeamColors.spec`; every pulse layer indexes this list via `pulseBlobAt`, while the sibling ring loops (`border.indexed`) simply skip. Guard the empty case (e.g. `border.isEmpty ? return` at call sites or a fallback in `pulseBlobAt`) so an invalid palette degrades instead of crashing the paint.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: When border is empty in a release build (asserts stripped), border[index % border.length] throws IntegerDivisionByZeroException during paint. The non-empty guarantee comes only from the debug assert(border.isNotEmpty, ...) in BeamColors.spec; every pulse layer indexes this list via pulseBlobAt, while the sibling ring loops (border.indexed) simply skip. Guard the empty case (e.g. border.isEmpty ? return at call sites or a fallback in pulseBlobAt) so an invalid palette degrades instead of crashing the paint.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At lib/src/painting/strategies/pulse_common.dart, line 8:

<comment>When `border` is empty in a release build (asserts stripped), `border[index % border.length]` throws IntegerDivisionByZeroException during paint. The non-empty guarantee comes only from the debug `assert(border.isNotEmpty, ...)` in `BeamColors.spec`; every pulse layer indexes this list via `pulseBlobAt`, while the sibling ring loops (`border.indexed`) simply skip. Guard the empty case (e.g. `border.isEmpty ? return` at call sites or a fallback in `pulseBlobAt`) so an invalid palette degrades instead of crashing the paint.</comment>

<file context>
@@ -4,6 +4,10 @@ import '../../animation/oscillator.dart';
 import '../gradient_builders.dart';
 
+/// Reads a pulse table's color source, cycling a short custom spec palette.
+BeamBlob pulseBlobAt(List<BeamBlob> border, int index) =>
+    border[index % border.length];
+
</file context>

[rehmatsg]

Fixed in 7df65f4, though by rejecting the input rather than degrading. An empty table is a programming error, and this package already validates invalid public inputs in release (validateBeamTiming, validateRepeat), so BeamColors.custom and BeamColors.spec now call a new validateColorTable during resolution — a named ArgumentError at config time in both modes, rather than a stripped assert in debug and an IntegerDivisionByZeroException deep inside a pulse strategy in release. pulseBlobAt documents the resulting non-empty invariant. (The const hierarchy is why this cannot be a constructor assert: const constructors cannot evaluate List.length.)

[cubic-dev-ai]

All reported issues were addressed across 12 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 3 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

2 issues found across 8 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="lib/src/border_beam.dart">

<violation number="1" location="lib/src/border_beam.dart:962">
P2: When a timing update changes a line duration factor, this offset does not preserve the affected track's phase because it accounts only for the cycle ratio. Retiming must also react to factor changes and maintain separate offsets for breathe, spike, and spike2, or explicitly document and handle those changes as phase resets.</violation>
</file>

<file name="lib/src/animation/beam_phases.dart">

<violation number="1" location="lib/src/animation/beam_phases.dart:212">
P2: When a line beam is restarted after a cycle retime, `BeamClock.activate()` resets elapsed time but `breatheTimeOffset` still carries the old timeline correction. The breathe and spike tracks therefore start out of phase with the restarted travel and hue tracks; clear this offset whenever a hidden clock restarts, alongside `hueTimeOffset`.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P2: When a timing update changes a line duration factor, this offset does not preserve the affected track's phase because it accounts only for the cycle ratio. Retiming must also react to factor changes and maintain separate offsets for breathe, spike, and spike2, or explicitly document and handle those changes as phase resets.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At lib/src/border_beam.dart, line 962:

<comment>When a timing update changes a line duration factor, this offset does not preserve the affected track's phase because it accounts only for the cycle ratio. Retiming must also react to factor changes and maintain separate offsets for breathe, spike, and spike2, or explicitly document and handle those changes as phase resets.</comment>

<file context>
@@ -945,7 +951,16 @@ class _BorderBeamState extends State<BorderBeam> with TickerProviderStateMixin {
+    // above, which is bent by the gap, the phase offset, the hand-back, and
+    // any whole-period lift. Put them back on the rescaled timeline.
+    _setBreatheTimeOffset(
+      (before + _breatheTimeOffset) * newCycle / oldCycle - after,
+    );
   }
</file context>

[rehmatsg]

Documented rather than compensated, deliberately — 84935d4.

Preserving phase across a period change is not possible in the way it is across a cycle change, and the two are different operations. A cycle change rescales elapsed time, so every cycle-derived track rides through at the same fraction. A period change (a factor here, or huePeriod) redefines what a full period is, so there is no fraction to carry: whatever offset you pick, the track lands somewhere new. Compensating would just be choosing a different landing point.

This is also already the behavior of huePeriod and bloomHuePeriod, which nobody has treated as a bug. Adding three offsets to make the line factors phase-stable would have left those two — the ones far more likely to be changed at runtime — behaving the opposite way, so I would have traded one inconsistency for a worse one.

So the contract is stated on all five period-defining fields (breatheFactor carries the full explanation, the other four point at it), and on breatheTimeOffset, which now says explicitly that it corrects for a cycle change only. A test pins it: changing breatheFactor 1.3 → 2.6 mid-run re-phases lineH and leaves the clock, travelProgress, spike, and spike2 untouched — so a period change stays confined to its own track. Happy to implement the offsets if you would rather have all five compensated; it is a coherent alternative, just a larger one.

[cubic-dev-ai]

P2: When a line beam is restarted after a cycle retime, BeamClock.activate() resets elapsed time but breatheTimeOffset still carries the old timeline correction. The breathe and spike tracks therefore start out of phase with the restarted travel and hue tracks; clear this offset whenever a hidden clock restarts, alongside hueTimeOffset.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At lib/src/animation/beam_phases.dart, line 212:

<comment>When a line beam is restarted after a cycle retime, `BeamClock.activate()` resets elapsed time but `breatheTimeOffset` still carries the old timeline correction. The breathe and spike tracks therefore start out of phase with the restarted travel and hue tracks; clear this offset whenever a hidden clock restarts, alongside `hueTimeOffset`.</comment>

<file context>
@@ -195,9 +209,10 @@ class BeamPhaseResolver {
-        final breathe = (t / (cs * config.breatheFactor)) % 1.0;
-        final spikeT = (t / (cs * config.spikeFactor)) % 1.0;
-        final spike2T = (t / (cs * config.spike2Factor)) % 1.0;
+        final bt = t + breatheTimeOffset;
+        final breathe = (bt / (cs * config.breatheFactor)) % 1.0;
+        final spikeT = (bt / (cs * config.spikeFactor)) % 1.0;
</file context>

[rehmatsg]

Fixed in 84935d4, and the hole was bigger than breatheTimeOffset.

All three offsets — hueTimeOffset, breatheTimeOffset, travelTimeOffset — are corrections measured against the running timeline, so a restart to zero invalidates every one of them. _start() cleared only the hue offset, and only for a beam that owns its clock: a BeamSync member never runs _start() and is never told its group restarted, so its corrections survived indefinitely. Clearing breatheTimeOffset at that same call site would have fixed the case you found and left the other two.

So instead of clearing at the call site, BeamClock now announces the two places it zeroes elapsed time (activate() from hidden, and fade-out completion) through a listener list kept separate from its per-frame ChangeNotifier listeners — a reset happens only on a restart, so registering costs nothing per frame. The beam registers for whichever clock it is on, own or shared, and drops all three. That also lets _start()'s if (!_clock.isVisible) guess go away: the clock states the fact instead, including on the paths _start() never runs.

Two tests, both verified against the old code: an own-clock beam retimed then stopped and restarted (offset was 0.5, now 0), and a BeamSync group doing the same (offset was −1.5). With the notification removed entirely both fail. CI green on 84935d4, 1195 tests.

[cubic-dev-ai]

All reported issues were addressed across 5 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 2 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>