@zigrivers/scaffold 3.8.0 → 3.9.0

package/content/knowledge/browser-extension/browser-extension-conventions.md

@@ -0,0 +1,156 @@
+---
+name: browser-extension-conventions
+description: Naming conventions for manifests, message action types, file organization, and i18n structure in browser extensions
+topics: [browser-extension, conventions, naming, i18n, file-organization, messaging]
+---
+
+Browser extensions accumulate technical debt faster than typical web apps because they span multiple execution contexts — content scripts, service workers, popup pages, options pages — each with distinct constraints. Consistent naming conventions and file organization make cross-context code navigable and reduce the cognitive overhead of working across these boundaries. Establish conventions before writing code.
+
+## Summary
+
+Browser extension conventions cover four areas: manifest field naming (follow the WebExtensions spec naming exactly, never invent aliases), message action types (use `SCREAMING_SNAKE_CASE` with a `namespace/ACTION` pattern to prevent cross-feature collisions), file organization (separate each execution context into its own source directory), and i18n structure (`_locales/` with `messages.json` per locale, all user-visible strings externalized from day one). Apply these conventions uniformly from the first commit.
+
+## Deep Guidance
+
+### Manifest Naming Conventions
+
+The `manifest.json` is not a place for creative naming. Every field name is defined by the WebExtensions specification. Use the canonical names exactly as specified:
+
+- `manifest_version` — always `3` for new extensions targeting Manifest V3.
+- `action` — the toolbar button (previously `browser_action` in MV2). Do not use `browser_action` in MV3 manifests.
+- `background.service_worker` — the path to the service worker script. Not `background.scripts` (MV2 syntax).
+- `content_scripts` — array of content script declarations. Each entry has `matches`, `js`, `css`, `run_at`.
+- `host_permissions` — separate from `permissions` in MV3. Do not mix host patterns into the `permissions` array.
+- `web_accessible_resources` — array of objects with `resources` and `matches`. MV3 requires the `matches` field; MV2 accepted a plain string array.
+
+**Version string format:** Follow semantic versioning with exactly four dot-separated integers: `MAJOR.MINOR.PATCH.BUILD` (e.g., `1.2.3.0`). The Chrome Web Store enforces four-part version strings. Keep the manifest `version` field in sync with `package.json` `version` via a build script.
+
+**Extension name and description:**
+- `name`: Under 45 characters. This appears in the toolbar tooltip and store listing.
+- `short_name`: Under 12 characters. Appears in constrained UI contexts. Define it explicitly rather than relying on automatic truncation.
+- `description`: Under 132 characters. This is the store listing short description.
+
+### Message Action Type Naming
+
+Cross-context messaging (`chrome.runtime.sendMessage`, `chrome.tabs.sendMessage`) requires a shared vocabulary for message types. Collisions between unrelated features produce hard-to-diagnose bugs because every message listener receives every message.
+
+**Recommended pattern — namespace/ACTION:**
+
+```typescript
+// Shared constants (src/shared/messages.ts)
+export const Messages = {
+  // Popup → Background
+  POPUP_GET_STATUS:        'popup/GET_STATUS',
+  POPUP_TOGGLE_ENABLED:    'popup/TOGGLE_ENABLED',
+
+  // Content → Background
+  CONTENT_PAGE_LOADED:     'content/PAGE_LOADED',
+  CONTENT_REQUEST_CONFIG:  'content/REQUEST_CONFIG',
+
+  // Background → Content
+  BG_INJECT_OVERLAY:       'bg/INJECT_OVERLAY',
+  BG_CLEAR_STATE:          'bg/CLEAR_STATE',
+} as const;
+
+export type MessageType = typeof Messages[keyof typeof Messages];
+```
+
+**Rules:**
+- All message types are defined in one shared constants file imported by all contexts.
+- Use `SCREAMING_SNAKE_CASE` for the constant key; use `namespace/ACTION` for the string value.
+- Never use raw string literals for message types — always reference the constant.
+- Each message type has exactly one handler. If multiple handlers respond to the same type, it is a design flaw.
+
+**Message payload typing:**
+
+```typescript
+type MessageMap = {
+  [Messages.POPUP_GET_STATUS]: { payload: undefined; response: StatusPayload };
+  [Messages.POPUP_TOGGLE_ENABLED]: { payload: { enabled: boolean }; response: void };
+};
+```
+
+Typed message maps prevent callers from passing incorrect payloads and give type-safe responses.
+
+### File Organization Conventions
+
+Each execution context gets its own top-level source directory. Do not co-locate content script code with popup code — they have different APIs, different DOM access, and different lifecycle constraints.
+
+**Source directory structure:**
+
+```
+src/
+  background/        # Service worker entry and background logic
+    index.ts         # Service worker entry point
+    handlers/        # Message handlers, one file per domain
+    alarms.ts        # Alarm setup and handlers
+  content/           # Content scripts
+    index.ts         # Content script entry point
+    injectors/       # DOM injection logic
+    observers/       # MutationObserver setup
+  popup/             # Popup page
+    index.html
+    index.ts
+    components/      # Popup-specific UI components
+  options/           # Options page
+    index.html
+    index.ts
+  shared/            # Code imported by multiple contexts
+    messages.ts      # Message type constants
+    storage.ts       # Storage key constants and typed wrappers
+    types.ts         # Shared TypeScript interfaces
+```
+
+**File naming:**
+- Use `kebab-case` for all source files.
+- Entry points for each context are always named `index.ts` / `index.html`.
+- Handler files are named after the domain they handle: `tab-handlers.ts`, `storage-handlers.ts`.
+- Never name a file `utils.ts` — name it after what it does: `url-helpers.ts`, `dom-sanitizer.ts`.
+
+### i18n Structure and Conventions
+
+Internationalization in extensions is mandatory if you ever plan to submit to markets outside your primary language. The `_locales/` directory is the WebExtensions standard mechanism.
+
+**Directory structure:**
+
+```
+_locales/
+  en/
+    messages.json
+  es/
+    messages.json
+  fr/
+    messages.json
+```
+
+**messages.json format:**
+
+```json
+{
+  "extensionName": {
+    "message": "My Extension",
+    "description": "The name of the extension"
+  },
+  "popupToggleLabel": {
+    "message": "Enable on this site",
+    "description": "Label for the enable/disable toggle in the popup"
+  },
+  "statusEnabled": {
+    "message": "Active",
+    "description": "Status label when extension is enabled"
+  }
+}
+```
+
+**Conventions:**
+- Message keys use `camelCase`. Never use dots or underscores — they suggest hierarchy that the flat message file does not support.
+- Every message has a `description` field. Translators need context. Empty descriptions lead to mistranslations.
+- Externalize all user-visible strings from day one, even if only targeting English initially. Retrofitting i18n into an extension that hardcodes strings is expensive.
+- Reference messages in the manifest with `__MSG_keyName__` syntax: `"name": "__MSG_extensionName__"`.
+- Reference messages in JavaScript with `chrome.i18n.getMessage('keyName')`.
+- Reference messages in HTML with the `data-i18n` attribute pattern (requires a small initialization script in the popup to apply translations on load).
+
+**Locale fallback:**
+- The `_locales/en/` directory is the fallback locale. If a translation is missing in another locale, Chrome falls back to `en`.
+- Always maintain the `en` locale as the source of truth.
+- Use the `browser.i18n.getUILanguage()` API to detect the user's browser language for locale-specific logic beyond string translation.

