saccade 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -2,15 +2,8 @@ import * as react from 'react';
 import { ReactNode } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
-type SaccadePosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-type SaccadeProps = {
-    /** Panel position. Default: 'bottom-left' */
-    position?: SaccadePosition;
-};
-declare function Saccade({ position }: SaccadeProps): react.ReactPortal | null;
-
 type ExportFilter = 'active' | 'all-animations' | 'all-elements';
-type OutputDetailLevel = 'compact' | 'standard' | 'detailed' | 'forensic';
+type OutputDetailLevel = 'brief' | 'moderate' | 'detailed' | 'granular';
 type Rect = {
     x: number;
     y: number;
@@ -112,6 +105,18 @@ declare class SaccadeEngine {
     getCapture(): TimelineCapture | null;
     setSpeed(speed: number): void;
     getSpeed(): number;
+    /**
+     * 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(): void;
+    /** Register a module-imported GSAP instance so saccade can slow it. */
+    registerGSAP(gsap: any): void;
     startRecording(boundingBox?: Rect | null): void;
     stopRecording(): TimelineCapture;
     seekTo(timeMs: number): void;
@@ -123,8 +128,23 @@ declare class SaccadeEngine {
     destroy(): void;
 }
 
-declare function SaccadeProvider({ children }: {
+type SaccadePosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+type SaccadeProps = {
+    /** Panel position. Default: 'bottom-left' */
+    position?: SaccadePosition;
+    /** Engine the panel should drive. Defaults to the shared singleton, so app
+     *  code can control the same engine the panel does (e.g. via
+     *  `getSharedEngine()` or `import 'saccade/install'`). Pass your own only if
+     *  you deliberately want an isolated engine. */
+    engine?: SaccadeEngine;
+};
+declare function Saccade({ position, engine }: SaccadeProps): react.ReactPortal | null;
+
+declare function SaccadeProvider({ children, engine }: {
     children: ReactNode;
+    /** Engine to provide. Defaults to the process-wide shared singleton so the
+     *  panel and app code (and `saccade/install`) all drive the same instance. */
+    engine?: SaccadeEngine;
 }): react_jsx_runtime.JSX.Element;
 declare function useSaccadeEngine(): SaccadeEngine;
 
@@ -151,4 +171,8 @@ declare function useSpeed(): {
     togglePause: () => void;
 };
 
-export { type AnimationInfo, type ExportFilter, type FrameSnapshot, type OutputDetailLevel, type Rect, Saccade, SaccadeEngine, type SaccadePosition, type SaccadeProps, SaccadeProvider, type SaccadeState, type TimelineCapture, type TimelineExport, useSaccadeEngine, useSpeed, useTimeline };
+declare function getSharedEngine(): SaccadeEngine;
+/** Test/teardown hook — drops the singleton so the next get() makes a fresh one. */
+declare function resetSharedEngine(): void;
+
+export { type AnimationInfo, type ExportFilter, type FrameSnapshot, type OutputDetailLevel, type Rect, Saccade, SaccadeEngine, type SaccadePosition, type SaccadeProps, SaccadeProvider, type SaccadeState, type TimelineCapture, type TimelineExport, getSharedEngine, resetSharedEngine, useSaccadeEngine, useSpeed, useTimeline };

package/dist/index.d.ts

@@ -2,15 +2,8 @@ import * as react from 'react';
 import { ReactNode } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
-type SaccadePosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-type SaccadeProps = {
-    /** Panel position. Default: 'bottom-left' */
-    position?: SaccadePosition;
-};
-declare function Saccade({ position }: SaccadeProps): react.ReactPortal | null;
-
 type ExportFilter = 'active' | 'all-animations' | 'all-elements';
-type OutputDetailLevel = 'compact' | 'standard' | 'detailed' | 'forensic';
+type OutputDetailLevel = 'brief' | 'moderate' | 'detailed' | 'granular';
 type Rect = {
     x: number;
     y: number;
@@ -112,6 +105,18 @@ declare class SaccadeEngine {
     getCapture(): TimelineCapture | null;
     setSpeed(speed: number): void;
     getSpeed(): number;
+    /**
+     * 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(): void;
+    /** Register a module-imported GSAP instance so saccade can slow it. */
+    registerGSAP(gsap: any): void;
     startRecording(boundingBox?: Rect | null): void;
     stopRecording(): TimelineCapture;
     seekTo(timeMs: number): void;
@@ -123,8 +128,23 @@ declare class SaccadeEngine {
     destroy(): void;
 }
 
-declare function SaccadeProvider({ children }: {
+type SaccadePosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+type SaccadeProps = {
+    /** Panel position. Default: 'bottom-left' */
+    position?: SaccadePosition;
+    /** Engine the panel should drive. Defaults to the shared singleton, so app
+     *  code can control the same engine the panel does (e.g. via
+     *  `getSharedEngine()` or `import 'saccade/install'`). Pass your own only if
+     *  you deliberately want an isolated engine. */
+    engine?: SaccadeEngine;
+};
+declare function Saccade({ position, engine }: SaccadeProps): react.ReactPortal | null;
+
+declare function SaccadeProvider({ children, engine }: {
     children: ReactNode;
+    /** Engine to provide. Defaults to the process-wide shared singleton so the
+     *  panel and app code (and `saccade/install`) all drive the same instance. */
+    engine?: SaccadeEngine;
 }): react_jsx_runtime.JSX.Element;
 declare function useSaccadeEngine(): SaccadeEngine;
 
@@ -151,4 +171,8 @@ declare function useSpeed(): {
     togglePause: () => void;
 };
 
-export { type AnimationInfo, type ExportFilter, type FrameSnapshot, type OutputDetailLevel, type Rect, Saccade, SaccadeEngine, type SaccadePosition, type SaccadeProps, SaccadeProvider, type SaccadeState, type TimelineCapture, type TimelineExport, useSaccadeEngine, useSpeed, useTimeline };
+declare function getSharedEngine(): SaccadeEngine;
+/** Test/teardown hook — drops the singleton so the next get() makes a fresh one. */
+declare function resetSharedEngine(): void;
+
+export { type AnimationInfo, type ExportFilter, type FrameSnapshot, type OutputDetailLevel, type Rect, Saccade, SaccadeEngine, type SaccadePosition, type SaccadeProps, SaccadeProvider, type SaccadeState, type TimelineCapture, type TimelineExport, getSharedEngine, resetSharedEngine, useSaccadeEngine, useSpeed, useTimeline };

package/dist/index.mjs

@@ -20,6 +20,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();
@@ -195,13 +196,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 {
     }
   }
@@ -247,10 +254,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;
@@ -1525,7 +1533,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) {
@@ -1540,7 +1548,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) {
@@ -1565,7 +1573,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}`);
@@ -1632,7 +1640,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);
@@ -1687,6 +1695,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;
@@ -1761,7 +1785,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);
@@ -1786,13 +1810,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
 import { jsx } from "react/jsx-runtime";
 var SaccadeContext = createContext(null);
-function SaccadeProvider({ children }) {
+function SaccadeProvider({
+  children,
+  engine
+}) {
   const engineRef = useRef(null);
   if (!engineRef.current) {
-    engineRef.current = new SaccadeEngine();
+    engineRef.current = engine ?? getSharedEngine();
   }
   return /* @__PURE__ */ jsx(SaccadeContext.Provider, { value: engineRef.current, children });
 }
@@ -1809,10 +1849,10 @@ import { useRef as useRef5, useCallback as useCallback5 } from "react";
 import { useCallback, useRef as useRef2, useState, useEffect } from "react";
 import { Fragment, jsx as jsx2, jsxs } from "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)";
@@ -1866,10 +1906,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];
@@ -2194,7 +2234,9 @@ function SpeedControl({ speed, isPaused, onSetSpeed, onTogglePause }) {
 
 // src/react/useTimeline.ts
 import { useState as useState2, useCallback as useCallback3, useEffect as useEffect2, useRef as useRef4, useSyncExternalStore } from "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 = useSyncExternalStore(
@@ -2205,7 +2247,7 @@ function useTimeline() {
   const [scrubTime, setScrubTime] = useState2(0);
   const [copied, setCopied] = useState2(false);
   const [exportFilter, setExportFilter] = useState2("all-animations");
-  const [detailLevel, setDetailLevel] = useState2("standard");
+  const [detailLevel, setDetailLevel] = useState2("moderate");
   const copiedTimeout = useRef4(null);
   const pendingSeek = useRef4(null);
   const rafId = useRef4(0);
@@ -2279,8 +2321,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]
@@ -2832,7 +2874,7 @@ var PANEL_STYLES = (
 
 // src/react/Saccade.tsx
 import { jsx as jsx5 } from "react/jsx-runtime";
-function Saccade({ position = "bottom-left" }) {
+function Saccade({ position = "bottom-left", engine }) {
   const [shadowRoot, setShadowRoot] = useState4(null);
   const hostRef = useRef6(null);
   useEffect4(() => {
@@ -2856,7 +2898,7 @@ function Saccade({ position = "bottom-left" }) {
   }, [position]);
   if (!shadowRoot) return null;
   return createPortal(
-    /* @__PURE__ */ jsx5(SaccadeProvider, { children: /* @__PURE__ */ jsx5(SaccadePanel, {}) }),
+    /* @__PURE__ */ jsx5(SaccadeProvider, { engine, children: /* @__PURE__ */ jsx5(SaccadePanel, {}) }),
     shadowRoot.lastElementChild || shadowRoot
   );
 }
@@ -2864,6 +2906,8 @@ export {
   Saccade,
   SaccadeEngine,
   SaccadeProvider,
+  getSharedEngine,
+  resetSharedEngine,
   useSaccadeEngine,
   useSpeed,
   useTimeline