saccade 0.1.0 → 0.2.0

package/dist/core.d.cts

@@ -1,5 +1,5 @@
 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;
@@ -101,6 +101,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;
@@ -112,6 +124,10 @@ declare class SaccadeEngine {
     destroy(): void;
 }
 
+declare function getSharedEngine(): SaccadeEngine;
+/** Test/teardown hook — drops the singleton so the next get() makes a fresh one. */
+declare function resetSharedEngine(): void;
+
 /**
  * Timing controller — patches all JS timing APIs to respect a speed factor.
  *
@@ -129,6 +145,7 @@ declare class TimingController {
     private _origAnimate;
     private installed;
     private animPollId;
+    private gsapInstance;
     private trackedAnims;
     private trackedMedia;
     private _raf;
@@ -155,6 +172,11 @@ declare class TimingController {
     private patchAnimations;
     /** Patch playbackRate on all video/audio elements. */
     private patchMedia;
+    /**
+     * Register a GSAP instance (for ES-module imports where window.gsap is
+     * undefined). Applies the current timeScale immediately if speed !== 1.
+     */
+    registerGSAP(gsap: any): void;
     /** Sync GSAP's global timeline if present. */
     private patchGSAP;
     /** Restore all patched APIs to originals. */
@@ -303,4 +325,4 @@ declare function getFrameAtTime(frames: FrameSnapshot[], timeMs: number): FrameS
 declare function generateExport(animations: AnimationInfo[], frames: FrameSnapshot[], timeMs: number, filter?: ExportFilter): TimelineExport;
 declare function formatExportForLLM(exp: TimelineExport, detail?: OutputDetailLevel): string;
 
-export { type AnimationInfo, type ElementSnapshot, type ExportFilter, type FrameAnimation, type FrameSnapshot, type InterceptedAnimation, type OutputDetailLevel, type PropertySnapshot, type Rect, SaccadeEngine, type SaccadeState, type ScrubberState, type SeekableClone, type TimelineCapture, type TimelineExport, TimelineRecorder, TimelineScrubber, TimingController, formatExportForLLM, generateExport, getFrameAtTime };
+export { type AnimationInfo, type ElementSnapshot, type ExportFilter, type FrameAnimation, type FrameSnapshot, type InterceptedAnimation, type OutputDetailLevel, type PropertySnapshot, type Rect, SaccadeEngine, type SaccadeState, type ScrubberState, type SeekableClone, type TimelineCapture, type TimelineExport, TimelineRecorder, TimelineScrubber, TimingController, formatExportForLLM, generateExport, getFrameAtTime, getSharedEngine, resetSharedEngine };

package/dist/core.d.ts

@@ -1,5 +1,5 @@
 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;
@@ -101,6 +101,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;
@@ -112,6 +124,10 @@ declare class SaccadeEngine {
     destroy(): void;
 }
 
+declare function getSharedEngine(): SaccadeEngine;
+/** Test/teardown hook — drops the singleton so the next get() makes a fresh one. */
+declare function resetSharedEngine(): void;
+
 /**
  * Timing controller — patches all JS timing APIs to respect a speed factor.
  *
@@ -129,6 +145,7 @@ declare class TimingController {
     private _origAnimate;
     private installed;
     private animPollId;
+    private gsapInstance;
     private trackedAnims;
     private trackedMedia;
     private _raf;
@@ -155,6 +172,11 @@ declare class TimingController {
     private patchAnimations;
     /** Patch playbackRate on all video/audio elements. */
     private patchMedia;
+    /**
+     * Register a GSAP instance (for ES-module imports where window.gsap is
+     * undefined). Applies the current timeScale immediately if speed !== 1.
+     */
+    registerGSAP(gsap: any): void;
     /** Sync GSAP's global timeline if present. */
     private patchGSAP;
     /** Restore all patched APIs to originals. */
@@ -303,4 +325,4 @@ declare function getFrameAtTime(frames: FrameSnapshot[], timeMs: number): FrameS
 declare function generateExport(animations: AnimationInfo[], frames: FrameSnapshot[], timeMs: number, filter?: ExportFilter): TimelineExport;
 declare function formatExportForLLM(exp: TimelineExport, detail?: OutputDetailLevel): string;
 
-export { type AnimationInfo, type ElementSnapshot, type ExportFilter, type FrameAnimation, type FrameSnapshot, type InterceptedAnimation, type OutputDetailLevel, type PropertySnapshot, type Rect, SaccadeEngine, type SaccadeState, type ScrubberState, type SeekableClone, type TimelineCapture, type TimelineExport, TimelineRecorder, TimelineScrubber, TimingController, formatExportForLLM, generateExport, getFrameAtTime };
+export { type AnimationInfo, type ElementSnapshot, type ExportFilter, type FrameAnimation, type FrameSnapshot, type InterceptedAnimation, type OutputDetailLevel, type PropertySnapshot, type Rect, SaccadeEngine, type SaccadeState, type ScrubberState, type SeekableClone, type TimelineCapture, type TimelineExport, TimelineRecorder, TimelineScrubber, TimingController, formatExportForLLM, generateExport, getFrameAtTime, getSharedEngine, resetSharedEngine };

package/dist/core.mjs

@@ -11,6 +11,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();
@@ -186,13 +187,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 {
     }
   }
@@ -238,10 +245,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;
@@ -1516,7 +1524,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) {
@@ -1531,7 +1539,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) {
@@ -1556,7 +1564,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}`);
@@ -1623,7 +1631,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);
@@ -1678,6 +1686,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;
@@ -1752,7 +1776,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);
@@ -1776,6 +1800,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;
+}
 export {
   SaccadeEngine,
   TimelineRecorder,
@@ -1783,6 +1820,8 @@ export {
   TimingController,
   formatExportForLLM,
   generateExport,
-  getFrameAtTime
+  getFrameAtTime,
+  getSharedEngine,
+  resetSharedEngine
 };
 //# sourceMappingURL=core.mjs.map