React Watchman

A human behavior-aware idle detection hook and boundary component for React, designed for intelligent session management, auto-logout, and behavioral analytics in modern web apps.

✨ Features

• 🧠 AI-Inspired Idle Detection: Combines mouse movement, typing, scrolling, and visibility events with customizable heuristics.
• ⚙️ Customizable Sensitivity & Debounce: Fine-tune detection accuracy.
• 📦 React Hook + HOC-Compatible: Works as a hook (useReactWatchman) or wrapped UI (WatchmanBoundary).
• 🔐 Auto Logout & Session Timeout: Trigger auto-logout logic or alerts after inactivity.
• 📡 Focus / Blur & Tab Visibility Tracking: Detect when user switches tabs or windows.
• 💓 Optional Heartbeat Support: Add a server ping to keep sessions alive.
• 🧪 Typescript Support: Fully typed, developer-friendly.

📦 Installation

npm install react-watchman
# or
yarn add react-watchman

Demo

Check out the project running here{:target="_blank"}!

🚀 Usage

1. useReactWatchman Hook

import { useReactWatchman } from "react-watchman";

function Dashboard() {
  const { isIdle } = useReactWatchman({
    idleTime: 60000,
    onIdle: () => console.log("User is idle"),
    onActive: () => console.log("User is active again"),
    onTabHide: () => console.log("Tab hidden"),
    onTabShow: (ms) => console.log(`Returned after ${ms}ms`),
    onFocus: () => console.log("Window focused"),
    onBlur: () => console.log("Window blurred"),
    debounce: 300,
    sensitivity: 1.0,
  });

  return <div>{isIdle ? "Idle..." : "Active 🟢"}</div>;
}

2. WatchmanBoundary Component

import { WatchmanBoundary } from "react-watchman";

export default function App() {
  return (
    <WatchmanBoundary
      timeout={120000}
      debounce={250}
      onIdle={() => console.log("Idle! Logging out soon")}
      onActive={() => console.log("User returned")}
      renderIdle={() => (
        <div className="idle-warning">You’re idle. Logging out...</div>
      )}
    >
      <Dashboard />
    </WatchmanBoundary>
  );
}

🧠 Parameters & Options

| Option | Type | Description | | -------------------- | ---------- | --------------------------------------------------------------------- | | idleTime | number | Time in ms to wait before considering user idle (default: 30000) | | debounce | number | Delay for debouncing activity events (default: 250) | | sensitivity | number | 0.1 to 1.0 — sensitivity to idle detection (lower = more tolerant) | | onIdle | function | Called when user is considered idle | | onActive | function | Called when user becomes active again | | onFocus | function | Called when window gains focus | | onBlur | function | Called when window loses focus | | onTabHide | function | Called when tab becomes hidden | | onTabShow | function | Called when tab becomes visible again, receives duration in ms | | onVisibilityChange | function | Called when tab visibility changes (param: "visible" or "hidden") |

🧪 Events Tracked

• mousemove, mousedown, keydown, wheel, touchstart, scroll, pointermove
• visibilitychange, focus, blur

🏭 Industries & Use Cases

| Industry | How It's Useful | | -------------- | -------------------------------------------------------- | | Fintech | Auto-logout inactive users for compliance & security | | SaaS | Notify users before logging out, track engagement | | Healthcare | Ensure sensitive records are not left exposed after idle | | E-learning | Detect disengagement and prompt user re-engagement | | Enterprise | Log audit trails of focus/blur or session activity | | Banking | Strict session expiry enforcement & risk mitigation |

👨‍💻 Why Developers Love It

• ✅ Plug-and-play: Simple drop-in solution
• ⚙️ Configurable: Fine-grained control for advanced apps
• 🔁 Reusable: Hook or boundary component
• 📈 Scalable: Add heartbeats, custom triggers, modals, etc.
• 🛡️ Secure by default: Helps enforce inactivity-based session logout

🧩 Future Plans

• ⏳ Idle countdown timer
• 🧠 Heuristic profiles (adaptive timeout)
• 🔄 Heartbeat/keep-alive via fetch
• 📊 Session activity analytics
• 💬 Idle modal prompts with confirm/extend/logout options

📝 License

MIT License

📫 Contact

Questions or feedback? Reach out via GitHub or create a discussion.

Built with ❤️ to make React apps smarter and safer.