SimplifyCaptcha

A modern React CAPTCHA component library with advanced human verification capabilities. Originally ad3. Device-Adaptive Scoring: Automatically detects device capabilities and adjusts scoring:

- Desktop: Focuses on mouse movement patterns and click behaviors
- Mobile: Emphasizes touch gestures and natural finger interactions
- Cross-platform: Adapts to device pixel ratio and input capabilities

4. Intelligent Human Detection: Advanced algorithm analyzes multiple factors:
- Time spent on page and interaction frequency
- Natural timing variations in user actions
- Device-appropriate interaction patterns
- Behavioral consistency and human-like randomness

5. Automatic Verification: If the human score is high enough (≥80%), verification passes automatically

6. SVG-Based Fallback CAPTCHA: When automatic verification fails, a beautiful SVG-rendered CAPTCHA is presented with:
- Advanced distortion effects using SVG filters and transformations
- Noise patterns and visual interference to prevent OCR attacks
- Dynamic character styling with random colors, rotations, and scales
- Accessibility features maintaining readability for humans

7. Multiple Attempts: Users get up to 30 attempts to solve the text CAPTCHA Native, this library provides intelligent behavior analysis and fallback text-based verification.

📖 Documentation

View Full Documentation →

The complete documentation includes:

- 🎮 Interactive Demo - Test the component with live behavior tracking
- 📋 Comprehensive API Reference - Complete TypeScript interfaces
- 💻 Code Examples - Real-world usage patterns
- 🚀 Installation Guide - Step-by-step setup instructions

Features

- 🤖 Intelligent Behavior Analysis - Advanced real-time gesture and interaction tracking
- 🖱️ Mouse Movement Tracking - Analyzes cursor patterns, velocity, and natural variations
- 👆 Touch Gesture Recognition - Detects multi-touch gestures and natural mobile interactions
- ⌨️ Keyboard Pattern Analysis - Monitors typing rhythm and natural keystroke variations
- 📜 Scroll Behavior Monitoring - Tracks natural scrolling patterns and content engagement
- 🎨 SVG-based CAPTCHA Rendering - High-quality, scalable vector graphics with distortion effects
- 🔒 Advanced Text Fallback - Beautiful SVG-rendered CAPTCHA with noise patterns and distortions
- 📱 Responsive Design - Works seamlessly on desktop and mobile devices
- 🎨 Customizable Styling - Easy to customize with CSS classes and inline styles
- ⚡ TypeScript Support - Full TypeScript definitions included
- 🚀 Easy Integration - Simple API with ref-based control
- 🎯 Zero CSS Imports - Styles are automatically injected, no separate CSS imports needed
- 📈 Automatic Version Bumping - Intelligent semantic versioning with pre-commit hooks
- 🔧 Development Tools - Built-in version management and git hooks for seamless development

Installation

``bash
npm install simplify-captcha
`

Note: No CSS imports are required! The component automatically injects its styles when used.

The library exports the following TypeScript types:

- SimplifyCaptcha - The main CAPTCHA component
- SimplifyCaptchaProps - Props interface for the component
- SimplifyCaptchaRef - Ref interface for imperative methods
- injectStyles - Utility function for manual style injection

Quick Start

`tsx
import React, { useRef } from 'react';
import { SimplifyCaptcha, SimplifyCaptchaRef } from 'simplify-captcha';

function MyComponent() {
const captchaRef = useRef(null);

const handleCaptchaResult = (event: { nativeEvent: { data: string } }) => {
const { data } = event.nativeEvent;

switch (data) {
case 'verified':
console.log('✅ User verified successfully!');
break;
case 'cancel':
console.log('❌ User cancelled verification');
break;
case 'error':
console.log('❌ Verification failed - too many attempts');
break;
}
};

return (



);
}
`

API Reference

$3

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| onMessage | (event: { nativeEvent: { data: string } }) => void | Yes | Callback for verification results |
| style | React.CSSProperties | No | Custom inline styles |
| className | string | No | Custom CSS class name |

$3

| Method | Description |
|--------|-------------|
| show() | Displays the CAPTCHA modal |
| hide() | Hides the CAPTCHA modal |

$3

The onMessage callback receives these possible results:

- 'verified' - User passed verification
- 'cancel' - User cancelled the verification process
- 'error' - Verification failed due to too many incorrect attempts

How It Works

1. Real-Time Gesture Analysis: The component continuously monitors user interactions including:
- Mouse movements: Cursor patterns, velocity changes, and natural variations
- Touch gestures: Multi-touch events, swipe patterns, and pressure sensitivity
- Keyboard interactions: Typing rhythm, keystroke timing, and natural variations
- Scroll behavior: Scrolling patterns indicating natural content consumption

2. Device-Adaptive Scoring: Automatically detects device capabilities and adjusts scoring:
- Desktop: Focuses on mouse movement patterns and click behaviors
- Mobile: Emphasizes touch gestures and natural finger interactions
- Cross-platform: Adapts to device pixel ratio and input capabilities

3. Intelligent Human Detection: Advanced algorithm analyzes multiple factors:
- Time spent on page and interaction frequency
- Natural timing variations in user actions
- Device-appropriate interaction patterns
- Behavioral consistency and human-like randomness

4. Automatic Verification: If the human score is high enough (≥80%), verification passes automatically

5. Fallback CAPTCHA: If automatic verification fails, a traditional text-based CAPTCHA is presented

6. Multiple Attempts: Users get up to 30 attempts to solve the text CAPTCHA

Customization

$3

The library automatically injects CSS styles when the component is used. This means:

- ✅ No CSS imports needed - Just import the component and it works
- ✅ No build configuration required - Styles are bundled with the JavaScript
- ✅ No style conflicts - Styles are scoped with sc- prefix
- ✅ SSR compatible - Only injects styles on the client side

If you need manual control over style injection:

`tsx
import { injectStyles } from 'simplify-captcha';

