# Greasemonkey Browser Extension

**Author:** Andy Dixon  
**Version:** 1.0.0

A powerful browser extension that allows you to execute custom JavaScript and CSS on web pages based on flexible matching conditions.

## Features

- 🎯 **Flexible Matching**: Execute scripts when:
  - A URL contains a specific string
  - A page contains a specific element (CSS selector)
  - Both conditions are met simultaneously

- 🎨 **Bootstrap Dark UI**: Intuitive configuration interface with Bootstrap 5 dark theme
- 💾 **Persistent Storage**: All rules are saved and synced across your browser sessions
- ⚡ **Multiple Rules**: Add, edit, and manage unlimited custom rules
- 🔄 **Toggle Controls**: Easily enable/disable individual rules
- 📝 **JavaScript & CSS**: Support for both JavaScript execution and CSS injection
- 🔍 **Visual Indicators**: Clear badges showing rule type (URL/Element/Both) and code types (JS/CSS)

## Installation

### Chrome Installation

1. Navigate to the `chrome` directory
2. Open Chrome and go to `chrome://extensions/`
3. Enable "Developer mode" (toggle in top-right corner)
4. Click "Load unpacked"
5. Select the `chrome` directory
6. The Greasemonkey extension is now installed!

### Firefox Installation

1. Navigate to the `firefox` directory
2. Open Firefox and go to `about:debugging#/runtime/this-firefox`
3. Click "Load Temporary Add-on"
4. Select the `manifest.json` file from the `firefox` directory
5. The Greasemonkey extension is now installed!

**Note:** For permanent Firefox installation, you'll need to sign the extension through [addons.mozilla.org](https://addons.mozilla.org).

## Usage

### Creating a Rule

1. Click the Greasemonkey icon in your browser toolbar
2. Click the "+ Add Rule" button
3. Fill in the rule details:
   - **Rule Name**: A descriptive name for your rule
   - **Match Type**: Choose how the rule should be triggered
     - *URL contains string*: Matches if URL contains the pattern
     - *Page contains element*: Matches if element selector exists
     - *Both URL and element*: Requires both conditions
   - **URL Pattern**: The string to match in the URL (e.g., `github.com`, `/search?`)
   - **Element Selector**: CSS selector to match (e.g., `#my-element`, `.my-class`, `div[data-id="123"]`)
   - **JavaScript Code**: Custom JavaScript to execute
   - **CSS Code**: Custom CSS to inject
   - **Enabled**: Toggle to enable/disable the rule
4. Click "Save Rule"

### Editing a Rule

1. Open the Greasemonkey popup
2. Click the edit button (pencil icon) on any rule card
3. Modify the rule details
4. Click "Save Rule"

### Deleting a Rule

1. Open the Greasemonkey popup
2. Click the delete button (trash icon) on any rule card
3. Confirm the deletion

### Toggling a Rule

Use the toggle switch on each rule card to quickly enable or disable rules without editing them.

## Examples

### Example 1: Hide Ads on Specific Sites

**Match Type:** URL contains string  
**URL Pattern:** `example.com`  
**CSS Code:**
```css
.advertisement,
.ad-banner,
#sidebar-ads {
  display: none !important;
}
```

### Example 2: Auto-fill Forms

**Match Type:** Both URL and element  
**URL Pattern:** `form-site.com`  
**Element Selector:** `#login-form`  
**JavaScript Code:**
```javascript
document.getElementById('username').value = 'myusername';
console.log('Auto-filled username field');
```

### Example 3: Dark Mode Override

**Match Type:** URL contains string  
**URL Pattern:** `news-site.com`  
**CSS Code:**
```css
body {
  background-color: #1a1a1a !important;
  color: #e0e0e0 !important;
}

a {
  color: #4a9eff !important;
}
```

### Example 4: Add Custom Features

**Match Type:** Element exists  
**Element Selector:** `.video-player`  
**JavaScript Code:**
```javascript
console.log('Video player detected!');

// Add a custom button
const button = document.createElement('button');
button.textContent = 'Custom Action';
button.style.cssText = 'position:fixed;top:10px;right:10px;z-index:9999;';
button.onclick = () => alert('Custom button clicked!');
document.body.appendChild(button);
```

### Example 5: Conditional Styling

**Match Type:** Both URL and element  
**URL Pattern:** `dashboard`  
**Element Selector:** `.data-table`  
**CSS Code:**
```css
.data-table {
  border: 2px solid #4CAF50;
  border-radius: 8px;
  box-shadow: 0 4px 6px rgba(0,0,0,0.1);
}

.data-table th {
  background-color: #4CAF50;
  color: white;
}
```

