saccade 0.0.3 → 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;
@@ -19,6 +19,8 @@ type AnimationInfo = {
     resolvedVars: Record<string, string> | null;
     conflicts: string[] | null;
     layoutAnimation?: boolean;
+    rawKeyframes?: Keyframe[];
+    rawTiming?: EffectTiming;
 };
 type PropertySnapshot = {
     property: string;
@@ -99,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;
@@ -110,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.
  *
@@ -120,12 +138,16 @@ declare class TimingController {
     private speed;
     private realBaseline;
     private virtualBaseline;
+    private dateRealBaseline;
+    private dateVirtualBaseline;
     private intervalMap;
     private nextIntervalId;
-    private mediaObserver;
-    private animObserver;
     private _origAnimate;
     private installed;
+    private animPollId;
+    private gsapInstance;
+    private trackedAnims;
+    private trackedMedia;
     private _raf;
     private _caf;
     private _setTimeout;
@@ -136,14 +158,27 @@ declare class TimingController {
     private _dateNow;
     constructor();
     private getVirtualTime;
+    private getVirtualDateNow;
     private reanchor;
+    /** Effective speed divisor — avoids division by zero at speed=0. */
+    private get speedDivisor();
     /** Install timing patches. Safe to call multiple times. */
     install(): void;
     /** Set playback speed. Requires install() first. */
     setSpeed(newSpeed: number): void;
-    /** Patch playbackRate on all active CSS transitions/animations via WAAPI. */
-    private patchAnimations;
     getSpeed(): number;
+    private startAnimationPoll;
+    /** Patch playbackRate on all active animations via WAAPI. */
+    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. */
     destroy(): void;
 }
@@ -197,6 +232,11 @@ declare class TimelineRecorder {
         animation: Animation;
         target: Element;
     }[];
+    readonly seekableClones: Map<string, {
+        animation: Animation;
+        element: HTMLElement;
+        effect: KeyframeEffect;
+    }>;
     private static readonly MAX_DURATION_MS;
     private static readonly MAX_FRAMES;
     private hiddenSince;
@@ -230,6 +270,12 @@ interface InterceptedAnimation {
     animation: Animation;
     target: Element;
 }
+/** A seekable WAAPI clone created from recorded keyframes. */
+interface SeekableClone {
+    animation: Animation;
+    element: HTMLElement;
+    effect: KeyframeEffect;
+}
 /**
  * State handed from the recorder after stopRecording().
  * This is everything the scrubber needs to replay frames.
@@ -245,26 +291,32 @@ interface ScrubberState {
     interceptedAnimations: InterceptedAnimation[];
     /** Set of CSS properties that are safe (visual-only, no layout side-effects) */
     SAFE_PROPS_SET: Set<string>;
+    /** Seekable WAAPI clones created from recorded animation keyframes */
+    seekableClones: Map<string, SeekableClone>;
 }
 /**
- * Timeline scrubber — applies captured frame snapshots to the live DOM.
+ * Timeline scrubber — seeks through recorded animation state using WAAPI.
  *
- * Ported from the inline JS that the Electron version injected via
- * executeJavaScript() in timeline-controller.ts (seekTo / releaseAnimations).
+ * Instead of applying computed styles as inline overrides (which breaks
+ * Tailwind/class-driven layouts), this scrubber creates paused WAAPI
+ * animation clones and seeks them via animation.currentTime. The browser
+ * computes exact intermediate values natively — the same mechanism Chrome
+ * DevTools uses for its Animation panel.
  */
 declare class TimelineScrubber {
     private elements;
     private frames;
     private capturedPortals;
     private interceptedAnimations;
-    private SAFE_PROPS_SET;
+    private seekableClones;
+    /** Precomputed frame range per animation for O(1) before/after lookup. */
+    private animFrameRanges;
     /** Saved originals for restore on release */
     private _originalAnimate;
     private _originalRaf;
     private _originalRemoveChild;
     private _originalRemove;
     constructor(state: ScrubberState);
-    private getSelector;
     seekTo(timeMs: number): void;
     release(): void;
 }
@@ -273,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 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;
@@ -19,6 +19,8 @@ type AnimationInfo = {
     resolvedVars: Record<string, string> | null;
     conflicts: string[] | null;
     layoutAnimation?: boolean;
+    rawKeyframes?: Keyframe[];
+    rawTiming?: EffectTiming;
 };
 type PropertySnapshot = {
     property: string;
@@ -99,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;
@@ -110,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.
  *
@@ -120,12 +138,16 @@ declare class TimingController {
     private speed;
     private realBaseline;
     private virtualBaseline;
+    private dateRealBaseline;
+    private dateVirtualBaseline;
     private intervalMap;
     private nextIntervalId;
-    private mediaObserver;
-    private animObserver;
     private _origAnimate;
     private installed;
+    private animPollId;
+    private gsapInstance;
+    private trackedAnims;
+    private trackedMedia;
     private _raf;
     private _caf;
     private _setTimeout;
@@ -136,14 +158,27 @@ declare class TimingController {
     private _dateNow;
     constructor();
     private getVirtualTime;
+    private getVirtualDateNow;
     private reanchor;
+    /** Effective speed divisor — avoids division by zero at speed=0. */
+    private get speedDivisor();
     /** Install timing patches. Safe to call multiple times. */
     install(): void;
     /** Set playback speed. Requires install() first. */
     setSpeed(newSpeed: number): void;
-    /** Patch playbackRate on all active CSS transitions/animations via WAAPI. */
-    private patchAnimations;
     getSpeed(): number;
+    private startAnimationPoll;
+    /** Patch playbackRate on all active animations via WAAPI. */
+    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. */
     destroy(): void;
 }
@@ -197,6 +232,11 @@ declare class TimelineRecorder {
         animation: Animation;
         target: Element;
     }[];
+    readonly seekableClones: Map<string, {
+        animation: Animation;
+        element: HTMLElement;
+        effect: KeyframeEffect;
+    }>;
     private static readonly MAX_DURATION_MS;
     private static readonly MAX_FRAMES;
     private hiddenSince;
@@ -230,6 +270,12 @@ interface InterceptedAnimation {
     animation: Animation;
     target: Element;
 }
+/** A seekable WAAPI clone created from recorded keyframes. */
+interface SeekableClone {
+    animation: Animation;
+    element: HTMLElement;
+    effect: KeyframeEffect;
+}
 /**
  * State handed from the recorder after stopRecording().
  * This is everything the scrubber needs to replay frames.
@@ -245,26 +291,32 @@ interface ScrubberState {
     interceptedAnimations: InterceptedAnimation[];
     /** Set of CSS properties that are safe (visual-only, no layout side-effects) */
     SAFE_PROPS_SET: Set<string>;
+    /** Seekable WAAPI clones created from recorded animation keyframes */
+    seekableClones: Map<string, SeekableClone>;
 }
 /**
- * Timeline scrubber — applies captured frame snapshots to the live DOM.
+ * Timeline scrubber — seeks through recorded animation state using WAAPI.
  *
- * Ported from the inline JS that the Electron version injected via
- * executeJavaScript() in timeline-controller.ts (seekTo / releaseAnimations).
+ * Instead of applying computed styles as inline overrides (which breaks
+ * Tailwind/class-driven layouts), this scrubber creates paused WAAPI
+ * animation clones and seeks them via animation.currentTime. The browser
+ * computes exact intermediate values natively — the same mechanism Chrome
+ * DevTools uses for its Animation panel.
  */
 declare class TimelineScrubber {
     private elements;
     private frames;
     private capturedPortals;
     private interceptedAnimations;
-    private SAFE_PROPS_SET;
+    private seekableClones;
+    /** Precomputed frame range per animation for O(1) before/after lookup. */
+    private animFrameRanges;
     /** Saved originals for restore on release */
     private _originalAnimate;
     private _originalRaf;
     private _originalRemoveChild;
     private _originalRemove;
     constructor(state: ScrubberState);
-    private getSelector;
     seekTo(timeMs: number): void;
     release(): void;
 }
@@ -273,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 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 };