gpui-motion-kit 0.4.0

Declarative, interruptible animations and text motion for GPUI Kit
Documentation

gpui-motion-kit

Declarative animation for native Rust apps built with GPUI Kit.

Keep the motion state in your view and describe its next destination. The adapter connects the shared gpui-ce-motion engine to Kit's elements, executor clock, frame scheduling, and reduced-motion preference. No JavaScript or renderer fork.

Crates.io · Published API reference · Product examples · Text gallery

Version 0.4.0 uses the shared gpui-ce-motion 0.3.0 engine and adds reactive values, nested orchestration, typed timelines, spatial helpers, rich text and formatted numbers. Explore the nine-scene motion_lab or the eight-scene helper gallery.

Install

[dependencies]
gpui-motion-kit = "0.4"
gpui-kit = { version = "=0.7.3", features = ["component", "assets"] }

Requires Rust 1.95+ and GPUI Kit's native build prerequisites. This release supports Kit 0.7.3 with its default gpui-pre backend. Use the same Kit version throughout your application; the alternative gpui-fast backend is not supported. macOS is covered by native CI. Linux API documentation builds in CI; Linux/Windows application behavior has not been validated.

You do not need a direct gpui-ce-motion dependency. Portable types such as Motion, Target, and Transition are available through gpui_motion_kit::core. Import native states from gpui_motion_kit, and UI types from gpui_kit. Do not enable the core engine's CE-specific gpui feature for this integration: Kit and CE native types belong to different GPUI crates and cannot be mixed.

Quick start

This complete application animates a panel containing a normal Kit button. Click repeatedly while it moves to interrupt the spring smoothly.

use gpui_kit::{
    AppContext, Context, Render, Window, WindowOptions,
    assets::Assets,
    component::{ActiveTheme, button::Button},
    div, prelude::*,
};

use gpui_motion_kit::{
    MotionState,
    core::{Motion, Target},
};

#[derive(Default)]
struct Panel {
    expanded: bool,
    motion: MotionState,
}

impl Render for Panel {
    fn render(&mut self, window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
        let width = if self.expanded { 320.0 } else { 180.0 };

        let target = Target::default()
            .width(width)
            .height(96.0)
            .border_radius(16.0);

        let frame = self.motion.frame(Motion::new(target), window, cx);

        let panel = div()
            .p_4()
            .bg(cx.theme().secondary)
            .child(
                Button::new("resize-panel")
                    .label("Resize panel")
                    .on_click(cx.listener(|this, _, _, cx| {
                        this.expanded = !this.expanded;
                        cx.notify();
                    })),
            );

        div()
            .size_full()
            .p_8()
            .bg(cx.theme().background)
            .text_color(cx.theme().foreground)
            .child(frame.apply(panel))
    }
}

fn main() {
    gpui_kit::application().with_assets(Assets).run(|cx| {
        gpui_kit::init(cx);

        gpui_kit::open_window(WindowOptions::default(), cx, |_, cx| {
            cx.new(|_| Panel::default())
        })
        .expect("open animation example");

        cx.activate(true);
    });
}

Motion is a declaration you can recreate each render. MotionState is retained history: keep one state per logical object. Springs preserve position and velocity when interrupted. The adapter requests another frame only while moving; notify the view after an input changes its target. The host app supplies Kit's reduced-motion preference, which the adapter reads when sampling.

The button keeps its Kit behavior. Frame::apply animates its wrapper's relative x/y, opacity, width, height, and border radius. Width and height perform real layout; they are not GPU scale transforms. Applying a corner radius does not clip children automatically. This integration does not automatically animate every internal property of every Kit component.

Enter and exit

Keep declaring the element after open becomes false. Frame::render retains it during the exit and returns an empty element once the exit finishes.

use gpui_kit::{AnyElement, App, Window, div, prelude::*};
use gpui_motion_kit::{MotionState, core::{Motion, Target}};

fn details(state: &mut MotionState, open: bool, window: &mut Window, cx: &App) -> AnyElement {
    let motion = Motion::new(Target::default())
        .initial(Target::default().y(12.0).opacity(0.0))
        .exit(Target::default().y(-8.0).opacity(0.0))
        .present(open);

    let frame = state.frame(motion, window, cx);

    frame.render(|frame| frame.apply(div().p_4().child("Details")))
}

Keep state on the owner. Before removing focused controls, restore focus to a remaining control, and guard outgoing input with frame.is_present().

Text and numbers

Retain TextMotionState and NumberMotionState on your view. These elements use Kit's native text renderer with the same shared text lifecycle and shaping logic as the CE adapter.

use gpui_kit::{IntoElement, SharedString, div, prelude::*};

use gpui_motion_kit::{
    NumberEffect, NumberMotionState, TextMotionState, TextPreset, TextUnit,
    core::StaggerFrom,
};

use std::time::Duration;

fn heading(
    text: &TextMotionState,
    count: &NumberMotionState,
    title: SharedString,
    total: i64,
) -> impl IntoElement {
    let title = text
        .element("heading", title)
        .units(TextUnit::Words)
        .preset(TextPreset::FadeUp)
        .stagger(Duration::from_millis(35), StaggerFrom::Start)
        .when(cfg!(target_os = "macos"), |title| {
            title.font_family("Helvetica Neue")
        });

    let total = count
        .element("total", total)
        .effect(NumberEffect::Roll)
        .when(cfg!(target_os = "macos"), |total| {
            total.font_family("Helvetica Neue")
        });

    div().flex().gap_4().child(title).child(total)
}

