Skip to content

Latest commit

 

History

History
209 lines (179 loc) · 8.62 KB

File metadata and controls

209 lines (179 loc) · 8.62 KB

SusRadar Chrome Extension - Complete Implementation Guide

Overview

SusRadar is a Chrome extension that helps users identify suspicious websites and provides alternative recommendations. It automatically detects tracked sites and shows dropdown alerts with company information, sus ratings, and better alternatives.

🎯 Core Concept

  • Company-centric tracking: Multiple URLs can map to the same company data
  • Automatic detection: Dropdown appears automatically when visiting tracked sites
  • Manual popup: Access via extension icon for managing entries
  • Local storage first: Built for future server migration
  • Playful design: Goofy, colorful interface with gradients and animations

📋 Implemented Features

✅ Automatic Site Detection

  • Content script monitors all page loads
  • Checks current URL against stored mappings
  • Shows dropdown alert in top-right corner for tracked sites
  • Clean URL matching (removes www, handles domains properly)

✅ Manual Popup Interface

  • Click extension icon to open popup
  • Shows same dropdown interface as automatic detection
  • Add new sites to tracking
  • Manage existing entries

BUG: For pages that does not exist this menue is different, which it should be. But it looks broken. there is no clickable + sign and there are a bunch off random letters displayed at the top. BUG: the automatic pop up has nice bebled edges, while the manual has 90 degree edges. BUG: ⚙️ no visible either when the url was not found.

✅ Unified Dropdown Component

Both automatic and manual interfaces use the same SusRadarDropdown class:

  • Company name displayed prominently
  • Origin tracking shows if entry is SusRadar original, user-created, or modified
  • Sus rating bar (1-5 scale, green to red gradient)
  • Rating dial animation that bounces on the scale
  • Description (truncated to 120 chars in dropdown)
  • Alternative companies (up to 3 shown, with "more" hint)
  • Manage button (⚙️) to open full management interface

✅ Entry Origin System

Three types of entries with clear visual indicators:

  • 🚨 SusRadar Original: Default extension entries (Meta, X, TikTok)
  • ✏️ Modified SusRadar: Original entries that user has edited
  • 👤 User Created: Completely new entries added by user

✅ Full Management Interface (all-entries.html)

  • Grid layout showing all tracked companies
  • Search functionality across names, descriptions, and URLs TODO: Weird formatting, i would suspect the text marker to be to the right of the amplifying glass
  • Edit modal with field-level origin tracking
  • Individual field reset buttons for modified entries
  • Reset all functionality for modified SusRadar entries
  • Delete entries with confirmation
  • Focus highlighting when opened via manage button BUG: This has worked before but does not seem to work now.

✅ Advanced Edit Modal

Professional in-page modal with:

  • Proper form fields: Company name, rating slider, description, alternatives
  • Field-level tracking: Each field shows its origin (SusRadar/User/Modified)
  • Granular reset: Individual 🔄 buttons to reset specific fields
  • Modal scrolling: Header/footer fixed, form content scrolls
  • Large text areas: Proper sizing for description and alternatives
  • Working slider: Full-width rating bar with real-time display
  • Success notifications: Beautiful temporary feedback messages

BUG: When a field is changed for an existing entry, all the filds show the ✏️ and 🔄 symbol TODO: Cancle has a weird color. TODO: After pressing "Reset all to defaul" I would expect the ✏️ and 🔄 symbols to dissapear. I only want to show these if the field is different from the default. TODO: scroll does not work as I want. The textboxes has their own scroll. I want the textboxes to increase in size instead, and for the window itself to be scrollable when long text is entered.

✅ Data Architecture

Clean separation ready for future server migration:

// Storage Provider Interface
class SiteInfoProvider {
  async getSiteInfo(url)
  async addSiteInfo(url, companyId, info)
  async updateSiteInfo(companyId, info)
  async deleteSiteInfo(companyId)
  async getAllSites()
}

// URL Matching Interface  
class URLMatcher {
  findMatch(currentUrl, urlMappings)
}