package/content/knowledge/browser-extension/browser-extension-cross-browser.md

@@ -0,0 +1,229 @@
+---
+name: browser-extension-cross-browser
+description: Using webextension-polyfill for API compatibility, manifest differences between Chrome and Firefox, browser-specific APIs, and managing a multi-browser build matrix
+topics: [browser-extension, cross-browser, firefox, chrome, webextension-polyfill, compatibility, build-matrix]
+---
+
+Browser extensions that target both Chrome and Firefox share most of their codebase, but the differences between the two platforms are significant enough to require explicit management. API namespaces differ, manifest syntax diverges in subtle ways, and some APIs exist only in Chrome or only in Firefox. A systematic cross-browser strategy prevents the "works in Chrome, broken in Firefox" class of bugs.
+
+## Summary
+
+Use `webextension-polyfill` to normalize the `chrome.*` API (callback-based) to the `browser.*` API (Promise-based) and fill gaps between browsers. Maintain separate manifest files per browser target (or a shared base with environment-specific overrides) because Chrome uses `background.service_worker` while Firefox still supports `background.scripts` with persistent pages. Build separate artifacts for each target using a build matrix with environment variables. Test on both browsers before each release — API parity is high but not complete.
+
+## Deep Guidance
+
+### webextension-polyfill
+
+Mozilla's `webextension-polyfill` wraps the `chrome.*` namespace (callback-based) with a `browser.*` namespace (Promise-based) that works in both Chrome and Firefox:
+
+**Installation:**
+
+```bash
+npm install webextension-polyfill
+npm install -D @types/webextension-polyfill
+```
+
+**Usage:**
+
+```typescript
+// Without polyfill — Chrome callback API
+chrome.storage.sync.get('key', (result) => {
+  console.log(result.key);
+});
+
+// With polyfill — Promise-based, works in Chrome and Firefox
+import browser from 'webextension-polyfill';
+
+const result = await browser.storage.sync.get('key');
+console.log(result.key);
+```
+
+Import `webextension-polyfill` once at the top of each context's entry point. All subsequent `browser.*` calls will be polyfilled in Chrome and will use Firefox's native Promise API in Firefox.
+
+**What the polyfill covers:**
+- All `chrome.*` → `browser.*` name normalization.
+- Converts callback-based APIs to Promises.
+- Fills some API gaps between Chrome and Firefox.
+
+**What the polyfill does not cover:**
+- APIs that only exist in Chrome (`chrome.declarativeNetRequest` advanced features, `chrome.sidePanel`, some scripting features).
+- Manifest syntax differences — those require separate manifest files.
+- Firefox's different extension signing and review requirements.
+
+### Manifest Differences
+
+Chrome and Firefox have diverged enough that maintaining separate manifest files (or a build-time merge strategy) is safer than one shared manifest.
+
+**Background script declaration:**
+
+```json
+// Chrome (Manifest V3) — manifest.json
+{
+  "background": {
+    "service_worker": "background.js",
+    "type": "module"
+  }
+}
+```
+
+```json
+// Firefox — manifest.json
+// Firefox supports MV3 but still supports MV2 with persistent background pages
+// Firefox MV3 uses background.scripts (plural) in some versions
+{
+  "background": {
+    "scripts": ["background.js"],
+    "type": "module"
+  }
+}
+```
+
+Firefox's MV3 support is still maturing (as of 2025). Many production extensions targeting Firefox maintain an MV2 manifest for Firefox to avoid compatibility issues with Firefox's incomplete MV3 implementation.
+
+**browser_specific_settings (Firefox only):**
+
+```json
+// Firefox manifest requires a unique extension ID
+{
+  "browser_specific_settings": {
+    "gecko": {
+      "id": "my-extension@example.com",
+      "strict_min_version": "109.0"
+    }
+  }
+}
+```
+
+Chrome ignores `browser_specific_settings`. Firefox requires a `gecko.id` for extensions submitted to AMO — without it, the extension ID is auto-generated and changes between installs.
+
+**Recommended build strategy — manifest merging:**
+
+```typescript
+// scripts/build-manifests.ts
+import baseManifest from './manifest.base.json';
+import chromeOverrides from './manifest.chrome.json';
+import firefoxOverrides from './manifest.firefox.json';
+
+const chromeManifest = { ...baseManifest, ...chromeOverrides };
+const firefoxManifest = { ...baseManifest, ...firefoxOverrides };
+
+writeFileSync('dist/chrome/manifest.json', JSON.stringify(chromeManifest, null, 2));
+writeFileSync('dist/firefox/manifest.json', JSON.stringify(firefoxManifest, null, 2));
+```
+
+### Browser-Specific API Differences
+
+**APIs available in Chrome but not Firefox:**
+
+| API | Chrome | Firefox | Notes |
+|---|---|---|---|
+| `chrome.sidePanel` | Yes (Chrome 114+) | No | Side panel UI in the browser window |
+| `chrome.declarativeNetRequest` | Full | Partial | Firefox support is partial |
+| `chrome.offscreen` | Yes (Chrome 109+) | No | Offscreen document for audio/clipboard |
+| `chrome.readingList` | Yes | No | Reading list integration |
+| `chrome.ttsEngine` | Yes | No | TTS engine extension |
+
+**APIs available in Firefox but not Chrome:**
+
+| API | Chrome | Firefox | Notes |
+|---|---|---|---|
+| `browser.menus` (full) | Partial | Yes | Firefox has richer context menu API |
+| `browser.pkcs11` | No | Yes | Smart card access |
+| `browser.theme` | No | Yes | Browser theme management |
+| `browser.userScripts` | Limited | Yes (via MV2) | User script management |
+
+**API behavior differences:**
+
+- `chrome.tabs.query({ active: true })` — Returns an array in both browsers, but Chrome always returns a single-element array for the focused window; Firefox may return empty if no window is focused.
+- `chrome.storage.sync` — Chrome syncs across devices via Google account. Firefox syncs via Firefox Sync. Storage limits differ slightly.
+- `chrome.runtime.sendMessage` — Chrome throws if no listener is registered. Firefox returns a rejected Promise with a specific error code. Handle both in cross-browser code.
+- Content script `matches` patterns — Both support the standard match pattern syntax, but Firefox has slightly stricter validation. Test patterns in both browsers.
+
+### Feature Detection Pattern
+
+Rather than browser-sniffing, use feature detection for browser-specific APIs:
+
+```typescript
+// Feature detection — works in both browsers
+export const canUseSidePanel = 'sidePanel' in chrome;
+export const canUseOffscreen = 'offscreen' in chrome;
+
+// Use conditionally
+if (canUseSidePanel) {
+  chrome.sidePanel.setOptions({ enabled: true });
+} else {
+  // Fallback: open as a popup instead
+  chrome.action.setPopup({ popup: 'popup/index.html' });
+}
+```
+
+Avoid `navigator.userAgent` parsing to detect Chrome vs Firefox — it is fragile and breaks with Chromium-based browsers that are not Chrome.
+
+### Build Matrix Configuration
+
+Structure the build to produce separate artifacts for each browser target:
+
+```json
+// package.json scripts
+{
+  "scripts": {
+    "build": "npm run build:chrome && npm run build:firefox",
+    "build:chrome": "BROWSER=chrome vite build --outDir dist/chrome",
+    "build:firefox": "BROWSER=firefox vite build --outDir dist/firefox",
+    "pack:chrome": "cd dist/chrome && zip -r ../../web-ext-artifacts/extension-chrome.zip .",
+    "pack:firefox": "web-ext build --source-dir dist/firefox --artifacts-dir web-ext-artifacts"
+  }
+}
+```
+
+```typescript
+// vite.config.ts — browser-conditional build
+const browser = process.env.BROWSER ?? 'chrome';
+
+export default defineConfig({
+  define: {
+    __BROWSER__: JSON.stringify(browser),
+    __IS_CHROME__: browser === 'chrome',
+    __IS_FIREFOX__: browser === 'firefox',
+  },
+  plugins: [
+    webExtension({
+      manifest: browser === 'chrome'
+        ? require('./manifest.chrome.json')
+        : require('./manifest.firefox.json'),
+    }),
+  ],
+});
+```
+
+### Cross-Browser Testing Checklist
+
+Run this checklist before every release:
+
+- Extension loads without errors in `chrome://extensions` (Chrome) and `about:debugging` (Firefox).
+- Content scripts inject correctly on target pages in both browsers.
+- Storage read/write works in both browsers (test with `chrome.storage.sync` and `browser.storage.sync`).
+- Message passing between popup ↔ background works in both browsers.
+- Permissions are granted correctly on install in both browsers.
+- Options page loads and saves settings in both browsers.
+- Extension icon appears correctly at 16×16 in the toolbar (both browsers render icons differently at small sizes).
+- `chrome.runtime.getURL()` returns correct paths in both browsers.
+- Any browser-specific feature fallbacks activate correctly in the non-supporting browser.
+
+### Continuous Integration for Cross-Browser
+
+Run automated tests against both browser targets in CI:
+
+```yaml
+# .github/workflows/test.yml
+jobs:
+  test:
+    strategy:
+      matrix:
+        browser: [chrome, firefox]
+    steps:
+      - run: npm run build:${{ matrix.browser }}
+      - run: npm run test:e2e -- --browser ${{ matrix.browser }}
+```
+
+Puppeteer supports loading Chrome extensions. Playwright supports loading Chrome extensions and (with additional configuration) Firefox extensions. Both are suitable for automated cross-browser extension testing in CI.

