Add comprehensive GitHub Copilot instructions

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
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,205 @@
+# 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` -- 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` -- 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` -- Avoid force-killing mid-bundle; stop, fix, then rebuild.
+  See "Time Expectations" and "Build Issues" for the hung-build policy and recovery steps.
+- Format code: `npm run pretty` -- uses Prettier to format all JS/JSX/CSS files. Run this before linting.
+- Lint code: `npm run lint` -- uses ESLint.
+- Safari build: `npm run build:safari` -- macOS with Xcode required.
+
+### 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:
+  - Chromium: `build/chromium-*.zip` (e.g., `build/chromium-<version>.zip`)
+  - Firefox: `build/firefox-*.xpi` (e.g., `build/firefox-<version>.xpi`)
+  - Safari: `Fission - ChatBox.app` and `safari.dmg` (see Safari Build section for details)
+
+## 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
+- **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 (Chrome, Edge, Opera, etc.)
+- `src/manifest.v2.json` - Manifest v2 for Firefox (current status; future MV3 migration may change this)
+  - Background runs as service worker (MV3) vs background page (MV2)
+  - Different permission models between manifest versions
+
+## 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", then select the folder `build/chromium/` (the folder must contain `manifest.json`).
+   - Firefox: Go to `about:debugging#/runtime/this-firefox`, click "Load Temporary Add-on", then choose the generated `.xpi` file from `build/` (recommended). To load unpacked instead, select the `manifest.json` file inside `build/firefox/` (do not select the folder directly). 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` (contains proper extension metadata)
+- `background.js` (service worker bundle)
+- `content-script.js` (main functionality)
+- `content-script.css` (styling)
+- `popup.html` and `popup.js` (popup interface)
+- `IndependentPanel.html` and `IndependentPanel.js` (standalone chat page)
+- `shared.js` (shared vendor/runtime; size varies by environment and dependencies)
+- `logo.png` (extension icon)
+- `rules.json` (declarative net request rules)
+
+Bundle sizes are approximate and not validation criteria.
+
+### 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)
+
+- 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
+
+## AI Model Support
+
+The extension supports multiple AI providers:
+
+- **Web (cookie-based)**: ChatGPT (Web), Claude.ai (Web), Kimi.Moonshot (Web), Bing (Web), Gemini (Web)
+- **APIs (key-based)**: OpenAI (API), Azure OpenAI (API), Claude.ai (API), OpenRouter (API), AI/ML (API), DeepSeek (API), Ollama (local), ChatGLM (API), Waylaidwanderer (API), Kimi.Moonshot (API)
+- **Custom/self-hosted**: Alternative endpoints and self-hosted backends
+
+## Troubleshooting
+
+### Build Issues
+
+- Build failures: Check Node.js version (requires Node 20+), clear caches and rebuild.
+  - macOS/Linux: `rm -rf node_modules && npm ci && rm -rf node_modules/.cache build/ dist/`
+  - Windows (PowerShell): `Remove-Item -Recurse -Force node_modules, build, dist; if (Test-Path node_modules\.cache) { Remove-Item -Recurse -Force node_modules\.cache }; npm ci`
+- Safari build fails: Ensure macOS with Xcode installed
+- "Module not found" errors: Usually indicate missing `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`: ~35 seconds (measured). Set timeout to 5-10 minutes; if it exceeds this and appears hung, see "Build Issues" for recovery steps.
+- `npm run dev`: ~15 seconds initial build, then watches for changes; use Ctrl+C to stop when switching branches or after config/dependency changes.
+- `npm run lint`: ~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.