fix: address code review feedback — fix LCP metric, debounce isolation, crossFade, auto-sync delay

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/react/src/hooks/useOffline.ts

@@ -261,13 +261,12 @@ export function useOffline(config: OfflineConfig = {}): OfflineResult {
     }
   }, [enabled, queue]);
 
-  // Auto-sync when coming back online
+  // Auto-sync when coming back online (short stabilization delay)
   useEffect(() => {
     if (!enabled || !isOnline || queue.length === 0) return;
-    const retryInterval = syncConfigRef.current?.retryInterval ?? 5000;
     const timer = setTimeout(() => {
       void sync();
-    }, retryInterval);
+    }, 100);
     return () => clearTimeout(timer);
     // Only trigger on isOnline changes, not on every queue change
     // eslint-disable-next-line react-hooks/exhaustive-deps

packages/react/src/hooks/usePageTransition.ts

@@ -165,9 +165,13 @@ export function usePageTransition(config: PageTransitionConfig = {}): PageTransi
     const enterStyle: React.CSSProperties = { ...baseStyle };
     const exitStyle: React.CSSProperties = { ...baseStyle };
 
+    // When crossFade is enabled, both the entering and exiting pages
+    // should overlap and transition opacity simultaneously.
     if (crossFade) {
-      enterStyle.opacity = 0;
-      enterStyle.animationName = undefined; // let the class handle it
+      enterStyle.position = 'absolute';
+      enterStyle.inset = '0';
+      exitStyle.position = 'absolute';
+      exitStyle.inset = '0';
     }
 
     return {

packages/react/src/hooks/usePerformance.ts

@@ -91,23 +91,26 @@ const DEFAULTS = {
 // Helpers
 // ---------------------------------------------------------------------------
 
-function getWebVital(name: string): number | null {
+function getFCP(): number | null {
   if (typeof performance === 'undefined' || !performance.getEntriesByType) return null;
   try {
     const entries = performance.getEntriesByType('paint');
-    const entry = entries.find((e) => e.name === name);
+    const entry = entries.find((e) => e.name === 'first-contentful-paint');
     return entry ? Math.round(entry.startTime) : null;
   } catch {
     return null;
   }
 }
 
 function getLCP(): number | null {
-  return getWebVital('largest-contentful-paint');
-}
-
-function getFCP(): number | null {
-  return getWebVital('first-contentful-paint');
+  if (typeof performance === 'undefined' || !performance.getEntriesByType) return null;
+  try {
+    const entries = performance.getEntriesByType('largest-contentful-paint');
+    const entry = entries.length > 0 ? entries[entries.length - 1] : undefined;
+    return entry ? Math.round(entry.startTime) : null;
+  } catch {
+    return null;
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -205,23 +208,33 @@ export function usePerformance(userConfig: PerformanceConfig = {}): PerformanceR
   }, []);
 
   const debounceMs = config.debounceMs;
-  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const timersRef = useRef<Set<ReturnType<typeof setTimeout>>>(new Set());
 
   const debounce = useCallback(
     <T extends (...args: unknown[]) => void>(fn: T): T => {
+      let timer: ReturnType<typeof setTimeout> | null = null;
       const debounced = (...args: unknown[]) => {
-        if (timerRef.current) clearTimeout(timerRef.current);
-        timerRef.current = setTimeout(() => fn(...args), debounceMs);
+        if (timer) {
+          clearTimeout(timer);
+          timersRef.current.delete(timer);
+        }
+        timer = setTimeout(() => {
+          fn(...args);
+          if (timer) timersRef.current.delete(timer);
+        }, debounceMs);
+        timersRef.current.add(timer);
       };
       return debounced as unknown as T;
     },
     [debounceMs],
   );
 
-  // Cleanup debounce timer
+  // Cleanup all debounce timers
   useEffect(() => {
+    const timers = timersRef.current;
     return () => {
-      if (timerRef.current) clearTimeout(timerRef.current);
+      timers.forEach((t) => clearTimeout(t));
+      timers.clear();
     };
   }, []);