reanimated-pause-state 0.1.0

package/src/index.ts

@@ -0,0 +1,553 @@
+/**
+ * reanimated-pause-plugin
+ *
+ * Pause and resume Reanimated animations with structured state snapshots.
+ */
+
+import type {
+  AnimationSnapshot,
+  AnimationRegistration,
+  PauseSnapshot,
+  AnimationType,
+  SharedValueRef,
+  SnapshotOptions,
+} from './types';
+
+export type { AnimationSnapshot, PauseSnapshot, AnimationType, SnapshotOptions } from './types';
+
+// Type declarations for globals
+declare global {
+  var __RPP__: {
+    paused: boolean;
+    pausedAt: number | null;
+    snapshot: PauseSnapshot | null;
+  } | undefined;
+  var __RPP_PAUSED__: boolean | undefined;
+  var __RPP_INSTALLED__: { installed: boolean; version: string } | undefined;
+  var __RPP_ORIGINAL_RAF__: ((callback: (timestamp: number) => void) => number) | undefined;
+  var __RPP_PENDING_CALLBACKS__: Array<(timestamp: number) => void> | undefined;
+  var __RPP_PAUSED_AT__: number | undefined;
+  var __RPP_ACCUMULATED_PAUSE__: number | undefined;
+  var __RPP_REGISTRY__: {
+    animations: Map<string, AnimationRegistration>;
+    register: (meta: any) => void;
+    unregister: (id: string) => void;
+    getAll: () => AnimationRegistration[];
+  } | undefined;
+}
+
+const VERSION = '0.1.0';
+
+/**
+ * Initialize JS-side state and registry
+ */
+function ensureInitialized(): void {
+  if (typeof globalThis.__RPP__ === 'undefined') {
+    globalThis.__RPP__ = {
+      paused: false,
+      pausedAt: null,
+      snapshot: null,
+    };
+  }
+
+  if (typeof globalThis.__RPP_REGISTRY__ === 'undefined') {
+    const animations = new Map<string, AnimationRegistration>();
+
+    globalThis.__RPP_REGISTRY__ = {
+      animations,
+      register: (meta: any) => {
+        // Skip registration in production - zero overhead
+        if (typeof __DEV__ !== 'undefined' && !__DEV__) {
+          return;
+        }
+
+        const config = meta.__rpp_config || {};
+
+        // Extract toValue and duration from config
+        const toValue = config.toValue ?? 0;
+        const duration = config.duration;
+
+        // Capture SharedValue reference if available
+        const sharedValue: SharedValueRef | undefined = meta.__rpp_sharedValue;
+
+        // Read the current value from SharedValue as the fromValue
+        // This works because Reanimated syncs SharedValue.value to JS thread
+        const fromValue = sharedValue?.value ?? 0;
+
+        const registration: AnimationRegistration = {
+          id: String(meta.__rpp_id),
+          type: meta.__rpp_type || 'unknown',
+          callsite: {
+            file: meta.__rpp_file || 'unknown',
+            line: meta.__rpp_line || 0,
+            column: meta.__rpp_column,
+          },
+          config,
+          startTime: Date.now(),
+          fromValue,
+          toValue,
+          duration,
+          sharedValue, // Store reference for reading current value at pause time
+          sharedValueName: meta.__rpp_sharedValueName,
+        };
+        animations.set(registration.id, registration);
+
+        // Don't auto-cleanup - animations may repeat or user may pause at any time
+        // Cleanup will happen on app reload or explicit clear
+      },
+      unregister: (id: string) => {
+        animations.delete(id);
+      },
+      getAll: () => Array.from(animations.values()),
+    };
+  }
+}
+
+/**
+ * Check if the Babel plugin is installed
+ */
+export function isInstalled(): boolean {
+  return globalThis.__RPP_INSTALLED__?.installed === true;
+}
+
+/**
+ * Check if animations are paused
+ */
+export function isPaused(): boolean {
+  ensureInitialized();
+  return globalThis.__RPP__!.paused;
+}
+
+/**
+ * Get the last pause snapshot (or null if not paused/no snapshot)
+ */
+export function getSnapshot(): PauseSnapshot | null {
+  ensureInitialized();
+  return globalThis.__RPP__!.snapshot;
+}
+
+/**
+ * Take a snapshot now with optional filtering
+ * This is the main API for getting animation state
+ */
+export function snapshotNow(opts?: SnapshotOptions): PauseSnapshot {
+  // No-op in production
+  if (typeof __DEV__ !== 'undefined' && !__DEV__) {
+    return { timestamp: 0, timestampISO: '', animations: [], totalCount: 0, summary: 'disabled in production' };
+  }
+
+  ensureInitialized();
+  return captureSnapshot(opts);
+}
+
+/**
+ * Get snapshot as JSON string (for clipboard/export)
+ */
+export function getSnapshotJSON(opts?: SnapshotOptions): string {
+  const snapshot = snapshotNow(opts);
+  return JSON.stringify(snapshot, null, 2);
+}
+
+/**
+ * Get snapshot as prompt-ready markdown
+ * Optimized for pasting into Claude/LLM context
+ */
+export function getSnapshotMarkdown(opts?: SnapshotOptions): string {
+  const snapshot = snapshotNow(opts);
+  if (!snapshot || snapshot.animations.length === 0) {
+    return '**Animation State:** No active animations captured.';
+  }
+
+  let md = `## Animation State at Pause\n\n`;
+  md += `> Captured: ${snapshot.timestampISO}\n\n`;
+
+  for (const anim of snapshot.animations) {
+    // Use SharedValue name as heading if available
+    const heading = anim.sharedValueName
+      ? `\`${anim.sharedValueName}\` (${anim.type})`
+      : `${anim.type} animation`;
+    md += `### ${heading}\n\n`;
+
+    // Current value is the most important for debugging
+    md += `| Property | Value |\n`;
+    md += `|----------|-------|\n`;
+    md += `| **Current** | \`${anim.values.current.toFixed(2)}\` |\n`;
+    md += `| From → To | ${anim.values.from} → ${anim.values.to} |\n`;
+
+    if (anim.timing.duration) {
+      const progress = anim.timing.progress?.toFixed(1) || '0';
+      md += `| Progress | ${progress}% (${anim.timing.elapsed}ms / ${anim.timing.duration}ms) |\n`;
+    } else {
+      md += `| Elapsed | ${anim.timing.elapsed}ms |\n`;
+    }
+
+    md += `| Location | \`${anim.callsite.file}:${anim.callsite.line}\` |\n`;
+
+    // Show relevant config
+    const cfg = anim.config.config as Record<string, unknown>;
+    if (anim.type === 'spring' && cfg.damping) {
+      md += `| Spring | damping=${cfg.damping}`;
+      if (cfg.mass) md += `, mass=${cfg.mass}`;
+      if (cfg.stiffness) md += `, stiffness=${cfg.stiffness}`;
+      md += ` |\n`;
+    }
+    if (anim.type === 'repeat') {
+      const reps = cfg.numberOfReps as number | undefined;
+      md += `| Repeat | ${reps === -1 ? 'infinite' : reps || 'unknown'}`;
+      if (cfg.reverse) md += ' (reversing)';
+      md += ` |\n`;
+    }
+
+    md += `\n`;
+  }
+
+  return md;
+}
+
+/**
+ * Install the frame interceptor on UI thread
+ * Only installs in __DEV__ mode - zero cost in production
+ */
+function installFrameInterceptor(): void {
+  // Skip in production - this is a dev/design review tool
+  if (typeof __DEV__ !== 'undefined' && !__DEV__) {
+    return;
+  }
+
+  try {
+    const { runOnUI } = require('react-native-reanimated');
+
+    runOnUI(() => {
+      'worklet';
+
+      if (globalThis.__RPP_ORIGINAL_RAF__) {
+        return;
+      }
+
+      const originalRAF = globalThis.requestAnimationFrame;
+      if (!originalRAF) {
+        console.warn('[rpp] requestAnimationFrame not found on UI thread');
+        return;
+      }
+
+      globalThis.__RPP_ORIGINAL_RAF__ = originalRAF;
+      globalThis.__RPP_PENDING_CALLBACKS__ = [];
+      globalThis.__RPP_PAUSED__ = false;
+      globalThis.__RPP_PAUSED_AT__ = 0;
+      globalThis.__RPP_ACCUMULATED_PAUSE__ = 0;
+
+      (globalThis as any).requestAnimationFrame = function(
+        callback: (timestamp: number) => void
+      ): number {
+        if (globalThis.__RPP_PAUSED__) {
+          globalThis.__RPP_PENDING_CALLBACKS__!.push(callback);
+          return -1;
+        }
+
+        return globalThis.__RPP_ORIGINAL_RAF__!((timestamp: number) => {
+          const adjustedTimestamp =
+            timestamp - (globalThis.__RPP_ACCUMULATED_PAUSE__ || 0);
+          callback(adjustedTimestamp);
+        });
+      };
+
+    })();
+  } catch (e) {
+    console.warn('[rpp] Failed to install frame interceptor:', e);
+  }
+}
+
+/**
+ * Flush pending callbacks after resume
+ */
+function flushPendingCallbacks(): void {
+  try {
+    const { runOnUI } = require('react-native-reanimated');
+
+    runOnUI(() => {
+      'worklet';
+
+      const pending = globalThis.__RPP_PENDING_CALLBACKS__ || [];
+      globalThis.__RPP_PENDING_CALLBACKS__ = [];
+
+      if (pending.length === 0) return;
+
+      const originalRAF = globalThis.__RPP_ORIGINAL_RAF__;
+      if (originalRAF) {
+        originalRAF((timestamp: number) => {
+          const adjusted =
+            timestamp - (globalThis.__RPP_ACCUMULATED_PAUSE__ || 0);
+          for (const cb of pending) {
+            try {
+              cb(adjusted);
+            } catch (e) {
+              // Ignore errors in callbacks
+            }
+          }
+        });
+      }
+    })();
+  } catch (e) {
+    console.warn('[rpp] Failed to flush callbacks:', e);
+  }
+}
+
+/**
+ * Create a snapshot of current animation state with optional filtering
+ */
+function captureSnapshot(opts?: SnapshotOptions): PauseSnapshot {
+  ensureInitialized();
+
+  const now = Date.now();
+  let registrations = globalThis.__RPP_REGISTRY__?.getAll() || [];
+
+  // Tier 1: Filter by file
+  if (opts?.filterFile) {
+    registrations = registrations.filter((reg) =>
+      reg.callsite.file.includes(opts.filterFile!)
+    );
+
+    // Tier 2: Filter by line proximity (requires filterFile)
+    if (opts.filterLine !== undefined) {
+      const threshold = opts.proximityThreshold ?? 200;
+      registrations = registrations.filter(
+        (reg) => Math.abs(reg.callsite.line - opts.filterLine!) < threshold
+      );
+    }
+  }
+
+  // Apply max limit
+  const maxAnimations = opts?.maxAnimations ?? 20;
+  if (registrations.length > maxAnimations) {
+    registrations = registrations.slice(0, maxAnimations);
+  }
+
+  const animations: AnimationSnapshot[] = registrations.map((reg) => {
+    const elapsed = now - reg.startTime;
+    const progress = reg.duration ? (elapsed / reg.duration) * 100 : undefined;
+
+    // Read the current value from the SharedValue if available
+    // Reanimated syncs SharedValue.value to JS thread automatically
+    let currentValue = reg.fromValue;
+    if (reg.sharedValue && typeof reg.sharedValue.value === 'number') {
+      currentValue = reg.sharedValue.value;
+    }
+
+    const snapshot: AnimationSnapshot = {
+      id: reg.id,
+      type: reg.type as AnimationType,
+      sharedValueName: reg.sharedValueName,
+      callsite: reg.callsite,
+      config: {
+        type: reg.type as any,
+        config: reg.config as any,
+      },
+      timing: {
+        startTime: reg.startTime,
+        elapsed,
+        duration: reg.duration,
+        progress: progress ? Math.min(progress, 100) : undefined,
+      },
+      values: {
+        from: reg.fromValue,
+        to: reg.toValue,
+        current: currentValue,
+      },
+      description: formatDescription(reg, elapsed, currentValue),
+    };
+
+    return snapshot;
+  });
+
+  const snapshot: PauseSnapshot = {
+    timestamp: now,
+    timestampISO: new Date(now).toISOString(),
+    animations,
+    totalCount: animations.length,
+    summary: `${animations.length} animation(s) captured`,
+  };
+
+  return snapshot;
+}
+
+/**
+ * Format a human-readable description optimized for prompt context
+ */
+function formatDescription(
+  reg: AnimationRegistration,
+  elapsed: number,
+  currentValue?: number
+): string {
+  const file = reg.callsite.file.split('/').pop() || reg.callsite.file;
+  const location = `${file}:${reg.callsite.line}`;
+  const config = reg.config as Record<string, unknown>;
+
+  // Start with SharedValue name if available (most useful for prompts)
+  let desc = reg.sharedValueName ? `${reg.sharedValueName}: ` : '';
+
+  desc += `${reg.type} `;
+
+  // Add config-specific details
+  switch (reg.type) {
+    case 'timing': {
+      if (reg.toValue !== 0) {
+        desc += `to ${reg.toValue} `;
+      }
+      if (reg.duration) {
+        desc += `(${reg.duration}ms) `;
+      }
+      break;
+    }
+    case 'spring': {
+      if (reg.toValue !== 0) {
+        desc += `to ${reg.toValue} `;
+      }
+      if (config.damping) {
+        desc += `damping=${config.damping} `;
+      }
+      break;
+    }
+    case 'repeat': {
+      const reps = config.numberOfReps as number | undefined;
+      if (reps === -1) {
+        desc += '(infinite) ';
+      } else if (reps) {
+        desc += `(${reps}x) `;
+      }
+      if (config.reverse) {
+        desc += 'reverse ';
+      }
+      break;
+    }
+    case 'delay': {
+      if (config.delayMs) {
+        desc += `${config.delayMs}ms `;
+      }
+      break;
+    }
+    case 'decay': {
+      if (config.velocity) {
+        desc += `velocity=${config.velocity} `;
+      }
+      break;
+    }
+    case 'sequence': {
+      if (config.count) {
+        desc += `(${config.count} animations) `;
+      }
+      break;
+    }
+  }
+
+  // Current value is the most important info for debugging
+  if (currentValue !== undefined) {
+    desc += `| current=${currentValue.toFixed(2)} `;
+  }
+
+  desc += `| ${elapsed}ms elapsed`;
+  if (reg.duration) {
+    const progress = Math.min((elapsed / reg.duration) * 100, 100).toFixed(0);
+    desc += ` (${progress}%)`;
+  }
+
+  desc += ` | ${location}`;
+
+  return desc;
+}
+
+/**
+ * Pause all animations and capture snapshot
+ * No-op in production builds
+ */
+export function pause(): PauseSnapshot {
+  // No-op in production
+  if (typeof __DEV__ !== 'undefined' && !__DEV__) {
+    return { timestamp: 0, timestampISO: '', animations: [], totalCount: 0, summary: 'disabled in production' };
+  }
+
+  ensureInitialized();
+
+  if (globalThis.__RPP__!.paused) {
+    return globalThis.__RPP__!.snapshot!;
+  }
+
+  installFrameInterceptor();
+
+  // Capture snapshot before pausing
+  const snapshot = captureSnapshot();
+  globalThis.__RPP__!.snapshot = snapshot;
+  globalThis.__RPP__!.paused = true;
+  globalThis.__RPP__!.pausedAt = Date.now();
+
+  try {
+    const { runOnUI } = require('react-native-reanimated');
+
+    runOnUI(() => {
+      'worklet';
+      globalThis.__RPP_PAUSED__ = true;
+      globalThis.__RPP_PAUSED_AT__ =
+        (globalThis as any)._getAnimationTimestamp?.() || Date.now();
+    })();
+  } catch (e) {
+    console.warn('[rpp] Failed to pause on UI thread:', e);
+  }
+
+  return snapshot;
+}
+
+/**
+ * Resume all animations
+ */
+export function resume(): void {
+  ensureInitialized();
+
+  if (!globalThis.__RPP__!.paused) {
+    return;
+  }
+
+  globalThis.__RPP__!.paused = false;
+
+  try {
+    const { runOnUI } = require('react-native-reanimated');
+
+    runOnUI(() => {
+      'worklet';
+
+      const pausedAt = globalThis.__RPP_PAUSED_AT__ || 0;
+      const now = (globalThis as any)._getAnimationTimestamp?.() || Date.now();
+      const pauseDuration = now - pausedAt;
+
+      globalThis.__RPP_ACCUMULATED_PAUSE__ =
+        (globalThis.__RPP_ACCUMULATED_PAUSE__ || 0) + pauseDuration;
+
+      globalThis.__RPP_PAUSED__ = false;
+    })();
+
+    flushPendingCallbacks();
+  } catch (e) {
+    console.warn('[rpp] Failed to resume:', e);
+  }
+
+}
+
+/**
+ * Toggle pause state
+ */
+export function toggle(): PauseSnapshot | null {
+  if (isPaused()) {
+    resume();
+    return null;
+  } else {
+    return pause();
+  }
+}
+
+// Auto-initialize registry immediately so Babel-injected trackers work
+ensureInitialized();
+
+// Auto-install interceptor in dev mode (delayed to ensure Reanimated is ready)
+if (typeof __DEV__ !== 'undefined' && __DEV__) {
+  setTimeout(() => {
+    installFrameInterceptor();
+  }, 100);
+}

