didi-lot3-frontend/extension/README.md

# DIDI Content Extractor - Browser Extension

Professional browser extension for extracting structured content from social media posts.

## 🎯 Features

### Platform-Specific Extraction
- **Facebook**: Clean extraction with intelligent text filtering and primary image detection
- **Twitter/X**: Tweet-specific extraction with proper content identification
- **LinkedIn**: Coming soon
- **Custom Websites**: Future OCR-based extraction

### Smart Content Detection
- **Post Container Detection**: Walks DOM tree to find exact post boundaries
- **Author Extraction**: Multiple selector patterns for reliable author identification
- **Text Filtering**: Removes UI noise (Like, Comment, Share buttons, etc.)
- **Primary Image**: Extracts main image only (200x200px minimum, excludes icons/emojis/profile pics)
- **Metadata**: Timestamp and post URL extraction

### Content Types
- `text` - Text only posts
- `image` - Image only posts
- `text+image` - Combined content posts
- `text+video` - Coming soon
- `video` - Coming soon

## 📦 Installation

1. Open Chrome/Edge and navigate to `chrome://extensions`
2. Enable **Developer mode** (top right toggle)
3. Click **Load unpacked**
4. Select the `browser-extension` folder
5. Extension installed!

## 🚀 Usage

### Facebook Extraction
1. Navigate to Facebook
2. Click extension icon
3. Click **"Activate Selection Mode"** under Facebook tab
4. Hover over any post (entire post highlighted with blue border)
5. Click to extract content
6. View extracted content in popup
7. Click **"💾 Save"** to store for later

### Twitter/X Extraction
1. Navigate to Twitter/X
2. Click extension icon
3. Click **"Activate Selection Mode"** under X/Twitter tab
4. Hover over any tweet (entire tweet highlighted)
5. Click to extract content
6. View and save as above

### Saved Extractions
- Switch to **"Saved"** tab to view all saved content
- **"👁️ View"** - View full details
- **"📋 Copy"** - Copy JSON to clipboard
- **"🗑️ Delete"** - Delete individual item
- **"Clear All"** - Remove all saved extractions

## 📊 Data Structure

```javascript
{
  platform: 'facebook' | 'twitter',
  type: 'text' | 'image' | 'text+image',
  author: 'Author Name',
  text: 'Post content...',
  image: {
    url: 'https://...',
    width: 1200,
    height: 800,
    alt: 'Description'
  },
  timestamp: '2024-01-15T10:30:00',
  postUrl: 'https://facebook.com/...',
  extractedAt: '2024-01-15T10:35:00.000Z'
}
```

## 🏗️ Architecture

### Platform Extractors

#### FacebookExtractor
- **Post Detection**: `[role="article"]` containers
- **Author**: `h2 a[role="link"]`, `h3 a[role="link"]`
- **Text**: `div[dir="auto"][style*="text-align"]` with UI noise filtering
- **Image**: Primary image detection (excludes icons/emoji/profiles)
- **Metadata**: Timestamp from `a[aria-label*="ago"]`, URL from permalinks

#### TwitterExtractor
- **Tweet Detection**: `article[data-testid="tweet"]` containers
- **Author**: `[data-testid="User-Name"] span`
- **Text**: `[data-testid="tweetText"]`
- **Image**: `[data-testid="tweetPhoto"] img`
- **Metadata**: Timestamp from `<time>` element

### Extractor Interface
All extractors follow this interface:
```javascript
class PlatformExtractor {
  findPostContainer(element)     // Locate post container
  extractAuthor(container)        // Get author name
  extractText(container)          // Get clean text
  extractPrimaryImage(container)  // Get main image
  extractTimestamp(container)     // Get post time
  extractPostUrl(container)       // Get permalink
  extract(element)                // Main extraction method
}
```

## 📁 File Structure

```
browser-extension/
├── manifest.json          # Extension configuration
├── popup.html            # Extension popup UI
├── popup.css             # DIDI-themed styling
├── popup.js              # Popup logic and state management
├── content.js            # Content script with extractors
├── content.css           # Selection box and notification styles
├── background.js         # Background service worker
├── extractors/           # Platform-specific extractors (standalone files)
│   ├── facebook.js
│   └── twitter.js
└── README.md             # This file
```

## 🎨 Design System

Uses DIDI's design system:
- **Colors**:
  - Trust Blue: `#0052CC`
  - Honest Teal: `#00BFCC`
  - Caution Red: `#E63946`
  - Background: `#0A0E27`
- **Font**: Plus Jakarta Sans (with fallbacks)
- **Effects**: Gradient transitions, smooth animations

## 🔒 Permissions

- `activeTab` - Access current tab content
- `storage` - Local storage for saved extractions
- `clipboardWrite` - Copy to clipboard functionality
- Host permissions for supported platforms

## 🐛 Troubleshooting

### Extension won't load
- Check if all files are present
- Verify manifest.json is valid JSON
- Try removing and re-adding the extension

### No extraction happening
- Refresh the page after installing extension
- Check browser console (F12) for errors
- Verify you're on a supported platform

### Selection box not appearing
- Click "Activate Selection Mode" again
- Hover directly over post content
- Check if posts are using expected DOM structure

## 🚀 Future Enhancements

- [ ] LinkedIn extraction
- [ ] Custom website extraction with OCR
- [ ] Video content extraction
- [ ] Export to various formats (CSV, JSON, Markdown)
- [ ] Cloud sync with main DIDI app
- [ ] Keycloak authentication integration
- [ ] Batch extraction mode
- [ ] Advanced filtering options

## 📝 Development Notes

- Extension uses Manifest V3 (latest Chrome standard)
- Platform extractors embedded in `content.js` (Chrome doesn't support ES modules in content scripts)
- Standalone extractor files in `extractors/` folder for code organization
- All extraction logic uses defensive programming (checks for null/undefined)
- Extensive console logging with prefixes: `[FB]`, `[Twitter]`, `[DIDI]`

## 🔗 Integration with DIDI App

Future integration will allow:
- Direct content send to Analysis tab
- Authentication via Keycloak
- Saved extractions sync across devices
- Export to DIDI's content database