// Company Data Model
class CompanyData {
  company_name: string
  sus_rating: number (1-5)
  description: string
  alternative_links: array[string]
  date_added: string
  user_added: boolean
  origin: 'susradar' | 'user'
  is_modified: boolean
  original_data: object | null
}

✅ Storage Structure

{
  url_mappings: {
    "facebook.com": "meta_corp",
    "www.facebook.com": "meta_corp",
    "instagram.com": "meta_corp",
    // ... more URLs mapping to company IDs
  },
  company_data: {
    "meta_corp": {
      company_name: "Meta (Facebook)",
      sus_rating: 4,
      description: "🕵️ Known for aggressive data collection...",
      alternative_links: ["https://signal.org", "https://mastodon.social"],
      origin: "susradar",
      is_modified: false,
      original_data: null
    }
  }
}

✅ Pre-loaded Data

Ships with information for major suspicious companies:

  • Meta (Facebook): Rating 4/5 - Data collection and privacy concerns
  • X (formerly Twitter): Rating 4/5 - Content moderation and bot issues
  • ByteDance (TikTok): Rating 5/5 - Chinese data collection concerns

Each includes multiple URL mappings and alternative recommendations.

✅ User Experience Features

  • Responsive design: Works on desktop and mobile
  • Smooth animations: Fade-in dropdown, bouncing rating dial
  • Error handling: Graceful fallbacks for extension reloads
  • Keyboard shortcuts: ESC to close modals
  • Click outside: Close dropdowns and modals
  • Focus management: Auto-focus on form fields
  • Button styling: Enhanced visibility with shadows and hover effects

✅ Technical Implementation

  • Manifest V3: Modern Chrome extension format
  • Content Security Policy: Proper external script handling
  • Event-driven: Proper event listeners (no inline onclick)
  • Error boundaries: Chrome storage API error handling
  • Clean CSS: Gradient backgrounds, proper flexbox layouts
  • Modular code: Easy to extend and modify

🏗️ Architecture Highlights

Future-Ready Design

  • Provider pattern: Easy to swap LocalStorageProvider for ServerProvider
  • URL matcher abstraction: Can upgrade from exact matching to domain/pattern matching
  • Component-based: Unified dropdown component used everywhere
  • Data model: Rich company data structure with extensible fields

File Structure

SusRadar/
├── manifest.json          # Extension configuration
├── background.js          # Service worker
├── content.js             # Main content script with dropdown logic
├── content.css            # Dropdown and form styling
├── popup.html             # Popup container
├── popup.js               # Popup implementation (same as content.js)
├── popup.css              # Enhanced button styling
├── all-entries.html       # Management interface
├── all-entries.js         # Management functionality
└── Instructions.md        # This file

🎨 Design Philosophy

  • Playful branding: "SusRadar" with radar emoji (🚨)
  • Gradient backgrounds: Purple-blue gradients throughout
  • Color-coded ratings: Green (safe) to red (sus) with yellow highlights
  • Smooth animations: Bouncing dials, fade transitions, hover effects
  • Clear iconography: ⚙️ for manage, 🔄 for reset, 🗑️ for delete
  • Intuitive labels: "Sus AF" instead of just numbers

✅ Working Features Summary

  1. Automatic site detection with dropdown alerts
  2. Manual popup interface via extension icon
  3. Company data management with full CRUD operations
  4. Entry origin tracking (SusRadar/User/Modified)
  5. Field-level editing with granular reset capabilities
  6. Search and filtering in management interface
  7. Professional edit modal with proper form handling
  8. Alternative companies display in dropdown
  9. Responsive design for all screen sizes
  10. Error handling and graceful degradation

📝 Notes for Future Development

  • Architecture supports easy server migration
  • URL matching can be enhanced to domain/pattern matching
  • Data model is extensible for additional fields
  • Component system allows easy UI updates
  • All user interactions are tracked for modification history

🔧 TODO Section

Add future feature requests and improvements here

🐛 BUG Section

Report any issues or bugs discovered during testing here