Skip to content

Rename to prismatic and add DistortionWave - #7

Merged
rehmatsg merged 114 commits into
mainfrom
feat/prismatic
Nov 17, 2026
Merged

rehmatsg merged 114 commits into
mainfrom
feat/prismatic

Conversation

@rehmatsg

@rehmatsg rehmatsg commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

What this does

Renames the package to prismatic and adds a second effect, DistortionWave: a colourful, refractive wave that carries one screen into the next. BorderBeam behaves exactly as before; its goldens are byte-identical across the rename and restructure.

In this PR

Rename and restructure

  • flutter_border_beam becomes prismatic (it was never published). Each effect has its own library (border_beam.dart, distortion_wave.dart); prismatic.dart exports both.
  • lib/src is split into core/, border_beam/ and distortion_wave/. The tests follow the same layout.
  • outline() moves into the shared shaders/common/outline.glsl.

DistortionWave

  • The DistortionWave widget, DistortionWaveRoute, DistortionWaveAnchor and WaveSource, a controller, a theme, WaveStyle and its groups, and palettes.
  • Rendering: both screens are drawn from GPU pictures of themselves, in one shader draw plus one atlas draw per frame.
    • No saveLayer, BackdropFilter or ImageFilter on the canvas.
    • Runs on Impeller, Skia and the web.
  • Calibration: checked against the SwiftUI original by rendering both at the same moments (mean difference about 1/255), then pinned by goldens.
  • Display corners: when a wave fills the screen, its light follows the display's own corners (MediaQuery.displayCornerRadii), each corner with its own radius. Tested on a phone with mixed sharp and round corners.

Fixes from an independent review

  • The route made a CurvedAnimation every frame and never disposed it.
  • The dots' disc image was never disposed.
  • The hidden screen could take keyboard focus.
  • Anchors ignored keyboard and screen-reader activation.
  • In release builds, a style value could reach the shader as NaN or divide by zero.
  • A WaveSource.key was measured only once.

Each fix has its own commit and a test that fails without it. The lifecycle and route tests now run under the leak tracker.

Example and docs

  • Example app: a full-screen wave showcase with an options panel. On iOS it reads the display's corners.
  • README: short and written for people, with a demo clip for each wave type.
  • doc/: the complete reference, written for agents, starting at doc/README.md.
  • AGENTS.md: the agent guide for Codex; CLAUDE.md imports it.
  • CHANGELOG: one entry for the first release.

Checks

  • dart format, flutter analyze (0 issues), and the example's analyze with --fatal-infos
  • flutter test --exclude-tags golden: 1116 tests passed
  • flutter test --tags golden (macOS, Flutter 3.50.0): 107 passed
  • Wave tests under --enable-impeller (Vulkan on SwiftShader)
  • dart pub publish --dry-run: the archive is 1 MB and includes the shaders and their includes
  • Release build run on a physical iPhone

When merging

  • Merge method: use a merge commit, not a squash. The commits are separate on purpose.
  • Order:
    1. Rename the repo to SimplifyJobs/prismatic just before merging. GitHub forwards this PR and the old git URLs.
    2. Merge. The Pages deploy that the merge triggers then builds the live demo at /prismatic/, and the issue-template and pubspec links resolve straight away.
    3. Point the repo's homepage at pub.dev/packages/prismatic and update local remotes.
  • pana: the pub.dev score job fails until the rename, because the pubspec's repository, issue and docs URLs point at SimplifyJobs/prismatic. Everything else in pana passes, including the MIT license.
  • First publish: run flutter pub publish once by hand. Then turn on pub.dev's automated publishing for tag v{{version}}.

Not in this PR (worth deciding before 0.3.0)

  • material_ui is a hard dependency used for one brightness lookup. An app on package:flutter/material.dart gets the light look unless it sets BeamStyle.theme.
  • Naming between the two effects:
    • BeamTheme (an enum) sits next to the BorderBeamTheme widget.
    • colors vs palette.
    • active vs revealed.
    • seek(Duration) vs seek(double).
  • onFinish can still fire when progress: is set during a run.
  • BeamFocusRing, BeamHover and BeamPress ignore BorderBeamTheme.effect.

🤖 Generated with Claude Code

