Add comprehensive GitHub Copilot instructions

Co-authored-by: PeterDaveHello <3691490+PeterDaveHello@users.noreply.github.com>
Co-authored-by: qodo-merge-pro[bot] <151058649+qodo-merge-pro[bot]@users.noreply.github.com>

Author: 3 people

.github/copilot-instructions.md

@@ -0,0 +1,202 @@
+# ChatGPTBox - Browser Extension
+
+ChatGPTBox is a cross-platform browser extension that deeply integrates ChatGPT and other AI models into web browsing. The extension provides chat dialogs, selection tools, site-specific adapters, and AI-powered features across the web.
+
+Always reference these instructions first and fall back to search or bash commands only when you encounter unexpected information that does not match the info here.
+
+## Working Effectively
+
+### Bootstrap and Build
+
+- Install dependencies: `npm ci` -- takes ~30 seconds. npm audit warnings may appear; for development-only dependencies they generally do not affect the shipped extension. Review and address runtime-impacting advisories separately.
+- Development build: `npm run dev` -- takes ~13 seconds initial build, runs webpack in watch mode. Do not kill mid-compilation, but stop gracefully when switching branches or after dependency/config changes, then restart to avoid stale watchers and inconsistent state.
+- Production build: `npm run build` -- takes ~33 seconds. If it exceeds 10 minutes, treat as hung: confirm Node 20+, clear caches (`rm -rf node_modules && npm ci`), clear build caches (e.g., `rm -rf node_modules/.cache build/ dist/`), and rerun. Avoid force-killing mid-bundle; stop, fix, then rebuild.
+- Format code: `npm run pretty` -- uses Prettier to format all JS/JSX/CSS files. Run this before linting.
+- Lint code: `npm run lint` -- takes ~3-5 seconds, uses ESLint.
+- Safari build: `npm run build:safari` -- only works on macOS with Xcode installed.
+
+### Build Output Structure
+
+Production build creates multiple variants in `build/` directory:
+
+- `chromium/` - Chromium-based browsers (Chrome, Edge) with full features
+- `firefox/` - Firefox with manifest v2
+- `chromium-without-KaTeX-and-tiktoken/` - Minimal build without math rendering and token encoding
+- `firefox-without-KaTeX-and-tiktoken/` - Minimal Firefox build without math rendering and token encoding
+- Distribution artifacts: `.zip` for Chromium variants and `.xpi` for Firefox.
+
+## Architecture Overview
+
+### Key Components
+
+- **Content Script** (`src/content-script/index.jsx`) - Injected into all web pages, provides main chat functionality
+- **Background Script** (`src/background/index.mjs`) - Handles browser APIs and cross-page communication
+  - Chromium (Manifest v3): runs as a service worker
+  - Firefox (Manifest v2): runs as a background page
+- **Popup** (`src/popup/`) - Extension popup interface accessible via browser toolbar
+- **Independent Panel** (`src/pages/IndependentPanel/`) - Standalone chat page and side panel
+- **Site Adapters** (`src/content-script/site-adapters/`) - Custom integrations for specific websites (Reddit, GitHub, YouTube, etc.)
+- **Selection Tools** (`src/content-script/selection-tools/`) - Text selection features (translate, summarize, explain, etc.)
+
+### Manifests
+
+- `src/manifest.json` - Manifest v3 for Chromium browsers
+- `src/manifest.v2.json` - Manifest v2 for Firefox
+  - Note: background runs as service worker in MV3 and as background page in MV2.
+
+## Testing and Validation
+
+### Manual Browser Extension Testing (CRITICAL)
+
+Since this is a browser extension with no automated tests, ALWAYS manually test functionality:
+
+1. **Load Extension in Browser:**
+   - Chrome: Go to `chrome://extensions/`, enable Developer Mode, click "Load unpacked", select `build/chromium/`
+   - Firefox: Go to `about:debugging#/runtime/this-firefox`, click "Load Temporary Add-on", then choose the built add-on (select the `build/firefox/` folder or the generated `.xpi`, not `manifest.json`). Note: Temporary add-ons are removed on browser restart.
+   - **Important**: Extension files cannot be tested by serving them via HTTP server - they must be loaded as a proper browser extension
+
+2. **Core Functionality Tests:**
+   - Press `Ctrl+B` (Windows/Linux) or `⌘+B` (macOS) to open the chat dialog on any webpage
+   - Select text on a page, verify selection tools appear
+   - Right-click and verify "Ask ChatGPT" context menu appears
+   - Click extension icon to open popup
+   - Press `Ctrl+Shift+H` (Windows/Linux) or `⌘+Shift+H` (macOS) to open the independent conversation page
+
+3. **Site Integration Tests:**
+   - Visit YouTube.com, verify video summary features work
+   - Visit Reddit.com, verify ChatGPT integration appears in sidebar
+   - Visit GitHub.com, verify code analysis features work
+   - Visit Google.com search results, verify ChatGPT responses appear
+
+4. **Configuration Tests:**
+   - Open extension popup, navigate through tabs (General, Feature Pages, Modules > Selection Tools, Modules > Sites, Advanced)
+   - Test API mode switching (Web API vs OpenAI API) under Modules > API Modes
+   - If using Web APIs, ensure you are signed in to the provider in the same browser profile; if using API Keys, configure valid keys in settings
+   - Verify language settings work
+
+### Build Validation
+
+Ensure these files exist in `build/chromium/` after successful build:
+
+- `manifest.json` (~2.4KB, contains proper extension metadata)
+- `background.js` (~427KB, service worker)
+- `content-script.js` (~1MB, main functionality)
+- `content-script.css` (~650KB, styling)
+- `popup.html` and `popup.js` (popup interface)
+- `IndependentPanel.html` and `IndependentPanel.js` (standalone chat page)
+- `shared.js` (typically around ~2MB; size may vary slightly by environment and dependencies)
+- `logo.png` (~18KB, extension icon)
+- `rules.json` (~1.4KB, declarative net request rules)
+
+### Verify Script Limitations
+
+- `npm run verify` tests search engine configurations by attempting to fetch search results from external search engines (Bing, Yahoo, Baidu, Naver) to validate that the site adapters can parse and handle real responses.
+- **Successful validation**: For each search engine, the script expects to receive a valid HTTP response (status 200) and to successfully extract and parse search results using the corresponding site adapter. If the adapter can parse the expected data structure from the response, the test is considered a pass.
+- **Expected failure modes**: In sandboxed or CI environments, the script may fail due to network restrictions (e.g., DNS errors, timeouts, connection refused), HTTP errors (e.g., 403, 429, 503), or changes in the search engine's response format. These failures are expected and do **not** indicate build problems.
+- If you see network or HTTP errors during `npm run verify`, you can safely ignore them unless you are specifically testing or updating site adapter logic.
+
+## Development Workflow
+
+### Code Style and Quality
+
+- ALWAYS run `npm run lint` before committing - CI will fail otherwise
+- ALWAYS run `npm run pretty` to format code consistently
+- ESLint configuration in `.eslintrc.json` enforces React/JSX standards
+- Prettier configuration in `.prettierrc` handles formatting
+
+### Pre-commit Hooks
+
+The repository uses pre-commit hooks that automatically:
+
+1. Run prettier formatting
+2. Stage formatted files
+3. Run lint checks
+
+### Common File Locations
+
+- Configuration: `src/config/index.mjs`
+- API integrations: `src/services/apis/`
+- Localization: `src/_locales/`
+- UI components: `src/components/`
+- Utilities: `src/utils/`
+
+### Key Directories
+
+```text
+src/
+├── background/             # Background script/service worker
+├── components/             # Reusable UI components
+├── config/                 # Configuration management
+├── content-script/         # Main content script and features
+│   ├── site-adapters/      # Website-specific integrations
+│   ├── selection-tools/    # Text selection features
+│   └── menu-tools/         # Context menu features
+├── pages/IndependentPanel/ # Standalone chat page
+├── popup/                  # Extension popup
+├── services/               # API clients and wrappers
+└── utils/                  # Helper functions
+```
+
+## Platform-Specific Instructions
+
+### Safari Build (macOS Only)
+
+- Requires macOS with Xcode installed
+- Run `npm run build:safari`
+- Creates `Fission - ChatBox.app` bundle and `safari.dmg` installer
+- Uses `safari/build.sh` script with platform-specific patches
+
+### Cross-Browser Compatibility
+
+- Uses `webextension-polyfill` for API compatibility
+- Manifest v3 for Chromium browsers (Chrome, Edge, Opera, etc.)
+- Manifest v2 for Firefox
+- Different permission models between manifest versions
+
+## AI Model Support
+
+The extension supports multiple AI providers:
+
+- **Web APIs** (free): ChatGPT, Claude, Kimi Moonshot (requires browser cookies)
+- **API Keys**: OpenAI GPT models, Claude API, OpenRouter, AI/ML, DeepSeek, Ollama
+- **Custom models**: Support for self-hosted and alternative API endpoints
+
+## Troubleshooting
+
+### Build Issues
+
+- If webpack build fails, check Node.js version (requires Node 20+)
+- If Safari build fails, ensure you're on macOS with Xcode installed
+- "Module not found" errors usually indicate missing `npm ci`. If persisting, remove caches and lockfile: `rm -rf node_modules package-lock.json && npm ci`.
+
+### Runtime Issues
+
+- Extension not loading: Check console for manifest errors
+- API not working: Verify browser has required permissions and cookies
+- Selection tools not appearing: Check if content script loaded correctly
+
+### Common Development Tasks
+
+- Adding new site adapter: Create new file in `src/content-script/site-adapters/`
+- Adding new selection tool: Modify `src/content-script/selection-tools/`
+- Updating API integration: Modify files in `src/services/apis/`
+- Adding new UI component: Create in `src/components/`
+
+## Time Expectations
+
+- Do not interrupt builds or long-running commands unless they appear hung or unresponsive.
+- `npm ci`: ~30 seconds
+- `npm run build`: ~33 seconds (measured). Set timeout to 5–10 minutes to allow for slowdowns; if it exceeds this window and appears hung, confirm Node 20+, clear caches (`rm -rf node_modules && npm ci`) and build caches (`rm -rf node_modules/.cache build/ dist/`), then rerun.
+- `npm run dev`: ~13 seconds initial build, then watches for changes; use Ctrl+C to stop when switching branches or after config/dependency changes.
+- `npm run lint`: ~3–5 seconds
+- Manual extension testing: 5-10 minutes for thorough validation
+- Safari build: 2-5 minutes (macOS only)
+
+## Critical Validation Steps
+
+1. ALWAYS run `npm run build` after any code changes
+2. ALWAYS manually load and test the built extension in a browser - automated testing is not available
+3. ALWAYS verify the build creates the expected file structure with correct file sizes
+4. ALWAYS test core extension functionality (popup, content script injection, keyboard shortcuts)
+
+Always build and manually test the extension in a browser before considering any change complete. Simply running the build is NOT sufficient - you must load the extension and test actual functionality.