saccade 0.0.3 → 0.2.0

package/README.md

@@ -27,9 +27,48 @@ function App() {
 
 A floating panel appears in the corner. Use it to control speed, record, and scrub.
 
+## Slowing every animation library
+
+Saccade slows anything driven by the standard time sources — CSS transitions,
+CSS `@keyframes`, the Web Animations API, `requestAnimationFrame` loops, video
+and audio, and JS libraries that read `Date.now`/`performance.now`/rAF such as
+**Framer Motion**. To reach them all reliably you need two things:
+
+### 1. Install before your app code (recommended)
+
+Libraries that cache a time function before saccade patches it never see
+slow-mo. Because `<Saccade>` mounts inside React, its patches go in *after*
+anything imported earlier. Import the side-effect entry **first** in your app
+entry so the timing APIs are patched before any other module runs:
+
+```ts
+// main.tsx — must be the first import
+import 'saccade/install'
+
+import { createRoot } from 'react-dom/client'
+import { App } from './App'
+// …
+```
+
+This patches the same shared engine `<Saccade>` uses, so the panel still
+controls everything. It's optional — without it, anything imported before
+`<Saccade>` mounts may not slow down.
+
+### 2. Register GSAP (ES-module imports only)
+
+GSAP is auto-detected when loaded as a global (UMD/CDN). When you `import` it as
+an ES module, `window.gsap` is undefined, so hand saccade your instance once:
+
+```ts
+import { gsap } from 'gsap'
+import { getSharedEngine } from 'saccade'
+
+getSharedEngine().registerGSAP(gsap)
+```
+
 ## Features
 
-- **Speed control** — Slow down or speed up all animations (CSS transitions, CSS animations, JS timers, `requestAnimationFrame`, video/audio)
+- **Speed control** — Slow down or speed up all animations: CSS transitions, CSS `@keyframes`, the Web Animations API, `requestAnimationFrame`, JS timers, video/audio, GSAP, and Framer Motion
 - **Timeline recording** — Record interactions, then scrub through captured frames to inspect mid-transition states
 - **LLM export** — Copy structured animation state (properties, keyframes, easing, progress) as markdown for AI coding agents
 - **Shadow DOM isolation** — Panel styles never leak into your app
@@ -38,13 +77,14 @@ A floating panel appears in the corner. Use it to control speed, record, and scr
 
 ## How it works
 
-Saccade patches timing APIs (`setTimeout`, `setInterval`, `requestAnimationFrame`, `performance.now`, `Date.now`) to scale time by a configurable factor. During recording, it snapshots computed styles, attributes, and animation state every frame. In scrub mode, it replays those snapshots by applying inline styles directly to the DOM.
+Saccade patches timing APIs (`setTimeout`, `setInterval`, `requestAnimationFrame`, `performance.now`, `Date.now`) to scale time by a configurable factor — this covers `requestAnimationFrame` loops and time-reading libraries like Framer Motion. CSS transitions, `@keyframes`, and Web Animations API animations are scaled via their `playbackRate`; GSAP via its global timeline `timeScale`. During recording, it snapshots computed styles, attributes, and animation state every frame. In scrub mode, it replays those snapshots by applying inline styles directly to the DOM.
 
 ## Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `position` | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `'bottom-left'` | Panel position |
+| `engine` | `SaccadeEngine` | shared singleton | Engine the panel drives. Defaults to the process-wide shared engine, so app code (via `getSharedEngine()`) and the panel control the same instance. Pass your own only to isolate. |
 
 ## Core API
 
@@ -59,6 +99,13 @@ const engine = new SaccadeEngine()
 engine.setSpeed(0.25) // quarter speed
 engine.getSpeed()
 
+// Patch timing APIs now, without changing speed (win the early-load race).
+// setSpeed/startRecording also install on demand, so this is only needed up front.
+engine.install()
+
+// Register a module-imported GSAP instance (window.gsap fallback otherwise)
+engine.registerGSAP(gsap)
+
 // Recording
 engine.startRecording()
 const capture = engine.stopRecording()
@@ -74,6 +121,22 @@ const markdown = engine.exportForLLM(500, 'active', 'standard')
 engine.destroy()
 ```
 
+### Shared engine
+
+`new SaccadeEngine()` gives you an isolated engine. If you also render
+`<Saccade>` and want app code to drive the same one the panel does, use the
+process-wide singleton instead:
+
+```ts
+import { getSharedEngine } from 'saccade' // or 'saccade/core'
+
+const engine = getSharedEngine() // same instance <Saccade> uses by default
+engine.setSpeed(0.5)
+```
+
+`saccade/install` installs this shared engine, so importing it and calling
+`getSharedEngine()` always refer to the same instance.
+
 ## React Hooks
 
 ```tsx