rehmatsg and others added 30 commits November 16, 2026 13:35
The package becomes the home for every shader effect, with BorderBeam the
first. flutter_border_beam was never published, so nothing is left behind
on pub.dev.

- pubspec name, URLs and version 0.3.0; CHANGELOG notes the rename
- lib/prismatic.dart re-exports lib/border_beam.dart (the old barrel)
- shader asset key and error library name use `prismatic`
- example app package, bundle ids, web metadata and Pages base-href
- CI, issue templates, docs and CLAUDE.md

The API is unchanged and every golden is byte-identical.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The package will hold more than one effect, so the beam's code moves under
lib/src/border_beam/ and its tests under test/border_beam/, and code every
effect shares goes in lib/src/core/.

BeamProgram becomes ShaderProgram (core), one instance per shader with its
own `ready`, keeping the per-zone load sharing and the retry after a failed
load; the beam's instance is `beamProgram`. Docs, CONTRIBUTING, the PR
template and .pubignore follow the new paths.

No behaviour change: every golden is byte-identical.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
outline() and the rounded-superellipse helpers move from beam.frag to
shaders/common/outline.glsl and take the radii, corner model, quadrant
starts and perimeter as arguments instead of reading beam's uniforms, so
the coming wave shaders draw their edges on the same corners. impellerc gets
the shaders directory as an include path (since 2024, well under the 3.47
floor); the .glsl is not listed under flutter: shaders: and ships with the
package.

beam.frag's header names its effect again rather than the package. Every
golden is byte-identical and the GPU-vs-BeamOutline test still passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The pure half of DistortionWave, ported from DistortionWavesKit's
WaveFront, WaveParticle and WaveRim as a reference for the look:

- WaveFrame.at: where the wave is at any progress — the front (a pill
  opening into an arc, or a ring), gravity, swell, glow, the edge and
  hairline wipes, and whether each side shows — as a pure function, so it
  scrubs, reverses and freezes for goldens
- WaveParticle (deterministic dots) and WaveRim (the edge lumps)
- WaveClock: one Ticker driving progress, interruptible without a jump
- WaveStyle and its groups (WaveTiming, WaveMotion, WaveLens, WaveGlow,
  WaveDots), all-nullable with merge, over per-type tuned defaults
  (look/wave_defaults.dart); WaveSpec settles them into seconds and pixels
- WavePalette: the reference's five palettes, single(), fromBeamColors()
- core/oklab.dart: OKLab conversion for palettes mixed per pixel

Tests port every WaveFrontTests case, plus a seeded property sweep,
the clock, the value objects and OKLab.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
wave.frag draws the whole transition in one pass over GPU images of the
two sides: the field (one signed distance to the front), the lens (one
rise per pixel, plus the pull toward the source), a progressive blur mixed
from the sharp side and two blurred copies by the radius each pixel
should have, the crossfade at the front, five-tap colour fringing along
the displacement, and the colour over it — the band on the front, the rim
and the hairline on the view's continuous corners — mixed in OKLab.
wave_glow.frag is the colour alone, for the end of the wave when the
revealed side is drawn as itself.

Both include one uniform block (common/wave_uniforms.glsl, vec4s only,
120 floats) packed by WaveFrameData, and the shared field, colour and
outline code; impellerc compiles both for Metal, Vulkan, GLES and SkSL.
The uniform-layout parser moves to test/support and follows #include;
the wave's layout test checks both shaders, the sampler order, the
arrays, the loops and every writer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
DistortionWave(revealed:, revealedChild:, child:) runs the wave between
two views. RenderWaveStage picks a phase each frame:

- rest: the visible side, as itself; nothing else
- distorting: both sides from GPU images (WaveSideImages: a detached
  OffsetLayer rasterised with toImageSync, as SnapshotWidget does, plus two
  small blurred copies baked once), drawn by wave.frag in one drawRect,
  with the dots in one drawRawAtlas — no layers, clips or filters
- glowing: the revealed side as itself under wave_glow.frag
- crossfading: reduced motion, or a side that cannot be rasterised

A side is pictured when first needed and again only when its content
repaints (RenderWaveSide catches the markNeedsPaint on its way up), or
every frame with WaveSnapshots.everyFrame; pictures are released as soon
as the content no longer bends.

