🛡️ JUMBLE
Advanced Bot Detection & Content Protection
[](https://npmjs.com/package/@4884org/jumble)
[](https://npmjs.com/package/@4884org/jumble)
[](https://opensource.org/licenses/MIT)
---
🛡️ **Advanced Bot Detection & Content Protection** 🤖
Automatically detects bots and scrapers using sophisticated heuristics, then scrambles text content and obfuscates media to protect your website while maintaining full accessibility for human users.
## 🔍 **SEO-Safe Protection** ✅
**Smart bot detection that protects your content from scrapers while allowing search engines to index your site properly:**
- ✅ **Google, Bing, Yahoo** → See real content for indexing
- ✅ **Facebook, Twitter, LinkedIn** → See real content for social previews
- ✅ **SEO tools** (SEMrush, Ahrefs) → See real content for analysis
- ❌ **Scrapers & headless browsers** → See scrambled content
- ❌ **AI training bots** → See scrambled content
- ❌ **Content harvesters** → See obfuscated media
**SEO protection is enabled by default** - no configuration needed!
## 📦 Installation
### NPM Installation
Install via npm for maximum flexibility and version control:
```bash
npm install @4884org/jumble
```
### CDN Installation
Quick setup via CDN for rapid prototyping:
```html
```
## 🚀 Universal Usage Pattern (Works with Any Framework)
**Add the loader script to ``, `` as the first element in ``, and the critical CSS/class to ``.**
```html
Protected Content
Your content will be protected automatically
This text will be scrambled for bots but readable for humans.
```
## 🛠️ Framework Integration
**This pattern works for React, Vue, Angular, Svelte, and static sites.**
- Do **not** use `` in any React/JSX/TSX/component file.
- Do **not** add custom element type declarations for React/TypeScript.
- Do **not** use `defineCustomElements()` in your app code unless you need advanced loader scenarios.
- Just add the loader script and `` to your main HTML file as above.
**Your app content works as usual. Jumble protects it automatically.**
## ⚙️ Component Attributes Reference
The `` component accepts the following attributes for customization:
| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| allow-seo | boolean | true | Allow search engine bots to see real content for SEO. |
| custom-allowlist | string[] | [] | Additional legitimate bot user agents to allow. |
| custom-denylist | string[] | [] | Additional suspicious bot patterns to block. |
## 📋 **Component Attributes Reference**
The `` component accepts the following attributes for customization:
| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `allow-seo` | `boolean` | `true` | Controls SEO protection mode. When `true`, legitimate search engines see real content. When `false`, ALL bots see scrambled content. |
| `custom-allowlist` | `string[]` | `[]` | JSON array of additional bot patterns to allow (added to default search engines). Case-insensitive matching. |
| `custom-denylist` | `string[]` | `[]` | JSON array of additional bot patterns to block (added to default malicious patterns). Case-insensitive matching. |
### **Basic Usage Examples**
```html
```
### **Attribute Details**
#### `allow-seo` (boolean)
- **Default:** `true` (SEO-safe mode)
- **When `true`:** Legitimate search engines (Google, Bing, Facebook, etc.) see real content for indexing and social previews
- **When `false`:** ALL bots see scrambled content (maximum protection but breaks SEO)
```html
```
#### `custom-allowlist` (string array)
- **Default:** `[]` (empty array)
- **Purpose:** Add specific bot patterns that should be allowed to see real content
- **Format:** JSON array of strings (case-insensitive partial matching)
- **Combined with:** Default legitimate search engines (Google, Bing, Facebook, etc.)
```html
```
#### `custom-denylist` (string array)
- **Default:** `[]` (empty array)
- **Purpose:** Add specific bot patterns that should be blocked and see scrambled content
- **Format:** JSON array of strings (case-insensitive partial matching)
- **Combined with:** Default malicious patterns (headless browsers, scrapers, AI training bots, etc.)
```html
```
### **Real-World Configuration Examples**
```html
```
## 📚 **Built-in Bot Detection**
### **Default Legitimate Bots (Always Allowed with `allow-seo="true"`)**
- **Search Engines:** Google, Bing, Yahoo, DuckDuckGo, Yandex, Baidu
- **Social Media:** Facebook, Twitter, LinkedIn, WhatsApp, Telegram, Discord
- **SEO Tools:** SEMrush, Ahrefs, Majestic, Moz, Screaming Frog
- **Monitoring:** UptimeRobot, Pingdom, GTmetrix
### **Default Malicious Patterns (Always Blocked)**
- **Automation Tools:** Selenium, Puppeteer, Playwright, PhantomJS
- **Generic Scrapers:** headless, scraper, crawler, harvester, extractor
- **AI Training Bots:** GPTBot, ClaudeBot, CCBot, meta-externalagent
- **And 20+ more malicious patterns...**
## 🌍 Multi-Language Support
Jumble intelligently handles different writing systems:
- **Latin Characters (a-z, A-Z):** Scrambled to random lowercase letters
- **Arabic Script (0x0600-0x06FF):** Scrambled to random Arabic characters
- **CJK Ideographs (0x4E00-0x9FFF):** Scrambled to random Chinese characters
- **Numbers (0-9):** Left unchanged for functionality
- **Punctuation & Symbols:** Preserved to maintain readability structure
- **Emojis:** Remain unchanged
## 🔧 Development
### Building
```bash
npm run build
```
### Testing
```bash
npm test
npm run test:e2e
npm run test:coverage
```
### Starting the dev server
```bash
npm start
```
## 📖 Additional Resources
- **[Live Demo](https://4884org.github.io/jumble/)** - Interactive demonstration
- **[NPM Package](https://www.npmjs.com/package/@4884org/jumble)** - Package details
- **[GitHub Repository](https://github.com/4884org/jumble)** - Source code
## 📄 License
MIT License - see LICENSE file for details.