Module motion 

Motion primitives shared by gpui-ai components.

Every effect here is built on GPUI’s animation system, so reduced-motion mode resolves to a useful static frame automatically: one-shot reveals settle at their end state and repeating effects (shimmer, breathing) render at rest. Components opt in explicitly — nothing in this module installs idle redraw on its own.

The motion policy

No component spells out a duration. Every animated timing in the crate resolves through MotionTokens, one application-global policy that crate::init installs with the crate’s defaults and an application may replace once, up front, for all components at a stroke.

The policy speaks two vocabularies:

• Semantic roles, the consumer-facing surface: MotionTokens::instant, MotionTokens::quick, MotionTokens::standard, and MotionTokens::deliberate for durations, and the four spring roles — press, selection, disclosure, reflow — as SpringRole response/damping pairs. Components consume roles, never raw numbers.
• Named effects, the crate-internal table: each shipped repeating effect (shimmer, grid sweep, image pulse, status spinner, breathing, orb lattice) keeps its own tempo entry, because collapsing six tuned tempos into one “ambient” number would be a visual change wearing a refactor’s clothes. These readers stay pub(crate).

A progress loop is bound to work that ends: the element carrying it is gone once the work finishes. An ambient loop has no completion to report and runs for as long as its element is on screen. The instant role is zero by conviction, not omission: nothing in the crate delays or eases a direct response to input.

Reduced motion outranks the policy. Every effect here routes through GPUI’s animation system, whose reduced-motion contract no token value can override — a policy with ten-second durations still renders still frames when the platform asks for stillness.

Example

use gpui_ai::motion::{Shimmer, reveal};

// A "Thinking…" label with a travelling highlight while work runs.
Shimmer::new("thinking-label", "Thinking…").active(is_running);

// A freshly inserted row fades and rises into place once.
reveal(v_flex().child("New tool call"), ("tool-call", 3_usize), window, cx);

Structs

MotionTokens

The application-global motion policy: every duration, stagger beat, and spring response the crate animates with, resolved through one value.

Shimmer

Text with a soft highlight travelling across it — the ecosystem’s “something is happening” label treatment for thinking, running tool groups, and streaming plans.

SpringRole

A spring’s feel, as the pair the ecosystem tunes springs by: the response period and the damping ratio.

Enums

MotionPreference

How much of the described motion actually runs.

Functions

breathing

Slowly breathes an element’s opacity — for indicators that mean “still working” without a measurable progress value.

reveal

Fades and lifts an element into place once when it first mounts.

reveal_progress

Progress of a one-shot reveal keyed by id, from 0.0 (just mounted) to 1.0 (settled), starting the clock the first time the element renders.

reveal_staggered

Like reveal, but item index waits index stagger beats before it starts, so a list of chips or rows ripples into place.