Also: DistortionWaveController (reveal/collapse/toggle/seek; owns
playback when attached), DistortionWaveTheme, WaveSource (rect, key, of)
and DistortionWaveAnchor, which gives the wave its button and touch with
no geometry plumbing; progress: holds the wave for screenshots.

Tests: behaviour, lifecycle, the per-phase frame budget, snapshot counts
and where pixels land in real frames.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A PageRoute that plays the wave from the widget that pushed it into the
new page, and collapses it back on pop:

  Navigator.of(context).push(DistortionWaveRoute(
    source: WaveSource.of(context),
    builder: (_) => const ReceiptScreen(),
  ));

The route's animation drives the same WaveStage as DistortionWave. The
page underneath is pictured from its route's own RepaintBoundary once the
push's first frame has painted it (until then the stage draws nothing over
it, so nothing jumps), and again as a pop starts; it plays no exit
transition of its own meanwhile (canTransitionFrom is false). The collapse
runs on the wave's easing; reduced motion makes it a 0.3 s crossfade.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Each wave type at the moments that show its parts — the pull before the
launch, the launch, the front crossing, the colour left on the edges — and
three palettes on the front: 14 scenes, macOS-generated on 3.50.0.

The scenes are the ones the look was calibrated on: DistortionWavesKit
built in a throwaway SwiftUI harness and rendered at the same progress
over the same mock screens differs from these by about 1/255 on average
(95% of pixels within 6/255; under 0.4% past 24/255, the dots' edges and
the edge lumps, whose positions follow Flutter's superellipse perimeter).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A side whose top and bottom differ, early in the pull where nothing far
from the source is bent, must show as it is: a picture sampled upside down
on some backend fails here. Passes on the default tester and under
`flutter test --enable-impeller` (Vulkan), where the wave's other render
and widget tests pass too and its frames differ from the goldens by under
1.3/255 on average.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- DistortionWave.precache() also draws both wave shaders, a blurred bake
  and an atlas once into a 4x4 offscreen image, so the GPU builds their
  pipelines before the first wave's first frames (the first wave's worst
  frame in a profile run on macOS/Impeller fell from 54 ms cold to 3 ms).
- Once a reveal no longer bends the revealed side (the edges' colour is
  still lingering), that side takes touches: "Done" no longer feels dead
  for a second and a half.
- A wave held with `progress:` opens from the anchor pressed last, as a
  running one does; letting go plays on from where it was held instead of
  jumping to the clock's resting value.
- DistortionWaveController.collapse and toggle take a `source`, as reveal
  does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A waves button in the header opens the DistortionWave page (pushed with a
DistortionWaveRoute): three swipeable demos — Send money (vertical, from
the Send button), a step-by-step flow (horizontal, from a side tab, with
Back) and a 500 pt success sheet (center, from its avatar) — with a type
selector, palettes (the five presets plus two border-beam palettes via
fromBeamColors), a scrub bar that holds the wave and lets it play on, and
a Route pill that pushes a full page. lib/wave_reel.dart records the
waves with tool/record_demo.sh; main.dart and the demo harness precache
the wave's shaders.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- README: one overview for both effects; the beam's docs move under
  "## BorderBeam" unchanged; a new "## DistortionWave" section (quick
  start, routes, types, palettes, style groups, control, how it renders,
  limits), with accessibility, performance, FAQ, example and credits
  updated for it
- doc/distortion_wave.md: how the wave is built — timeline, phases,
  pictures of the sides, the shader step by step, the uniform block, the
  route, invariants and calibration; architecture.md points to it
- CLAUDE.md: both effects' architecture, map, hard rules and test
  conventions; fixes the historical golden path the restructure rewrote
- CHANGELOG 0.3.0: the DistortionWave entry; LICENSE: the Distortion
  waves notice; pubspec: description, topics and two wave screenshots;
  CONTRIBUTING: the wave's rendering rules

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
When nothing sets WaveGlow.cornerRadius (neither the wave's style nor a
theme) and the stage fills the whole view, the colour on the edges and
the hairline follow MediaQuery.displayCornerRadii instead of the type's
default radius, so they sit on the glass on every device. Android's
engine reports the display's radii (Flutter 3.42+); on other platforms an
app can supply them with MediaQueryData.applyDisplayCornerRadii. A wave
that does not fill the view, or a radius set explicitly, is unchanged.
DistortionWaveRoute does the same.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
From a review of the wave shaders' per-pixel cost (pixel-exact unless
noted, verified against every golden and on every backend):

