@a5c-ai/babysitter-observer-dashboard 1.0.0

package/src/hooks/__tests__/use-smart-polling.test.ts

@@ -0,0 +1,305 @@
+import { renderHook, act } from '@testing-library/react';
+import { useSmartPolling } from '../use-smart-polling';
+
+// Track unsubscribers for cleanup
+let activeUnsubscribers: Array<() => void> = [];
+
+type MockEventSourceInstance = {
+  onopen: ((event: Event) => void) | null;
+  onmessage: ((event: MessageEvent) => void) | null;
+  onerror: ((event: Event) => void) | null;
+  close: ReturnType<typeof vi.fn>;
+  readyState: number;
+  url: string;
+};
+
+let mockEventSourceInstances: MockEventSourceInstance[] = [];
+
+class MockEventSource {
+  static CONNECTING = 0;
+  static OPEN = 1;
+  static CLOSED = 2;
+
+  onopen: ((event: Event) => void) | null = null;
+  onmessage: ((event: MessageEvent) => void) | null = null;
+  onerror: ((event: Event) => void) | null = null;
+  close = vi.fn();
+  readyState = MockEventSource.OPEN;
+  url: string;
+
+  constructor(url: string) {
+    this.url = url;
+    mockEventSourceInstances.push(this);
+  }
+}
+
+function mockFetchSuccess(data: unknown) {
+  return vi.fn().mockResolvedValue(
+    new Response(JSON.stringify(data), {
+      status: 200,
+      headers: { 'Content-Type': 'application/json' },
+    })
+  );
+}
+
+describe('useSmartPolling', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    mockEventSourceInstances = [];
+    vi.stubGlobal('EventSource', MockEventSource);
+    vi.stubGlobal('fetch', mockFetchSuccess({ items: [1, 2, 3] }));
+  });
+
+  afterEach(() => {
+    for (const unsub of activeUnsubscribers) {
+      unsub();
+    }
+    activeUnsubscribers = [];
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it('fetches data immediately on mount', async () => {
+    const { result } = renderHook(() =>
+      useSmartPolling<{ items: number[] }>('/api/data', { interval: 5000 })
+    );
+
+    expect(result.current.loading).toBe(true);
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+    });
+
+    expect(result.current.data).toEqual({ items: [1, 2, 3] });
+    expect(result.current.loading).toBe(false);
+    expect(result.current.error).toBeNull();
+  });
+
+  it('polls at specified interval', async () => {
+    renderHook(() =>
+      useSmartPolling('/api/data', { interval: 5000 })
+    );
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    expect(fetch).toHaveBeenCalledTimes(1);
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(5000);
+    });
+    expect(fetch).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not fetch when enabled is false', async () => {
+    const { result } = renderHook(() =>
+      useSmartPolling('/api/data', { enabled: false })
+    );
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(10000);
+    });
+
+    expect(fetch).not.toHaveBeenCalled();
+    expect(result.current.loading).toBe(false);
+  });
+
+  it('handles fetch errors', async () => {
+    // Use 422 (not 404, because 404 is retryable in resilientFetch)
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue(
+        new Response('HTTP 422', { status: 422 })
+      )
+    );
+
+    const { result } = renderHook(() =>
+      useSmartPolling('/api/data', { interval: 5000 })
+    );
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+    });
+
+    expect(result.current.error).toBe('HTTP 422');
+    expect(result.current.loading).toBe(false);
+  });
+
+  it('triggers debounced refetch when SSE event matches filter', async () => {
+    const sseFilter = vi.fn().mockReturnValue(true);
+
+    renderHook(() =>
+      useSmartPolling('/api/data', {
+        interval: 5000,
+        sseFilter,
+      })
+    );
+
+    // Initial fetch
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+    });
+
+    const initialCallCount = (fetch as ReturnType<typeof vi.fn>).mock.calls.length;
+
+    // Simulate SSE message via the EventSource
+    const instance = mockEventSourceInstances[0];
+    if (instance?.onmessage) {
+      act(() => {
+        instance.onmessage!(
+          new MessageEvent('message', {
+            data: JSON.stringify({ type: 'run_updated', runId: 'run-1' }),
+          })
+        );
+      });
+    }
+
+    // Before debounce window (1500ms), no additional fetch
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1000);
+    });
+    expect((fetch as ReturnType<typeof vi.fn>).mock.calls.length).toBe(initialCallCount);
+
+    // After debounce window completes (1500ms total)
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(500);
+    });
+
+    // Should have triggered an additional fetch after 1500ms debounce
+    expect((fetch as ReturnType<typeof vi.fn>).mock.calls.length).toBeGreaterThan(initialCallCount);
+  });
+
+  it('coalesces rapid SSE events within debounce window into single fetch', async () => {
+    const sseFilter = vi.fn().mockReturnValue(true);
+
+    renderHook(() =>
+      useSmartPolling('/api/data', {
+        interval: 5000,
+        sseFilter,
+      })
+    );
+
+    // Initial fetch
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+    });
+
+    const initialCallCount = (fetch as ReturnType<typeof vi.fn>).mock.calls.length;
+
+    const instance = mockEventSourceInstances[0];
+    if (instance?.onmessage) {
+      // Fire 3 rapid SSE events within 100ms
+      act(() => {
+        instance.onmessage!(
+          new MessageEvent('message', {
+            data: JSON.stringify({ type: 'update', runId: 'run-1' }),
+          })
+        );
+      });
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(50);
+      });
+      act(() => {
+        instance.onmessage!(
+          new MessageEvent('message', {
+            data: JSON.stringify({ type: 'update', runId: 'run-2' }),
+          })
+        );
+      });
+      await act(async () => {
+        await vi.advanceTimersByTimeAsync(50);
+      });
+      act(() => {
+        instance.onmessage!(
+          new MessageEvent('message', {
+            data: JSON.stringify({ type: 'update', runId: 'run-3' }),
+          })
+        );
+      });
+    }
+
+    // Wait for the debounce to fire (1500ms from last event)
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1500);
+    });
+
+    // Should only trigger ONE additional fetch despite 3 events
+    expect((fetch as ReturnType<typeof vi.fn>).mock.calls.length).toBe(initialCallCount + 1);
+  });
+
+  it('does not refetch when SSE event does not match filter', async () => {
+    const sseFilter = vi.fn().mockReturnValue(false);
+
+    renderHook(() =>
+      useSmartPolling('/api/data', {
+        interval: 5000,
+        sseFilter,
+      })
+    );
+
+    // Initial fetch
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+    });
+
+    const callCount = (fetch as ReturnType<typeof vi.fn>).mock.calls.length;
+
+    // Simulate SSE message that does NOT match filter
+    const instance = mockEventSourceInstances[0];
+    if (instance?.onmessage) {
+      act(() => {
+        instance.onmessage!(
+          new MessageEvent('message', {
+            data: JSON.stringify({ type: 'run_updated', runId: 'run-2' }),
+          })
+        );
+      });
+    }
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+    });
+
+    // No additional fetch should have happened
+    expect((fetch as ReturnType<typeof vi.fn>).mock.calls.length).toBe(callCount);
+  });
+
+  it('provides a manual refresh function', async () => {
+    const { result } = renderHook(() =>
+      useSmartPolling('/api/data', { interval: 5000 })
+    );
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    expect(fetch).toHaveBeenCalledTimes(1);
+
+    await act(async () => {
+      result.current.refresh();
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    expect(fetch).toHaveBeenCalledTimes(2);
+  });
+
+  it('cleans up polling on unmount', async () => {
+    const { unmount } = renderHook(() =>
+      useSmartPolling('/api/data', {
+        interval: 5000,
+      })
+    );
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(0);
+    });
+    const callsAfterMount = (fetch as ReturnType<typeof vi.fn>).mock.calls.length;
+
+    unmount();
+
+    // Advance time - no more fetches should happen
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(30000);
+    });
+
+    expect((fetch as ReturnType<typeof vi.fn>).mock.calls.length).toBe(callsAfterMount);
+  });
+});