The macOS font override avoids a stock system-font clipping issue at display sizes. Text also supports graphemes, wrapped lines, custom targets, matching, reflow, wipes, scrambling, playback and scrubbing. Numbers support Roll, Fade, Slide, and Count. See the text contracts.

Layout positions

Keep one LayoutGroup per coordinate scope and stable IDs for its children. When normal layout moves an item, this wrapper animates from its previous position.

use gpui_kit::{IntoElement, div, prelude::*};
use gpui_motion_kit::LayoutGroup;

fn rows(layout: &LayoutGroup, order: &[usize]) -> impl IntoElement {
    div().flex().flex_col().gap_2().children(order.iter().map(|&id| {
        let row = div()
            .id(("row", id))
            .p_3()
            .child(format!("Task {id}"));

        layout.position(("row-position", id), row)
    }))
}

Paint, hitboxes, and accessibility bounds move together. Sizes change immediately; this is position-only animation, not size projection or cross-parent shared layout.

Animated values

Use ValueState when a Kit control or your own drawing consumes a numeric value. This helper animates a progress fill in logical pixels:

use gpui_kit::{App, IntoElement, Window, div, prelude::*, px, rgb};
use gpui_motion_kit::{ValueState, core::Transition};

fn progress(
    state: &mut ValueState,
    target_width: f64,
    window: &mut Window,
    cx: &App,
) -> impl IntoElement {
    let frame = state.frame(target_width, Transition::default(), window, cx);

    div()
        .w(px(frame.value() as f32))
        .h_2()
        .bg(rgb(0x84cc16))
}

Initialize the retained state once with ValueState::new(0.0). Avoid giving the same property a second interpolator inside a Kit component.

VectorState supplies compatible-path morphing and stroke reveal. The automation example shows it in a complete flow. The native helpers below reuse the same published portable engine; their rendering and input types are Kit-native.

Style transitions

StyleMotionState applies colors, per-corner radii, border widths, padding, margins, gaps and a single outer shadow. Undeclared properties preserve existing styles; previously introduced tracks retain their destinations. Styles that change layout perform real layout. Keep the sampler on the owning view.

use gpui_kit::{App, IntoElement, Window, div, prelude::*};
use gpui_motion_kit::{StyleMotionState, core::{Color, ColorProperty, StyleMotion, StyleTarget}};

fn styled_panel(state: &mut StyleMotionState, expanded: bool, window: &mut Window, cx: &App) -> impl IntoElement {
    let padding = if expanded { 24.0 } else { 12.0 };

    let target = StyleTarget::default()
        .padding([padding; 4])
        .radii([16.0; 4])
        .color(ColorProperty::Background, Color::rgb(0x4338ca))
        .shadow([0.0, 8.0], 20.0, 0.0, Color::rgba(0.0, 0.0, 0.0, 0.2));

    let frame = state.frame(StyleMotion::new(target), window, cx);

    frame.apply(div().child("Settings"))
}

Stock Kit 0.7.3 has no public element blur/backdrop-filter API. A portable target containing StyleProperty::Blur or BackdropBlur is therefore unsupported. frame.try_apply(element) returns UnsupportedStyle (with property()); apply panics for those declarations, including radius zero. No filter is silently ignored. Shadow blur is supported. color_to_rgba converts a sampled engine color to Kit's native color when you paint your own element.

Hover, press, focus and drag

Retain one GestureState per logical control. Configure its drag bounds and optional visibility policy once, then bind its current targets during render. Native input resolves interaction flags automatically. Arrow keys move a focused drag target; Escape, deactivation, blur and a lost mouse button cancel the grab.

use gpui_kit::{Role, div, prelude::*, px};
use gpui_motion_kit::{GestureElement, GestureState, core::{Drag, GestureTargets, Motion, Target}};

fn drag_state() -> GestureState {
    GestureState::default()
        .with_drag(Drag::new([0.0, 0.0], [0.0, 0.0], [240.0, 0.0]).snap_grid(20.0))
        .in_view(0.5, false)
}

fn draggable(state: &GestureState) -> GestureElement {
    let card = div()
        .id("drag-card")
        .role(Role::Button)
        .aria_label("Drag card; use arrow keys to move")
        .w(px(100.0))
        .h(px(64.0))
        .child("Drag me");

    let targets = GestureTargets::default()
        .while_hover(Target::default().opacity(0.85))
        .while_press(Target::default().opacity(0.65))
        .while_focus(Target::default().y(-2.0));

    state.bind("drag-motion", card, Motion::new(Target::default()), targets)
}

interaction(), presented(), and focus_handle() expose current state. .in_view(amount, once) observes the clipped ancestor viewport; use a while_in_view target to animate it. .enabled(false) disables input/tab stops and cancels a grab on the next render; the owner restores focus and supplies its disabled semantics. cancel(cx) cancels explicitly.

