|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +This file provides guidance to Codex (Codex.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +Useful Scripts is a Chrome extension that provides a collection of utility scripts for various websites and tasks. It includes scripts for Facebook, Instagram, YouTube, TikTok, Google Drive, and many other platforms. The extension allows users to run scripts on-demand or automatically based on URL patterns. |
| 8 | + |
| 9 | +## Architecture |
| 10 | + |
| 11 | +### Script Execution Contexts |
| 12 | + |
| 13 | +The extension uses **four distinct execution contexts** for scripts, each with different capabilities and restrictions: |
| 14 | + |
| 15 | +1. **popupScript**: Runs in extension popup context |
| 16 | + - Can use Chrome Extension APIs |
| 17 | + - Can inject scripts into active tab via `chrome.scripting.executeScript` |
| 18 | + - Cannot access page DOM directly |
| 19 | + - Used for user-triggered actions from the popup |
| 20 | + |
| 21 | +2. **contentScript**: Runs in ISOLATED/SANDBOX world |
| 22 | + - Can use limited Chrome Extension APIs |
| 23 | + - Can access/modify DOM |
| 24 | + - **Cannot** access page JavaScript variables (different world) |
| 25 | + - Can communicate with background script via `chrome.runtime.sendMessage` |
| 26 | + |
| 27 | +3. **pageScript**: Runs in webpage's MAIN world |
| 28 | + - **Cannot** use Chrome Extension APIs |
| 29 | + - Can access/modify DOM and page JavaScript variables |
| 30 | + - Can override default page behaviors |
| 31 | + - Communicates with contentScript via `window.postMessage` |
| 32 | + |
| 33 | +4. **backgroundScript**: Runs as service worker |
| 34 | + - Can use full Chrome Extension APIs |
| 35 | + - **Cannot** use dynamic imports (use GLOBAL variables instead) |
| 36 | + - Handles events like `onBeforeRequest`, `tabs.onUpdated`, etc. |
| 37 | + - Context is the GLOBAL variable in `background_script.js` |
| 38 | + |
| 39 | +### Communication Between Contexts |
| 40 | + |
| 41 | +- **popupScript ↔ backgroundScript**: `chrome.runtime.sendMessage` |
| 42 | +- **contentScript ↔ backgroundScript**: `chrome.runtime.sendMessage` |
| 43 | +- **pageScript ↔ contentScript**: `window.postMessage` |
| 44 | +- **pageScript → backgroundScript**: `UfsGlobal.Extension.runInBackground` |
| 45 | + |
| 46 | +### Directory Structure |
| 47 | + |
| 48 | +- **`scripts/`**: All script functionality files |
| 49 | + - **`@index.js`**: Exports all scripts (required for new scripts) |
| 50 | + - **`@allScripts.js`**: Generated list of all scripts |
| 51 | + - **`background-scripts/background_script.js`**: Service worker entry point |
| 52 | + - **`content-scripts/`**: Content script infrastructure |
| 53 | + - **`helpers/`**: Shared utility functions |
| 54 | + - Individual script files (e.g., `fb_toggleLight.js`, `youtube_downloadVideo.js`) |
| 55 | + |
| 56 | +- **`popup/`**: Extension popup UI |
| 57 | + - **`tabs.js`**: Defines script categories and organization (required for new scripts) |
| 58 | + - **`helpers/`**: UI helper modules (category, lang, modal, storage, theme, utils) |
| 59 | + - **`index.js`**: Main popup logic |
| 60 | + - **`main.js`**: Entry point |
| 61 | + |
| 62 | +- **`pages/`**: Supporting pages (view script source, settings) |
| 63 | + |
| 64 | +- **`templates/`**: Script templates |
| 65 | + - **`simple.js`**: Minimal script template |
| 66 | + - **`full.js`**: Complete template with all available options and documentation |
| 67 | + |
| 68 | +## Adding a New Script |
| 69 | + |
| 70 | +1. **Create script file** in `scripts/` directory with descriptive name (e.g., `platform_feature.js`) |
| 71 | + |
| 72 | +2. **Use template**: Copy from `templates/simple.js` or `templates/full.js` |
| 73 | + |
| 74 | +3. **Script structure** (minimal): |
| 75 | +```javascript |
| 76 | +export default { |
| 77 | + icon: '<i class="fa-solid fa-icon"></i>', |
| 78 | + name: { |
| 79 | + en: "English name", |
| 80 | + vi: "Vietnamese name", |
| 81 | + }, |
| 82 | + description: { |
| 83 | + en: "English description", |
| 84 | + vi: "Vietnamese description", |
| 85 | + }, |
| 86 | + |
| 87 | + // URL filtering |
| 88 | + whiteList: ["https://*.example.com/*"], // Only run on these URLs |
| 89 | + blackList: [], // Don't run on these URLs |
| 90 | + |
| 91 | + // Choose one or more contexts |
| 92 | + popupScript: { |
| 93 | + onClick: () => { /* code */ }, |
| 94 | + }, |
| 95 | + |
| 96 | + contentScript: { |
| 97 | + onClick: () => { /* code */ }, |
| 98 | + onDocumentIdle: () => { /* code */ }, |
| 99 | + }, |
| 100 | + |
| 101 | + pageScript: { |
| 102 | + onClick: () => { /* code */ }, |
| 103 | + onDocumentIdle: () => { /* code */ }, |
| 104 | + }, |
| 105 | +}; |
| 106 | +``` |
| 107 | + |
| 108 | +4. **Import in `scripts/@index.js`**: |
| 109 | +```javascript |
| 110 | +export { default as scriptName } from "./scriptName.js"; |
| 111 | +``` |
| 112 | + |
| 113 | +5. **Regenerate metadata** (IMPORTANT): |
| 114 | +```bash |
| 115 | +npm run build:metadata |
| 116 | +``` |
| 117 | +This updates `scripts/@metadata.js` for fast popup loading (see Performance section below). |
| 118 | + |
| 119 | +6. **Add to category in `popup/tabs.js`**: |
| 120 | +```javascript |
| 121 | +const tabs = [ |
| 122 | + { |
| 123 | + ...CATEGORY.categoryName, |
| 124 | + scripts: [ |
| 125 | + s.scriptName, // Add your script here |
| 126 | + ], |
| 127 | + }, |
| 128 | +]; |
| 129 | +``` |
| 130 | + |
| 131 | +6. **Test** by opening the extension popup and running the script |
| 132 | + |
| 133 | +## Script Lifecycle Events |
| 134 | + |
| 135 | +- **onDocumentStart**: Runs as early as possible (before DOM is fully loaded) |
| 136 | +- **onDocumentIdle**: Runs when DOM is ready (recommended for most scripts) |
| 137 | +- **onDocumentEnd**: Runs when page is fully loaded |
| 138 | +- **onClick**: Runs when user clicks the script in popup |
| 139 | + |
| 140 | +To run in all frames (including iframes), append `_` to function name: `onDocumentIdle_()`, `onClick_()`, etc. |
| 141 | + |
| 142 | +## Common Patterns |
| 143 | + |
| 144 | +### Using UfsGlobal |
| 145 | + |
| 146 | +UfsGlobal provides shared utilities across contexts: |
| 147 | + |
| 148 | +```javascript |
| 149 | +import { UfsGlobal } from "./content-scripts/ufs_global.js"; |
| 150 | + |
| 151 | +// Wait for elements |
| 152 | +UfsGlobal.DOM.onElementsAdded('selector', (element) => { |
| 153 | + // Do something with element |
| 154 | +}); |
| 155 | + |
| 156 | +// Run in background context |
| 157 | +UfsGlobal.Extension.runInBackground({ |
| 158 | + fnPath: "functionName", |
| 159 | + params: [arg1, arg2] |
| 160 | +}); |
| 161 | +``` |
| 162 | + |
| 163 | +### Download Files |
| 164 | + |
| 165 | +Use Chrome's download API in popupScript or backgroundScript: |
| 166 | + |
| 167 | +```javascript |
| 168 | +chrome.downloads.download({ |
| 169 | + url: fileUrl, |
| 170 | + filename: "myfile.ext" |
| 171 | +}); |
| 172 | +``` |
| 173 | + |
| 174 | +### Inject Code into Page |
| 175 | + |
| 176 | +From popupScript, use utilities: |
| 177 | + |
| 178 | +```javascript |
| 179 | +await utils.runScriptInCurrentTab(() => { |
| 180 | + // This code runs in page context |
| 181 | + console.log(window.location.href); |
| 182 | +}); |
| 183 | +``` |
| 184 | + |
| 185 | +## Important Notes |
| 186 | + |
| 187 | +- **No package.json**: This is a vanilla JavaScript Chrome extension without build tools |
| 188 | +- **ES6 modules**: Use `import`/`export` for code organization |
| 189 | +- **Icon library**: Uses Font Awesome for script icons |
| 190 | +- **Localization**: Support both English (`en`) and Vietnamese (`vi`) |
| 191 | +- **Trusted Types**: Scripts that inject HTML must comply with Chrome's Trusted Types policy |
| 192 | +- **Linux compatibility**: Use relative paths and proper casing for file names |
| 193 | +- **Auto-run capability**: Scripts with `onDocumentStart`/`Idle`/`End` can be enabled for automatic execution |
| 194 | + |
| 195 | +## Development Workflow |
| 196 | + |
| 197 | +1. Load extension in Chrome via `chrome://extensions/` (Developer mode → Load unpacked) |
| 198 | +2. Make changes to script files |
| 199 | +3. Click refresh icon in `chrome://extensions/` to reload extension |
| 200 | +4. Test changes in target websites |
| 201 | +5. Check console for errors in both page context and extension context (inspect popup) |
| 202 | + |
| 203 | +## Common Script Categories |
| 204 | + |
| 205 | +- **CATEGORY.facebook**: Facebook-related utilities (download, reveal messages, toggle UI) |
| 206 | +- **CATEGORY.youtube**: YouTube tools (download, captions, PiP) |
| 207 | +- **CATEGORY.download**: General download utilities |
| 208 | +- **CATEGORY.automation**: Automation and productivity scripts |
| 209 | +- **CATEGORY.unlock**: Bypass paywalls and restrictions |
| 210 | +- **CATEGORY.webUI**: UI manipulation scripts |
| 211 | + |
| 212 | +## Testing |
| 213 | + |
| 214 | +- No automated test suite currently |
| 215 | +- Manual testing workflow: |
| 216 | + 1. Install extension locally |
| 217 | + 2. Navigate to target website |
| 218 | + 3. Open extension popup and run script |
| 219 | + 4. Verify expected behavior |
| 220 | + 5. Check browser console for errors |
| 221 | + |
| 222 | +## Performance Optimization |
| 223 | + |
| 224 | +### Lazy Loading Architecture |
| 225 | + |
| 226 | +The extension uses a lazy loading strategy to achieve 10-20x faster popup load times: |
| 227 | + |
| 228 | +**How it works:** |
| 229 | +1. **Popup loads** → Only `scripts/@metadata.js` is imported (lightweight metadata) |
| 230 | +2. **User clicks script** → Full script dynamically imported on-demand |
| 231 | +3. **Script cached** → Subsequent clicks use cached version (instant) |
| 232 | +4. **Popular scripts preloaded** → Common scripts loaded in background |
| 233 | + |
| 234 | +**Files involved:** |
| 235 | +- `scripts/@metadata.js` - Auto-generated metadata registry (lightweight) |
| 236 | +- `scripts/@index.js` - Full scripts (used by background, not popup) |
| 237 | +- `scripts/build/extractMetadata.js` - Metadata extraction tool |
| 238 | +- `popup/tabs.js` - Imports metadata instead of full scripts |
| 239 | +- `popup/index.js` - Implements lazy loading logic |
| 240 | + |
| 241 | +**Regenerating metadata:** |
| 242 | +```bash |
| 243 | +npm run build:metadata |
| 244 | +``` |
| 245 | +Run this after adding/modifying scripts to update the metadata registry. |
| 246 | + |
| 247 | +**Performance gains:** |
| 248 | +- Popup load: 500-1000ms → 50-100ms (10-20x faster) |
| 249 | +- Memory usage: ~20MB → ~2MB (90% reduction) |
| 250 | +- First click: ~10-50ms delay (dynamic import) |
| 251 | +- Cached click: ~0ms (instant) |
| 252 | + |
| 253 | +See `OPTIMIZATION_DONE.md` for full details. |
| 254 | + |
| 255 | +## External Resources |
| 256 | + |
| 257 | +- Demo site: https://useful-scripts-extension.github.io/useful-script/popup/popup.html |
| 258 | +- Facebook Group: https://www.facebook.com/groups/fbaio2 |
| 259 | +- Developer tutorials: YouTube playlist in README |
0 commit comments