package/src/hooks/use-animated-number.ts

@@ -0,0 +1,87 @@
+"use client";
+import { useState, useEffect, useRef, useCallback } from "react";
+
+/**
+ * Hook that smoothly animates a number from its previous value to the target.
+ * Uses requestAnimationFrame for smooth 60fps transitions.
+ *
+ * @param target - The number to animate towards
+ * @param duration - Animation duration in ms (default 600)
+ * @returns The current animated value (integer)
+ */
+export function useAnimatedNumber(target: number, duration = 600): number {
+  const [display, setDisplay] = useState(target);
+  const animRef = useRef<number | null>(null);
+  const startRef = useRef<{ value: number; time: number } | null>(null);
+  const targetRef = useRef(target);
+  const displayRef = useRef(target);
+
+  // Easing function: ease-out cubic for a natural deceleration feel
+  const easeOutCubic = useCallback((t: number): number => {
+    return 1 - Math.pow(1 - t, 3);
+  }, []);
+
+  useEffect(() => {
+    const prevTarget = targetRef.current;
+    targetRef.current = target;
+
+    // No change — skip animation
+    if (prevTarget === target) return;
+
+    // Cancel any running animation
+    if (animRef.current !== null) {
+      cancelAnimationFrame(animRef.current);
+      animRef.current = null;
+    }
+
+    const startValue = displayRef.current;
+    const diff = target - startValue;
+
+    // If diff is 0, just snap
+    if (diff === 0) {
+      setDisplay(target);
+      displayRef.current = target;
+      return;
+    }
+
+    // For very small changes (1-2), snap immediately
+    if (Math.abs(diff) <= 2) {
+      setDisplay(target);
+      displayRef.current = target;
+      return;
+    }
+
+    const startTime = performance.now();
+    startRef.current = { value: startValue, time: startTime };
+
+    function animate(now: number) {
+      const elapsed = now - startTime;
+      const progress = Math.min(elapsed / duration, 1);
+      const easedProgress = easeOutCubic(progress);
+
+      const current = Math.round(startValue + diff * easedProgress);
+      displayRef.current = current;
+      setDisplay(current);
+
+      if (progress < 1) {
+        animRef.current = requestAnimationFrame(animate);
+      } else {
+        animRef.current = null;
+        // Ensure we land exactly on target
+        displayRef.current = target;
+        setDisplay(target);
+      }
+    }
+
+    animRef.current = requestAnimationFrame(animate);
+
+    return () => {
+      if (animRef.current !== null) {
+        cancelAnimationFrame(animRef.current);
+        animRef.current = null;
+      }
+    };
+  }, [target, duration, easeOutCubic]);
+
+  return display;
+}

