presentation/widgets/common/confetti_overlay library

Classes

ConfettiOverlay: Full-screen confetti burst — N colored paper pieces rain down from the top, sway, spin, and fade out; the effect stops and hides itself after duration (unlike NeonBg/AuroraBgLayer, which run forever). Drop it in a Stack over a win/level-complete screen; give it a fresh key each time you want to retrigger it (a new key mounts a fresh particle set and ticker instead of reusing a finished one).
ConfettiParticle: One confetti piece's fixed randomized traits, generated once at spawn. Motion at any time t is a pure function of these traits (see confettiOffsetAt/confettiRotationAt/confettiOpacityAt) so the simulation is deterministic and unit-testable without building a widget.

ConfettiShape: Confetti piece shape — mixed randomly so a burst isn't visually uniform.

confettiOffsetAt(ConfettiParticle particle, double t) → Offset: Offset from its spawn point at t seconds since the burst started: falls straight down at ConfettiParticle.fallSpeed while swaying side-to-side on a sine wave. Pure function of (particle, t) — no widget/render state involved, so it's unit-testable on its own.
confettiOpacityAt(double t, double totalSeconds) → double: Opacity at t seconds into a totalSeconds effect: fully opaque until 70% elapsed, then fades linearly to 0 so the burst doesn't cut off abruptly. totalSeconds <= 0 is treated as already-finished (0).
confettiRotationAt(ConfettiParticle particle, double t) → double: Rotation (radians) at t seconds since the burst started.
generateConfettiParticles(int count, List<Color> colors, {Random? random}) → List<ConfettiParticle>: Generates count particles with randomized traits drawn from colors. Pure aside from random (pass a seeded Random for deterministic tests) — kept separate from the widget so "did we spawn the right number of particles, with colors from the given palette" is a plain unit test.