Capture every animation and scroll in a real browser. Compare it with an approved baseline. See the difference, frame by frame.
Website · Documentation · Interactive demo · Changelog · Roadmap · Contributing
Important
Alpha. Published to npm on the alpha tag for feedback, not for production use: the
capture format and the API can still change before 1.0. Chromium, Firefox and WebKit, each
with its own baseline. See Status.
npm install -D @erenthedeveloper0/motionpr@alpha
npx motionpr install # Chromium, once per machine (or: install firefox webkit, install --all)
npx motionpr init # writes motionpr.config.ts
npx motionpr run # capture → compare with the baseline → report
npx motionpr run --browser all # the same in Chromium, Firefox and WebKit// motionpr.config.ts
import { defineConfig } from "@erenthedeveloper0/motionpr";
export default defineConfig({
baseURL: "http://localhost:3000",
webServer: {
command: "npm run dev",
url: "http://localhost:3000",
reuseExistingServer: !process.env.CI,
},
scenarios: [
{
id: "menu",
steps: [
{ type: "click", selector: "[data-testid=menu-toggle]" },
{ type: "capture", label: "open" },
],
},
],
});Change a transition from 300ms cubic-bezier(0.16, 1, 0.3, 1) to 600ms ease-in-out and run
again. This is MotionPR's real output:
✖ menu-open@default 1 critical · 1 warning · 1 info
✖ menu-open: css-transition “transform” on menu: Duration 300ms → 600ms (+300ms, +100%)
▲ menu-open: css-transition “transform” on menu: Easing cubic-bezier(0.16, 1, 0.3, 1) → ease-in-out (max deviation 70% of …
● menu-open: css-transition “transform” on menu: translateX path deviates up to 195.3px at 26% progress
Result FAILED fail on: critical 1 critical · 1 warning · 1 info
The command exits 1, and the report in .motionpr/report/ plays both versions side by side, on
one clock, frame by frame.
Contents: The idea · What it catches · Status · Integrations · Browsers · How it works · CI · Try it · Layout · Documentation · Contributing
Your code changed. See how your interface moves.
Motion is behaviour, and it is the part of a change code review sees least. A pull request that
turns 320ms into 560ms, or swaps a tuned cubic-bezier() for a design-token ease-in-out,
reads like cleanup. Unit tests assert on state, end-to-end tests wait for animations to finish,
and screenshot tests compare the settled frame, which is the same before and after.
MotionPR records motion as data: every animation's timing, easing curve (65 samples), animated properties and sampled computed values, every timeline's labels, and every scroll's position over time. Data can be compared exactly, with tolerances you choose, and every difference gets a severity from a named rule.
The logo is the same idea. Take a circle, move it, overlay both positions and keep only the pixels that changed: what remains is the MotionPR mark. If nothing moves differently, the mark disappears. The website's hero draws it from the demo app's real baseline and candidate.
| A change in your code | What MotionPR reports (real messages) |
|---|---|
transition duration and easing |
Duration 320ms → 560ms (+240ms, +75%) · Easing … → ease-in-out (max deviation 70% of progress at 27% time) |
A clip-path reveal animation deleted |
critical Removed: css-animation “wipe-in” on case-image |
element.animate() stagger from 70 to 120 ms |
Stagger interval 70ms → 120ms across 6 elements |
GSAP power3.out → back.out(1.7) |
Easing power3.out → back.out(1.7) (max deviation 16% of progress at 41% time; now overshoots) |
An Anime.js timeline step moved from -=120 to +=120 |
Label “ship” moved 600ms → 840ms, Timeline duration 840ms → 1080ms |
Lenis lerp from 0.1 to 0.06 |
Scroll takes 1229ms → 2046ms to settle (+816ms), Peak scroll velocity 4.11 → 2.56 px/ms (-38%) |
A ScrollTrigger start moved |
Scroll-linked progress at the same scroll position differs by up to 14% |
| An element matched only by DOM position changed | uncertain, never a failure: (element matched by DOM position only) |
Every row comes from the bundled demo app, whose candidate variant contains eleven deliberate
motion changes; npx motionpr demo reproduces them (the messages above are Chromium's; Firefox and
WebKit find the same changes). Severities, rules and their rationale are
in Severity & thresholds.
Alpha — 0.2.0-alpha. It works end to end in Chromium, Firefox and WebKit for the engines below, and
every claim in the documentation is backed by an automated test. Do not put it on a path that
blocks production releases yet: the capture format and the public API may change before 1.0.
Older captures are migrated when they are read.
- Capture of CSS transitions, CSS animations and Web Animations, with deterministic replay (paused clones, callbacks muted), sampled computed styles and geometry, and content-addressed filmstrips.
- Three browser engines: Chromium, Firefox and WebKit (Playwright 1.65's builds), each with its
own baseline, captures and report;
--browser allruns them in one go, and comparing two engines is explicit. - Adapters for GSAP (tweens, timelines, staggers, keyframes; ScrollTrigger as metadata plus
live progress), Anime.js v4 (animations, timelines, staggers,
waapi.animate) and Lenis (scroll motion), all through public APIs and no-ops outside a capture. - Scroll motion as its own record, recorded live and compared by distance, settle time, normalized progress curve, peak velocity, overshoot and lag.
- Comparison of timing, easing curves, iterations, direction, playback rate, staggers, keyframes, trajectories, opacity and size, timelines and labels, scroll, and settled pixels, with severities from named, overridable rules and uncertainty kept separate from regressions.
- An offline report viewer: side by side, overlay, onion skin with motion paths, wipe, pixel difference, a shared timeline with easing curves, an inspector, and keyboard navigation.
- A CLI (
init,install,capture,compare,run,baseline,report,doctor,demo) with CI exit codes, JSON and Markdown output, and a least-privilege GitHub Actions template.
Windows in CI · replaying scroll-linked tween values · nested native scroll containers · Shadow DOM selector piercing · example projects · engines in parallel within one run. The roadmap orders them, and Limitations lists every known gap.
| Integration | Role | Support |
|---|---|---|
| Native CSS (transitions, animations) | Animation | Verified, no setup |
Web Animations API (element.animate) |
Animation | Verified, no setup |
GSAP · @erenthedeveloper0/motionpr/gsap |
Animation, timelines | Verified with 3.15.1 (>=3.12 <4); ScrollTrigger: metadata + live progress |
Anime.js · @erenthedeveloper0/motionpr/animejs |
Animation, timelines, staggers | Verified with 4.5.0 (>=4 <5); v3 is not supported |
Lenis · @erenthedeveloper0/motionpr/lenis |
Scroll motion | Verified with 1.3.27 (>=1.1 <2) |
| CSS scroll-driven animations | Animation | Metadata only |
"Verified" means covered by automated tests against a real browser in this repository, in Chromium, Firefox and WebKit. The animation engines are optional peer dependencies.
import gsap from "gsap";
import { motionprGsap } from "@erenthedeveloper0/motionpr/gsap";
motionprGsap.register(gsap); // a no-op unless MotionPR is capturing the pageGuides: Native CSS · WAAPI · GSAP · Anime.js · Lenis · Combining adapters.
| Engine | Build tested (Playwright 1.65) | Install | Run |
|---|---|---|---|
| Chromium | Chrome for Testing 158 | npx motionpr install |
npx motionpr run (default) |
| Firefox | Firefox 159 | npx motionpr install firefox |
npx motionpr run --browser firefox |
| WebKit | WebKit 27.2 | npx motionpr install webkit |
npx motionpr run --browser webkit |
Engines render, lay out and schedule motion differently, so each one is compared with its own
baseline in .motionpr/baseline/<browser>/: accepting the Firefox baseline never touches the
Chromium one. --browser all runs every engine against one web server and exits with the worst
result; .motionpr/report/index.html lists each engine's report. To see how two engines differ,
ask for it: npx motionpr compare --browser webkit --against chromium (pixel and layout differences
are then uncertain). WebKit is Playwright's WebKit, the engine behind Safari, not Safari itself.
See Browser support and
Cross-browser testing.
- Capture. MotionPR opens each scenario in Chromium, Firefox or WebKit and injects an agent before your scripts run. Your steps drive the page with real input; adapters report GSAP, Anime.js and Lenis.
- Analyze. When motion settles, the window is replayed at exact times with callbacks muted, to sample computed values and render frames. Scroll is recorded live and never replayed.
- Compare. Records are matched by element identity, type and name, then compared field by field and curve by curve. Every difference gets a severity from a rule.
- Inspect. An offline HTML report plays baseline (blue) and candidate (peach) on one clock.
- Report. A summary, a Markdown step summary in GitHub Actions, and an exit code.
The internals are in Architecture.
npx motionpr init --github writes a workflow that needs only contents: read, pins every action
to a commit SHA, runs motionpr run --ci, and uploads the report as an artifact even when the
job fails. Exit codes: 0 within thresholds, 1 regression, 2 error. For several engines, use a
matrix with --browser ${{ matrix.browser }}, or one job with --browser all.
See GitHub Actions.
npx @erenthedeveloper0/motionpr@alpha install # Chromium (or: install firefox, install webkit)
npx @erenthedeveloper0/motionpr@alpha demo # the demo app in two versions, and a real report
npx @erenthedeveloper0/motionpr@alpha demo --browser firefoxOr work on the repository (Node ≥ 22.18 and pnpm through Corepack):
git clone https://github.com/erenthedeveloper0/motionpr.git && cd motionpr
corepack enable && pnpm install
pnpm exec playwright install chromium firefox webkit
pnpm build # agent bundle, report viewer, demo app, CLI
pnpm typecheck && pnpm lint && pnpm format:check
pnpm test # unit tests
pnpm test:integration # real Chromium: capture engine, adapters, CLI, all three engines in one project
MOTIONPR_TEST_BROWSER=firefox pnpm test:integration # the same suites in Firefox (or webkit)
pnpm test:e2e # the demo app captured for real; the report viewer and the website driven like a user
pnpm pack:check --install # what ships to npm, installed into a clean project and run
pnpm dev:docs # the website on http://localhost:4321/motionpr/| Suite | What it proves |
|---|---|
packages/core/tests |
Config schema and defaults, easing parsing and evaluation (Chromium-exact to 1e-4), capture/comparison schemas, v1 → v2 migrations, path-traversal guards |
packages/comparison/tests |
Matching, every comparison rule and its thresholds, stagger detection, scroll metrics, regressions found earlier |
packages/capture/tests |
The agent in real Chromium, Firefox and WebKit: discovery, settling, deterministic replay, filmstrips, privacy masks, memory, engine edge cases |
packages/adapters/*/tests |
GSAP, Anime.js (including a sample-for-sample port of its eases) and Lenis adapters in all three engines, with lifecycle and cleanup |
packages/report/tests, e2e/report.spec.ts |
Report generation and the viewer driven like a user |
packages/cli/tests |
Every command, exit codes, prompts that refuse in CI, a GSAP + Anime.js + Lenis motionpr run, per-browser baselines and --browser all |
e2e/demo-expectations.spec.ts |
Every intended change in the demo app is found, and nothing else is reported, in each engine |
e2e/docs-site.spec.ts |
The website: every route and link, soft navigation with history and scroll restoration, animation cleanup, search, copy, mobile, reduced motion, keyboard, and every interactive component |
scripts/tests/docs.test.ts |
Every export, step type, CLI command and config section is documented; config examples validate against the schema; no workflow can publish to npm |
scripts/pack-check.mjs |
The npm tarball: an allowlist of files, entry points, types, and an install into a clean project |
packages/
core/ schemas (capture/comparison v2), config, easing math, adapter protocol, storage
capture/ Playwright runner (Chromium, Firefox, WebKit) and the in-page agent
comparison/ matching, animation/scroll/timeline comparison, severity, visual diff
report/ the offline report viewer (React, one HTML file) and its generator
adapters/ gsap · animejs · lenis (browser code)
cli/ the motionpr CLI and public entry points: the only published package
apps/docs/ the website: landing page, documentation, interactive demo, playground
docs/ the documentation, in Markdown (rendered by apps/docs, readable on GitHub)
fixtures/ the demo app, with baseline and candidate variants
e2e/ Playwright tests: demo expectations, report viewer, website
brand/ the MotionPR brand: logo geometry, logos, icons, social images
scripts/ pack check, release preparation, version sync, demo capture
@erenthedeveloper0/motionpr bundles the private workspace packages; its tarball contains only
dist/, README.md, LICENSE and THIRD_PARTY_NOTICES.md.
- Start: Introduction · Requirements · Installation · First capture · First comparison
- Features: Interaction scenarios · Motion comparison · Easing analysis · Severity & thresholds · HTML reports
- Reference: CLI · Configuration · Public API · Capture serialization
- Browsers: Browser support · Cross-browser testing · Chromium · Firefox · WebKit
- Operations: GitHub Actions · Baseline management · Troubleshooting · Privacy
Everything is also on the website, with search: https://erenthedeveloper0.github.io/motionpr/docs/
Contributions are welcome. CONTRIBUTING.md has the setup, the checks and the conventions; SECURITY.md explains how to report a vulnerability privately, and SUPPORT.md where to ask questions. Three rules worth knowing up front:
- A claim needs a test. A compatibility claim in the docs needs a real-browser test; a
documented option needs to exist in the schema.
scripts/tests/docs.test.tschecks both. - Uncertainty is not a regression. When MotionPR cannot be sure (a weak element match,
incomplete data), the difference is
uncertainand never fails a run by default. - Adapters read public APIs only, never re-fire application callbacks, and leave every engine exactly as they found it.
MIT © Eren Sümer. Third-party components bundled into the package are listed in THIRD_PARTY_NOTICES.md; contributors in CONTRIBUTORS.md.