For agents: start with the agent guide. Every page is Markdown by default; add Accept: text/html for HTML.

Motion

What it does

@rat-stack/motion moves values over time in a Foldkit²⁷ app. Its core is four TypeScript modules in packages/motion/src/*.pure.ts. They import only each other, so another project can copy them at a pinned commit.¶

• Easing: Robert Penner’s ten curve families come in three variants each: in, out and in-out.¶
• CSS easing: linear, cubic-bezier(), steps() and keywords such as ease-in-out follow the CSS spec.¶
• Tween: a value moves between two endpoints over a duration along one easing. The sample function reads the value at any time. A retarget starts a new tween from the sampled value, so the value never jumps.¶
• Spring: a value of any dimension follows a target with stiffness, damping and mass. The critical(frequency) preset arrives without overshoot.¶
• Interpolation: numbers, tuples, colours in OKLab, and 2D transforms split into translate, scale and rotate.¶

The spring takes fixed steps of 1/120 s. It carries the leftover time to the next frame. When it comes to rest, it snaps exactly onto the target.¶

  const span = Math.min(MAX_STEP_MS, Math.max(0, elapsed));
  const ticks = into.remainder + span / SUBSTEP_MS;
  const substeps = Math.floor(ticks + SUBSTEP_GRID_TOLERANCE);

  for (let substep = 0; substep < substeps; substep += 1) {
    substepInto(into);

    if (atRest(into.config, into.position, into.velocity, into.target)) {
      return snapInto(into);
    }
  }

  into.remainder = Math.max(0, ticks - substeps);

  return into;

The Foldkit adapter³⁰, @rat-stack/motion/foldkit, keeps a clock and the named tweens and springs in the Model. A frame is a TickedFrame Message. Motion.advance steps every spring and moves the clock. The view samples each tween at the clock time.¶

export const motionSubscriptions = <Model, Message>(
  options: MotionSubscriptionOptions<Model, Message>
) =>
  Subscription.make<Model, Message>()(() => ({
    motionFrame: Subscription.animationFrameEntry<Model, Message>({
      isActive: options.isAnimating,
      toMessage: (elapsed) =>
        options.toMessage(Message.TickedFrame({ elapsed })),
    }),
    reducedMotion: Subscription.persistentEntry(
      Dom.streamFromMediaQuery({
        mapMatches: (isReducedMotion) =>
          options.toMessage(Message.ChangedReducedMotion({ isReducedMotion })),
        query: REDUCED_MOTION_QUERY,
      })
    ),
  }));

Pick a target in the demo at the end of this page, then pick another before the dots arrive. The tween restarts its curve. The spring keeps its speed and turns.¶

The curve gallery plots every easing.¶

The standard

• Every easing starts at 0 and ends at 1. The CSS start jumps are the exception: steps(n, jump-start) begins at 1/n, as the spec requires.¶
• Every curve except back, elastic and bounce never falls. Every out curve mirrors its in curve: out(t) = 1 - in(1 - t).¶
• cubicBezier agrees with an exact bisection reference for any valid control points.¶
• A tween with a monotonic easing stays between its endpoints. A retarget keeps the sampled value.¶
• One spring step of a span gives the same state as two steps that split it on the substep grid.¶
• A critically damped spring from rest settles within six periods, snaps exactly, and never overshoots in one dimension.¶
• Under prefers-reduced-motion, every tween and spring lands on its target at once.¶
• No Worker⁶⁰ graph imports the package, so it adds no startup bytes.¶

Each rule is an it.prop property over generated inputs. Each property also runs against a planted bug, and the suite fails if the property passes it.¶

      "the frame-rate property catches an integrator that takes whole frames",
      () =>
        falsifies(
          Arbitrary.all([
            movingSpring,
            integerBetween(1, 6),
            integerBetween(1, 6),
          ]),
          ([from, first, second]) =>
            splitAgrees(wholeFrameEuler, from, first, second)
        )
    );

How to check

• pnpm --filter @rat-stack/motion test runs the properties and the planted bugs.¶
• packages/motion/test/vendoring.test.ts fails if a core module imports anything except another core module, or names a browser global.¶
• pnpm --filter @rat-stack/site typecheck prints the Mischief startup size against its ceiling.¶
• Open /systems/motion with reduced motion turned on. The dots and curves show their end state.¶

Last changed 2026-11-02 in 67d126f. Source on GitHub. Change log.