package/src/types.ts

@@ -0,0 +1,156 @@
+/**
+ * Animation snapshot captured at pause time
+ */
+export interface AnimationSnapshot {
+  /** Unique ID for this animation instance */
+  id: string;
+
+  /** Animation type: 'timing' | 'spring' | 'decay' | 'repeat' | 'sequence' | 'delay' */
+  type: AnimationType;
+
+  /** Variable name of the animated SharedValue (e.g., "translateX") */
+  sharedValueName?: string;
+
+  /** Source location where the animation was created */
+  callsite: {
+    file: string;
+    line: number;
+    column?: number;
+  };
+
+  /** Animation configuration */
+  config: AnimationConfig;
+
+  /** Timing information */
+  timing: {
+    /** When the animation started (ms since epoch) */
+    startTime: number;
+    /** How long the animation has been running (ms) */
+    elapsed: number;
+    /** Expected duration (for timing animations) */
+    duration?: number;
+    /** Progress as percentage 0-100 (for timing animations) */
+    progress?: number;
+  };
+
+  /** Value information */
+  values: {
+    /** Starting value */
+    from: number;
+    /** Target value */
+    to: number;
+    /** Current value at pause */
+    current: number;
+  };
+
+  /** Human-readable description */
+  description: string;
+}
+
+export type AnimationType =
+  | 'timing'
+  | 'spring'
+  | 'decay'
+  | 'repeat'
+  | 'sequence'
+  | 'delay'
+  | 'unknown';
+
+export interface TimingConfig {
+  duration: number;
+  easing?: string;
+}
+
+export interface SpringConfig {
+  damping?: number;
+  mass?: number;
+  stiffness?: number;
+  overshootClamping?: boolean;
+  restDisplacementThreshold?: number;
+  restSpeedThreshold?: number;
+}
+
+export interface DecayConfig {
+  velocity?: number;
+  deceleration?: number;
+}
+
+export interface RepeatConfig {
+  numberOfReps?: number;
+  reverse?: boolean;
+}
+
+export type AnimationConfig =
+  | { type: 'timing'; config: TimingConfig }
+  | { type: 'spring'; config: SpringConfig }
+  | { type: 'decay'; config: DecayConfig }
+  | { type: 'repeat'; config: RepeatConfig }
+  | { type: 'sequence'; config: { count: number } }
+  | { type: 'delay'; config: { delayMs: number } }
+  | { type: 'unknown'; config: Record<string, unknown> };
+
+/**
+ * Full pause state snapshot
+ */
+export interface PauseSnapshot {
+  /** When the snapshot was taken */
+  timestamp: number;
+
+  /** ISO timestamp string */
+  timestampISO: string;
+
+  /** All active animations at pause time */
+  animations: AnimationSnapshot[];
+
+  /** Total count of tracked animations */
+  totalCount: number;
+
+  /** Summary for quick reference */
+  summary: string;
+}
+
+/**
+ * Options for filtering snapshots
+ */
+export interface SnapshotOptions {
+  /** Filter animations by file path (partial match) */
+  filterFile?: string;
+
+  /** Filter animations by line proximity (requires filterFile) */
+  filterLine?: number;
+
+  /** Max distance in lines from filterLine (default: 200) */
+  proximityThreshold?: number;
+
+  /** Max animations to return (default: 20) */
+  maxAnimations?: number;
+}
+
+/**
+ * SharedValue type from Reanimated (minimal interface for our needs)
+ */
+export interface SharedValueRef {
+  value: number;
+}
+
+/**
+ * Registration data for tracking an animation
+ */
+export interface AnimationRegistration {
+  id: string;
+  type: AnimationType;
+  callsite: {
+    file: string;
+    line: number;
+    column?: number;
+  };
+  config: Record<string, unknown>;
+  startTime: number;
+  fromValue: number;
+  toValue: number;
+  duration?: number;
+  /** Reference to the SharedValue being animated */
+  sharedValue?: SharedValueRef;
+  /** Variable name of the SharedValue (e.g., "translateX", "scale") */
+  sharedValueName?: string;
+}