@tokentop/ttop 0.5.0 → 0.6.0

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/useValueFlash.ts

@@ -1,4 +1,5 @@
 import { useEffect, useRef, useState } from "react";
+import { animationTick } from "./useAnimationTick.ts";
 
 export interface UseValueFlashOptions {
   durationMs?: number;
@@ -20,12 +21,9 @@ export function useValueFlash(
 
   const prevValueRef = useRef<number>(value);
   const [isFlashing, setIsFlashing] = useState(false);
-  const [step, setStep] = useState(0);
-  const flashTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-  const animationIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
-
-  const steps = 18;
-  const stepDuration = durationMs / steps;
+  const [intensity, setIntensity] = useState(0);
+  const flashStartRef = useRef(0);
+  const unsubRef = useRef<(() => void) | null>(null);
 
   useEffect(() => {
     const prevValue = prevValueRef.current;
@@ -34,45 +32,39 @@ export function useValueFlash(
     const shouldFlash = increaseOnly ? delta > threshold : Math.abs(delta) > threshold;
 
     if (shouldFlash && prevValue !== value) {
-      if (flashTimeoutRef.current) {
-        clearTimeout(flashTimeoutRef.current);
-      }
-      if (animationIntervalRef.current) {
-        clearInterval(animationIntervalRef.current);
-      }
+      // Clean up any existing subscription
+      unsubRef.current?.();
 
+      flashStartRef.current = Date.now();
       setIsFlashing(true);
-      setStep(0);
-
-      let currentStep = 0;
-      animationIntervalRef.current = setInterval(() => {
-        currentStep++;
-        if (currentStep >= steps) {
-          if (animationIntervalRef.current) {
-            clearInterval(animationIntervalRef.current);
-            animationIntervalRef.current = null;
-          }
+
+      // Subscribe to global tick
+      unsubRef.current = animationTick.subscribe((now) => {
+        const elapsed = now - flashStartRef.current;
+        const progress = elapsed / durationMs;
+
+        if (progress >= 1) {
           setIsFlashing(false);
-          setStep(0);
+          setIntensity(0);
+          unsubRef.current?.();
+          unsubRef.current = null;
         } else {
-          setStep(currentStep);
+          const currentIntensity = Math.sin(progress * Math.PI);
+          setIntensity(currentIntensity);
         }
-      }, stepDuration);
+      });
     }
 
     prevValueRef.current = value;
 
     return () => {
-      if (flashTimeoutRef.current) {
-        clearTimeout(flashTimeoutRef.current);
-      }
-      if (animationIntervalRef.current) {
-        clearInterval(animationIntervalRef.current);
-      }
+      unsubRef.current?.();
+      unsubRef.current = null;
     };
-  }, [value, durationMs, increaseOnly, threshold, steps, stepDuration]);
+  }, [value, durationMs, increaseOnly, threshold]);
 
-  const intensity = isFlashing ? Math.sin((step / steps) * Math.PI) : 0;
+  // step is kept for backward API compatibility
+  const step = isFlashing ? Math.round(intensity * 9) : 0;
 
   return { isFlashing, intensity, step };
 }

package/src/tui/index.tsx

@@ -13,6 +13,7 @@ export interface TuiOptions {
   demoSeed?: number;
   demoPreset?: DemoPreset;
   cliPlugins?: string[];
+  cliTheme?: string;
 }
 
 const FORCE_EXIT_GRACE_MS = 1_000;
@@ -45,6 +46,9 @@ export async function startTui(options: TuiOptions = {}) {
   if (options.cliPlugins !== undefined) {
     appOptions.cliPlugins = options.cliPlugins;
   }
+  if (options.cliTheme !== undefined) {
+    appOptions.cliTheme = options.cliTheme;
+  }
 
   root.render(createAppElement(appOptions));
 

package/src/tui/types/projectSort.ts

@@ -0,0 +1,35 @@
+import type { SortFieldDef } from "./sort.ts";
+import { buildShortcutMap } from "./sort.ts";
+
+export type ProjectSortField =
+  | "project"
+  | "cost"
+  | "tokens"
+  | "sessions"
+  | "cache"
+  | "cpr"
+  | "activity";
+
+export const PROJECT_SORT_FIELDS: readonly SortFieldDef<ProjectSortField>[] = [
+  { id: "project", label: "Project", shortcutKey: "P", defaultDirection: "asc" },
+  { id: "cost", label: "Cost", shortcutKey: "C", defaultDirection: "desc" },
+  { id: "tokens", label: "Tokens", shortcutKey: "K", defaultDirection: "desc" },
+  { id: "sessions", label: "Sessions", shortcutKey: "S", defaultDirection: "desc" },
+  { id: "cache", label: "Cache", shortcutKey: "H", defaultDirection: "desc" },
+  { id: "cpr", label: "$/Req", shortcutKey: "R", defaultDirection: "desc" },
+  { id: "activity", label: "Activity", shortcutKey: "A", defaultDirection: "desc" },
+] as const;
+
+/** Map from lowercase shortcut key → ProjectSortField */
+export const PROJECT_SHORTCUT_TO_FIELD: ReadonlyMap<string, ProjectSortField> =
+  buildShortcutMap(PROJECT_SORT_FIELDS);
+
+export function getProjectSortFieldDef(field: ProjectSortField): SortFieldDef<ProjectSortField> {
+  const def = PROJECT_SORT_FIELDS.find((f) => f.id === field);
+  if (!def) throw new Error(`Unknown project sort field: ${field}`);
+  return def;
+}
+
+export function getProjectSortFieldLabel(field: ProjectSortField): string {
+  return getProjectSortFieldDef(field).label;
+}

package/src/tui/types/sort.ts

@@ -0,0 +1,61 @@
+export type SortDirection = "asc" | "desc";
+
+export interface SortFieldDef<F extends string = string> {
+  readonly id: F;
+  readonly label: string;
+  /** Uppercase letter shown in overlay + used as Shift+key shortcut */
+  readonly shortcutKey: string;
+  /** Default direction when switching to this field */
+  readonly defaultDirection: SortDirection;
+}
+
+/** Build a lowercase-key → field-id map from any fields array */
+export function buildShortcutMap<F extends string>(
+  fields: readonly SortFieldDef<F>[],
+): ReadonlyMap<string, F> {
+  return new Map(fields.map((f) => [f.shortcutKey.toLowerCase(), f.id]));
+}
+
+// ---------------------------------------------------------------------------
+// Dashboard sort fields
+// ---------------------------------------------------------------------------
+
+export type SortField =
+  | "cost"
+  | "tokens"
+  | "time"
+  | "requests"
+  | "duration"
+  | "project"
+  | "agent"
+  | "model"
+  | "name";
+
+export const SORT_FIELDS: readonly SortFieldDef<SortField>[] = [
+  { id: "agent", label: "Agent", shortcutKey: "A", defaultDirection: "desc" },
+  { id: "model", label: "Model", shortcutKey: "M", defaultDirection: "desc" },
+  { id: "requests", label: "Requests", shortcutKey: "E", defaultDirection: "desc" },
+  { id: "tokens", label: "Tokens", shortcutKey: "K", defaultDirection: "desc" },
+  { id: "cost", label: "Cost", shortcutKey: "C", defaultDirection: "desc" },
+  { id: "project", label: "Project", shortcutKey: "O", defaultDirection: "desc" },
+  { id: "name", label: "Name", shortcutKey: "N", defaultDirection: "desc" },
+  { id: "duration", label: "Duration", shortcutKey: "U", defaultDirection: "desc" },
+  { id: "time", label: "Time", shortcutKey: "T", defaultDirection: "desc" },
+] as const;
+
+/** Map from lowercase shortcut key → SortField (dashboard) */
+export const SHORTCUT_TO_FIELD: ReadonlyMap<string, SortField> = buildShortcutMap(SORT_FIELDS);
+
+export function getSortFieldDef(field: SortField): SortFieldDef<SortField> {
+  const def = SORT_FIELDS.find((f) => f.id === field);
+  if (!def) throw new Error(`Unknown sort field: ${field}`);
+  return def;
+}
+
+export function getSortFieldLabel(field: SortField): string {
+  return getSortFieldDef(field).label;
+}
+
+export function getSortDirectionIndicator(dir: SortDirection): string {
+  return dir === "desc" ? "▼" : "▲";
+}