// Manually inject styles (optional - happens automatically)
injectStyles();
`

$3

The component uses CSS classes with the sc- prefix. You can override these styles:

`css
/ Override the overlay background /
.sc-overlay {
background-color: rgba(0, 0, 0, 0.8);
}

/ Customize the container /
.sc-container {
border-color: #your-color;
background-color: #your-background;
}

/ Style the submit button /
.sc-submit-button {
background-color: #your-primary-color;
}
`

$3

`tsx
ref={captchaRef}
onMessage={handleCaptchaResult}
className="my-custom-captcha"
style={{
borderColor: '#ff6b6b',
backgroundColor: '#2c3e50'
}}
/>
`

Development

`bash


Install dependencies

npm install

Start development server with demo

npm run dev

Build the library

npm run build

Build library only

npm run build:lib

Serve documentation locally

npm run serve:docs

Version management

npm run version:bump # Manual version bump with confirmation
npm run version:bump:auto # Automatic version bump
npm run install:hooks # Install pre-commit hooks for auto-versioning
npm run uninstall:hooks # Remove pre-commit hooks
`

🔧 Version Management

This project includes an intelligent automatic version bumping system:

$3

`bash


Install pre-commit hooks for automatic version bumping

npm run install:hooks

Now every commit will automatically bump the version based on your changes!

`

$3

`bash


Analyze changes and bump version with confirmation

npm run version:bump

Automatically bump version without confirmation

npm run version:bump:auto
`

$3

The system analyzes git changes and determines the appropriate semantic version bump:

- 🔴 MAJOR (X.0.0): Breaking changes, significant core library changes
- 🟡 MINOR (0.X.0): New features, components, API additions
- 🟢 PATCH (0.0.X): Bug fixes, documentation updates, small changes

$3

When pre-commit hooks are installed:

1. Every commit is analyzed for changes
2. Version is automatically bumped based on change significance
3. Updated package.json is included in your commit
4. No manual version management needed!

📖 Documentation Development

To work on the documentation:

1. Local Testing: Run npm run serve:docs or use the quick-start scripts:
- Linux/Mac: ./quick-start.sh
- Windows: quick-start.bat

2. GitHub Pages Setup: See GITHUB_PAGES_SETUP.md for detailed deployment instructions

3. Documentation Files:
- docs/index.html - Main documentation page
- docs/styles.css - Styling
- docs/script.js - Interactive demo functionality

Browser Support

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

License

MIT

Contributing

Contributions are welcome! Please follow these guidelines:

$3

When reporting bugs, please include:

- Clear description of the issue
- Steps to reproduce
- Expected vs actual behavior
- Browser/environment details
- Minimal code example

$3

For new features:

- Explain the use case and benefit
- Provide examples of how it would be used
- Consider backward compatibility

$3

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Install dependencies: npm install
4. Make your changes
5. Test locally: npm run dev and npm run serve:docs
6. Build to ensure no errors: npm run build
7. Commit with clear messages: git commit -m 'Add amazing feature'
8. Push to your branch: git push origin feature/amazing-feature
9. Create a Pull Request

$3

For documentation updates:

- Edit files in the docs/ directory
- Test locally with npm run serve:docs`
- Ensure responsive design works on mobile
- Update code examples if needed
- Check that interactive demo still functions

$3

- Test on multiple browsers (Chrome, Firefox, Safari, Edge)
- Verify both desktop and mobile experiences
- Ensure the behavior analysis works correctly
- Test the fallback text CAPTCHA functionality

$3

- Follow existing TypeScript patterns
- Use meaningful variable and function names
- Add JSDoc comments for public APIs
- Maintain backward compatibility when possible

Thank you for contributing to SimplifyCaptcha! 🎉