The child is a styled stateful native element, including Kit's observed elements from .test_support(). Attach control semantics and activation to that child; this wrapper does not replace a Kit Button's own internal interaction system. Use a dedicated drag surface rather than competing with nested editors/buttons for pointer and focus ownership. Mouse/keyboard and native pinch are supported. Recognized touch dragging is opt-in with touch_drag(true). See the measured-input and spatial-reorder sections for handles, direction locking and edge scrolling. OS-wide capture remains platform work.

Scroll-driven animation

Retain a Kit ScrollHandle and attach it to the real scroll container. ScrollMotion reads its measured extent/offset, refreshes after resize, and maps progress to a numeric target. Mapping is instant unless you choose smoothing.

use gpui_kit::{IntoElement, ScrollHandle, div, prelude::*, px};
use gpui_motion_kit::{Axis, ScrollMotion, core::{Target, Transition}};

fn scrolled_panel(scroll: &ScrollHandle) -> impl IntoElement {
    let indicator = ScrollMotion::new(
        "scroll-progress",
        scroll.clone(),
        Axis::Y,
        Target::default().width(0.0),
        Target::default().width(300.0),
        div().h(px(4.0)).bg(gpui_kit::rgb(0x4338ca)),
    )
    .transition(Transition::default());

    div().flex().flex_col()
        .child(indicator)
        .child(div().id("scroll-area").h(px(200.0)).overflow_y_scroll().track_scroll(scroll)
            .child(div().h(px(800.0)).child("Scrollable content")))
}

native_scroll_progress(&handle, Axis::Y) is available for custom mappings. An unscrollable container reports zero. A dimension declared at only one endpoint is held at that numeric value; undeclared dimensions keep their element style.

Measured content sizing

AutoSize measures a separate child layout root, reserves its animated size, and clips paint/input to the reservation. Keep its ID stable. Supply explicit available constraints; these do not force a child to have that width or height.

use gpui_kit::{IntoElement, div, prelude::*, px};
use gpui_motion_kit::{AutoSize, SizeAxis};

fn accordion(expanded: bool) -> impl IntoElement {
    let content = div().w(px(300.0)).p_4()
        .child("Details")
        .when(expanded, |content| content.child("Additional content wraps naturally."));

    AutoSize::new("accordion", content)
        .width(300.0)
        .axis(SizeAxis::Height)
}

Width, height and both axes are supported. First measurement snaps by default; .initial([width, height]) opts into entrance from a numeric size. Unanimated axes follow content immediately without keeping an animation loop alive.

Reordering and popped exits

ReorderGroup owns logical order and measured variable-size items. new chooses a single axis; spatial also supports automatic detection and 2D grids. Keep the group and domain keys stable. Pointer movement reorders; Option+arrows on macOS (Alt+arrows elsewhere) moves the focused item. Escape/deactivation cancels.

use gpui_kit::{IntoElement, div, prelude::*};
use gpui_motion_kit::{Axis, ReorderGroup};

fn tasks(group: &ReorderGroup<usize>) -> impl IntoElement {
    let order = group.order().to_vec();

    div().flex().flex_col().children(order.into_iter().map(|key| {
        let row = div().id(("task", key)).p_4().child(format!("Task {key}"));

        group.item(("task-motion", key), key, row)
    }))
}

let group = ReorderGroup::new(vec![1, 2, 3], Axis::Y).expect("unique task keys");

on_change reports pointer commit/keyboard changes without borrowing group state. Capture application entities weakly. set_order updates membership transactionally and cancels a grab; call it on model changes, not every render. The owner handles persistence and focus after removal. See spatial reorder for grid collision behavior and optional edge autoscroll.

PopLayout lets an outgoing item leave normal flow immediately while retaining its last visible parent-relative bounds. It also animates sibling reflow:

use gpui_kit::{IntoElement, div, prelude::*};
use gpui_motion_kit::PopLayout;

fn notifications(pop: &PopLayout, first_present: bool) -> impl IntoElement {
    let rows = div().flex().flex_col().gap_2()
        .child(pop.item("first", first_present, div().child("Retained first row")))
        .child(pop.item("second", true, div().child("Second row")));

    pop.container("notifications", rows)
}

Pair it with Motion::present/Frame::render and, for keyed membership, core::PresenceGroup to retain exiting content until its fade completes. Guard outgoing input and restore focus. Do not add LayoutGroup to the same popped item; both would own its position. An inner child can animate its own exit offsets.

Shared position and crossfade

SharedLayout coordinates one active appearance per key in a common overlay. Retain outgoing appearances during their normal exits. Sizes change immediately; this is position/crossfade, not size projection or cross-parent coordinate discovery.

use gpui_kit::{IntoElement, div, prelude::*, px};
use gpui_motion_kit::SharedLayout;

fn selection(shared: &SharedLayout<usize>, expanded: bool) -> impl IntoElement {
    let old = div().absolute().left(px(0.0)).w(px(100.0)).h(px(60.0));
    let new = div().absolute().left(px(240.0)).w(px(180.0)).h(px(100.0));

    div().relative().h(px(220.0))
        .child(shared.member(1, "old-selection", !expanded, old))
        .child(shared.member(1, "new-selection", expanded, new))
}

The owner suppresses outgoing input and duplicate semantics. Call remove(&key) when an identity is finished; len/is_empty expose retained membership.

Prepared playback and timelines