## Technical Details

### File Structure

```
greasemonkey/
├── chrome/                 # Chrome extension files
│   ├── manifest.json      # Chrome extension manifest (v3)
│   ├── background.js      # Background service worker
│   ├── content.js         # Content script (runs on pages)
│   ├── popup.html         # Extension popup UI
│   ├── popup.css          # Popup styling
│   ├── popup.js           # Popup functionality
│   └── icon*.png          # Extension icons
├── firefox/               # Firefox extension files
│   ├── manifest.json      # Firefox extension manifest (v2)
│   ├── background.js      # Background script
│   ├── content.js         # Content script (runs on pages)
│   ├── popup.html         # Extension popup UI
│   ├── popup.css          # Popup styling
│   ├── popup.js           # Popup functionality
│   └── icon*.png          # Extension icons
└── README.md              # This file
```

### How It Works

1. **Content Script**: Runs on every page load (`document_idle`)
2. **Rule Matching**: Checks all enabled rules against current page
3. **Condition Evaluation**: Tests URL patterns and element selectors
4. **Code Execution**: 
   - JavaScript is injected as a script element
   - CSS is injected as a style element
5. **Storage**: Rules are stored in browser's sync storage

### Storage Format

Rules are stored as JSON in browser sync storage:

```javascript
{
  "rules": [
    {
      "name": "Example Rule",
      "matchType": "url",
      "urlPattern": "example.com",
      "elementSelector": "",
      "javascript": "console.log('Hello');",
      "css": "body { background: red; }",
      "enabled": true
    }
  ]
}
```

### Browser Compatibility

- **Chrome**: Requires Chrome 88+ (Manifest V3)
- **Firefox**: Requires Firefox 48+ (Manifest V2)
- **Edge**: Should work (Chromium-based, same as Chrome)
- **Opera**: Should work (Chromium-based, same as Chrome)

## Building for Distribution

### Chrome

1. Ensure all files are in the `chrome` directory
2. Go to `chrome://extensions/`
3. Click "Pack extension"
4. Select the `chrome` directory
5. This creates a `.crx` file for distribution

### Firefox

1. Install `web-ext` tool: `npm install -g web-ext`
2. Navigate to the `firefox` directory
3. Run: `web-ext build`
4. This creates a `.zip` file in `web-ext-artifacts/`
5. Submit to [addons.mozilla.org](https://addons.mozilla.org) for signing

## Security Considerations

- **User Responsibility**: Be cautious with JavaScript code execution
- **HTTPS**: Script injection works on both HTTP and HTTPS sites
- **CSP**: Some sites with strict Content Security Policy may block injected scripts
- **Permissions**: Extension requires broad permissions (`<all_urls>`) to work on all sites

## Troubleshooting

### Rules Not Executing

1. **Check the browser console** for error messages (F12)
2. **Verify the rule is enabled** (toggle switch)
3. **Test the URL pattern** - ensure it matches the current page
4. **Test the element selector** - open console and run `document.querySelector('your-selector')`
5. **Reload the page** after creating/editing rules

### CSS Not Applying

- Use `!important` flag to override existing styles
- Check for syntax errors in CSS
- Verify the rule conditions are met

### JavaScript Not Running

- Check browser console for errors
- Ensure JavaScript syntax is correct
- Some sites may have strict Content Security Policies

### Storage Not Syncing

- Ensure browser sync is enabled
- Check available storage quota
- For Firefox temporary add-ons, sync storage may not persist

## Development

### Local Development

1. Make changes to files in `chrome/` or `firefox/` directories
2. Reload the extension:
   - **Chrome**: Go to `chrome://extensions/` and click reload icon
   - **Firefox**: Go to `about:debugging` and click reload
3. Test your changes

### Debugging

- **Background Script**: Check browser console in extension management page
- **Content Script**: Check page console (F12)
- **Popup**: Right-click popup and select "Inspect"

## Privacy

- No data is sent to external servers
- All rules are stored locally in browser storage
- No analytics or tracking
- No network requests made by the extension

## License

This extension is provided as-is for personal and educational use.

## Support

For issues, questions, or feature requests, please contact Andy Dixon.

## Version History

### 1.0.0 (Initial Release)
- URL pattern matching
- Element selector matching
- Combined URL + Element matching
- JavaScript execution
- CSS injection
- Bootstrap dark theme UI
- Add/Edit/Delete rules
- Enable/Disable toggle
- Persistent storage
- Chrome and Firefox support