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.
• Analyze bundle: npm run analyze -- Inspects the size of webpack output files.
• 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 (see Platform-Specific Instructions for details)

Build Performance Options

• BUILD_PARALLEL: Toggle parallel build of production variants
  • Default: on (parallel). Set to 0 to run sequentially (lower CPU/IO spikes on low-core machines)
• BUILD_THREAD / BUILD_THREAD_WORKERS: Control Babel parallelism via thread-loader
  • Default: threads enabled in dev/prod; workers = CPU cores
  • Set BUILD_THREAD=0 to disable; set BUILD_THREAD_WORKERS=<n> to override worker count
• BUILD_CACHE_COMPRESSION: Webpack filesystem cache compression
  • Default: 0 (no compression) for faster warm builds on CPU-bound SSD machines
  • Options: 0|false|none, gzip (or brotli if explicitly desired)
  • Affects only .cache/webpack size/speed; does not change final artifacts
  • Note: Babel loader cache uses its own compression setting (currently disabled for speed) and is independent of BUILD_CACHE_COMPRESSION
• BUILD_WATCH_ONCE (dev): When set, npm run dev runs a single build and exits (useful for timing)
• BUILD_POOL_TIMEOUT: Override thread-loader production pool timeout (ms)
  • Default: 2000. Increase if workers recycle too aggressively on slow machines/CI
• BUILD_RESOLVE_SYMLINKS: When set to 1/true, re-enable Webpack symlink resolution for npm link/pnpm workspace development. Default is false to improve performance and ensure consistent module identity (avoids duplicate module instances)
• Source maps (dev): Dev builds emit external .map files next to JS bundles for CSP-safe debugging; production builds disable source maps

Performance defaults: esbuild handles JS/CSS minification. In development, CSS is injected via style-loader; in production, CSS is extracted via MiniCssExtractPlugin. Thread-loader is enabled by default in both dev and prod.

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
  • Firefox: build/firefox.zip
  • Safari: ChatGPTBox.app and safari.dmg (see Safari Build section for details)

Architecture Overview

The project uses Preact (for React-like components), SCSS (for styling), and Webpack 5 (for bundling).

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)

This browser extension includes automated unit tests, but manual browser extension testing is still essential:

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 select the manifest.json file inside build/firefox/ (do not select the folder directly). Note: Temporary (unsigned) add-ons are removed on browser restart; reload them via the same "This Firefox" page after every restart, and some environments with enterprise policies may block loading from file.
   • 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

Debugging tips:

• Inspect background Service Worker, page DevTools for content scripts, and use "Inspect popup" for the popup UI
• After rebuilds, reload the extension and refresh the page to re‑inject content scripts

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.

Usage notes:

• Default checks target: https://www.bing.com/search?q=hello, https://search.yahoo.co.jp/search?p=hello, https://www.baidu.com/s?wd=hello, https://search.naver.com/search.naver?query=hello
• Optional engines (may be blocked by region or anti-bot measures): Google, DuckDuckGo, Brave, Searx.
• Troubleshooting: If a site fails, try adjusting Accept-Language/User-Agent headers in the script, update the site's selector arrays with ordered fallbacks, or temporarily reduce the test to a single URL while iterating.

Development Workflow

Code Style, Quality, and File Organization

• 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 (100 char width, no semicolons, single quotes, trailing commas)

✅ Good: import Browser from 'webextension-polyfill' (single quotes, no semicolon) ❌ Bad: import Browser from "webextension-polyfill"; (double quotes, semicolon)

• Naming conventions: component directories use PascalCase; feature folders use kebab-case; entry files are typically index.jsx or index.mjs
• Avoid heavy dependencies; if necessary, justify and keep bundle size under control

Pre-commit hooks automatically:

1. Run prettier formatting
2. Stage formatted files
3. Run lint checks

Key file locations:

• Configuration: src/config/index.mjs
• API integrations: src/services/apis/
• Localization: src/_locales/
• UI components: src/components/
• Utilities: src/utils/

Commits & PRs

• Keep changes minimal and focused. Avoid unrelated refactors in the same PR.
• Commit subject: imperative, capitalize first word; separate subject/body with a blank line; wrap at ~72 characters; explain what and why.
• PRs: link related issues, summarize scope/behavior changes; include screenshots for UI changes.
• Note i18n updates in PR description when src/_locales/ changes.
• If any validation step is skipped, document the reason and the skipped check(s) in the PR description (see Critical Validation Steps below).

Directory Structure

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 (requires macOS with Xcode installed)
• Creates ChatGPTBox.app bundle and safari.dmg installer
• Uses safari/build.sh script with platform-specific build settings

Cross-Browser Compatibility

• Uses webextension-polyfill for API compatibility

Security & Privacy

• Do not commit secrets, API keys, or user data
• Keep manifest permissions minimal and justify any additions
• Centralize network/API logic under src/services/apis/ and keep endpoints auditable

Localization

• Source of truth: src/_locales/en/main.json; do not change existing keys (only add new ones)
• Add new source strings to en/main.json first and translate user-facing text in other locales as appropriate
• Do not duplicate unchanged model or provider labels across non-English locales; rely on the English fallback unless the displayed text requires localization
• Register new locales in src/_locales/resources.mjs
• Preserve placeholders and product names; keep punctuation/quotes intact
• For Traditional Chinese (Taiwan), use src/_locales/zh-hant/main.json and avoid zh‑CN terms

AI Model Support

The extension supports multiple AI providers:

• Web (cookie-based): ChatGPT (Web), Claude (Web), Kimi.Moonshot (Web), Bing (Web), Bard (Web)
• APIs (key-based): OpenAI (API), Azure OpenAI (API), Anthropic (Claude 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 22+), 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
• "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/, register it in src/content-script/site-adapters/index.mjs, keep selectors minimal with feature detection, and verify on Chromium/Firefox
• Adding new selection tool: Modify src/content-script/selection-tools/, keep UI and logic separate, and reuse helpers in src/utils/
• Updating API integration: Modify files in src/services/apis/
• Adding new UI component: Create in src/components/

Note: Ask before deleting/renaming files, modifying build config/manifests, or making changes that affect multiple site adapters. If the user explicitly requests one of these changes, proceed and document scope and risk in the current workflow handoff output, and in the PR summary when applicable.

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 for system variations.
• 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. General changes (any change not covered by Step 2 or Step 3): run npm test and npm run build, verify expected build artifacts, and run manual browser smoke tests. If changes include safari/**, also run npm run build:safari on macOS. If macOS is unavailable for those changes, document the skip reason in PR validation notes.
2. Behavior-adjacent localization changes (src/_locales/** only): run npm run build and manual browser smoke tests. Use this step only when all changed files are under src/_locales/**.
3. Docs-only changes (*.md, screenshots/**): build/manual browser tests may be skipped, but the PR description must include Validation skipped: docs/screenshots-only change; no runtime files touched.
4. If changes span multiple categories, apply the strictest applicable step (runtime > localization > docs/screenshots); when in doubt, treat the change as runtime-impacting and execute the full validation flow.

Most of this document was generated by AI and reviewed under human supervision. If you find any clear errors while using it, please submit corrections with supporting evidence where possible.