Keep clips and native players in the view. AnimationState::frame returns a Kit-ready Frame; Timeline::frame returns a retained slice indexed by each track's insertion result. Track setup allocates; sampling reuses the frame buffer.

use gpui_kit::{App, IntoElement, Window, div, prelude::*};
use gpui_motion_kit::{AnimationState, core::{Animation, Easing, Target}};
use std::time::Duration;

fn make_clip() -> Animation {
    Animation::to(Target::default().x(200.0), Duration::from_millis(400), Easing::EaseOut)
}

fn animated_card(player: &mut AnimationState, clip: &Animation, window: &mut Window, cx: &App) -> impl IntoElement {
    let frame = player.frame(clip, window, cx);

    frame.apply(div().child("Prepared animation"))
}

Playback controls use the same Kit executor epoch, not Instant::now():

use gpui_kit::App;
use gpui_motion_kit::AnimationState;
use std::time::Duration;

fn scrub(player: &mut AnimationState, cx: &App) {
    let now = player.now(cx);

    player.pause(now);
    player.seek(Duration::from_millis(200), now);
    player.set_speed(0.5, now).expect("finite speed");
    player.play(now);
}

Players also support stop, restart, finish, iteration, and is_playing. Timeline supports pause/play, restart, seek, and speed including negative rates:

use gpui_kit::{App, IntoElement, Window, div, prelude::*};
use gpui_motion_kit::{Timeline, core::{Animation, Easing, Target}};
use std::time::Duration;

fn make_timeline() -> Timeline {
    let slide = Animation::to(Target::default().x(120.0), Duration::from_millis(300), Easing::EaseOut);

    let mut timeline = Timeline::default();

    timeline.at(Duration::ZERO, slide.clone());
    timeline.label("after-first").expect("unique label");
    timeline.then(slide).expect("finite predecessor");

    timeline
}

fn sequence(timeline: &mut Timeline, window: &mut Window, cx: &App) -> impl IntoElement {
    let frames = timeline.frame(window, cx);

    div().flex().flex_col().children(frames.iter().copied().enumerate().map(|(id, frame)| {
        frame.apply(div().id(("track", id)).child(format!("Track {id}")))
    }))
}

at_label adds overlapping tracks at a named cursor plus an offset. Future tracks still schedule frames even before their first movement. Paused/settled/reduced-motion players stop requesting frames, including forever clips. As with portable playback, a loop can deliberately jump at its boundary. Do not mix explicit sample epochs with native frame/now calls on one retained owner.

SVG drawing transforms

Kit supports SVG-specific signed scale, rotation and translation. Retain a SvgMotionState; the shared engine preserves unwrapped angles and interruption momentum. Only the SVG drawing transforms, not its layout, hitbox, clipping, text or children. Provide a fixed padded parent for interaction.

use gpui_kit::{App, IntoElement, Window, div, prelude::*, px, svg};
use gpui_motion_kit::{SvgMotionState, core::{SvgMotion, SvgTarget}};

fn icon(state: &mut SvgMotionState, expanded: bool, window: &mut Window, cx: &App) -> impl IntoElement {
    let target = SvgTarget::default()
        .scale(if expanded { 1.4 } else { 1.0 })
        .rotate_degrees(if expanded { 90.0 } else { 0.0 });

    let frame = state.frame(SvgMotion::new(target), window, cx);

    div().p_8().child(frame.apply(svg().path("icons/arrow-right.svg").size(px(32.0))))
}

transformation() produces a Kit native center-origin transform; transformation_about(bounds_size, pivot) compensates for a custom pixel pivot. These replace the drawing's existing transform. Frame, StyleFrame, and SvgFrame accept their portable core frames through From for custom clocks. General subtree transforms and full layout projection remain renderer limitations.

Helper gallery

cargo run --manifest-path integrations/gpui-kit/Cargo.toml --features demo --example helpers

Eight scenes exercise native styles, bounded drag, manual scrolling/in-view, measured content sizing, popped exits/reorder, shared positions, clip/timeline controls, and SVG transforms. Use Change state during travel, pause/seek/replay, drag variable-size rows, and enable reduced motion. Option/Alt+arrows reorder a focused row. The gallery uses actual Kit controls; its production interaction tests dispatch native pointer/keyboard/scroll input.

Product examples

Six interactive product examples are included in the repository and crate archive. Run from the repository root:

cargo run --manifest-path integrations/gpui-kit/Cargo.toml --features demo --example showcase

Use the tabs to switch examples. Each example keeps its state. You can also open one directly by appending -- inbox, -- assets, -- downloads, -- palette, -- kanban, or -- automation.

Example Try it Motion
Inbox Select messages, archive them, and undo during or after the exit. Keyed presence, spring reflow, smooth interruption
Assets Filter or search the artwork, inspect a thumbnail, and close the inspector. Animated filtering, crossfades, inspector width
Downloads Start the simulated transfers, pause, resume, cancel, and add downloads. Scalar progress, enter/exit, measured row positions
Commands Search documents, preview with arrows, and open with Enter. Measured palette height, interrupted preview transitions
Planner Drag cards between columns or into a new order. Arrow buttons offer the same move by keyboard. Insertion previews, native dragging, spring settling
Automation Run the simulated release, pause it, let publishing fail, and retry. Progress, vector stroke reveal, coordinated steps, expanding errors

