Class RefreshController

src/browser/utils/RefreshController.ts:88–532

const MIN_REFRESH_INTERVAL_MS = 500;

export class RefreshController {
  private readonly onRefresh: () => Promise<void> | void;
  private readonly onRefreshComplete: ((info: LastRefreshInfo) => void) | null;
  private readonly onRefreshError: ((info: RefreshFailureInfo) => void) | null;
  private readonly debounceMs: number;
  private readonly priorityDebounceMs: number;
  private readonly refreshOnFocus: boolean;
  private readonly focusDebounceMs: number;
  private readonly isPaused: (() => boolean) | null;
  private readonly isManualBlockedFn: (() => boolean) | null;
  private readonly debugLabel: string | null;

  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
  private cooldownTimer: ReturnType<typeof setTimeout> | null = null;
  private inFlight = false;
  private pendingBecauseHidden = false;
  private pendingBecauseInFlight = false;
  private pendingBecausePaused = false;
  private lastFocusRefreshMs = 0;
  private disposed = false;
  private lifecycleGeneration = 0;

  // Track last refresh for debugging
  private _lastRefreshInfo: LastRefreshInfo | null = null;
  private pendingTrigger: RefreshTrigger | null = null;

  // Timestamp of last refresh START (not completion)
  private lastRefreshStartMs = 0;

  // Track if listeners are bound (for cleanup)
  private listenersBound = false;
  private boundHandleVisibility: (() => void) | null = null;
  private boundHandleFocus: (() => void) | null = null;

  constructor(options: RefreshControllerOptions) {
    this.onRefresh = options.onRefresh;
    this.onRefreshComplete = options.onRefreshComplete ?? null;
    this.onRefreshError = options.onRefreshError ?? null;
    this.debounceMs = options.debounceMs ?? 3000;
    this.priorityDebounceMs = options.priorityDebounceMs ?? this.debounceMs;
    this.refreshOnFocus = options.refreshOnFocus ?? false;
    this.focusDebounceMs = options.focusDebounceMs ?? 500;
    this.isPaused = options.isPaused ?? null;
    this.isManualBlockedFn = options.isManualBlocked ?? null;
    this.debugLabel = options.debugLabel ?? null;
  }

  private updatePendingTrigger(trigger: RefreshTrigger): void {
    const priorities: Record<RefreshTrigger, number> = {
      manual: 3,
      priority: 2,
      scheduled: 1,
      focus: 0,
      visibility: 0,
      unpaused: 0,
      "in-flight-followup": 0,
    };