- at most two texture fetches per side per tap: past the near blur level
  the sharp fetch was dead, and past the far level the near one
- the colour is gated by region before the outline is worked out, with a
  lower bound on the inset (the outline contains the box with its corners
  cut where the straight edges end); per-pixel atan/sin/cos only where the
  ring or the rim needs them
- the lens's and the pull's exp/length only while energy or gravity act
- wave_glow.frag rules most of the view out before the outline, and stops
  before the field where the rim has faded below a level
- a pixel with under 0.002 of the near copy (a blur of under a fifth of a
  point) shows the sharp side alone: far from the front a pixel is now one
  fetch (goldens move by at most 1/255 on at most 226 pixels; regenerated)

About a quarter fewer texture fetches and a fifth fewer transcendentals
per frame through the crossing, more far from the front. Also fixes an
undefined atan(0, 0) at a ring's centre and a one-pixel line along the
pill's spine while it opens.

CLAUDE.md: after editing only shaders/common/*.glsl, clear build/ and
touch the .frag files — flutter test can run stale compiled shaders.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- On a phone the send and step demos fill the screen edge to edge, with
  the device's real status bar and home indicator, so the wave can be
  tried at full size; the success sheet sits at the bottom at the height
  the center wave is tuned for. The options (demo, palette, the bar that
  holds the wave, a page opened on a route) slide in from a slim tab on
  the right edge and turn see-through while the wave is held. On a wide
  screen they sit in a side bar beside a framed phone.
- The display's corner radius: Flutter reports it on Android; on iOS the
  example's app delegate reads the screen's private corner radius (key
  assembled at run time, checked with responds(to:) first) and the app
  puts it in MediaQuery with applyDisplayCornerRadii, so a wave that fills
  the screen follows the glass. The package itself reads only the public
  MediaQuery value.
- README and CHANGELOG describe the display-corner behaviour.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The edges' colour and hairline followed one radius: the display's four
averaged, or the spec's. A display whose corners differ (some phones'
top and bottom corners do) put the colour off the glass at two of them.

The wave shaders now get all four radii in a new uRadii uniform,
appended to the block (124 floats; no offset moves), and outline() uses
them, as the beam's always could. uBand.w becomes the largest corner,
which keeps the region gate's bound conservative. The stage follows
MediaQuery.displayCornerRadii corner by corner while it fills the view.
Goldens are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The edges' colour and hairline ran at full strength up to the outline and
past it, so the app's clip made the only cut — and clips on Impeller are
not anti-aliased, which showed as jaggies where bright colour met the page
around a sheet's corners. The colour now fades out across one device
pixel at the outline, so its edge is smooth by itself; the content under
it is untouched. Goldens change only in the corners outside the outline.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The iOS display has four corners of its own on some devices (the iPhone
Duo's left corners are 8 pt, its right ones 59 pt), and the screen's
private corner radius gives one number. On iOS 26 and later the app
delegate now asks UIKit's public concentric-corner API instead: a hidden
window-sized view with corners concentric to its container reports each
corner's effective radius — the display's. The private single radius
remains only as the fallback before iOS 26, whose devices have equal
corners. The radii go into MediaQuery corner by corner.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The rim's lumps and its shimmer were placed by the arc length of the
nearest point of the outline. Inside a corner that point flips from one
edge to the other across the corner's diagonal; with a round corner the
flip lies deeper than any colour, but with a sharp one (the iPhone Duo's
8 pt corners) it ran through the lit rim as a line.

The rim now goes by its own coordinate along the edge (waveEdgeAt): arc
length on a box whose corners are circular with a radius at least as deep
as the rim reaches, so inside a corner a point goes by its angle round
that arc and the flip happens only where nothing is lit. A structure test
walks across every corner's diagonal at several depths: the old
coordinate fails it (a 47-level step), the new one passes. The lumps sit
a few dozen points differently along the edges; goldens regenerated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The rim's depth was the distance to the outline, which creases along a
corner's diagonal where the nearest edge changes: round a sharp corner
(the iPhone Duo's 8 pt ones) the colour turned from one edge to the next
along a mitre. Its depth now eases the distances to the two edges meeting
there into each other (a smooth minimum over 2.5 rim widths), so the
colour turns smoothly and pools a little into the corner; round a round
corner the outline's own distance is the smaller and nothing changes. The
hairline still sits on the glass, and the early-outs widen by the extra
reach. Goldens move by at most 6/255 near corners.

The seam test now measures spikes — a step far above its neighbours —
rather than steep steps, which the edge of a lump also makes: the old
coordinate fails it with a 72-level spike, the current shader passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Easing the crease was not enough where a display's corners differ: the
colour still followed each corner as it is, so the iPhone Duo's 8 pt left
corners turned it through near-square corners beside the 59 pt round ones
on the right.

The rim's depth is now measured as if every corner were as round as the
view's roundest (and never sharper than the easing), so the colour
follows the same curve round every corner. The sliver between that curve
and a sharper corner is lit as the glass edge is, so the light fills the
corner rather than turning a square; deeper than the curve the two edge
distances stay eased. The hairline still traces each corner as it is.
The early-out bounds widen by the largest such gap.

A new golden pins a full-view wave on corners of 8, 59, 59 and 8 pt; the
others move by at most 6/255 near corners.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Measuring the rim's depth to a corner rounded to the roundest radius made
its curve smooth, but lit the whole sliver between that curve and a
sharper corner at the glass edge's brightness: the iPhone Duo's 8 pt
corners filled with light, heavy beside the slim curve of light along its
59 pt corners.

The depth is now signed: the colour is brightest along the round curve
and fades out past it into the sliver as it does inward, so a sharp
corner shows the same slim curve as a round one, its tip as dark as the
glass beyond a round corner's curve. The hairline still traces the corner
itself. Only the mixed-corner golden moves (the others by a pixel).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A full-screen demo drew the mock status bar wherever the top safe-area
inset was zero — which it is on a device whose status bar sits at the
side, so the iPhone Duo showed a fake "9:41" over the real one. Screens of
a full-screen demo now always leave the real inset and draw no mock.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The rim's light now turns each corner along that corner's own radius, as
the hairline does: on a display whose corners differ (the iPhone Duo's
8 pt left and 59 pt right corners) it hugs the sharp corners tightly and
the round ones along their curve, rather than following the roundest
corner everywhere. Deeper than a corner's radius, where the distance to
the outline would crease along the diagonal, the two edge distances stay
eased into each other, so the light's inner edge turns smoothly. The
early-out slack shrinks to match. The mixed-corner golden moves; the
others by at most 2/255.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The colour faded over one device pixel centred on the view's outline. A
view the app clips to that outline (the success sheet) is cut by a clip
that on Impeller is not anti-aliased, and it cut through the still-lit
outer half of that fade, leaving a bright staircase round the sheet's
corners while the wave ran (at rest the same staircase is dark on dark).
The fade now ends just inside the outline, so the clip only meets
already-dark pixels. Goldens change in the one-pixel ring at the outline.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The corners were measured once, at launch; rotating a phone whose corners
differ left the wave's light on the wrong ones. DisplayCornersScope now
measures again once the frame for a new window size or orientation is
laid out, and puts the result in MediaQuery. Outside release builds each
measurement is logged, and the options panel shows the radii the waves
follow (top-left clockwise), so what a device reports can be read off it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Round a round corner the rim is one band of light following the outline,
as the glass does. Round a sharp one no single band could bend without
showing it: along a mitre, filling the corner, or (last) bowing into a
notch where a thick stretch on one edge met a thin one on the other.

Now each of the two edges meeting at a sharp corner glows on its own,
with its own thickness where the point falls on it, and the two overlap
at the corner as light along a frame does. Corners blend between the two
models by their radius next to the rim's width, so round corners are
untouched (goldens identical) and only the mixed-corner golden moves. The
extra work runs only where both edges of a sharp corner reach.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
With each edge of a sharp corner glowing on its own, each carried its own
thickness right into the corner: a thick stretch on one edge beside a
thin one on the other left the corner lit on one side and short of light
on the other. Now, right at a sharp corner, both edges are as thick as
the corner is, and each eases into its own thickness over the rim's
reach, as thickness eases along a round corner's curve; the corner is lit
evenly. Only the mixed-corner golden moves.

The colour-only shader's thickness early-out also no longer applies
inside a sharp corner, where a pixel's light comes from two edges and its
own thickness says nothing about them (it cut nothing in the frames
checked, but it could).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The white disc the dots are drawn from was cached in a static map shared
by every wave in the process and never disposed, so an app's own leak
tests flagged it. Now each wave keeps its own disc (a few hundred bytes,
drawn once per size) and disposes it with itself.

The lifecycle tests now run under the leak tracker, so every wave they
build and tear down must dispose what it made.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`buildTransitions` runs on every frame of a transition, and the route
built a new `CurvedAnimation` there each time. Each one added a listener
to the route's animation and was never disposed: one push and pop left
dozens behind. The route now makes the curve once and disposes it with
itself.

The route tests now run under the leak tracker, with a push-and-pop test
of their own.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
rehmatsg and others added 21 commits November 16, 2026 18:19
performance.md said the stage's canvas never gets an image draw, while
its own table lists a `drawRawAtlas` for the dots, which draws a sprite
image. It now names the excluded calls, `drawImage` and
`drawImageRect`, and calls out the dots' atlas as the one image the
stage draws.

Reported by cubic-dev-ai on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
performance.md said the stage and spec uniforms are rewritten only when
they change, but `_writeUniforms` calls `setStage` on every paint; only
the spec is written once and again when it or the corners change. The
sentence now says that.

Reported by cubic-dev-ai on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The architecture doc listed `Oklab` as code both effects share, but
only the wave uses it. It, the wave's internals doc and the agent
guide's intro now list `ShaderProgram` as the shared code and say
`Oklab` lives in `lib/src/core/` but only the wave uses it.

Reported by cubic-dev-ai on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The agent guide, and the architecture doc's look table, quoted the
compact-chip threshold as 56px, a tuned look value hard rule 8 says not
to quote. Both now name the constant, `compactMaxExtent` in
`look/rotate_look.dart`.

Reported by cubic-dev-ai on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
effects.md named `look/rotate_look.dart` relative, while the rest of the
doc uses full `lib/src/border_beam/…` paths. It now gives the full path,
so readers can find `compactMaxExtent`.

Reported by cubic-dev-ai on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`WaveRim.thickness`'s doc called its shader counterpart `rimThickness`;
the shader function is `waveRimThickness` (`shaders/common/
wave_colour.glsl`). The doc now names it.

Reported by cubic-dev-ai on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`reveal`'s doc said the wave opens from the given source, but like
`collapse` and `toggle` it takes one only when the run starts from rest;
mid-run it keeps the source it opened from. The doc now says so.

Reported by cubic-dev-ai on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The usage doc's route example called `WaveSource.of(context)` with a
context outside any `DistortionWaveAnchor`, so it measured the
surrounding widget and carried no touch, while its comment said it
carried one. The example now wraps the button in an anchor and takes
the context from a `Builder` inside it.

Reported by cubic-dev-ai on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The pubspec described the package as built for Impeller with one draw
per frame, which contradicts the docs: the wave runs on Skia and the
web too, and draws a shader plus at most one atlas per frame. It now
says built for Impeller and also runs on Skia and web, and drops the
draw count; it is also back under pub.dev's 180 characters.

Reported by cubic-dev-ai on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The library doc said the wave is drawn by one fragment shader, but it
uses two, `wave.frag` and `wave_glow.frag`, plus an atlas draw for the
dots. It now says fragment shaders, with the dots in one atlas draw.

Reported by cubic-dev-ai on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The center type's doc said the source gets no pull, swell, blur or
colour, which read as if its tuned look zeroed those, while
`wave_defaults.dart` sets a pull, swell and blur. What holds is the
source region: the shader's hold keeps it out of the bend and the
colour. The doc now says the pull, swell and blur bend what is round
the source and never the source, and names what the tuned look does
zero: the colour and dots gathered before the launch, and fringing.

Reported by cubic-dev-ai on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The doc said the stage and the spec are written only when they change,
but the stage calls `setStage` on every paint; only the spec is kept
until it or the corners change. The doc now says so.

Reported by cubic-dev-ai on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The comment on the field's x metric was hard to parse and seemed to
contradict the code: `mx = q.x * squash` scales the x metric up, which
makes the front narrower across. It now says that scaling x up by a
squash of 1 or more gives the front a sideways reach of
radius / squash, narrower than a circle of the same radius, which keeps
it bowed as it grows. Comment only.

Reported by cubic-dev-ai on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The bug report's version placeholder was still 0.2.0, which was never
published as prismatic; this release is 0.3.0.

Reported by cubic-dev-ai on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The example's web manifest still used `border beam` as its short name,
so an installed copy kept the old branding. It is now `prismatic`.

Reported by cubic-dev-ai on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The recording command in `wave_reel.dart` (and in the agent guide)
omitted `--no-crop`, so `record_demo.sh` cropped to a centred band that
cuts the reel's full-screen scenes. Both now pass it, as
`example/README.md` already does.

Reported by cubic-dev-ai on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The example README said the demo fills the screen on a phone, but the
success sheet sits at the bottom of it. It now says the send and step
demos fill the screen and the success sheet sits at the bottom.

Reported by cubic-dev-ai on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`DisplayCorners.radii` said it held the radii last measured, but only
`load()` wrote it: a re-measurement after a rotation never reached it,
so a scope created later started from the launch-time corners.
`measure()` now keeps every successful measurement, and `load()` is a
first measurement.

Reported by cubic-dev-ai on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`DisplayCornersScope` returned its child bare until the radii arrived
and a `MediaQuery` around it after, so the change remounted the whole
app below it, resetting navigation and any wave in flight. It now
always returns the `MediaQuery`, with the radii applied only once there
are radii to apply.

Reported by cubic-dev-ai on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… screen

The iOS 26 path measures the key window (or the first), but the
pre-iOS 26 fallback read the screen of the first connected scene, which
need not hold that window. Both paths now pick the window once, and the
fallback reads the screen of that window's scene.

Reported by cubic-dev-ai on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The scrub bar exposed only a slider role and a label, so a screen
reader could neither read where the wave is nor move it. It now reports
the wave's progress as a percentage, with the values a step up and down
would reach, and its increase and decrease actions step the wave by a
tenth as a short drag would: held at the new point, then let go to play
on.

Reported by cubic-dev-ai on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
devin-ai-integration[bot]

This comment was marked as resolved.

Each screen-reader increase or decrease started a hold and ended it at
once, so a wave at rest played straight back to its nearer end and
stepping could never advance it. A step now holds the wave at the
stepped point, as a drag does, and further steps move the hold; the
wave is let go — to play on — when the screen reader's focus leaves the
bar, or three seconds after the last step. A drag takes the hold over,
and a bar disposed mid-hold lets go after the frame (the page ignores a
let-go once it has gone).

Reported by devin-ai-integration on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
cubic-dev-ai[bot]

This comment was marked as resolved.

rehmatsg and others added 4 commits November 16, 2026 18:42
Letting go of a held `progress` starts the clock without the controller
asking, so the controller's listeners never heard that `isRunning` had
turned true; they heard only the arrival. The wave now tells the
controller when that run starts (not when it arrives at once, which
already notifies).

Reported by cubic on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The usage doc said the constructors assert every documented range, but
the length minimums (`lead`, `tail`, `rimWidth`, `rimSoftness`) are only
applied when `WaveSpec` settles the style. The Validation paragraph now
says which ranges are asserted in debug builds and that the minimums are
raised silently, in every build mode.

Reported by cubic on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The cache test stopped at four specs, so a regression to first-in,
first-out eviction, or to none, would have passed. A fifth spec now
pushes out the one used least recently, while one used again is kept.

Reported by cubic on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
SECURITY.md said the package has no runtime dependencies beyond the
Flutter SDK, but the pubspec declares `material_ui`, which the beam reads
its surface's theme from.

Reported by cubic on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
devin-ai-integration[bot]

This comment was marked as resolved.

Letting go of a hold told the controller its run had started from inside
`didUpdateWidget`, so a controller listener that rebuilt an ancestor of
the wave called setState during the build and threw. The notification
now waits until after the frame, and is skipped if the wave has gone or
the run has already ended by then.

Reported by Devin Review on #7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant