👁 Ghost Lens

Behavioral idle-detection contextual help overlay for React and Web Components.

Ghost Lens detects when users are lost — no button clicks required. A configurable idle timer triggers a kinetic "Clear Curtain" sweep revealing contextual tooltips keyed to data-ghost attributes. The moment a user moves their mouse or types, everything vanishes.

Install

npm install ghost-lens

React

import { GhostLens } from 'ghost-lens';

export default function App() {
  return (
    <GhostLens idleDelay={3000}>
      <YourApp />
    </GhostLens>
  );
}

Then add data-ghost to any element:

<button data-ghost="Click to save your changes to the cloud">
  Save
</button>

<nav data-ghost="Navigate between sections of your project">
  ...
</nav>

React Hook

import { useGhostLens } from 'ghost-lens';

function Dashboard() {
  const { activate, deactivate } = useGhostLens({ idleDelay: 4000 });

  return <button onClick={activate}>Show Help</button>;
}

ghost() Helper

import { ghost } from 'ghost-lens';

<button {...ghost('Click to submit the form')}>Submit</button>

Web Component

<script type="module">
  import 'ghost-lens/web-component';
</script>

<ghost-lens idle-delay="3000"></ghost-lens>

<button data-ghost="Click to submit the form">Submit</button>

Vanilla JS

import { GhostLensEngine } from 'ghost-lens';

const lens = new GhostLensEngine(null, {
  idleDelay: 3000,
  onActivate: () => console.log('Lens active'),
  onDeactivate: () => console.log('Lens dismissed'),
});

// Manual control
lens.activate();
lens.deactivate();
lens.destroy();

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | idleDelay | number | 3000 | ms of idle before lens activates | | curtainDuration | number | 600 | ms for the curtain sweep animation | | accentColor | string | '#00c8ff' | Primary accent color | | tooltipBg | string | 'rgba(0,18,30,0.92)' | Tooltip background | | tooltipBorder | string | 'rgba(0,200,255,0.4)' | Tooltip border color | | tooltipColor | string | '#a8f0ff' | Tooltip text color | | zIndex | number | 9999 | Overlay z-index | | badgeText | string | 'GHOST LENS' | Badge title text | | badgeSubtext | string | 'Augmentation Active' | Badge subtitle | | disabled | boolean | false | Disable the lens | | onActivate | function | null | Callback on activation | | onDeactivate | function | null | Callback on deactivation |

How It Works

1. Ghost Lens listens for mousemove, keydown, click, scroll, and touchstart events globally
2. After idleDelay ms of no activity, the lens activates
3. A "Clear Curtain" gradient sweeps across the viewport (kinetic HUD power-up effect)
4. Tooltips appear at the real-time bounding box coordinates of every [data-ghost] element
5. Any user activity immediately dismisses everything — zero friction
6. Users can permanently disable via "Disable Ghost Lens Forever" (stored in localStorage)

User Respect

Ghost Lens is designed with users in mind:

• "Disable Ghost Lens Forever" persists to localStorage — no dark patterns
• No analytics or tracking by default
• Dismisses instantly on any activity — never in the way

License

MIT © Tom Ashby / xdrabbit