The inbox supports Command+Backspace to archive and Command+Z to undo on macOS; use Control on other desktop platforms. Command+Q/Control+Q quits. Kit controls keep their native keyboard, focus, and accessibility behavior. Finite transitions honor GPUI's reduced-motion preference. Transfers and releases are explicitly simulated; these examples do not access email, download files, or publish anything. Artwork is embedded in the executable and decoded once at startup. The showcase was validated on macOS; Linux/Windows runs and screen-reader behavior are unverified.

Reactive values and subscriptions

MotionGraph retains sources, derived values, and subscriptions. A sample updates all dependencies before dispatching events. Keep the subscription handle alive; dropping it unsubscribes. Prepare mappings once, outside rendering.

use gpui_motion_kit::core::{MotionGraph, MotionEventKind, Transition};
use std::time::Duration;

let mut graph = MotionGraph::default();
let progress = graph.source(0.0);
let x = graph.derive(&[progress], |values| values[0] * 240.0).unwrap();
let opacity = graph.derive(&[progress], |values| 0.4 + values[0] * 0.6).unwrap();

let subscription = graph.subscribe(x, |event| {
    if event.kind == MotionEventKind::Complete {
        println!("Arrived at {}", event.value);
    }
}).unwrap();

graph.animate(progress, 1.0, Transition::default(), Duration::ZERO).unwrap();
graph.sample(Duration::from_millis(100), false);

let position = graph.get(x).unwrap();
let alpha = graph.get(opacity).unwrap();

set records direct input velocity; jump resets momentum. animate preserves spring momentum. Events are Start, Cancel, Change, and Complete. Multiple writes coalesce per sample. Callbacks may cancel subscriptions or update another owner; defer edits to the graph being sampled until callbacks return.

Use typed_source, animate_typed, and typed_value for colors, Target, StyleTarget, SvgTarget, TextTarget, arrays, or your own MotionData<N> type. target(base, &[(Property, ValueId)]) binds graph values to native target fields.

Parent and child sequences

A retained MotionTree propagates variants, staggers siblings, and sequences parents before or after children. Add parents first. Keys are application data.

use gpui_motion_kit::core::{ChildrenOrder, Motion, MotionConfig, MotionNode, MotionTree, Target, Variants};
use std::time::Duration;

let variants = || Variants::new([
    (true, Motion::new(Target::default().y(0.0).opacity(1.0))),
    (false, Motion::new(Target::default()).present(false)
        .exit(Target::default().y(12.0).opacity(0.0))),
]).unwrap();

let mut tree = MotionTree::default()
    .config(MotionConfig::default().stagger(Duration::from_millis(40)));

tree.add(MotionNode::new("panel", Target::default(), variants())
    .when(ChildrenOrder::BeforeChildren)
    .exit_when(ChildrenOrder::AfterChildren)).unwrap();
tree.add(MotionNode::new("title", Target::default(), variants())
    .parent("panel")).unwrap();

tree.set_variant(&false, Duration::ZERO, false).unwrap();
tree.sample(Duration::from_millis(100), false);

let retain_panel = tree.is_mounted(&"panel");
let title = tree.get(&"title").unwrap();

Together, BeforeChildren, and AfterChildren choose the timing relationship. exit_when optionally chooses a separate policy for leaving. inherit(false) blocks ancestor variant propagation into that subtree; set_node_variant explicitly selects one subtree. set_motion accepts a dynamic Rust-computed declaration for one node. Identical declarations do not restart. Gated animations hold their local clock and momentum. Nested exits keep a parent mounted until every participating descendant exits; a non-exiting child keeps it mounted. The application removes the view and restores focus afterward.

MotionConfig::transition(...).motion(target) supplies explicit defaults to your render helpers. It installs no global provider and does not override OS preferences.

Typed clips and mixed timelines

TypedAnimation<T, N> supports scalars, colors, numeric targets, styles, SVG transforms, text targets, and arrays. Implement MotionData<N> for another fixed numeric representation. Seed and clip must declare the same property mask.

use gpui_motion_kit::core::{Color, Easing, SvgTarget, TypedAnimation, TypedTimeline};
use std::time::Duration;

let mut timeline = TypedTimeline::default();

let color = timeline.at(
    Duration::ZERO,
    Color::rgb(0x223344),
    TypedAnimation::to(Color::rgb(0xd8f58b), Duration::from_millis(400), Easing::EaseInOut).unwrap(),
);

timeline.label("turn", Duration::from_millis(120)).unwrap();

let icon = timeline.at_label(
    "turn",
    -0.04,
    SvgTarget::default(),
    TypedAnimation::to(SvgTarget::default().rotate_degrees(360.0), Duration::from_millis(600), Easing::EaseInOut).unwrap(),
).unwrap();

timeline.sample(Duration::from_millis(300), false);

let background = timeline.value(color).unwrap();
let transform = timeline.value(icon).unwrap();

Use TypedKeyframe::new/current/easing, TypedAnimation::keyframes/to/spring, delay, and repeat to prepare clips. TypedState::sample plays one typed value with per-channel spring interruption. TypedTimeline::after accepts signed seconds for gaps or overlaps; adding after a forever track returns an error. Track IDs belong to their creating timeline. Setup allocates; sampling reuses state.