package/src/hooks/use-batched-updates.ts

@@ -0,0 +1,150 @@
+"use client";
+import { useState, useEffect, useRef, useCallback } from "react";
+import { subscribe, StreamEvent } from "./use-event-stream";
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/** Window (ms) for counting rapid SSE events to detect burst mode. */
+const BURST_WINDOW_MS = 5000;
+
+/** Number of SSE events within the burst window that triggers catch-up mode. */
+const BURST_THRESHOLD = 10;
+
+/** How long (ms) to hold catch-up mode after the burst subsides. */
+const CATCHUP_HOLD_MS = 3000;
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface CatchUpState {
+  /** Whether we are in catch-up mode (burst of events detected). */
+  active: boolean;
+  /** Number of batched/buffered updates while in catch-up mode. */
+  bufferedCount: number;
+  /** Dismiss catch-up mode and apply buffered updates immediately. */
+  flush: () => void;
+}
+
+export interface UseBatchedUpdatesOptions {
+  /** SSE filter: only count events matching this predicate for burst detection. */
+  sseFilter?: (event: StreamEvent) => boolean;
+  /** Callback invoked when catch-up mode ends (either by timeout or flush). */
+  onFlush?: () => void;
+  /** Whether the hook is enabled (default true). */
+  enabled?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+
+/**
+ * Monitors SSE event rate and activates "catch-up mode" when a burst of
+ * events is detected (e.g. opening dashboard after overnight runs).
+ *
+ * In catch-up mode, the caller should suppress real-time UI updates and
+ * instead show a summary notification ("12 runs updated"). When the burst
+ * subsides or the user clicks "refresh now", catch-up mode ends and the
+ * caller should do a single full refresh.
+ */
+export function useBatchedUpdates(
+  options: UseBatchedUpdatesOptions = {}
+): CatchUpState {
+  const { sseFilter, onFlush, enabled = true } = options;
+  const [active, setActive] = useState(false);
+  const [bufferedCount, setBufferedCount] = useState(0);
+
+  // Track SSE event timestamps within the burst window
+  const eventTimestampsRef = useRef<number[]>([]);
+  const catchUpActiveRef = useRef(false);
+  const holdTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const sseFilterRef = useRef(sseFilter);
+  sseFilterRef.current = sseFilter;
+  const onFlushRef = useRef(onFlush);
+  onFlushRef.current = onFlush;
+
+  const exitCatchUp = useCallback(() => {
+    catchUpActiveRef.current = false;
+    setActive(false);
+    setBufferedCount(0);
+    eventTimestampsRef.current = [];
+    if (holdTimerRef.current) {
+      clearTimeout(holdTimerRef.current);
+      holdTimerRef.current = null;
+    }
+    onFlushRef.current?.();
+  }, []);
+
+  const flush = useCallback(() => {
+    if (catchUpActiveRef.current) {
+      exitCatchUp();
+    }
+  }, [exitCatchUp]);
+
+  useEffect(() => {
+    if (!enabled) return;
+
+    const unsubscribe = subscribe((event: StreamEvent) => {
+      // Ignore non-data events
+      if (
+        event.type === "connected" ||
+        event.type === "disconnect" ||
+        event.type === "error"
+      ) {
+        return;
+      }
+
+      // Apply optional filter
+      if (sseFilterRef.current && !sseFilterRef.current(event)) return;
+
+      const now = Date.now();
+
+      // Record timestamp and prune old entries
+      eventTimestampsRef.current.push(now);
+      eventTimestampsRef.current = eventTimestampsRef.current.filter(
+        (t) => now - t < BURST_WINDOW_MS
+      );
+
+      if (catchUpActiveRef.current) {
+        // Already in catch-up mode — increment buffered count
+        setBufferedCount((c) => c + 1);
+
+        // Reset the hold timer since events are still arriving
+        if (holdTimerRef.current) {
+          clearTimeout(holdTimerRef.current);
+        }
+        holdTimerRef.current = setTimeout(() => {
+          exitCatchUp();
+        }, CATCHUP_HOLD_MS);
+      } else {
+        // Check if we should enter catch-up mode
+        if (eventTimestampsRef.current.length >= BURST_THRESHOLD) {
+          catchUpActiveRef.current = true;
+          setActive(true);
+          setBufferedCount(eventTimestampsRef.current.length);
+
+          // Set initial hold timer
+          holdTimerRef.current = setTimeout(() => {
+            exitCatchUp();
+          }, CATCHUP_HOLD_MS);
+        }
+      }
+    });
+
+    return () => {
+      unsubscribe();
+      if (holdTimerRef.current) {
+        clearTimeout(holdTimerRef.current);
+        holdTimerRef.current = null;
+      }
+    };
+  }, [enabled, exitCatchUp]);
+
+  return { active, bufferedCount, flush };
+}
+
+// Export constants for testing
+export { BURST_WINDOW_MS, BURST_THRESHOLD, CATCHUP_HOLD_MS };

package/src/hooks/use-event-stream.ts

@@ -0,0 +1,150 @@
+"use client";
+import { useState, useEffect, useRef } from "react";
+
+export interface StreamEvent {
+  type: string;
+  runId?: string;
+  /** Batched runIds from leading-edge debounce (SSE broadcast level). */
+  runIds?: string[];
+  status?: string;
+  timestamp?: number;
+}
+
+type EventCallback = (event: StreamEvent) => void;
+
+// Module-level state for shared EventSource connection
+let sharedEventSource: EventSource | null = null;
+let subscriberCount = 0;
+let reconnectAttempts = 0;
+let reconnectTimeout: NodeJS.Timeout | null = null;
+const subscribers: Set<EventCallback> = new Set();
+
+function getReconnectDelay(): number {
+  const delays = [1000, 2000, 4000, 8000, 30000];
+  return delays[Math.min(reconnectAttempts, delays.length - 1)];
+}
+
+function createEventSource() {
+  if (typeof EventSource === "undefined") {
+    // eslint-disable-next-line no-console
+    console.warn("EventSource not supported in this environment");
+    return null;
+  }
+
+  const source = new EventSource("/api/stream");
+
+  source.onopen = () => {
+    // eslint-disable-next-line no-console
+    console.log("SSE connected");
+    reconnectAttempts = 0;
+  };
+
+  source.onmessage = (event) => {
+    try {
+      const data = JSON.parse(event.data);
+      subscribers.forEach((callback) => callback(data));
+    } catch (err) {
+      console.error("Failed to parse SSE message:", err);
+    }
+  };
+
+  source.onerror = () => {
+    console.error("SSE connection error");
+    source.close();
+    sharedEventSource = null;
+
+    // Notify subscribers of disconnect so they can fall back to polling
+    subscribers.forEach((callback) => callback({ type: "disconnect" }));
+
+    // Auto-reconnect with exponential backoff
+    if (subscriberCount > 0) {
+      reconnectAttempts++;
+      const delay = getReconnectDelay();
+      // eslint-disable-next-line no-console
+      console.log(`Reconnecting in ${delay}ms (attempt ${reconnectAttempts})`);
+      reconnectTimeout = setTimeout(() => {
+        if (subscriberCount > 0) {
+          sharedEventSource = createEventSource();
+        }
+      }, delay);
+    }
+  };
+
+  return source;
+}
+
+export function subscribe(callback: EventCallback): () => void {
+  subscribers.add(callback);
+  subscriberCount++;
+
+  // Open connection on first subscriber
+  if (subscriberCount === 1 && !sharedEventSource) {
+    sharedEventSource = createEventSource();
+  }
+
+  // Return unsubscribe function
+  return () => {
+    subscribers.delete(callback);
+    subscriberCount--;
+
+    // Close connection on last unsubscribe
+    if (subscriberCount === 0) {
+      if (reconnectTimeout) {
+        clearTimeout(reconnectTimeout);
+        reconnectTimeout = null;
+      }
+      if (sharedEventSource) {
+        sharedEventSource.close();
+        sharedEventSource = null;
+      }
+      reconnectAttempts = 0;
+    }
+  };
+}
+
+export function useEventStream() {
+  const [connected, setConnected] = useState(false);
+  const [lastEvent, setLastEvent] = useState<StreamEvent | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const mountedRef = useRef(true);
+
+  useEffect(() => {
+    mountedRef.current = true;
+
+    if (typeof EventSource === "undefined") {
+      setError("EventSource not supported");
+      setConnected(false);
+      return;
+    }
+
+    const handleEvent = (event: StreamEvent) => {
+      if (mountedRef.current) {
+        setLastEvent(event);
+        // Only mark as connected for real data events, not disconnect/error
+        if (event.type !== "disconnect" && event.type !== "error") {
+          setConnected(true);
+          setError(null);
+        }
+      }
+    };
+
+    const unsubscribe = subscribe(handleEvent);
+
+    // Check connection status
+    const checkConnection = setInterval(() => {
+      if (mountedRef.current) {
+        setConnected(
+          sharedEventSource !== null && sharedEventSource.readyState === EventSource.OPEN
+        );
+      }
+    }, 1000);
+
+    return () => {
+      mountedRef.current = false;
+      unsubscribe();
+      clearInterval(checkConnection);
+    };
+  }, []);
+
+  return { connected, lastEvent, error };
+}