.cursorrules (deprecated)

1# Chrome Extension Manifest V3 — Cursor Rules
2 
3You are an expert Chrome Extension developer building extensions with Manifest V3, using TypeScript, modern web APIs, and Chrome Extension best practices.
4 
5## Code Style
6 
7- Use TypeScript for all extension code. Install `chrome-types` npm package for full Chrome API type definitions (`@anthropic-ai/chrome-types` or `chrome-types`).
8- Reference Chrome API types with the `chrome` global namespace. The types package provides complete definitions for `chrome.runtime`, `chrome.storage`, `chrome.tabs`, etc.
9- Use `camelCase` for variables and functions, `PascalCase` for classes and components, `UPPER_SNAKE_CASE` for constants.
10- Use named exports. Group code by concern: content scripts, background service worker, popup, options page.
11- Use ESM syntax with a bundler (webpack, Vite, or esbuild) that outputs browser-compatible JavaScript.
12- Follow Chrome Extension style: concise, performance-focused, minimal permissions.
13 
14## Manifest V3 Configuration
15 
16- Use `"manifest_version": 3` exclusively. Do not use Manifest V2 patterns.
17- Declare the minimum permissions required in `permissions`. Use `optional_permissions` for features that aren't always needed.
18- Use `host_permissions` for site-specific access. Prefer specific patterns over `<all_urls>`.
19- Define `content_scripts` with precise URL matches. Use `matches` patterns, not `<all_urls>` unless truly needed.
20- Register the service worker in `background.service_worker`, not `background.scripts`.
21- Use `action` (not `browser_action` or `page_action`) for the toolbar icon.
22- Specify `content_security_policy.extension_pages` if you need to relax CSP (rare — prefer default).
23- Declare `web_accessible_resources` with resource patterns and match conditions for files accessed from web pages.
24 
25## Service Worker (Background)
26 
27- The service worker is event-driven. It starts on events and terminates when idle. Do not rely on persistent state.
28- Use `chrome.storage.local` or `chrome.storage.session` for persisting data across service worker restarts.
29- Register all event listeners at the top level of the service worker — not inside other callbacks or async functions.
30- Use `chrome.alarms` for periodic tasks instead of `setInterval` (service worker terminates between events).
31- Handle extension lifecycle events: `chrome.runtime.onInstalled` for setup, migrations, and first-run experience.
32- Use `chrome.runtime.onMessage` for communication with content scripts and popup.
33- Keep the service worker lightweight. Offload heavy processing to content scripts or offscreen documents.
34- Use `chrome.offscreen.createDocument()` for DOM access from the background (audio, canvas, clipboard).
35 
36## Content Scripts
37 
38- Content scripts run in a separate isolated world. They share the DOM but not JavaScript variables with the page.
39- Use `chrome.runtime.sendMessage()` to communicate with the service worker.
40- Use `chrome.runtime.onMessage.addListener()` to receive messages from the service worker.
41- Access the page's DOM directly. Use `MutationObserver` to react to dynamic DOM changes.
42- Inject CSS with `chrome.scripting.insertCSS()` from the service worker, or include in `manifest.json` `content_scripts.css`.
43- Use `chrome.scripting.executeScript()` for programmatic injection from the service worker.
44- Namespace your DOM modifications to avoid conflicts with the page: use unique class prefixes, shadow DOM.
45- Use Shadow DOM for injected UI components to isolate styles from the host page.
46- Clean up on deactivation: remove observers, event listeners, and injected elements.
47 
48## Message Passing
49 
50- Use `chrome.runtime.sendMessage()` for one-time messages between content scripts and service worker.
51- Use `chrome.runtime.connect()` for long-lived connections (port-based messaging).
52- Define a message protocol with typed action names:
53```typescript
54  type Message =
55    | { action: 'GET_DATA'; payload: { key: string } }
56    | { action: 'SAVE_DATA'; payload: { key: string; value: unknown } }
57    | { action: 'TOGGLE_FEATURE'; payload: { featureId: string; enabled: boolean } }
58```
59- Always return `true` from `onMessage` listeners when responding asynchronously with `sendResponse`.
60- Validate all incoming messages. Never trust data from content scripts without validation.
61- Use `chrome.tabs.sendMessage(tabId, message)` to send messages to a specific tab's content script.
62- Use `chrome.runtime.sendMessage()` from content scripts to send to the service worker.
63 
64## Storage
65 
66- Use `chrome.storage.local` for persistent extension data (settings, cached data). Up to 10MB (or more with `unlimitedStorage`).
67- Use `chrome.storage.sync` for user settings that sync across devices. Limited to 100KB total.
68- Use `chrome.storage.session` for temporary data that persists across service worker restarts but not browser restarts.
69- Always handle storage errors: `chrome.runtime.lastError` in callbacks, or use promise-based API.
70- Use `chrome.storage.onChanged` to react to storage changes across extension contexts.
71- Store structured data as JSON objects. Use versioned storage schemas for migration support.
72- Batch storage operations: `chrome.storage.local.set({ key1: val1, key2: val2 })` instead of multiple set calls.
73 
74## Popup and Options Pages
75 
76- Keep the popup lightweight. It's destroyed when closed — fetch state from storage, not service worker.
77- Use a modern frontend framework (React, Svelte, Vue) or vanilla TypeScript for popup and options pages.
78- Load state from `chrome.storage` on popup open. Save changes back to storage immediately.
79- Use `chrome.runtime.sendMessage()` to request actions from the service worker.
80- Handle the popup lifecycle: it may open and close rapidly. Save state on every change.
81- Style popups with a fixed width (300-400px) and scrollable content area.
82- Options page: use `chrome.storage.sync` for settings that should sync across devices.
83- Provide sensible defaults for all settings. Check for existing values on first load.
84 
85## Error Handling
86 
87- Always check `chrome.runtime.lastError` after Chrome API calls (callback style).
88- Use promise-based Chrome API (Manifest V3 supports promises natively) with try/catch.
89- Handle extension context invalidation: `chrome.runtime.lastError` with "Extension context invalidated".
90- Log errors to a background error tracking system or `chrome.storage` for debugging.
91- Provide fallback behavior when permissions are not granted.
92- Handle tab/window lifecycle: tabs can close while you're processing messages.
93- Content scripts should handle page navigation gracefully — clean up and re-initialize as needed.
94 
95## Testing
96 
97- Use Jest or Vitest for unit testing business logic and message handlers.
98- Mock Chrome APIs with `jest-chrome` or custom mocks of `chrome.*` namespace.
99- Test message handling by simulating message events.
100- Test content scripts with DOM testing libraries (Testing Library, jsdom).
101- Use Chrome DevTools for manual testing: inspect service worker, content script, popup.
102- Test on multiple Chrome versions. Check the minimum Chrome version for APIs you use.
103- Use Playwright or Puppeteer with the `--load-extension` flag for e2e testing.
104 
105## File Structure
106 
107```
108src/
109  background/
110    service-worker.ts   — Main service worker entry point
111    handlers/
112      messages.ts       — Message handlers
113      alarms.ts         — Alarm handlers
114    storage.ts          — Storage operations
115  content/
116    index.ts            — Content script entry point
117    dom-observer.ts     — DOM mutation observer
118    ui/
119      sidebar.ts        — Injected sidebar component
120      overlay.ts        — Injected overlay component
121  popup/
122    index.html
123    index.ts            — Popup entry point
124    components/         — Popup UI components
125    styles.css
126  options/
127    index.html
128    index.ts            — Options page entry point
129  shared/
130    types.ts            — Shared type definitions
131    constants.ts        — Extension-wide constants
132    messages.ts         — Message protocol types
133    utils.ts            — Shared utility functions
134  manifest.json
135public/
136  icons/
137    icon-16.png
138    icon-32.png
139    icon-48.png
140    icon-128.png
141```
142 
143## Security
144 
145- Request minimum permissions. Use `optional_permissions` and request at runtime with `chrome.permissions.request()`.
146- Validate all data received via messages. Content scripts run on untrusted pages.
147- Use Content Security Policy — Manifest V3 enforces stricter CSP by default. Do not relax it without justification.
148- Never use `eval()`, `new Function()`, or inline scripts. CSP blocks them in Manifest V3.
149- Sanitize user-generated content before injecting into the DOM. Use `textContent` over `innerHTML`.
150- Use HTTPS for all external API calls. Never transmit sensitive data over HTTP.
151- Store user credentials securely using `chrome.identity` API for OAuth or `chrome.storage.local` with encryption.
152- Avoid `<all_urls>` in permissions. Request specific host permissions.
153- Use `externally_connectable` to restrict which websites can send messages to your extension.
154 
155## Performance
156 
157- Keep the service worker idle time minimal. Register events, process quickly, terminate.
158- Use lazy loading: import heavy modules only when needed.
159- Use `chrome.scripting.executeScript` with `target.allFrames: false` unless you need all frames.
160- Debounce DOM observers in content scripts to avoid performance impact on web pages.
161- Use `chrome.storage.session` for frequently accessed temporary data (faster than local storage reads).
162- Minimize content script injection footprint: small scripts, scoped CSS, efficient DOM queries.
163- Bundle and minify all extension code for smaller package size and faster loading.
164- Use `requestIdleCallback` for non-urgent processing in content scripts.
165