package/content/knowledge/browser-extension/browser-extension-dev-environment.md

@@ -0,0 +1,247 @@
+---
+name: browser-extension-dev-environment
+description: Build tooling with Webpack/Vite, hot reload via web-ext and crx-hotreload, and browser launch configuration for extension development
+topics: [browser-extension, dev-environment, vite, webpack, hot-reload, web-ext, build]
+---
+
+Browser extension development requires a different local setup than web app development. There is no dev server to navigate to — the extension must be loaded into a real browser instance, and changes require either a manual reload or a dedicated hot-reload tool. Getting this setup right at the start of the project eliminates the most friction-heavy part of the development loop.
+
+## Summary
+
+Use Vite with `vite-plugin-web-extension` (or `@crxjs/vite-plugin` for Chrome-only projects) as the build tool — it handles multi-entry bundling, manifest processing, and dev-mode content script injection automatically. For hot reload in development, use `web-ext` (Mozilla's CLI tool, works for both Chrome and Firefox) with its `--watch` flag, which reloads the extension on file changes. For Chrome-specific hot reload, `crx-hotreload` provides a lightweight alternative. Use separate npm scripts for dev (with watch + auto-reload) and build (production bundle for store submission).
+
+## Deep Guidance
+
+### Build Tool: Vite with Extension Plugin
+
+Vite is the recommended build tool for new browser extension projects. Its ES module native dev server is not used directly (extensions load from `dist/`, not a dev server), but Vite's build pipeline provides fast incremental rebuilds, TypeScript compilation, CSS processing, and tree shaking.
+
+**vite-plugin-web-extension** (cross-browser, recommended):
+
+```bash
+npm install -D vite vite-plugin-web-extension
+```
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import webExtension from 'vite-plugin-web-extension';
+
+export default defineConfig({
+  plugins: [
+    webExtension({
+      manifest: () => require('./manifest.json'),
+      // Automatically discovers entry points from manifest.json
+      // and configures multi-entry build
+    }),
+  ],
+});
+```
+
+`vite-plugin-web-extension` reads `manifest.json` and automatically derives all build entry points from `background.service_worker`, `content_scripts[].js`, `action.default_popup`, and `options_page` fields. No manual entry point configuration required.
+
+**@crxjs/vite-plugin** (Chrome-only, with HMR support):
+
+```bash
+npm install -D vite @crxjs/vite-plugin
+```
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { crx } from '@crxjs/vite-plugin';
+import manifest from './manifest.json';
+
+export default defineConfig({
+  plugins: [
+    crx({ manifest }),
+  ],
+});
+```
+
+`@crxjs/vite-plugin` additionally supports Hot Module Replacement for popup and options pages in Chrome, making UI development significantly faster. Note: Firefox support is limited and experimental with this plugin.
+
+**Webpack alternative** (for projects with existing Webpack investment):
+
+```bash
+npm install -D webpack webpack-cli copy-webpack-plugin ts-loader
+```
+
+Webpack requires manual entry point configuration for each context. Use `copy-webpack-plugin` to copy `manifest.json`, `_locales/`, and `public/` assets to `dist/`. The manual configuration is verbose; prefer Vite unless the project already uses Webpack.
+
+### Hot Reload: web-ext
+
+`web-ext` is Mozilla's official CLI for extension development. Despite being maintained by Mozilla, it works equally well with Chromium-based browsers.
+
+**Installation:**
+
+```bash
+npm install -D web-ext
+```
+
+**Configuration file (web-ext-config.yml):**
+
+```yaml
+sourceDir: ./dist
+artifactsDir: ./web-ext-artifacts
+build:
+  overwriteDest: true
+run:
+  firefox: '/Applications/Firefox.app/Contents/MacOS/firefox'
+  # For Chrome:
+  # chromiumBinary: '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
+  # chromiumProfile: ./dev-profile
+  startUrl:
+    - about:newtab
+  watchFiles:
+    - dist/**/*
+```
+
+**Development workflow with web-ext:**
+
+```json
+// package.json scripts
+{
+  "scripts": {
+    "dev": "vite build --watch & web-ext run --config web-ext-config.yml",
+    "build": "vite build",
+    "build:watch": "vite build --watch",
+    "start:chrome": "web-ext run --target chromium --config web-ext-config.yml",
+    "start:firefox": "web-ext run --target firefox --config web-ext-config.yml"
+  }
+}
+```
+
+`vite build --watch` rebuilds `dist/` on every source change. `web-ext run --config web-ext-config.yml` watches `dist/` and reloads the extension in the browser when the built files change. Together they form a full hot-reload loop.
+
+**What web-ext does on reload:**
+- Reloads the extension manifest and background service worker.
+- Reloads all open popup instances.
+- Content scripts on already-open tabs are NOT automatically re-injected — you must navigate to a new page or manually reload the tab to test content script changes.
+
+### Hot Reload: crx-hotreload
+
+For Chrome-only development, `crx-hotreload` is a lightweight alternative that adds hot reload by injecting a small background script into your extension:
+
+```bash
+npm install -D crx-hotreload
+```
+
+Add the hot reload script to your manifest in development:
+
+```json
+// manifest.json (development variant)
+{
+  "background": {
+    "service_worker": "background.js"
+  }
+}
+```
+
+```typescript
+// background/index.ts
+if (process.env.NODE_ENV === 'development') {
+  // crx-hotreload polls for dist/ changes and triggers extension reload
+  import('crx-hotreload');
+}
+```
+
+`crx-hotreload` is simpler than `web-ext` but Chrome-only and does not handle Firefox or cross-browser testing.
+
+### Browser Launch Configuration
+
+**Loading an unpacked extension in Chrome:**
+1. Navigate to `chrome://extensions`.
+2. Enable "Developer mode" (top-right toggle).
+3. Click "Load unpacked" and select the `dist/` directory.
+4. Note the assigned extension ID — it changes if you remove and re-add the extension, which breaks `chrome.runtime.getURL()` calls that embed the ID.
+
+**Persistent dev profile for Chrome:**
+
+Using a dedicated Chrome profile for development prevents the extension from interfering with your daily browsing and keeps the dev extension ID stable:
+
+```bash
+# Launch Chrome with a dedicated dev profile
+"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+  --user-data-dir="$(pwd)/.dev-profile" \
+  --load-extension="$(pwd)/dist" \
+  --no-first-run
+```
+
+Add this to a `scripts/dev-chrome.sh` helper. The `--load-extension` flag auto-loads the extension at browser start, skipping the manual "Load unpacked" step.
+
+**Loading in Firefox:**
+
+```bash
+# Temporary install (survives until browser restart)
+web-ext run --source-dir ./dist --firefox firefox
+
+# Or via about:debugging
+# Navigate to about:debugging → This Firefox → Load Temporary Add-on
+# Select dist/manifest.json
+```
+
+Temporary installs in Firefox are removed when the browser restarts. For persistent dev installs, create a signed development build via `web-ext build` and install the `.zip` as a permanent add-on.
+
+### Environment Variables and Build Modes
+
+Use Vite's mode system to separate development and production builds:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+
+export default defineConfig(({ mode }) => ({
+  define: {
+    __DEV__: mode === 'development',
+    __EXT_VERSION__: JSON.stringify(process.env.npm_package_version),
+  },
+  build: {
+    sourcemap: mode === 'development' ? 'inline' : false,
+    minify: mode !== 'development',
+  },
+}));
+```
+
+**Never ship development-only code to the store.** Use `__DEV__` guards around logging, hot-reload imports, and debug panels. Dead-code elimination in the production build will strip guarded code when `__DEV__` is `false`.
+
+### TypeScript Configuration for Extension Contexts
+
+```json
+// tsconfig.json (base)
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "types": ["chrome"]
+  }
+}
+```
+
+```json
+// tsconfig.background.json (service worker — no DOM)
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "lib": ["ES2022", "WebWorker"],
+    "types": ["chrome"]
+  },
+  "include": ["src/background/**/*", "src/shared/**/*"]
+}
+```
+
+```json
+// tsconfig.content.json (content scripts — DOM access)
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "lib": ["ES2022", "DOM"],
+    "types": ["chrome"]
+  },
+  "include": ["src/content/**/*", "src/shared/**/*"]
+}
+```
+
+Install the Chrome types package: `npm install -D @types/chrome`. This provides full type definitions for the `chrome.*` API namespace across all contexts.