saccade 0.1.0 → 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

package/dist/core.cjs

@@ -26,7 +26,9 @@ __export(core_exports, {
   TimingController: () => TimingController,
   formatExportForLLM: () => formatExportForLLM,
   generateExport: () => generateExport,
-  getFrameAtTime: () => getFrameAtTime
+  getFrameAtTime: () => getFrameAtTime,
+  getSharedEngine: () => getSharedEngine,
+  resetSharedEngine: () => resetSharedEngine
 });
 module.exports = __toCommonJS(core_exports);
 
@@ -43,6 +45,7 @@ var TimingController = class {
     this._origAnimate = null;
     this.installed = false;
     this.animPollId = 0;
+    this.gsapInstance = null;
     // WeakMap tracking for animations and media
     this.trackedAnims = /* @__PURE__ */ new WeakMap();
     this.trackedMedia = /* @__PURE__ */ new WeakMap();
@@ -218,13 +221,19 @@ var TimingController = class {
     } catch {
     }
   }
+  /**
+   * Register a GSAP instance (for ES-module imports where window.gsap is
+   * undefined). Applies the current timeScale immediately if speed !== 1.
+   */
+  registerGSAP(gsap) {
+    this.gsapInstance = gsap;
+    if (this.speed !== 1) this.patchGSAP();
+  }
   /** Sync GSAP's global timeline if present. */
   patchGSAP() {
     try {
-      const gsap = window.gsap;
-      if (gsap?.globalTimeline) {
-        gsap.globalTimeline.timeScale(this.speed || 1e-3);
-      }
+      const gsap = this.gsapInstance ?? window.gsap;
+      gsap?.globalTimeline?.timeScale(this.speed || 1e-3);
     } catch {
     }
   }
@@ -270,10 +279,11 @@ var TimingController = class {
     } catch {
     }
     try {
-      const gsap = window.gsap;
-      if (gsap?.globalTimeline) gsap.globalTimeline.timeScale(1);
+      const gsap = this.gsapInstance ?? window.gsap;
+      gsap?.globalTimeline?.timeScale(1);
     } catch {
     }
+    this.gsapInstance = null;
     delete window.__LAPSE_ORIGINAL_RAF__;
     delete window.__saccadeInstalled;
     this.installed = false;
@@ -1548,7 +1558,7 @@ function generateExport(animations, frames, timeMs, filter = "active") {
     animations: animExports
   };
 }
-function formatExportForLLM(exp, detail = "standard") {
+function formatExportForLLM(exp, detail = "moderate") {
   const lines = [];
   const grouped = /* @__PURE__ */ new Map();
   for (const anim of exp.animations) {
@@ -1563,7 +1573,7 @@ function formatExportForLLM(exp, detail = "standard") {
     const [from, to] = prop.range.split(" \u2192 ");
     return !(from && to && from.trim() === to.trim());
   }
-  if (detail === "compact") {
+  if (detail === "brief") {
     lines.push(`# Animation State at ${exp.timestamp}`);
     lines.push("");
     for (const [, group] of grouped) {
@@ -1588,7 +1598,7 @@ function formatExportForLLM(exp, detail = "standard") {
   }
   lines.push(`# Animation State at ${exp.timestamp}`);
   lines.push("");
-  if (detail === "forensic") {
+  if (detail === "granular") {
     lines.push("**Environment:**");
     lines.push(`- Viewport: ${window.innerWidth}\xD7${window.innerHeight}`);
     lines.push(`- URL: ${window.location.href}`);
@@ -1655,7 +1665,7 @@ function formatExportForLLM(exp, detail = "standard") {
       lines.push(`Transitions: ${[...transitionSet].join(", ")}`);
       lines.push("");
       for (const line of cssPropLines) lines.push(line);
-      if (detail === "detailed" || detail === "forensic") {
+      if (detail === "detailed" || detail === "granular") {
         const allVars = {};
         for (const anim of cssAnims) {
           if (anim.resolvedVars) Object.assign(allVars, anim.resolvedVars);
@@ -1710,6 +1720,22 @@ var SaccadeEngine = class {
   getSpeed() {
     return this.timing.getSpeed();
   }
+  /**
+   * Install the timing patches immediately, without changing speed.
+   *
+   * Call this as early as possible (before app code, GSAP, or Framer Motion
+   * run) so they capture the patched time functions rather than the originals.
+   * Idempotent and harmless to call more than once. `setSpeed` and
+   * `startRecording` also install on demand, so this is only needed to win the
+   * early-load race against libraries that cache `Date.now`/`performance.now`.
+   */
+  install() {
+    this.timing.install();
+  }
+  /** Register a module-imported GSAP instance so saccade can slow it. */
+  registerGSAP(gsap) {
+    this.timing.registerGSAP(gsap);
+  }
   // -- Timeline recording ---------------------------------------------------
   startRecording(boundingBox) {
     if (this._state !== "idle") return;
@@ -1784,7 +1810,7 @@ var SaccadeEngine = class {
       filter
     );
   }
-  exportForLLM(timeMs, filter = "active", detail = "standard") {
+  exportForLLM(timeMs, filter = "active", detail = "moderate") {
     const exp = this.generateExport(timeMs, filter);
     if (!exp) return "";
     return formatExportForLLM(exp, detail);
@@ -1808,6 +1834,19 @@ var SaccadeEngine = class {
     this._state = "idle";
   }
 };
+
+// src/core/shared.ts
+var KEY = "__saccadeSharedEngine__";
+function getSharedEngine() {
+  const g = globalThis;
+  if (!g[KEY]) g[KEY] = new SaccadeEngine();
+  return g[KEY];
+}
+function resetSharedEngine() {
+  const g = globalThis;
+  g[KEY]?.destroy();
+  g[KEY] = null;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   SaccadeEngine,
@@ -1816,6 +1855,8 @@ var SaccadeEngine = class {
   TimingController,
   formatExportForLLM,
   generateExport,
-  getFrameAtTime
+  getFrameAtTime,
+  getSharedEngine,
+  resetSharedEngine
 });
 //# sourceMappingURL=core.cjs.map