@n-uf/motion

One frame loop with an injected clock, fine-grained signals, springs and tweens, and a DOM-free gesture recogniser. No DOM, no framework, no globals: the host hands in a clock, and tests hand in a fake one.

npm i @n-uf/motion

• clock/: one frame loop that runs tasks in phases (input → update → layout → write) with a frame budget and stats, on a clock you pass in.
• signals/: reactive values, computed values and effects; a change recomputes only what depends on it, and effects can run once per frame.
• values/: springs and tweens over numbers, points, rects and vectors, stepped by the clock, with velocity that carries over a retarget, settle detection and a reduced-motion switch; and the window motion rules: settle (one fast-then-gentle curve that never passes its target), hold (what a pointer owns sits exactly under it) and reveal (glide a window without stretching its content).
• gestures/: a recogniser that turns pointer, wheel and trackpad events (plain objects) into one gesture stream (click or drag, double click, long press, pinch, scroll, zoom, recovery from lost releases), a frame coalescer, and a dwell (spring-load) machine.

One package, seven entries: @n-uf/motion (everything in the core), its four folders on their own (@n-uf/motion/clock, /signals, /values, /gestures), @n-uf/motion/testing (frame-sampled checks of the motion rules, for tests and browser specs), and @n-uf/motion/browser, the clock on requestAnimationFrame and the reduced-motion media query. The core entries touch no host; importing several of them still gives one signal graph.

One frame

import { computed, createFrameCoalescer, createFrameLoop, effect, signal, springValue } from "@n-uf/motion";
import { createBrowserClock, prefersReducedMotion } from "@n-uf/motion/browser";

const el = document.querySelector<HTMLElement>("#box")!;
const loop = createFrameLoop({ clock: createBrowserClock() });

// Input: one pointer sample per frame, delivered in the input phase.
const pointer = signal({ x: 0, y: 0 });
const input = createFrameCoalescer<{ x: number; y: number }>((p) => (pointer.value = p), loop.frames("input"));
addEventListener("pointermove", (e) => input.schedule({ x: e.clientX, y: e.clientY }));

// Layout: a target derived from state.
const target = computed(() => ({ x: Math.round(pointer.value.x / 50) * 50, y: 0 }));

// Motion: a spring follows the target, stepping in the layout phase.
const box = springValue(loop, { x: 0, y: 0 }, { reducedMotion: prefersReducedMotion() });
box.follow(() => target.value);

// Write: once per frame while it moves; the loop idles when it settles.
effect(() => {
  el.style.transform = `translate(${box.value.x}px, ${box.value.y}px)`;
}, { schedule: loop.scheduler("write") });

clock/

Each task gets { time, delta, index, phase, budgetMs, elapsed(), remaining() }. delta is the time since the last frame, clamped to maxDeltaMs (default 64), and frameMs for the first frame after the loop was idle.

Within a phase, one-shot tasks run first, then the repeating ones, then any one-shots they queued for that phase. A task queued for a later phase runs in the same frame; one queued for an earlier phase runs in the next.

import { createFakeClock, createFrameLoop } from "@n-uf/motion";

const clock = createFakeClock();
const loop = createFrameLoop({ clock, budgetMs: 8 });
loop.schedule("write", () => console.log("write"));
loop.schedule("input", () => console.log("input"));
clock.frame(); // input, write
loop.stats(); // { frames: 1, overBudget: 0, ... }

signals/

An effect's own writes don't re-run it; writes inside an effect are batched until it returns; effects that keep re-triggering each other throw instead of hanging. The graph algorithm is alien-signals↗ (opens in a new tab)' published core (alien-signals/system, the same core Vue 3.6 uses), under this API; bench/RESULTS.md↗ (opens in a new tab) has the comparison behind that choice.

import { computed, createFakeClock, createFrameLoop, effect, signal } from "@n-uf/motion";

const loop = createFrameLoop({ clock: createFakeClock() });
const width = signal(800);
const columns = computed(() => Math.max(1, Math.floor(width.value / 300)));
effect(() => console.log("columns", columns.value), { schedule: loop.scheduler("write") });
width.value = 850; // still 2 columns: the effect won't run
width.value = 1300; // runs once, in the next frame's write phase

values/

Values are plain: a number, { x, y }, { x, y, width, height } or an array of numbers, a fresh object after every change. Velocity is in units per second. A spring keeps its velocity when its target changes mid-flight. A value is at rest when it is within restDelta of the target and slower than restSpeed (defaults 0.1 and 1, tuned for pixels; use about 0.001 and 0.01 for opacity or scale), and then it snaps onto the target exactly. With reducedMotion on (a boolean or a function read on every target and frame), targets are reached at once.

Motion values step in the layout phase by default, after that phase's one-shot tasks: a target set in input, update or layout moves the value in the same frame, and write sees it.

import { createFakeClock, createFrameLoop, springValue } from "@n-uf/motion";