Both owners support pause, play, seek, restart, speed (including reverse), and completion. TypedState::finish finishes even a forever clip. Applying sampled values uses the existing numeric/style/SVG/text adapters. Kit still rejects blur and backdrop blur through StyleFrame::try_apply; typed tracks add no renderer hooks.

Completion futures

AnimationState, TypedState, TypedTimeline, and MotionTree expose completion(). Requesting a future allocates observer storage; ordinary sampling does not. Await it on your application's executor while native frames drive the animation. Completion, replacement, explicit cancellation, restart, and owner drop all resolve the observer instead of leaving a waiting task behind.

use gpui_motion_kit::core::{Animation, AnimationState, CompletionStatus, Easing, Target};
use std::time::Duration;

let clip = Animation::to(Target::default().x(80.0), Duration::from_millis(300), Easing::Linear);
let mut state = AnimationState::default();

state.sample(&clip, Duration::ZERO, false);

let finished = state.completion();

state.sample(&clip, Duration::from_millis(300), false);

async move {
    match finished.await {
        CompletionStatus::Completed => println!("Finished"),
        CompletionStatus::Cancelled => println!("Replaced or cancelled"),
    }
};

SVG path preparation and following

PathShape::parse_svg accepts SVG path data, including relative, smooth, implicit, and elliptical arc commands. Enable svg-path for portable use; the native adapters enable it. This parses path data, not an SVG document or CSS.

use gpui_motion_kit::core::{PathMeasure, PathShape};

let circle = PathShape::parse_svg("M180 100 A80 80 0 1 1 20 100 A80 80 0 1 1 180 100 Z").unwrap();
let triangle = PathShape::parse_svg("M100 20 L185 170 L15 170 Z").unwrap();

let (from, to) = circle.normalize_for_morph(&triangle, 72).unwrap();
let path = PathShape::parse_svg("M10 130 C100 0 180 220 310 60").unwrap();
let measure = PathMeasure::new(&path).unwrap();

let point = measure.point(0.4);
let position = point.position;
let angle_degrees = point.tangent_degrees;

Feed the normalized pair to PathMorphState or VectorState; feed measured position/tangent to a numeric target or SVG transform. Normalize and measure once. Queries allocate nothing. Curves use 32 subdivisions; normalization resamples to line contours with your chosen point budget. Contour count, order, open/closed status, start points, and winding must correspond. It does not infer semantic shape correspondence. Subpath gaps do not become visible connecting segments.

Rich text, vertical reveals, and decimal counters

use gpui_motion_kit::core::{Color, FixedNumber, NumberFormat, RichText, TextSpan};

let title = RichText::new([
    TextSpan::new("Café ").font_weight(500.0),
    TextSpan::new("in motion.").font_weight(700.0).color(Color::rgb(0xd8f58b)),
]);

let euros = NumberFormat::default()
    .prefix("€")
    .decimal(",")
    .grouping(" ", 3, 3);

let value = FixedNumber::new(120900, 2).unwrap();
let formatted = euros.format(value, 0);

assert_eq!(formatted.text(), "€1 209,00");

TextSpan::font_family and font_weight choose native faces per span. The full string is shaped before units split. Font size and line height remain label-wide. This is a display-label API; selection/editing and variable-font-axis interpolation are outside its contract. Numeric endpoints use an exact i64 coefficient plus 0–18 decimal places. Separators, affixes, digit alphabets, and 3/3 or 3/2 grouping are explicit; it does not bundle automatic CLDR/ICU locale rules. Currency conversion and rounding remain application decisions. Digit identities follow decimal places across grouping/affix changes and integer growth. Affixes and separators have distinct identities; the chosen effect applies to changed glyphs.

Native graph and tree owners

Retain GraphState or MotionTreeState in your view. Call frame once before reading bound values. Use now(cx) for input/control timestamps; do not mix that executor clock with an unrelated Instant or a manually sampled epoch. Notify the owning view after edits. Idle or paused owners stop requesting frames.

use gpui_motion_kit::{GraphState, MotionTreeState};
use gpui_motion_kit::core::MotionTree;

let graph = GraphState::default();
let tree = MotionTreeState::new(MotionTree::<u8, bool>::default());

TypedState and TypedTimeline also provide native frame and now methods. Reduced motion settles pending transitions and bypasses tree gates/staggers.

Measured scroll targets and viewport roots

Retain one MotionAnchor per measured element and mount each once. Anchors use logical window coordinates, keep native input/accessibility, and request a follow-up frame after changed measurements. Clear an anchor before reusing it in another window.

use gpui_kit::{ScrollHandle, div, prelude::*, px};
use gpui_motion_kit::{Axis, MotionAnchor, ScrollTracker};
use gpui_motion_kit::core::{ScrollEdge, ScrollOffsets};

let scroll = ScrollHandle::new();
let viewport = MotionAnchor::default();
let target = MotionAnchor::default().scroll_source(scroll.clone());

let mut tracker = ScrollTracker::new(scroll.clone(), viewport.clone(), target.clone(), Axis::Y)
    .offsets(ScrollOffsets::new(
        ScrollEdge::new(0.0, 1.0, 0.0),
        ScrollEdge::new(1.0, 0.0, 0.0),
    ))
    .margins([16.0, 0.0, 16.0, 0.0]);

