agent_thinking_orbs library

Dotted thought-orb loading indicators for AI & agent UIs in Flutter.

Ported directly from the React/iOS thinking-orbs specification with 100% geometry-exact parity, multi-theme auto-detection, and synchronized clocking.

Classes

Dot

A rendered dot primitive in 3D space with projection coordinates and ink properties.

Line

A stroked line edge between two projected points (e.g. for connecting mode).

OrbClock

Monotonic shared clock for all ThinkingOrb instances.

OrbFrame

One rendered instant: a complete, final set of draw instructions. dots is already z-sorted into draw order and radius-clamped; lines are drawn first.

Preset

Shipped preset values for a given mode and size.

ResolvedPreset

Resolved preset with effective mode, base speed, and fully scaled options.

ThinkingOrb

Dotted thought-orb loading indicator widget for AI and agent UIs.

ThinkingOrbPainter

Custom painter for rendering an OrbFrame onto a Flutter Canvas.

Enums

ModeKey

The 9 underlying geometry modes.

OrbSize

Rendered size preset.

OrbState

The nine shipped states — each a hand-tuned animation:

OrbTheme

Theme mode.

Constants

kCountKeys → const List<String>

Flat list count keys that scale linearly.

kCountPairs → const List<(String, String)>

Count pairs that scale with sqrt(scale) on each axis so total count scales by scale.

kIconDensityKeys → const List<String>

Icon density keys for morph outlines.

kRadiusKeys → const List<String>

Radius keys to scale together.

kStateToMode → const Map<OrbState, ModeKey>

Mapping from OrbState to internal ModeKey.

Properties

kBaseProfiles → Map<String, ModeOpts>

Base (fine) profiles per mode, before preset multipliers.

final

kModeFrames → Map<ModeKey, ModeFrameFunction>

Registry of mode frame generators.

final

kPresets → Map<ModeKey, Map<int, Preset>>

Shipped presets for all modes at both 64px and 20px sizes.

final

Functions

angleDelta(double a, double b) → double

Shortest signed angular distance, wrapped to (-π, π].

fibDir(int i, int n) → (double, double, double)

Stable directions on a unit sphere (Fibonacci lattice).

finalizeFrame(List<Dot> dots, List<Line> lines, [double rMin = 0.3]) → OrbFrame

Turn raw mode output into a finished frame: drop invisible marks, clamp radii to the mode's floor, and stably z-sort far→near into draw order.

frac(double x) → double

Fractional part of x, matching x - Math.floor(x) in JavaScript.

frameBraid(double size, double t, ModeOpts o) → OrbFrame

Braid mode: weaving — three strands plait around the sphere.

frameGlobe(double size, double t, ModeOpts o) → OrbFrame

Globe mode: searching — a scan meridian sweeps a dotted globe.

frameMorph(double size, double t, ModeOpts o) → OrbFrame

Morph mode: shaping — a dotted outline cycling circle → triangle → square → circle.

frameOrbits(double size, double t, ModeOpts o) → OrbFrame

Orbits mode: working — particles on tilted orbits.

frameRibbon(double size, double t, ModeOpts o) → OrbFrame

Ribbon mode: composing (ribbon) and breathing (ring).

frameRubik(double size, double t, ModeOpts o) → OrbFrame

Rubik mode: solving — bands twist in quarter turns, scramble → solve.

frameWave(double size, double t, ModeOpts o) → OrbFrame

Wave mode: listening — a waveform rolls through latitude rings.

frameWeb(double size, double t, ModeOpts o) → OrbFrame

Web mode: connecting — a constellation wires itself with packets.

hashD(double a, double b) → double

Deterministic hash in [0, 1).

lerp(double a, double b, double f) → double

Linear interpolation between a and b by factor f.

makeProj(double yaw, double tilt, double cx, double cy, double scale) → Projector

Shared spin + tilt + orthographic projection.

radiusScale(double size, double pow) → double

Sub-linear radius scaling: keeps small spinners legible.

resolvePreset(OrbState state, int sizeDimension) → ResolvedPreset

Resolves an OrbState and dimension (e.g. 64 or 20) into its ResolvedPreset.

scaleCounts(ModeOpts opts, double scale) → ModeOpts

Scales count parameters in opts according to the spec scaling rules.

scaleRadii(ModeOpts opts, double scale) → ModeOpts

Scales all radius parameters in opts by scale.

vnoise(double x, double y) → double

Value noise on a 2D lattice — smooth, deterministic, cheap.

Typedefs

ModeFrameFunction = OrbFrame Function(double size, double t, ModeOpts opts)

Geometry function signature for a single instant.

ModeOpts = Map<String, double>

Mode options map.

Projector = (double, double, double) Function(double x, double y, double z)

A 3D projection function mapping (x, y, z) to 2D screen (px, py, depth z).