@tokentop/ttop 0.4.0 → 0.6.0

package/src/tui/contexts/PluginContext.tsx

@@ -1,3 +1,11 @@
+import type {
+  AgentPlugin,
+  Credentials,
+  NotificationPlugin,
+  ProviderPlugin,
+  ProviderUsageData,
+  ThemePlugin,
+} from "@tokentop/plugin-sdk";
 import {
   createContext,
   type ReactNode,
@@ -14,10 +22,6 @@ import { safeInvoke, safeInvokeSync } from "@/plugins/plugin-host.ts";
 import { pluginRegistry } from "@/plugins/registry.ts";
 import { createPluginLogger, createSandboxedHttpClient } from "@/plugins/sandbox.ts";
 import { installGlobalFetchGuard, runInPluginGuard } from "@/plugins/sandbox-guard.ts";
-import type { AgentPlugin } from "@/plugins/types/agent.ts";
-import type { NotificationPlugin } from "@/plugins/types/notification.ts";
-import type { Credentials, ProviderPlugin, ProviderUsageData } from "@/plugins/types/provider.ts";
-import type { ThemePlugin } from "@/plugins/types/theme.ts";
 import { initPricingFromPlugins } from "@/pricing/index.ts";
 import type { ProviderSnapshotInsert } from "@/storage/types.ts";
 import { useConfig } from "./ConfigContext.tsx";
@@ -40,6 +44,8 @@ export interface ProviderState {
   loading: boolean;
   lastFetchAt: number | null;
   history: UsageSnapshot[];
+  /** Timestamp (ms) until which this provider should be skipped due to rate limiting. 0 = not rate limited. */
+  rateLimitUntil: number;
 }
 
 interface PluginContextValue {
@@ -186,6 +192,7 @@ export function PluginProvider({ children, cliPlugins }: PluginProviderProps) {
           loading: false,
           lastFetchAt: null,
           history: [],
+          rateLimitUntil: 0,
         });
 
         if (configured) {
@@ -260,6 +267,18 @@ export function PluginProvider({ children, cliPlugins }: PluginProviderProps) {
         return;
       }
 
+      // Skip providers that are currently rate-limited (backoff)
+      const now = Date.now();
+      if (state.rateLimitUntil > now) {
+        const remainingSec = Math.round((state.rateLimitUntil - now) / 1000);
+        debug(
+          `Skipping ${providerId}: rate limited for ${remainingSec}s more`,
+          undefined,
+          "refresh",
+        );
+        return;
+      }
+
       info(`Refreshing ${providerId}...`, undefined, "refresh");
 
       setProviders((prev) => {
@@ -306,6 +325,7 @@ export function PluginProvider({ children, cliPlugins }: PluginProviderProps) {
               usage,
               loading: false,
               lastFetchAt: Date.now(),
+              rateLimitUntil: 0,
               history: addToHistory(currentHistory, snapshotEntry),
             });
             return next;
@@ -333,16 +353,24 @@ export function PluginProvider({ children, cliPlugins }: PluginProviderProps) {
         const http = createSandboxedHttpClient(providerId, state.plugin.permissions);
         const logger = createPluginLogger(providerId);
 
-        const fetchResult = await safeInvoke(providerId, "fetchUsage", () =>
-          runInPluginGuard(providerId, state.plugin.permissions, () =>
-            state.plugin.fetchUsage({
-              credentials: creds,
-              http,
-              logger,
-              config: {},
-              signal: AbortSignal.timeout(30_000),
-            }),
-          ),
+        const fetchResult = await safeInvoke(
+          providerId,
+          "fetchUsage",
+          () =>
+            runInPluginGuard(providerId, state.plugin.permissions, () =>
+              state.plugin.fetchUsage({
+                credentials: creds,
+                http,
+                logger,
+                config: {},
+                signal: AbortSignal.timeout(30_000),
+              }),
+            ),
+          {
+            // Count non-rate-limit errors as circuit breaker failures.
+            // Rate limits are handled separately via backoff scheduling.
+            isFailure: (usage) => !!usage.error && !usage.rateLimited,
+          },
         );
 
         if (!fetchResult.ok) {
@@ -351,6 +379,34 @@ export function PluginProvider({ children, cliPlugins }: PluginProviderProps) {
 
         const usage = fetchResult.value;
 
+        // Handle rate-limited responses: set backoff, preserve last good data
+        if (usage.rateLimited) {
+          const backoffMs = usage.retryAfterMs ?? 300_000; // default 5 min
+          const backoffUntil = Date.now() + backoffMs;
+          warn(
+            `${providerId} rate limited, backing off for ${Math.round(backoffMs / 1000)}s`,
+            { retryAfterMs: backoffMs, until: new Date(backoffUntil).toISOString() },
+            "refresh",
+          );
+
+          setProviders((prev) => {
+            const next = new Map(prev);
+            const current = next.get(providerId);
+            // Preserve the last successful usage data if we have it
+            const preservedUsage = current?.usage && !current.usage.error ? current.usage : usage;
+            next.set(providerId, {
+              ...state,
+              usage: preservedUsage,
+              loading: false,
+              lastFetchAt: Date.now(),
+              rateLimitUntil: backoffUntil,
+              history: current?.history ?? [],
+            });
+            return next;
+          });
+          return;
+        }
+
         if (usage.error) {
           warn(`${providerId} returned error: ${usage.error}`, undefined, "refresh");
         } else {
@@ -395,6 +451,7 @@ export function PluginProvider({ children, cliPlugins }: PluginProviderProps) {
             usage,
             loading: false,
             lastFetchAt: Date.now(),
+            rateLimitUntil: 0,
             history: addToHistory(currentHistory, snapshot),
           });
           return next;
@@ -414,6 +471,7 @@ export function PluginProvider({ children, cliPlugins }: PluginProviderProps) {
             },
             loading: false,
             lastFetchAt: Date.now(),
+            rateLimitUntil: current?.rateLimitUntil ?? 0,
             history: current?.history ?? [],
           });
           return next;

package/src/tui/contexts/RealTimeActivityContext.tsx

@@ -1,3 +1,4 @@
+import type { ActivityUpdate } from "@tokentop/plugin-sdk";
 import {
   createContext,
   type ReactNode,
@@ -9,7 +10,6 @@ import {
 } from "react";
 import { createPluginContext } from "@/plugins/plugin-context-factory.ts";
 import { pluginRegistry } from "@/plugins/registry.ts";
-import type { ActivityUpdate } from "@/plugins/types/agent.ts";
 import { useDemoMode } from "./DemoModeContext.tsx";
 import { useLogs } from "./LogContext.tsx";
 import { usePlugins } from "./PluginContext.tsx";
@@ -50,25 +50,38 @@ export function RealTimeActivityProvider({ children }: { children: ReactNode })
     };
   }, []);
 
-  const handleActivityUpdate = useCallback(
-    (update: ActivityUpdate) => {
-      const key = `${update.sessionId}:${update.messageId}`;
-      const prev = lastSeenRef.current.get(key);
-      const prevTokens = prev?.tokens ?? 0;
-      const newTokens = update.tokens.input + update.tokens.output + (update.tokens.reasoning ?? 0);
-      const delta = Math.max(0, newTokens - prevTokens);
-
-      if (delta > 0) {
-        lastSeenRef.current.set(key, { tokens: newTokens, updatedAt: Date.now() });
-        setLastActivityAt(update.timestamp);
-        debug(`Real-time activity: +${delta} tokens`, { sessionId: update.sessionId }, "realtime");
-
-        for (const listener of listenersRef.current) {
-          listener(delta, update.timestamp);
-        }
+  // Store the actual handler logic in a ref so it always has access to the
+  // latest `debug` without changing callback identity. This prevents the
+  // useEffect below from re-running on every render (which would trigger
+  // stopActivityWatch/startActivityWatch churn on every plugin).
+  const handleActivityUpdateRef = useRef<(update: ActivityUpdate) => void>(() => {});
+  handleActivityUpdateRef.current = (update: ActivityUpdate) => {
+    const key = `${update.sessionId}:${update.messageId}`;
+    const prev = lastSeenRef.current.get(key);
+    const prevTokens = prev?.tokens ?? 0;
+    const input = update.tokens.input ?? 0;
+    const output = update.tokens.output ?? 0;
+    const reasoning = update.tokens.reasoning ?? 0;
+    const newTokens = input + output + reasoning;
+    if (!Number.isFinite(newTokens)) return;
+    const delta = Math.max(0, newTokens - prevTokens);
+
+    if (delta > 0) {
+      lastSeenRef.current.set(key, { tokens: newTokens, updatedAt: Date.now() });
+      setLastActivityAt(update.timestamp);
+      debug(`Real-time activity: +${delta} tokens`, { sessionId: update.sessionId }, "realtime");
+
+      for (const listener of listenersRef.current) {
+        listener(delta, update.timestamp);
       }
-    },
-    [debug],
+    }
+  };
+
+  // Stable wrapper — identity never changes, so the useEffect below only
+  // runs once per plugin initialization (not on every debug/info change).
+  const handleActivityUpdate = useCallback(
+    (update: ActivityUpdate) => handleActivityUpdateRef.current(update),
+    [],
   );
 
   useEffect(() => {
@@ -106,7 +119,7 @@ export function RealTimeActivityProvider({ children }: { children: ReactNode })
         cleanupRef.current = null;
       }
     };
-  }, [pluginsInitialized, demoMode, handleActivityUpdate, info]);
+  }, [pluginsInitialized, demoMode, handleActivityUpdate]);
 
   useEffect(() => {
     const interval = setInterval(() => {

package/src/tui/contexts/ThemeContext.tsx

@@ -1,12 +1,12 @@
-import { createContext, type ReactNode, useContext, useState } from "react";
-import { tokyoNightTheme } from "@/plugins/themes/tokyo-night.ts";
 import type {
   ColorScheme,
   ColorSchemePreference,
   ThemeColors,
   ThemeComponents,
   ThemePlugin,
-} from "@/plugins/types/theme.ts";
+} from "@tokentop/plugin-sdk";
+import { createContext, type ReactNode, useContext, useState } from "react";
+import { tokyoNightTheme } from "@/plugins/themes/tokyo-night.ts";
 
 interface ThemeContextValue {
   theme: ThemePlugin;
@@ -16,6 +16,7 @@ interface ThemeContextValue {
   setTheme: (theme: ThemePlugin) => void;
   previewTheme: ThemePlugin | null;
   setPreviewTheme: (theme: ThemePlugin | null) => void;
+  cliTheme: string | undefined;
 }
 
 const defaultComponents: ThemeComponents = {
@@ -29,10 +30,11 @@ const ThemeContext = createContext<ThemeContextValue | null>(null);
 
 interface ThemeProviderProps {
   initialTheme?: ThemePlugin;
+  cliTheme?: string;
   children: ReactNode;
 }
 
-export function ThemeProvider({ initialTheme, children }: ThemeProviderProps) {
+export function ThemeProvider({ initialTheme, cliTheme, children }: ThemeProviderProps) {
   const [theme, setTheme] = useState<ThemePlugin>(initialTheme ?? tokyoNightTheme);
   const [previewTheme, setPreviewTheme] = useState<ThemePlugin | null>(null);
 
@@ -46,6 +48,7 @@ export function ThemeProvider({ initialTheme, children }: ThemeProviderProps) {
     setTheme,
     previewTheme,
     setPreviewTheme,
+    cliTheme,
   };
 
   return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;

package/src/tui/createApp.tsx

@@ -13,6 +13,7 @@ export interface CreateAppOptions {
   demoSeed?: number;
   demoPreset?: DemoPreset;
   cliPlugins?: string[];
+  cliTheme?: string;
 }
 
 export const DEFAULT_APP_OPTIONS = {
@@ -32,6 +33,7 @@ export function createAppElement(options: CreateAppOptions = {}): ReactNode {
       {...(options.demoSeed !== undefined ? { demoSeed: options.demoSeed } : {})}
       {...(options.demoPreset !== undefined ? { demoPreset: options.demoPreset } : {})}
       {...(options.cliPlugins ? { cliPlugins: options.cliPlugins } : {})}
+      {...(options.cliTheme ? { cliTheme: options.cliTheme } : {})}
     />
   );
 

package/src/tui/hooks/index.ts

@@ -6,6 +6,7 @@ export {
   useAnimatedTokens,
   useAnimatedValue,
 } from "./useAnimatedValue.ts";
+export { animationTick, useAnimationTick } from "./useAnimationTick.ts";
 export type { DashboardDeltas, UseDashboardStateResult } from "./useDashboardState.ts";
 export { useDashboardState } from "./useDashboardState.ts";
 export type { ActivityDebugData, ActivityState, UseActivityRateResult } from "./useEmaActivity.ts";

package/src/tui/hooks/useAnimatedValue.ts

@@ -1,4 +1,5 @@
 import { useEffect, useRef, useState } from "react";
+import { animationTick } from "./useAnimationTick.ts";
 
 export type EasingFunction = (t: number) => number;
 
@@ -14,6 +15,7 @@ export interface UseAnimatedValueOptions {
   durationMs?: number;
   easing?: keyof typeof easings | EasingFunction;
   precision?: number;
+  /** @deprecated Ignored — animations now use the global 30 Hz tick. */
   frameRate?: number;
 }
 
@@ -21,57 +23,58 @@ export function useAnimatedValue(
   targetValue: number,
   options: UseAnimatedValueOptions = {},
 ): number {
-  const { durationMs = 300, easing = "easeOutQuad", precision = 2, frameRate = 60 } = options;
+  const { durationMs = 300, easing = "easeOutQuad", precision = 2 } = options;
 
   const [displayValue, setDisplayValue] = useState(targetValue);
-  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  const displayRef = useRef(targetValue);
   const startValueRef = useRef(targetValue);
-  const startTimeRef = useRef<number>(Date.now());
+  const startTimeRef = useRef(0);
   const targetRef = useRef(targetValue);
+  const unsubRef = useRef<(() => void) | null>(null);
 
   const easingFn = typeof easing === "function" ? easing : easings[easing];
-  const frameInterval = Math.round(1000 / frameRate);
 
   useEffect(() => {
-    if (targetRef.current === targetValue && displayValue === targetValue) {
+    // Already at target — nothing to animate
+    if (targetRef.current === targetValue && displayRef.current === targetValue) {
       return;
     }
 
-    if (intervalRef.current !== null) {
-      clearInterval(intervalRef.current);
-    }
+    // Clean up any existing subscription
+    unsubRef.current?.();
 
-    startValueRef.current = displayValue;
+    // Set up animation from current display value to new target
+    startValueRef.current = displayRef.current;
     startTimeRef.current = Date.now();
     targetRef.current = targetValue;
 
-    intervalRef.current = setInterval(() => {
-      const elapsed = Date.now() - startTimeRef.current;
+    // Subscribe to global tick — auto-starts the shared timer
+    unsubRef.current = animationTick.subscribe((now) => {
+      const elapsed = now - startTimeRef.current;
       const progress = Math.min(elapsed / durationMs, 1);
       const easedProgress = easingFn(progress);
-
       const startVal = startValueRef.current;
-      const currentValue = startVal + (targetRef.current - startVal) * easedProgress;
-      const roundedValue = Number(currentValue.toFixed(precision));
+      const target = targetRef.current;
+      const currentValue = startVal + (target - startVal) * easedProgress;
+      const rounded = Number(currentValue.toFixed(precision));
 
-      setDisplayValue(roundedValue);
+      displayRef.current = rounded;
+      setDisplayValue(rounded);
 
       if (progress >= 1) {
-        if (intervalRef.current !== null) {
-          clearInterval(intervalRef.current);
-          intervalRef.current = null;
-        }
-        setDisplayValue(targetRef.current);
+        displayRef.current = target;
+        setDisplayValue(target);
+        // Unsubscribe — if no other animations are active, the global timer stops
+        unsubRef.current?.();
+        unsubRef.current = null;
       }
-    }, frameInterval);
+    });
 
     return () => {
-      if (intervalRef.current !== null) {
-        clearInterval(intervalRef.current);
-        intervalRef.current = null;
-      }
+      unsubRef.current?.();
+      unsubRef.current = null;
     };
-  }, [targetValue, durationMs, easingFn, precision, frameInterval, displayValue]);
+  }, [targetValue, durationMs, easingFn, precision]);
 
   return displayValue;
 }

package/src/tui/hooks/useAnimationTick.ts

@@ -0,0 +1,93 @@
+/**
+ * Global animation tick manager.
+ *
+ * Replaces per-component setInterval timers with a single shared 30 Hz tick.
+ * This eliminates the ~90 concurrent timers that were causing ~2,400 state
+ * updates/sec and ~60% CPU usage at idle.
+ *
+ * The tick automatically starts when the first subscriber joins and stops
+ * when the last subscriber leaves, consuming zero CPU when no animations
+ * are active.
+ *
+ * @see https://github.com/tokentopapp/tokentop/issues/55
+ */
+import { useEffect, useRef } from "react";
+
+type TickCallback = (now: number) => void;
+
+const TICK_RATE_HZ = 30;
+const TICK_INTERVAL_MS = Math.round(1000 / TICK_RATE_HZ);
+
+class AnimationTickManager {
+  private callbacks = new Set<TickCallback>();
+  private interval: ReturnType<typeof setInterval> | null = null;
+
+  /**
+   * Subscribe a callback to the global tick.
+   * Returns an unsubscribe function. When the last subscriber leaves,
+   * the underlying setInterval is cleared automatically.
+   */
+  subscribe(callback: TickCallback): () => void {
+    this.callbacks.add(callback);
+    if (this.callbacks.size === 1) {
+      this.start();
+    }
+    return () => {
+      this.callbacks.delete(callback);
+      if (this.callbacks.size === 0) {
+        this.stop();
+      }
+    };
+  }
+
+  /** Number of active subscribers (useful for debugging). */
+  get subscriberCount(): number {
+    return this.callbacks.size;
+  }
+
+  /** Whether the global interval is currently running. */
+  get isRunning(): boolean {
+    return this.interval !== null;
+  }
+
+  private start(): void {
+    if (this.interval !== null) return;
+    this.interval = setInterval(() => {
+      const now = Date.now();
+      for (const cb of this.callbacks) {
+        cb(now);
+      }
+    }, TICK_INTERVAL_MS);
+  }
+
+  private stop(): void {
+    if (this.interval !== null) {
+      clearInterval(this.interval);
+      this.interval = null;
+    }
+  }
+}
+
+/** Global animation tick singleton — single 30 Hz timer shared by all hooks. */
+export const animationTick = new AnimationTickManager();
+
+/**
+ * React hook to subscribe to the global animation tick.
+ *
+ * The callback fires at ~30 Hz while `active` is true.
+ * Uses a ref to always call the latest callback (no stale closures).
+ *
+ * @param callback - Called with current timestamp (Date.now()) on each tick
+ * @param active - Whether to subscribe (default: true). When false, the
+ *   subscription is paused and the global timer may stop if no other
+ *   subscribers remain.
+ */
+export function useAnimationTick(callback: TickCallback, active = true): void {
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
+  useEffect(() => {
+    if (!active) return;
+    return animationTick.subscribe((now) => callbackRef.current(now));
+  }, [active]);
+}

package/src/tui/hooks/useDashboardKeyboard.ts

@@ -7,6 +7,7 @@ import { useAgentSessions } from "../contexts/AgentSessionContext.tsx";
 import { useInputFocus } from "../contexts/InputContext.tsx";
 import { useTimeWindow } from "../contexts/TimeWindowContext.tsx";
 import { useToastContext } from "../contexts/ToastContext.tsx";
+import type { SortDirection, SortField } from "../types/sort.ts";
 
 function formatSessionSummary(session: AgentSessionAggregate): string {
   const effectiveTokens = session.totals.input + session.totals.output;
@@ -54,7 +55,9 @@ interface DashboardKeyboardState {
   sidebarCollapsed: boolean;
   filterQuery: string;
   isFiltering: boolean;
-  sortField: "cost" | "tokens" | "time";
+  sortField: SortField;
+  sortDirection: SortDirection;
+  showSortOverlay: boolean;
   pendingG: boolean;
   scrollOffset: number;
   limitSelectedIndex: number;
@@ -76,13 +79,15 @@ interface DashboardKeyboardActions {
   setSidebarCollapsed: (fn: (prev: boolean) => boolean) => void;
   setFilterQuery: (fn: (prev: string) => string) => void;
   setIsFiltering: (val: boolean) => void;
-  setSortField: (fn: (prev: "cost" | "tokens" | "time") => "cost" | "tokens" | "time") => void;
+  setSortField: (fn: (prev: SortField) => SortField) => void;
+  setSortDirection: (fn: (prev: SortDirection) => SortDirection) => void;
   setPendingG: (val: boolean) => void;
   setScrollOffset: (val: number) => void;
   setLimitSelectedIndex: (fn: (prev: number) => number) => void;
   setDriverDimension: (fn: (prev: DriverDimension) => DriverDimension) => void;
   setSelectedDriverIndex: (fn: (prev: number) => number) => void;
   setActiveDriverFilter: (val: string | null) => void;
+  setShowSortOverlay: (val: boolean) => void;
 }
 
 interface UseDashboardKeyboardProps {
@@ -115,7 +120,7 @@ export function useDashboardKeyboard({
 
   useEffect(() => {
     isFilteringRef.current = state.isFiltering;
-    modalOpenRef.current = state.showHelp || state.showSessionDrawer;
+    modalOpenRef.current = state.showHelp || state.showSessionDrawer || state.showSortOverlay;
     pendingGRef.current = state.pendingG;
     sessionsRef.current = processedSessions;
     focusedPanelRef.current = state.focusedPanel;
@@ -129,6 +134,7 @@ export function useDashboardKeyboard({
     state.isFiltering,
     state.showHelp,
     state.showSessionDrawer,
+    state.showSortOverlay,
     state.pendingG,
     processedSessions,
     state.focusedPanel,
@@ -242,8 +248,9 @@ export function useDashboardKeyboard({
       return;
     }
 
+    // Open sort overlay menu
     if (key.name === "s") {
-      actions.setSortField((curr) => (curr === "cost" ? "tokens" : "cost"));
+      actions.setShowSortOverlay(true);
       return;
     }
 

package/src/tui/hooks/useEntranceAnimation.ts

@@ -1,7 +1,9 @@
 import { useEffect, useRef, useState } from "react";
+import { animationTick } from "./useAnimationTick.ts";
 
 export interface UseEntranceAnimationOptions {
   durationMs?: number;
+  /** @deprecated Ignored — animations now use the global 30 Hz tick. */
   fps?: number;
 }
 
@@ -11,26 +13,30 @@ export interface UseEntranceAnimationOptions {
  * Use this to fade in new items in a list.
  */
 export function useEntranceAnimation(options: UseEntranceAnimationOptions = {}): number {
-  const { durationMs = 400, fps = 30 } = options;
+  const { durationMs = 400 } = options;
   const mountTime = useRef(Date.now());
   const [intensity, setIntensity] = useState(0);
+  const unsubRef = useRef<(() => void) | null>(null);
 
   useEffect(() => {
-    const intervalMs = 1000 / fps;
-
-    const tick = () => {
-      const elapsed = Date.now() - mountTime.current;
+    unsubRef.current = animationTick.subscribe((now) => {
+      const elapsed = now - mountTime.current;
       const progress = Math.min(1, elapsed / durationMs);
       const eased = 1 - (1 - progress) ** 2;
       setIntensity(eased);
 
-      if (progress < 1) {
-        setTimeout(tick, intervalMs);
+      if (progress >= 1) {
+        setIntensity(1);
+        unsubRef.current?.();
+        unsubRef.current = null;
       }
-    };
+    });
 
-    tick();
-  }, [durationMs, fps]);
+    return () => {
+      unsubRef.current?.();
+      unsubRef.current = null;
+    };
+  }, [durationMs]);
 
   return intensity;
 }

package/src/tui/hooks/usePulse.ts

@@ -1,4 +1,5 @@
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
+import { animationTick } from "./useAnimationTick.ts";
 
 /**
  * Options for the usePulse hook.
@@ -39,7 +40,7 @@ function parseHexColor(hex: string): [number, number, number] | null {
   const g = parseInt(expandedHex.slice(2, 4), 16);
   const b = parseInt(expandedHex.slice(4, 6), 16);
 
-  if (isNaN(r) || isNaN(g) || isNaN(b)) {
+  if (Number.isNaN(r) || Number.isNaN(g) || Number.isNaN(b)) {
     return null;
   }
 
@@ -104,6 +105,9 @@ export function getPulseColor(
  * Returns the current step in the pulse cycle, which can be used
  * with getPulseColor to create smooth color transitions.
  *
+ * Subscribes to the global animation tick when enabled and unsubscribes
+ * when disabled, so the global timer stops when no pulses are active.
+ *
  * @param options - Configuration options for the pulse animation
  * @returns Current step in the pulse cycle (0 to steps-1), or 0 when disabled
  *
@@ -120,6 +124,7 @@ export function getPulseColor(
 export function usePulse(options: UsePulseOptions): number {
   const { enabled, intervalMs = 200, steps = 12 } = options;
   const [step, setStep] = useState(0);
+  const lastAdvanceRef = useRef(Date.now());
 
   useEffect(() => {
     if (!enabled) {
@@ -127,11 +132,12 @@ export function usePulse(options: UsePulseOptions): number {
       return;
     }
 
-    const interval = setInterval(() => {
-      setStep((prev) => (prev + 1) % steps);
-    }, intervalMs);
-
-    return () => clearInterval(interval);
+    return animationTick.subscribe((now) => {
+      if (now - lastAdvanceRef.current >= intervalMs) {
+        lastAdvanceRef.current = now;
+        setStep((prev) => (prev + 1) % steps);
+      }
+    });
   }, [enabled, intervalMs, steps]);
 
   return step;

package/src/tui/hooks/useSessionEnrichedProviders.ts

@@ -1,6 +1,6 @@
+import type { ProviderUsageData } from "@tokentop/plugin-sdk";
 import { useMemo } from "react";
 import type { AgentSessionAggregate } from "@/agents/types.ts";
-import type { ProviderUsageData } from "@/plugins/types/provider.ts";
 import type { ProviderState } from "../contexts/PluginContext.tsx";
 
 interface ProviderSessionTotals {