@magic-spells/frame-engine

Frame
Engine

Position-driven CSS keyframe interpolation. Colors, transforms, filters, opacity — calculated between any number of keyframes in real time.

Install npm i @magic-spells/frame-engine
Size (gzip) ~5 KB

Quick Start

Define keyframes as CSS style objects at percentage positions. Call getFrame() with any value from 0 to 1 to get interpolated styles.

Setup 
import FrameEngine from '@magic-spells/frame-engine'

const animation = new FrameEngine({
  0:   { opacity: '1',   transform: 'translateX(0px)' },
  50:  { opacity: '0.5', transform: 'translateX(200px)' },
  100: { opacity: '0',   transform: 'translateX(400px)' },
})
Usage 
// Get styles at any position (0–1)
const styles = animation.getFrame(0.5)
// → { opacity: '0.5', transform: 'translateX(200px)' }

// Apply to an element
Object.assign(element.style, styles)

// Works beyond 0–1 for overshoot
animation.getFrame(1.2)
// → extrapolated values past 100%

Color Interpolation

Smooth RGB channel blending across four color stops. Hex values are decomposed, interpolated per-channel, and recomposed.

Position 0%

Transform Composition

Independent interpolation of translateX, rotate, and scale within a single compound transform string. Each function is parsed and tweened separately.

Position 0%

Filter Effects

CSS filter functions — blur, brightness, hue-rotate — each interpolated as independent numeric values within the filter string.

Position 0%

Multi-Property Orchestra

Everything at once — color, transform, opacity, border-width, and filters all interpolated from a single position value across four keyframes.

Position 0%

Extrapolation & Clamping

Drag past 100% to see physics-friendly overshoot. Position and custom properties extrapolate freely while bounded properties like opacity clamp to valid CSS ranges.

100%
Position 0%

Metamorphosis

Driven by @magic-spells/physics-engine — a spring drives progress through five Frame Engine keyframes. The orb morphs color, border-radius, scale, and glow with natural overshoot and settle.

Spring Traverse

Driven by @magic-spells/physics-engine — a spring propels a shape across the stage. Frame Engine maps the spring progress to compound transforms, color shifts, and border-radius.

Parameter Lab

Driven by @magic-spells/physics-engine — adjust attraction and friction to feel how spring dynamics change. Higher attraction snaps faster. Higher friction damps the bounce.

Attraction 0.026
Friction 0.28
Distance 1200
Velocity 20

Cascade

Driven by @magic-spells/physics-engine — eight elements, each with its own spring, launched in sequence. The same Frame Engine keyframes on every dot — staggered timing creates a wave of color and motion.