feat!: native single-pass shader renderer (0.2.0)
Why
Showing a beam heated phones. The 0.1.0 renderer emulated the React library's CSS layer stack on a Canvas: per frame 3–4 saveLayers, an ImageFilter.blur plus a MaskFilter.blur, five anti-aliased path clips, and full-rect dstIn masks, all re-rasterized on every vsync. The pulse variants' "30fps cap" only skipped repaints; the ticker still produced a frame every vsync.
Result
Nine 230×110 cards (three each of rotate, pulse, and 0.1's pulse-outside), dark theme, flutter run --profile -d macos --enable-impeller, FrameTiming over 6 s after a 3 s warm-up, measured during development:
| raster avg | raster p99 | build avg | frames in 6 s | |
|---|---|---|---|---|
0.1.0 (main) | 54.03 ms | 56.96 ms | 8.25 ms | 108 (~18 fps) |
| this PR | 0.45 ms | 1.13 ms | 0.35 ms | 713 (display-bound) |
About 120× less raster time. Release builds run smoothly on an iPhone at 120 Hz, but no FrameTiming profile has been taken on a phone.
What changes
Renderer. shaders/beam.frag evaluates every layer of an effect per pixel and composites them in one draw call — no saveLayer, clip, ImageFilter, or MaskFilter. Each layer follows the original design's construction (radial colour-blob stacks, conic windows and highlights, an edge-faded inner glow with an inset shadow, a hairline ring, a colour filter); every blur is analytic. test/render/frame_budget_test.dart asserts the one-draw budget across every effect × theme × palette × shape × instant.
Effects. BorderBeam(effect: BeamEffect.rotate() | line() | pulse()). small folds into rotate (compact tables at a short side ≤ 56 px); rotate gains length, count, and comet; line takes an edge. pulseOutside has no direct replacement (the CHANGELOG points at pulse() or rotate(comet: true)).
Motion. Fades run on critically damped springs (BeamSpringCurve, Apple's damping-ratio + response model): about 0.5 s in, 0.6 s out, in real time regardless of speed. The 0.1 spring overshot and was clamped, so its "0.5 s" fade-out actually cut to zero at 135 ms. The pulse's corners breathe in quicker than out.
Superellipse corners follow Flutter's own RSuperellipse construction (ported from impeller), so a beam sits on RoundedSuperellipseBorder at every aspect ratio: a 270×56 pill went from 3.5 px off to under 0.02 px, and a 200 px circle from 12.6 px to 0.02 px. A test renders the real shader at 3× and checks its distance against the Dart mirror.
Palettes. 19 presets (the 4 originals, 7 existing extras, 8 new), plus BeamColors(colors, stops:), .solid, .fromSeed, .fromScheme, .lerp, .scaleAlpha.
API. The CSS-emulation knobs are gone (renderScale, themeConfig, opacity factors, blur/brightness/saturation hooks, sparkle, arbitrary contours, …); BorderBeamThemeData gains effect; BorderBeam.precache() loads the shader early. Full migration table in the CHANGELOG.
Fixes (a defect list that had been pinned by skipped tests, now all passing): fades no longer scale with speed; a controller can move between beams in a frame and its speed composes with speedListenable; a cycleGap-only change keeps the sweep in place; a BeamSync member's retime no longer moves the group; releasing follow keeps a bouncing beam's direction; debugFrozenAt toggles at runtime; BeamDecoration honours repeat; non-finite inputs count as unset; the line's bloom stays blurred under a fixed hue (gold).
Example. A one-screen showcase: swipe between the three effects, each on the kind of widget it's for, with palette swatches and a theme toggle, on continuous corners. The playground, snippet generator, and share links are gone; CI gates the example on analyze and a web build.
Docs & media. README, doc/, CHANGELOG 0.2.0 (with migration table), CONTRIBUTING, and CLAUDE.md are checked against the code — every Dart snippet analyzes, every link resolves. Screenshots and the showcase reel are re-captured from this renderer.
CI & packaging. Actions pinned to SHAs with least-privilege permissions and timeouts; .pubignore no longer ships gitignored files (CI's archive had been 18 MB); stricter lints including comment_references; pana must score full marks. Decoupled from upstream: the transcribed constants, spec fixtures, parity tests, tool/spec/, and the drift workflow are removed; credits and the MIT notice are kept.
Since the first review
material_ui, Flutter ≥ 3.47. The package, tests, and example importmaterial_uiinstead of the deprecatedpackage:flutter/material.dart. ItsTheme/ColorSchemeare separate types from the framework's, soBeamTheme.autoreads amaterial_uitheme andfromSchemetakes amaterial_uiColorScheme; README, the theming guide, and the CHANGELOG give apps on the old import the migration command. The floor moves to Flutter 3.47.0 / Dart 3.13 (material_ui's), and the min-SDK job is now namedMinimum supported Flutterwith no version so later bumps don't rename a required check.- CI pins Flutter 3.50.0; all 92 goldens pass unchanged on it.
- API decisions:
attach/detachandclockOf/reducedMotionOfare hidden;BeamFocusRing.colorsis nullable, so style and theme colours reach it;controller.start()resumes a paused beam. - Reduced motion now holds a controller-driven beam still (
start()/resume()no longer tick understaticFrame/hide). A non-finite controller orBeamSyncspeed throws in release builds too. - cubic review: all 64 threads triaged against the current code: 47 fixed (one commit each), 12 obsolete after the effect removals, 5 declined with reasons on the thread.
- Dependabot #5 is merged to
mainand folded in: each action keeps its SHA pin, moved to the major Dependabot chose.
Verification
| analyze | tests | goldens | |
|---|---|---|---|
| Flutter 3.50.0 (CI pin) | --fatal-infos clean | 910 passed, 0 skipped | 92 / 92 |
| Flutter 3.47.0 (min) | clean | passed (CI) | — |
- pana full marks in CI;
dart pub publish --dry-run: no warnings,shaders/beam.fragincluded. - Example:
flutter analyze --fatal-infosclean,flutter build websucceeds.
For review
- Superellipse corners with uneven radii keep each corner to its own quarter of the box rather than Flutter's proportional split: exact in ordinary use, off by about 2% of the radius only where a half-short-side corner meets a square one.
- Branch protection still lists the old required check
Minimum supported Flutter (3.35.0); it should becomeMinimum supported Flutter. - After merge, watch the first Pages deploy from this branch's workflow: the build job has
pages: read; give itpages: writeifconfigure-pagesrefuses. - Follow-ups, not in this PR: the shader's per-layer colour matrix is now always the identity (filters fold on the CPU) and the dither toggle is always on, so both can be dropped from the uniform block.
rotate's inner glow andpulse's bloom replace the palette's alpha with a fixed design alpha, soscaleAlphadoesn't dim those two layers.
🤖 Generated with Claude Code