Version 1.1 Documentation

🛡️ aCAPTCHA v1.1

A lightweight, no-backend CAPTCHA system designed for modern web applications. Supports visual challenges, audio verification, hybrid modes, and tracks client-side analytics—all while being self-contained and secure.

📋 Documentation Contents

🚀 Features Overview

Everything you need for modern CAPTCHA verification

✅
Visual CAPTCHA grid
🔊
Audio CAPTCHA (with fallback speech)
🎯
Hybrid mode (visual + audio)
🌙
Built-in Dark Mode
📈
Success rate, average time, and difficulty analytics
💾
LocalStorage settings (sound & dark mode)
🔐
Anti-inspection security (DevTools detection, obfuscation)
📦
No backend or API required

📁 Installation & Setup

Get started in under 2 minutes

1. Include the Script

📄 HTML Include
HTML 
<script src="captcha-v1.1.js" defer></script>

2. Use the Custom Component

🧩 Basic Usage
HTML 
<captcha-element></captcha-element>
✅
That's it! You now have a working CAPTCHA with all default features enabled.

🧠 Challenge Types

Choose the verification method that fits your needs

Type Description Usage Example
visual Standard image grid puzzle <captcha-element type="visual"></captcha-element>
audio 4-digit audio verification <captcha-element type="audio"></captcha-element>
both Hybrid; lets users switch modes <captcha-element type="both"></captcha-element>

🌗 Dark Mode

Enable dark mode for better user experience in low-light environments:

🌙 Dark Mode Example
HTML 
<captcha-element type="both" dark-mode="true"></captcha-element>
💡
Dark mode is also toggleable in the UI settings panel for user convenience.

🔊 Audio CAPTCHA – Self Hosting

Critical setup information for offline environments

⚠️
Critical Note: If you are running this offline or self-hosted, the sounds/ folder must be placed in the same directory as captcha-v1.1.js.

Required Audio Files Structure

📁 Directory Structure
TREE 
sounds/
├── 0.mp3
├── 1.mp3
├── 2.mp3
├── 3.mp3
├── 4.mp3
├── 5.mp3
├── 6.mp3
├── 7.mp3
├── 8.mp3
└── 9.mp3
🔄
Fallback Behavior: If audio files are missing or incorrect, the system will automatically fall back to speech synthesis (not recommended for critical use).

🔧 Customization via Attributes

Configure your CAPTCHA with simple HTML attributes

Attribute Description Accepted Values Default
type Challenge type visual, audio, both both
dark-mode Enable dark mode true, false false
sound-enabled Enable sound effects true, false true

✅ Full HTML Examples

Complete implementation examples for different use cases

🔹 Example 1: Visual Only

👁️ Visual CAPTCHA Only
HTML 
<captcha-element type="visual"></captcha-element>

🔹 Example 2: Audio Only

🔊 Audio CAPTCHA with Dark Mode
HTML 
<captcha-element type="audio" dark-mode="true"></captcha-element>

🔹 Example 3: Full Hybrid Setup with Form

🎯 Complete Form Integration
HTML 
<form id="my-form">
  <captcha-element id="captcha" type="both" dark-mode="true"></captcha-element>
  <br>
  <button type="submit">Submit</button>
</form>

<script>
  const captcha = document.getElementById('captcha');
  const form = document.getElementById('my-form');

  captcha.addEventListener('verified', (e) => {
    console.log("CAPTCHA passed!", e.detail);
    form.submit(); // or unlock protected actions
  });

  form.addEventListener('submit', (e) => {
    if (!captcha.isValid()) {
      e.preventDefault();
      alert("⚠️ Please complete the CAPTCHA first.");
    }
  });
</script>

📊 CAPTCHA Stats and Analytics

Built-in tracking for performance insights

Built-in tracking includes:

  • 📈 Total attempts
  • ✅ Success rate (percentage)
  • ⏱️ Average solving time (in seconds)
  • 🎯 Count by difficulty level

📤 Get Analytics Data

📊 Retrieve Analytics
JS 
const stats = document.querySelector('captcha-element').getAnalytics();
console.log(stats);

📋 Example Response

📋 Analytics Object
JSON 
{
  "totalAttempts": 5,
  "successRate": 80,
  "averageTime": 13,
  "difficultyCounts": {
    "easy": 2,
    "medium": 2,
    "hard": 1,
    "extreme": 0
  }
}

🧪 Programmatic Control

JavaScript API for advanced integration

➕ Get Status

🔍 Check CAPTCHA Status
JS 
captcha.getStatus(); // returns 'true' or 'null'
captcha.isValid();   // returns true if passed

🔁 Reset CAPTCHA

🔄 Reset Function
JS 
captcha.reset();

Event Triggered:

📡 Reset Event Listener
JS 
captcha.addEventListener('reset', () => {
  console.log("CAPTCHA reset by user");
});

🔐 Security & Anti-Bot Features

Built-in protection against automated attacks

aCAPTCHA includes the following security features:

  • 🔍 DevTools detection (via viewport delta)
  • 🔒 Obfuscated inner HTML and injected junk nodes
  • 🚫 Right-click + keybinding prevention
  • 🛡️ UI inspection protection
  • 📱 Scroll-lock and element focus override
  • 🌑 Shadow DOM encapsulation
💡
Client-Side Security: These defenses are fully client-side and do not require a backend. They provide reasonable protection against basic automated attacks while maintaining ease of use.

🧩 Feature Summary

Complete overview of all included features

Feature Included
Visual Grid Challenge✅
Audio Numbers (0-9) Challenge✅
Hybrid Switching✅
Dark Mode Toggle✅
Sound Effects (optional)✅
Stats Tracking (client-side)✅
Shadow DOM Encapsulation✅
DevTool Detection✅
Offline Support w/ Audio Files✅
Fully Custom HTML Component✅

💬 Have Feedback?

This CAPTCHA is designed to be lightweight and modular. If you need hooks, server-side integrations, or custom challenge logic—just reach out or fork it. we I am always looking to improve the user experience while maintaining security.