saccade 0.0.3 → 0.2.0

package/dist/index.d.cts

@@ -1,16 +1,9 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
-
-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_jsx_runtime.JSX.Element;
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
 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;
@@ -30,6 +23,8 @@ type AnimationInfo = {
     resolvedVars: Record<string, string> | null;
     conflicts: string[] | null;
     layoutAnimation?: boolean;
+    rawKeyframes?: Keyframe[];
+    rawTiming?: EffectTiming;
 };
 type PropertySnapshot = {
     property: string;
@@ -110,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;
@@ -121,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;
 
@@ -149,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

@@ -1,16 +1,9 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
-
-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_jsx_runtime.JSX.Element;
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
 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;
@@ -30,6 +23,8 @@ type AnimationInfo = {
     resolvedVars: Record<string, string> | null;
     conflicts: string[] | null;
     layoutAnimation?: boolean;
+    rawKeyframes?: Keyframe[];
+    rawTiming?: EffectTiming;
 };
 type PropertySnapshot = {
     property: string;
@@ -110,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;
@@ -121,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;
 
@@ -149,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 };