saccade 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -24,6 +24,8 @@ __export(src_exports, {
   Saccade: () => Saccade,
   SaccadeEngine: () => SaccadeEngine,
   SaccadeProvider: () => SaccadeProvider,
+  getSharedEngine: () => getSharedEngine,
+  resetSharedEngine: () => resetSharedEngine,
   useSaccadeEngine: () => useSaccadeEngine,
   useSpeed: () => useSpeed,
   useTimeline: () => useTimeline
@@ -50,6 +52,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();
@@ -225,13 +228,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 {
     }
   }
@@ -277,10 +286,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;
@@ -1555,7 +1565,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) {
@@ -1570,7 +1580,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) {
@@ -1595,7 +1605,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}`);
@@ -1662,7 +1672,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);
@@ -1717,6 +1727,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;
@@ -1791,7 +1817,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);
@@ -1816,13 +1842,29 @@ var SaccadeEngine = class {
   }
 };
 
+// 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;
+}
+
 // src/react/SaccadeContext.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
 var SaccadeContext = (0, import_react.createContext)(null);
-function SaccadeProvider({ children }) {
+function SaccadeProvider({
+  children,
+  engine
+}) {
   const engineRef = (0, import_react.useRef)(null);
   if (!engineRef.current) {
-    engineRef.current = new SaccadeEngine();
+    engineRef.current = engine ?? getSharedEngine();
   }
   return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(SaccadeContext.Provider, { value: engineRef.current, children });
 }
@@ -1839,10 +1881,10 @@ var import_react6 = require("react");
 var import_react2 = require("react");
 var import_jsx_runtime2 = require("react/jsx-runtime");
 var DETAIL_LABELS = {
-  compact: "Compact",
-  standard: "Standard",
+  brief: "Brief",
+  moderate: "Moderate",
   detailed: "Detailed",
-  forensic: "Forensic"
+  granular: "Granular"
 };
 function CopyCheckIcon({ copied }) {
   const spring = "cubic-bezier(0.34, 1.15, 0.64, 1)";
@@ -1896,10 +1938,10 @@ function CopyCheckIcon({ copied }) {
   ] });
 }
 var DETAIL_BRIGHT_COUNT = {
-  compact: 1,
-  standard: 2,
+  brief: 1,
+  moderate: 2,
   detailed: 3,
-  forensic: 4
+  granular: 4
 };
 function DetailIcon({ level }) {
   const bright = DETAIL_BRIGHT_COUNT[level];
@@ -2224,7 +2266,9 @@ function SpeedControl({ speed, isPaused, onSetSpeed, onTogglePause }) {
 
 // src/react/useTimeline.ts
 var import_react4 = require("react");
-var DETAIL_LEVELS = ["compact", "standard", "detailed", "forensic"];
+var _realSetTimeout = setTimeout.bind(window);
+var _realClearTimeout = clearTimeout.bind(window);
+var DETAIL_LEVELS = ["brief", "moderate", "detailed", "granular"];
 function useTimeline() {
   const engine = useSaccadeEngine();
   const state = (0, import_react4.useSyncExternalStore)(
@@ -2235,7 +2279,7 @@ function useTimeline() {
   const [scrubTime, setScrubTime] = (0, import_react4.useState)(0);
   const [copied, setCopied] = (0, import_react4.useState)(false);
   const [exportFilter, setExportFilter] = (0, import_react4.useState)("all-animations");
-  const [detailLevel, setDetailLevel] = (0, import_react4.useState)("standard");
+  const [detailLevel, setDetailLevel] = (0, import_react4.useState)("moderate");
   const copiedTimeout = (0, import_react4.useRef)(null);
   const pendingSeek = (0, import_react4.useRef)(null);
   const rafId = (0, import_react4.useRef)(0);
@@ -2309,8 +2353,8 @@ function useTimeline() {
       navigator.clipboard.writeText(text).catch(() => {
       });
       setCopied(true);
-      if (copiedTimeout.current) clearTimeout(copiedTimeout.current);
-      copiedTimeout.current = setTimeout(() => setCopied(false), 2e3);
+      if (copiedTimeout.current) _realClearTimeout(copiedTimeout.current);
+      copiedTimeout.current = _realSetTimeout(() => setCopied(false), 1800);
       return text;
     },
     [engine, capture, scrubTime, exportFilter, detailLevel]
@@ -2862,7 +2906,7 @@ var PANEL_STYLES = (
 
 // src/react/Saccade.tsx
 var import_jsx_runtime5 = require("react/jsx-runtime");
-function Saccade({ position = "bottom-left" }) {
+function Saccade({ position = "bottom-left", engine }) {
   const [shadowRoot, setShadowRoot] = (0, import_react7.useState)(null);
   const hostRef = (0, import_react7.useRef)(null);
   (0, import_react7.useEffect)(() => {
@@ -2886,7 +2930,7 @@ function Saccade({ position = "bottom-left" }) {
   }, [position]);
   if (!shadowRoot) return null;
   return (0, import_react_dom.createPortal)(
-    /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(SaccadeProvider, { children: /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(SaccadePanel, {}) }),
+    /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(SaccadeProvider, { engine, children: /* @__PURE__ */ (0, import_jsx_runtime5.jsx)(SaccadePanel, {}) }),
     shadowRoot.lastElementChild || shadowRoot
   );
 }
@@ -2895,6 +2939,8 @@ function Saccade({ position = "bottom-left" }) {
   Saccade,
   SaccadeEngine,
   SaccadeProvider,
+  getSharedEngine,
+  resetSharedEngine,
   useSaccadeEngine,
   useSpeed,
   useTimeline