Motion: one clock for every animation

Status: landed (2026-11-01). The primitive is architect_shell::motion (features/shell/src/motion.rs); the shell’s drawers and sidebars and the workspace host’s docks, tabs, stacked strips and splits move on it. Its springs were timed to Obsidian’s, measured frame by frame (#155, The reference: Obsidian).

Before this, the workspace had no animation: a sidebar opened in one frame, a dropped tab jumped to its place, a split appeared at full size. The only motion was the shell’s phone drawer, eased by a futures_timer loop on the wall clock, which architect-guide’s runner could not drive, so a film never showed it.

The primitive#

A Motion is a value that moves (features/shell/src/motion.rs Motion, made with use_motion):

• sent somewhere with Motion::to (Motion::to_then calls back when it gets there), it moves on a Spring: a response (how long one swing takes, seconds) and a damping (1 stops without passing its target, below 1 overshoots). The spring is solved, not stepped (Spring::step), so where it is depends on the time alone: a slow frame moves it further, never slower, and a film is the same at any frame rate;
• held with Motion::hold (a finger, a trackpad, a scrollbar’s drag), it is where it is put, and it measures how fast it is moved;
• let go into Motion::to or Motion::coast it starts at that speed: a spring sent elsewhere mid-way, or a held value let go, keeps its velocity. A coast slows by e every COAST seconds and is sprung back inside its bounds if it runs past one.

Its state is plain data (Track), tested without a renderer. Its value is a signal: the component that reads Motion::value redraws each frame it moves; a Motion copied into another component’s handler still runs its frames in the component that made it.

The springs used, timed to Obsidian’s (measured below), none overshooting: Spring::PANEL (0.12 s: a sidebar, a dock, a split), Spring::SNAPPY (0.22 s: tabs, a stacked strip’s wheel notch and spine), Spring::TRACK (0.11 s: the drop highlight following the pointer). Spring::SHEET (0.32 s) is a phone’s drawer, its tab switcher, the keyboard’s lift and a tour’s spotlight (features/guide/src/tour.rs TourLayer), which the study (on a desk) did not measure.

One clock#

features/shell/src/motion.rs now and next_frame are the clock every motion reads:

• In a window it is the wall clock, a frame each FRAME (60 fps), on boundaries of the clock so every motion moves in the same frames (one redraw for all of them).
• In a run (features/guide/src/run.rs run) the runner starts a VirtualClock on its thread before it opens the documents and moves it to frame n’s time (n / fps) each frame, then polls the documents and lays them out. Stylo’s own transitions are resolved at the same time, so a film shows every in-between frame of both, the same on every run, and a test (no film) runs the same frames. While a motion waits for the next frame, waiting on a step’s done is frames too, so a close that waits for its group to fold lands.

Reduced motion#

set_reduced_motion is the app’s setting (Some(true) reduced, None the OS’s preference, read on macOS from NSWorkspace); reduced_motion is what holds. Reduced, every to jumps to its end (and calls its to_then), and every coast stops where it is. A virtual clock ignores the OS, so a film is the same on every machine. The sandbox’s Settings › Appearance › Reduce motion is the setting (apps/ui/src/lib.rs).

What moves#

Which close animates: only a tab’s ✕ on the last tab of a group in a split (a command or a menu row closes at once, so a script that closes and then acts sees the close).

What Blitz draws well#

opacity changes nothing in the layout, and a relatively placed box’s left moves only that box: the tabs slide by left, in points (a translate moves by device pixels, half as far on a 2x screen; apps/sandbox/media/tests/tab_slide.rs drags a tab at 2x). A clipped box’s width lays out only that box’s row (the tree inside keeps its size). A paragraph keeps the lines of its own width while its neighbours move (the FTS Blitz fork’s fts-measure-2026-11; before it a note drew the lines of the zero width a parent measured it at, a word per line, #152; apps/sandbox/media/tests/reflow.rs checks the films’ every frame). A stacked pane is placed by left in an absolutely positioned strip. Blitz has no requestAnimationFrame; the wall clock’s FRAME wakes the motions, and FTS_FPS_LOG=1 (the FTS Blitz fork’s blitz-shell) logs frames and their cost each second.

The FTS fork draws a document’s own updates at most FTS_MAX_FPS times a second (30 unless set), so meters and clocks do not each repaint the window at every vsync, but draws a running CSS animation at the display’s rate. MotionFrames (features/shell/src/motion.rs) bridges the two: while any motion runs it runs an invisible 1 px CSS animation, and it stops it when they rest. The element stays mounted: a node made just after it went drew under its animation’s opacity (blank) (skills/architect/references/blitz-quirks.md). AppShell mounts it, and so do the workspace’s host (outside a shell) and its pop-outs. Measured in the sandbox on an M4 Mac mini: a sidebar fold went from 32 to 140 frames a second, 6.8 ms a frame on average, 12.5 ms at worst.

A motion’s frames run in its window’s root scope (a motion may be sent from a component that is going, a tab dropped into another bar); they end once the component that made it goes, and every method on a motion whose component has gone does nothing.

Measured in the sandbox#

The sandbox (apps/desktop) driven with real pointer and wheel events, recorded at the display’s capture rate (about 29 fps):

Those were filmed before the springs were timed to Obsidian (below). The sandbox’s films (sandbox-media … --keep-frames, 20 fps on the virtual clock), their raw frames compared before and after the tuning, against Obsidian’s (about 29 fps):

Signs#

A stacked strip takes a wheel’s delta as Blitz scrolls a box: a delta to the right brings the strip’s start into view, so a swipe moves it the way it moves every scrolled box. architect-guide’s @scroll{dx} is signed the same (a negative dx brings what is to the right into view).

In the films#

architect-guide’s @scroll is a trackpad’s flick (quick, coasting to a stop) in pixel deltas, as macOS sends them. The sandbox’s scenarios film the motion: apps/sandbox/scenarios/stacked-tabs.styx (a small scroll, a long one, a spine pressed), apps/sandbox/scenarios/tab-reorder.styx (the tabs making room), apps/sandbox/scenarios/workspace-docks-ribbon.styx (the sidebar folding and opening), apps/sandbox/scenarios/workspace-split-drag.styx (the highlight following, the split growing in, the divider, the close folding back).

The reference: Obsidian#

The behaviour follows Obsidian’s (sidebars that slide and clip, stacked panes that slide over each other to their spines) and VS Code’s and Zed’s tab drags (tabs that make room). Obsidian is a reference for behaviour and timing only.

Obsidian, measured#

Obsidian 1.14.5 on an M4 Mac mini (airlock), a 1400 × 900 window, driven with real pointer, key and wheel events (cua-driver) and filmed at the display’s capture rate (about 29 fps, a frame each 35 ms), then measured frame by frame from the raw frames (edges and glyphs tracked along pixel rows). A curve is fitted to each interaction’s frames with its start free between the last still frame and the first moving one; at 29 fps a motion under 35 ms is one frame, so “at once” means within a frame.

What Obsidian does not do, and architect does: its tabs do not make room during a drag and a dropped tab does not settle (architect follows VS Code’s and Zed’s here, on Spring::SNAPPY, which is the timing of Obsidian’s own tab width changes); a new split does not grow in and a closed one does not fold (architect grows and folds them on Spring::PANEL, now as quick as Obsidian’s sidebars, so they read as a quick slide rather than a jump). Where they differ in layout: Obsidian’s right sidebar carries its content with its moving edge, architect’s keeps it held to the window’s edge, as the left one does.

The constants tuned from it, in features/shell/src/motion.rs: Spring::PANEL 0.32 → 0.12 s (the sidebars), Spring::TRACK 0.16 → 0.11 s (the highlight), Spring::SNAPPY kept at 0.22 s (it matched the tabs’ 0.20–0.21 s and the wheel’s 0.20 s), and the stacked strip’s easing (features/workspace/src/host/group.rs Stacked) moved from Spring::PANEL to Spring::SNAPPY. A spring takes the same time over any distance, so a spine pressed far away moves in 0.25 s where Obsidian’s smooth scroll takes up to 0.9 s. WHEEL_LINE (40 points a notch) is not changed: the 80 px measured is what cua-driver’s notch became in Chromium, not a hardware wheel’s.