const clock = createFakeClock();
const loop = createFrameLoop({ clock });
const rect = springValue(loop, { x: 0, y: 0, width: 200, height: 100 }, { dampingRatio: 0.7 });
rect.onSettle((r) => console.log("settled at", r));
rect.set({ x: 300, y: 40, width: 240, height: 100 });
clock.runUntilIdle(); // settled at { x: 300, y: 40, width: 240, height: 100 }

Window motion: settle, hold, reveal

Three rules make windows move the way a tiling window manager feels smooth (Hyprland is the reference): what the pointer holds is glued to it, everything else moves on one front-loaded curve that never passes its target, and content is never stretched.

import { createFakeClock, createFrameLoop, settleValue } from "@n-uf/motion";

const clock = createFakeClock();
const loop = createFrameLoop({ clock });
const win = settleValue(loop, { x: 0, y: 0, width: 400, height: 300 });
win.set({ x: 400, y: 0, width: 200, height: 300 }); // a reflow: position and size arrive together
clock.frame();
win.set({ x: 300, y: 0, width: 300, height: 300 }); // retargeted mid-flight: on from where it is drawn
clock.runUntilIdle();
console.log(win.value); // { x: 300, y: 0, width: 300, height: 300 }, never past it on the way

layout/

@n-uf/motion/layout applies the window motion rules to a whole surface: give each item an id and a target rect, and it moves the real elements, every one on one frame loop that runs only while something moves. It animates the rects it is given and nothing else: which items move where (making room, drop targets) is the caller's layout.

import { createFakeClock, createFrameLoop } from "@n-uf/motion";
import { createLayoutMotion, holdItem } from "@n-uf/motion/layout";

const clock = createFakeClock();
const loop = createFrameLoop({ clock });
const motion = createLayoutMotion({ loop });
const panel = motion.add("panel", { layOut: () => {}, draw: () => {} }, { x: 0, y: 0, width: 200, height: 100 });
panel.moveTo({ x: 300, y: 0, width: 240, height: 100 }); // a settle, its new width revealed
clock.runUntilIdle();
const held = holdItem(panel, { x: 20, y: 10 }); // grabbed 20 px in, 10 px down
held.move({ x: 120, y: 60 }); // held 1:1: drawn at { x: 100, y: 50 }
const release = held.land({ x: 0, y: 0, width: 200, height: 100 });
console.log(release); // { x: 100, y: 50, width: 240, height: 100 }: the landing starts there
clock.runUntilIdle();
console.log(panel.drawn); // { x: 0, y: 0, width: 200, height: 100 }

A host that draws every item itself, once per frame:

import { createFakeClock, createFrameLoop } from "@n-uf/motion";
import { createLayoutMotion } from "@n-uf/motion/layout";

const clock = createFakeClock();
const loop = createFrameLoop({ clock });
const batches: string[][] = [];
const host = createLayoutMotion({ loop, onDraw: (batch) => batches.push(batch.map((e) => e.id)) });
const noop = { layOut: () => {}, draw: () => {} };
const a = host.add("a", noop, { x: 0, y: 0, width: 100, height: 100 });
host.add("b", noop, { x: 0, y: 200, width: 100, height: 100 });
host.flush(); // both drawn now, in one batch: ["a", "b"]
a.moveTo({ x: 300, y: 0, width: 100, height: 100 });
host.flush(); // right after the host's commit: ["a"], at the rect it is drawn at
clock.runUntilIdle(); // one batch per frame, each ["a"] (b is at rest)
host.retain(["a"]); // b left the layout
console.log(host.items.size); // 1

testing/

@n-uf/motion/testing checks recorded frames against the rules. Record what was drawn each frame (on the fake clock, or in a browser spec once per animation frame) and ask:

Each returns { ok, failures }, a failure naming the frame and component. The motion lab in the n-uf/motion repository↗ (opens in a new tab) (apps/lab) runs them on every move.

gestures/

The recogniser takes plain objects the host copies out of DOM events, with their timestamps; nothing in it touches the DOM. Mouse, pen and touch share one path. There is one press at a time, a second finger turns it into a pinch, and a press only becomes a drag past its device's threshold, so a modifier+click stays a click for the content. It recovers releases that never arrive (a move with no buttons down, the same pointer pressing again, a press left untouched for staleMs when another pointer goes down). Its timers are a clock (any ClockPort), used for the long press. Hit testing and routing (what is under a point, who gets the gesture) are the host's.

import { createFakeClock, createRecognizer } from "@n-uf/motion";

const clock = createFakeClock();
const recognizer = createRecognizer({ toCanvas: (p) => p, timers: clock }, (g) => console.log(g.type));
const finger = { pointerId: 1, pointerType: "touch", button: 0, screen: { x: 0, y: 0 } } as const;
recognizer.feed({ ...finger, type: "pointerdown", buttons: 1, time: clock.now() }); // press
clock.tick(500); // longPress
recognizer.feed({ ...finger, type: "pointerup", buttons: 0, time: clock.now() }); // release, click: false

A paged swipe, its timers on a clock:

import { createFakeClock, createPagedSwipe, NO_MODIFIERS } from "@n-uf/motion";