let panel = viewport.element("viewport", div().id("scroll")
    .w(px(300.0)).h(px(200.0)).overflow_scroll().track_scroll(&scroll)
    .child(target.element("target", div().h(px(600.0)))));

Call tracker.frame(window, cx) during rendering. The returned ScrollFrame contains readiness, progress, velocity, offsets, and active status; target(from, to) maps progress to numeric targets. Optional transition smooths with the shared solver. Negative margins expand the viewport; ScrollOffsets::unclamped permits anticipation. Explicit scroll_source avoids stale measurements between prepaints. For nested scrolling, track the nearest source and measure again after ancestor scrolling/layout; this is not an automatic browser-style ancestor observer.

GestureState::view_root(anchor).view_margins([top, right, bottom, left]) customizes in-view observation while preserving normal ancestor clipping.

Measured drag bounds, handles, and pinch

use gpui_motion_kit::{GestureState, MotionAnchor};
use gpui_motion_kit::core::{Drag, GesturePhase};

let bounds = MotionAnchor::default();

let gesture = GestureState::default()
    .with_drag(Drag::unconstrained([0.0, 0.0]).direction_lock(8.0))
    .constraints(bounds.clone())
    .on_drag(|event, _, _| {
        if event.phase == GesturePhase::Ended {
            println!("Released at {:?}", event.offset);
        }
    })
    .on_pinch(|event, _, _| println!("Pinch scale: {}", event.scale));

Mount bounds.element(...), then wrap the control with gesture.bind(...). Measured constraints update on resize. Set .drag_listener(false) on the binding and call gesture.start_drag([x, y], window, cx) from a separate handle's mouse-down handler. Focus, keyboard equivalents, cancellation, release outside, and smooth inertial interruption remain supported. DragEvent reports phase, point, delta, offset, velocity, and direction lock. Callbacks run after internal borrows end; use weak view/entity captures rather than retaining the same owner in its callback. Pinch reports native trackpad lifecycle; mapping its scale to an SVG or another supported property is explicit. It cannot scale an ordinary element subtree.

On stock Kit, .touch_drag(true) opts into its recognized touch-drag stream. Spatial reorder also consumes that stream. The OS/backend determines which touch and pinch gestures are delivered; physical mobile-device acceptance is separate.

Spatial reorder and edge scrolling

use gpui_kit::ScrollHandle;
use gpui_motion_kit::{MotionAnchor, ReorderGroup};
use gpui_motion_kit::core::{AutoScroll, ReorderAxis};

let scroll = ScrollHandle::new();
let viewport = MotionAnchor::default();

let group = ReorderGroup::spatial(vec!["one", "two", "three"], ReorderAxis::Auto)
    .unwrap()
    .autoscroll(scroll.clone(), viewport.clone(), AutoScroll::default());

Render group.order() inside your ordinary row/column/wrapped grid, wrapping each stable-key item with group.item(...). Auto measures whether it is a row, column, or grid; explicit X, Y, and XY are available. Pointer collisions use nearest measured slots. Batched pointer/key input keeps the latest measured slot map stable until layout catches up. Option/Alt + arrows choose a physical neighbor in grids. Auto chooses its axis at acquisition. Use .drag_listener(false) plus start_drag(&key, point, window, cx) for handles. External set_order changes require a fresh layout before acquiring another drag. Edge scrolling uses elapsed time and native bounds, and stops on release, Escape, blur, deactivation, or reaching a limit. One pointer owns a group. This is a measured reorder list/grid, not a virtualized arbitrary drag/drop data-transfer framework.

Cross-container shared movement

use gpui_kit::{div, prelude::*, px};
use gpui_motion_kit::SharedOverlay;

let overlay = SharedOverlay::<u8>::default();
let source = overlay.anchor(1, "inbox", div().w(px(140.0)).h(px(80.0)));
let destination = overlay.anchor(1, "today", div().w(px(140.0)).h(px(80.0)));

overlay.select(1, "today");

let floating = overlay.element(1, "moving-card", div()
    .w(px(140.0)).h(px(80.0)).child("Read this later"));

Anchors may live in separate clipped containers. Render floating appearances in an unclipped window-root overlay so movement can cross them. scroll_anchor tracks a scroll source; measurements must belong to the same native window. active(false) crossfades a retiring appearance; retain it while exiting, disable its input, and manage focus in the host. match_size(true) uses destination sizes immediately through real layout. Position uses interruptible shared springs; this provides no GPU size projection. remove(&key) releases completed history.

Native rich text and formatted numbers

use gpui_kit::{div, prelude::*, px};
use gpui_motion_kit::{NumberMotionState, TextMotionState};
use gpui_motion_kit::core::{Color, FixedNumber, NumberFormat, RichText, TextPreset, TextSpan, Transition};

let text = TextMotionState::default();
let number = NumberMotionState::default();

let rich = RichText::new([
    TextSpan::new("Café "),
    TextSpan::new("in motion.").color(Color::rgb(0xd8f58b)),
]);

let label = text.rich_element("title", &rich)
    .preset(TextPreset::WipeDown)
    .color_transition(Transition::default())
    .animate_font_size(48.0, Transition::default());

let format = NumberFormat::default().prefix("€").grouping(",", 3, 3);
let count = number.formatted_element("balance", FixedNumber::new(120900, 2).unwrap(), &format);

let content = div().font_family("Helvetica Neue").text_size(px(40.0))
    .child(label)
    .child(count);

WipeDown and WipeUp complement existing horizontal reveals; reveal_axis(TextRevealAxis::Vertical) configures custom wipes. Colors interpolate in linear light, retaining per-glyph state. NumberElement also forwards color_transition and animate_font_size. Font size animates by native shaping and layout, so it costs more than opacity/translation. Pause/play freezes glyph motion, font-size and color transitions; normalized seek/restart controls the entrance sequence, not style history. Keep one mounted element per text state.

Checks

cargo fmt --manifest-path integrations/gpui-kit/Cargo.toml --all --check
cargo test --manifest-path integrations/gpui-kit/Cargo.toml --locked --features demo,native-tests
cargo test --manifest-path integrations/gpui-kit/Cargo.toml --locked --features demo,native-tests --example showcase
cargo test --manifest-path integrations/gpui-kit/Cargo.toml --locked --features demo,native-tests --example helpers
cargo clippy --manifest-path integrations/gpui-kit/Cargo.toml --locked --all-targets --features demo,native-tests -- -D warnings
python3 scripts/check_spacing.py --project integrations/gpui-kit

Append --fix to the spacing command to apply the same shared Dylint policy as the CE crate. The repository's pinned Dylint nightly and CLI are required; see development instructions. The spacing command also compiles every Rust example in this README against Kit. Tests and benchmarks reuse CE fixtures and run from the repository; the published archive contains the library, runnable demos, their assets, and licenses.

Native interaction tests render the production views and dispatch real Kit pointer/keyboard input. TestPlatform substitutes the display/GPU, so those tests verify behavior and geometry rather than GPU presentation.

Performance

The helper benchmark compares 100 direct elements with styles, scroll bindings, clip/timeline playback, gestures, sizing, popped exits, reorder, shared positions, vectors, and direct/animated SVG drawing. It uses five fresh contexts, 24 warmup and 240 measured frames per batch, retargeting every 24 frames:

cargo bench --manifest-path integrations/gpui-kit/Cargo.toml --features demo,native-tests --bench helpers_native

These are CPU construction/layout/prepaint/paint-preparation timings on TestPlatform with synthetic fonts/display/GPU. They do not measure GPU execution, OS input latency, frame presentation or energy. Direct and animated SVG cases use identical fixed SVG data and caching; the comparison includes normal builder costs. See helper measurements.

cargo bench --manifest-path integrations/gpui-kit/Cargo.toml --features demo,native-tests --bench kit_layout

The benchmark compares direct layout, position tracking without interpolation, and interrupted position animation for 400 elements over seven batches of 240 measured frames, after warmup. It reports CPU construction/layout/prepaint/paint preparation on TestPlatform, not GPU completion or display latency. Keep profile, machine, and workload the same when comparing results. Live-window checks are still needed for presentation, input feel, and platform behavior.

Local release-profile result on macOS ARM64 with Rust 1.95.0, recorded on 2026-10-18 after other builds had finished:

Workload Median batch mean, ms/frame Aggregate frame P95, ms
Direct layout 1.259 1.397
Position tracking, interpolation disabled 1.779 2.004
Animated measured positions with interruption 2.014 2.294

This is one shared-desktop CPU comparison, not a frame-rate guarantee. The animated wrapper adds roughly 0.76 ms to the median batch mean in this workload. These figures do not measure all six product screens or GPU execution.

Text gallery

The native text API shares its renderer and portable engine with the CE adapter. Keep TextMotionState or NumberMotionState from gpui_motion_kit in the owner. Text grouping, targets, presets and number effects are re-exported alongside them; existing transitions, prepared animations and stagger origins come from core.

cargo run --manifest-path integrations/gpui-kit/Cargo.toml --features demo --example text_motion

Try all twelve modes, edit the input, or press Change text repeatedly while it moves. Replay/Pause/Resume control text playback; Scrub exposes a draggable reveal slider. Numbers demonstrates Roll/Fade/Slide/Count with increment/decrement buttons. The reduced-motion checkbox settles every mode. The text API and contracts cover Unicode shaping, matching, clipping, playback and the finite scrub horizon.

The text-native benchmark compares ordinary text replacement, settled adapter rendering, interrupted word/grapheme movement and deterministic scrambling for 40 labels. Like the layout benchmark, it measures CPU preparation on TestPlatform.

The final local run measured 0.271 ms/frame for ordinary text, 0.419 ms for interrupted words, 0.542 ms for graphemes and 0.560 ms for scrambling. These are median batch means; see measurement details and P95 for workload differences, repeat-run variation and the stock-CE comparison.

MIT OR Apache-2.0. See LICENSE-MIT and LICENSE-APACHE.

Motion lab

Run cargo run --features demo --example motion_lab from this directory. Nine interactive scenes cover connected values, child sequences, mixed timelines, scroll intersections, measured handles/pinch, grid reorder/autoscroll, cross-container transfer, parsed paths/morphs/following, rich labels and currency counters.

The expanded engine's CPU benchmarks, allocation checks and native acceptance are recorded in the performance report.