const clock = createFakeClock();
const swipe = createPagedSwipe({ clock });
swipe.send({ type: "context", hasPrev: true, hasNext: true, size: 1000 });
swipe.send({ type: "wheel", dx: 400, dy: 0, t: clock.now(), modifiers: NO_MODIFIERS });
console.log(swipe.state.phase, swipe.state.progress); // tracking 0.4
clock.tick(120); // the wheel rests: past 35 %, it commits
console.log(swipe.state.phase, swipe.state.target); // settling next
swipe.send({ type: "settled" }); // the host's page transition is done: momentum is locked out
console.log(swipe.state.phase); // lockout

drag/

@n-uf/motion/drag decides, from the pointer's path, when a drop indicator shows, which target it shows, when the others make room, and what a release lands on. It is pure: the host feeds it the pointer once a frame and plain-data targets, and draws what it says. It is only there, not in the root.

A target is { id, priority, hit, slot?, label?, free? }: hit is the zone the pointer can be in, priority how precise it is (a tab strip 1, a slot 2, a large area 3). The rules:

• The indicator shows only when the pointer has left the item's home, a target is under it, and the pointer aims (slows down or holds still). Crossing targets at speed shows nothing.
• The current target holds within a band around its zone, unless a more precise target is clearly under the pointer. Leaving the shown target, a flying pointer hides the indicator at once; an aiming one moves it once the new target has held 150 ms, so no indicator ever shows for less.
• Room is made once the shown target, and the place in it (placeOf: a tab index, say), have held 160 ms; never for a free target.
• placeOf(target, point, previous) gets the place it gave that target on the last sample, so a place can hold near its boundary. A null place is no target: nothing shows there (a target beneath with a place can), no room opens, and a release there lands on a target beneath, else goes home. placeOf is also asked about the current target just outside its zone (within the band or the gap grace): answer the nearest place there, and return null only for a part of the target that takes no drop. It runs on every sample for each target under the pointer, so keep it cheap.
• A release lands on the shown target whenever one shows (drop = shown), else on the target under the pointer, else nowhere. A release over home does nothing.
• The three previews only change what is drawn: all follow these rules, so a drop lands where the preview showed it in each.

import { createDragIntent, type DragTarget } from "@n-uf/motion/drag";

const slot: DragTarget = { id: "slot", priority: 2, hit: { x: 0, y: 0, width: 200, height: 100 } };
const intent = createDragIntent({ home: { x: 300, y: 300, width: 100, height: 50 } });
for (let t = 0; t <= 300; t += 16) intent.update({ x: 100, y: 50 }, t, [slot]); // held still over the slot
console.log(intent.state.shown?.id); // "slot"
console.log(intent.release({ x: 100, y: 50 }, [slot])?.id); // "slot"

// A pane that takes drops on its right half only; that half holds 6 px past the line.
const pane: DragTarget = { id: "pane", priority: 2, hit: { x: 0, y: 0, width: 200, height: 100 } };
const zones = createDragIntent<DragTarget>({
  home: { x: 300, y: 300, width: 100, height: 50 },
  placeOf: (_t, p, previous) => (p.x >= (previous === "right" ? 94 : 100) ? "right" : null),
});
for (let t = 0; t <= 300; t += 16) zones.update({ x: 50, y: 50 }, t, [pane]); // held over its left half
console.log(zones.state.shown, zones.release({ x: 50, y: 50 }, [pane])); // null null: nothing shows, the item goes home

The intent works in one coordinate space: the one its targets and home are in. On a page drawn scaled (a zoomed canvas, a fitted preview), convert each pointer sample into page coordinates first, (p − origin) / scale, and the band, breakthrough and stillness distances stay page px:

// The page is drawn at half size, its top-left corner at (300, 200) on screen; targets are in page px.
const origin = { x: 300, y: 200 };
const scale = 0.5;
const toPage = (p: { x: number; y: number }) => ({ x: (p.x - origin.x) / scale, y: (p.y - origin.y) / scale });
const onPage = createDragIntent({ home: { x: 600, y: 600, width: 100, height: 50 } });
const screen = { x: 350, y: 225 }; // the pointer, as the browser reports it
for (let t = 0; t <= 300; t += 16) onPage.update(toPage(screen), t, [slot]); // page (100, 50): over the slot
console.log(onPage.state.shown?.id, onPage.release(toPage(screen), [slot])?.id); // "slot" "slot"

@n-uf/motion/browser

The host is typed by its shape, not by lib.dom, so tests and workers can pass their own.

Testing

Everything runs on createFakeClock(): frames, timers, springs and machine deadlines move only when the test moves the clock, so motion is exact and repeatable. @n-uf/motion/testing (above) checks the frames you record.

Benchmarks

pnpm bench times the signals against alien-signals' and @preact/signals-core's own APIs on graphs of a few thousand nodes, and prints bundle sizes and the deepest chain each survives. Results and the choice they led to are in bench/RESULTS.md↗ (opens in a new tab).

Versions

Calendar versions YY.M.R (year, month of the release, counter within the month), the same scheme as @n-uf/hypr-tiling. pnpm version:bump sets the next one; never type one by hand.

License

PolyForm Perimeter 1.0.1↗ (opens in a new tab).