@zigrivers/scaffold 3.8.0 → 3.9.0

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

@@ -0,0 +1,220 @@
+---
+name: browser-extension-manifest
+description: Manifest V3 schema, permissions declarations, host_permissions, content_scripts configuration, and background service_worker setup
+topics: [browser-extension, manifest, manifest-v3, permissions, content-scripts, service-worker, host-permissions]
+---
+
+The `manifest.json` is the contract between your extension and the browser. Every capability your extension uses must be declared here before it can be used. Manifest V3 (MV3) is the current standard, having replaced Manifest V2 (MV2) in Chrome. Understanding the MV3 schema in depth prevents runtime errors, store rejections, and security review failures.
+
+## Summary
+
+Manifest V3 separates `permissions` (API access) from `host_permissions` (URL access), requires a service worker instead of a background page, restricts remote code execution, and requires `web_accessible_resources` to include a `matches` field. Declare the minimum required permissions. Use `optional_permissions` and `optional_host_permissions` for features not needed by all users. The `action` key replaces `browser_action`. All `content_scripts` must declare their `matches` precisely.
+
+## Deep Guidance
+
+### Minimal Valid Manifest V3
+
+```json
+{
+  "manifest_version": 3,
+  "name": "__MSG_extensionName__",
+  "version": "1.0.0",
+  "description": "__MSG_extensionDescription__",
+  "short_name": "__MSG_extensionShortName__",
+  "default_locale": "en",
+
+  "action": {
+    "default_popup": "popup/index.html",
+    "default_icon": {
+      "16": "icons/icon-16.png",
+      "32": "icons/icon-32.png",
+      "48": "icons/icon-48.png",
+      "128": "icons/icon-128.png"
+    },
+    "default_title": "__MSG_actionTitle__"
+  },
+
+  "background": {
+    "service_worker": "background.js",
+    "type": "module"
+  },
+
+  "content_scripts": [
+    {
+      "matches": ["https://*.example.com/*"],
+      "js": ["content.js"],
+      "css": ["content.css"],
+      "run_at": "document_idle"
+    }
+  ],
+
+  "permissions": ["storage", "alarms"],
+  "host_permissions": ["https://*.example.com/*"],
+
+  "options_page": "options/index.html",
+
+  "icons": {
+    "16": "icons/icon-16.png",
+    "32": "icons/icon-32.png",
+    "48": "icons/icon-48.png",
+    "128": "icons/icon-128.png"
+  }
+}
+```
+
+### permissions Field
+
+`permissions` grants access to Chrome extension APIs. Declare only the APIs your extension actually calls:
+
+| Permission | Grants access to |
+|---|---|
+| `storage` | `chrome.storage.local`, `chrome.storage.sync`, `chrome.storage.session` |
+| `alarms` | `chrome.alarms` (recurring background tasks) |
+| `tabs` | `chrome.tabs` (tab URL, title, favicon — triggers install warning) |
+| `activeTab` | Active tab URL/content on user gesture (no install warning) |
+| `contextMenus` | `chrome.contextMenus` (right-click menu items) |
+| `notifications` | `chrome.notifications` |
+| `identity` | `chrome.identity` (OAuth2 flow) |
+| `webRequest` | `chrome.webRequest` (intercept requests — high scrutiny) |
+| `declarativeNetRequest` | `chrome.declarativeNetRequest` (rule-based request blocking) |
+| `scripting` | `chrome.scripting.executeScript` (inject scripts programmatically) |
+| `history` | `chrome.history` (browsing history access) |
+| `bookmarks` | `chrome.bookmarks` |
+| `cookies` | `chrome.cookies` |
+| `downloads` | `chrome.downloads` |
+
+**activeTab vs tabs:** Prefer `activeTab` over `tabs`. `activeTab` grants temporary access to the current tab URL and content only when the user explicitly invokes the extension (toolbar click, keyboard shortcut, context menu). It does not trigger an install-time warning and does not grant persistent access. Use `tabs` only when you need to enumerate all tabs or access tab information without a user gesture.
+
+### host_permissions Field
+
+`host_permissions` controls which URLs the extension can access via content scripts, `fetch()` from the background, or `chrome.tabs.executeScript()`.
+
+```json
+"host_permissions": [
+  "https://api.myservice.com/*",
+  "https://*.example.com/*"
+]
+```
+
+**Match pattern syntax:**
+
+- `https://example.com/*` — Only `example.com`, HTTPS only.
+- `https://*.example.com/*` — All subdomains of `example.com`, HTTPS only.
+- `https://example.com/path/*` — Only paths under `/path/`.
+- `*://example.com/*` — Both HTTP and HTTPS.
+- `<all_urls>` — Every URL. Triggers maximum-severity install warning. Avoid unless the use case is genuinely broad (ad blockers, password managers, reading mode).
+
+**Optional host permissions** reduce the install-time permission scope and request access contextually:
+
+```json
+"optional_host_permissions": ["https://*.github.com/*"]
+```
+
+```typescript
+// Request at runtime when the user enables the GitHub integration
+const granted = await chrome.permissions.request({
+  origins: ['https://*.github.com/*'],
+});
+```
+
+### content_scripts Configuration
+
+Content scripts are injected into matching pages according to their declaration in `manifest.json`.
+
+```json
+"content_scripts": [
+  {
+    "matches": ["https://*.example.com/*"],
+    "exclude_matches": ["https://example.com/admin/*"],
+    "js": ["content.js"],
+    "css": ["content.css"],
+    "run_at": "document_idle",
+    "all_frames": false,
+    "world": "ISOLATED"
+  }
+]
+```
+
+**run_at options:**
+- `"document_start"` — Injected before any DOM is built. Useful for blocking scripts from loading. High risk of performance impact.
+- `"document_end"` — Injected after DOM is ready but before sub-resources (images, stylesheets) finish loading.
+- `"document_idle"` — (Default) Injected after `DOMContentLoaded` and when the page is "idle." Best choice for most extensions.
+
+**world options (MV3 Chrome 102+):**
+- `"ISOLATED"` — (Default) Content script runs in the isolated JavaScript world. Cannot access page's JavaScript variables.
+- `"MAIN"` — Content script runs in the page's JavaScript world. Can access page variables and global state. Use only when you must interact with the page's JavaScript API. Increases security risk.
+
+**all_frames:** Set to `true` to inject into iframes on matching pages. Default is `false`. Only enable if the extension's functionality is needed within iframes.
+
+**Programmatic injection with chrome.scripting:**
+
+For content scripts that should only be injected on user demand (not all matching pages):
+
+```typescript
+// Background — inject only when user requests it
+chrome.action.onClicked.addListener(async (tab) => {
+  if (!tab.id) return;
+  await chrome.scripting.executeScript({
+    target: { tabId: tab.id },
+    files: ['content.js'],
+  });
+  await chrome.scripting.insertCSS({
+    target: { tabId: tab.id },
+    files: ['content.css'],
+  });
+});
+```
+
+Programmatic injection requires the `scripting` permission and appropriate `host_permissions` for the target URL.
+
+### background.service_worker
+
+```json
+"background": {
+  "service_worker": "background.js",
+  "type": "module"
+}
+```
+
+`"type": "module"` enables ES module syntax (`import`/`export`) in the service worker. Recommended for TypeScript projects since the bundler outputs ES modules. Without this field, the service worker is treated as a classic script.
+
+**MV2 to MV3 migration notes:**
+
+- MV2 `"background": { "scripts": [...] }` → MV3 `"background": { "service_worker": "..." }`.
+- MV2 background pages are persistent. MV3 service workers are not. State in global variables will be lost.
+- `chrome.browserAction` → `chrome.action`.
+- `chrome.pageAction` → `chrome.action` (with `show_matches` / `hide_matches`).
+- Remote code execution (`eval`, remote `<script>` tags, `new Function()` from remote strings) is prohibited in MV3.
+
+### web_accessible_resources
+
+Resources that content scripts or host pages need to load from the extension package:
+
+```json
+"web_accessible_resources": [
+  {
+    "resources": ["images/*.png", "fonts/*.woff2"],
+    "matches": ["https://*.example.com/*"]
+  },
+  {
+    "resources": ["sandbox.html"],
+    "matches": ["<all_urls>"]
+  }
+]
+```
+
+The `matches` field is required in MV3 (optional in MV2). Restricting `matches` to only the pages that need the resources limits the attack surface — arbitrary pages cannot load the extension's resources unless they match. Use `"<all_urls>"` only for resources that genuinely need to be accessible from any page.
+
+Access declared resources in content scripts with `chrome.runtime.getURL('images/logo.png')`.
+
+### Version Management
+
+```json
+"version": "1.4.2",
+"version_name": "1.4.2 Beta"
+```
+
+- `version` — Machine-readable four-part version used by the store for update detection. Must be strictly greater than the previous published version to be accepted as an update.
+- `version_name` — Human-readable display name shown in the extensions management page. Optional; defaults to `version` if omitted.
+
+Automate version synchronization between `manifest.json` and `package.json` with a build script that reads `package.json` version and writes it to `manifest.json` before building.

package/content/knowledge/browser-extension/browser-extension-project-structure.md

@@ -0,0 +1,183 @@
+---
+name: browser-extension-project-structure
+description: Directory layout for browser extensions covering src/popup, src/content, src/background, src/options, public/icons, and _locales
+topics: [browser-extension, project-structure, file-organization, build, icons]
+---
+
+Browser extension project structure must account for multiple compilation targets (one bundle per execution context), static assets that bypass the build pipeline, and locale files consumed by the WebExtensions runtime. A well-organized project structure makes build configuration straightforward, keeps context-specific code isolated, and prevents accidentally importing browser APIs that are unavailable in a given context.
+
+## Summary
+
+Browser extension projects organize source code by execution context (`src/background/`, `src/content/`, `src/popup/`, `src/options/`), share cross-context code via `src/shared/`, serve static assets and icons from `public/`, store locale strings in `_locales/`, and output all built artifacts to `dist/`. The build tool (Vite or Webpack) is configured with multiple entry points — one per context. The `manifest.json` lives at the root and references compiled output paths.
+
+## Deep Guidance
+
+### Top-Level Directory Layout
+
+```
+my-extension/
+  src/                     # All TypeScript/JavaScript source
+  public/                  # Static assets copied verbatim to dist/
+  _locales/                # WebExtensions i18n message files
+  manifest.json            # Extension manifest (source of truth)
+  dist/                    # Build output (gitignored)
+  tests/                   # Unit and integration tests
+  scripts/                 # Build and release helper scripts
+  package.json
+  tsconfig.json
+  vite.config.ts           # (or webpack.config.ts)
+```
+
+**Key decisions at this level:**
+- `manifest.json` is a source file, not generated. Keep it at the root and have the build tool copy it to `dist/` with any environment-specific substitutions applied.
+- `dist/` is always gitignored. It is a build artifact, not source.
+- `public/` contains files that are copied as-is without processing — icons, web-accessible static HTML, third-party JS files that must not be bundled.
+
+### src/ — Source Organized by Execution Context
+
+```
+src/
+  background/
+    index.ts               # Service worker entry point
+    message-router.ts      # Central message dispatch
+    handlers/
+      tab-handlers.ts
+      storage-handlers.ts
+      alarm-handlers.ts
+    alarms.ts              # Alarm registration
+    install.ts             # onInstalled handler (first-run setup)
+
+  content/
+    index.ts               # Content script entry point
+    injectors/
+      overlay-injector.ts  # Injects UI overlays into the host page
+      banner-injector.ts
+    observers/
+      dom-observer.ts      # MutationObserver for dynamic pages
+    styles/
+      content.css          # Styles injected alongside content scripts
+
+  popup/
+    index.html             # Popup page HTML (references compiled JS)
+    index.ts               # Popup entry point
+    App.tsx                # Root component (if using React)
+    components/
+      Toggle.tsx
+      StatusBadge.tsx
+    hooks/
+      useExtensionState.ts
+
+  options/
+    index.html             # Options page HTML
+    index.ts               # Options page entry point
+    App.tsx
+    components/
+      SettingsForm.tsx
+      PermissionsPanel.tsx
+
+  shared/
+    messages.ts            # Message type constants (used by all contexts)
+    storage.ts             # chrome.storage typed wrappers and key constants
+    types.ts               # Shared TypeScript interfaces
+    constants.ts           # App-wide constants (version, default config)
+    utils/
+      url-helpers.ts
+      sanitizer.ts
+```
+
+**Why isolate by context:**
+- Content scripts run in the page context with restricted API access (no `chrome.tabs`, for example).
+- Service workers have no DOM access and are terminated between events.
+- Popup and options pages are full HTML pages with full API access but a different lifecycle from the service worker.
+- Keeping code per context prevents accidental API calls that are undefined in that context and makes the build configuration's entry points map directly to directories.
+
+### public/ — Static Assets
+
+```
+public/
+  icons/
+    icon-16.png            # 16×16 toolbar icon
+    icon-32.png            # 32×32 (Windows HiDPI toolbar)
+    icon-48.png            # 48×48 (extension management page)
+    icon-128.png           # 128×128 (Chrome Web Store listing)
+  images/
+    logo.svg               # Brand assets for options page
+```
+
+**Icon requirements:**
+- Provide all four sizes (16, 32, 48, 128). Missing sizes cause the browser to scale up smaller icons, producing blurry results.
+- Icons must be PNG. SVG is not supported in `manifest.json` icon fields.
+- Design icons to be recognizable at 16×16 (the smallest size shown in the toolbar). Detailed illustrations fail at this scale.
+- Provide separate icon sets for active and inactive states if the extension toggles on/off — users expect visual feedback.
+- The Chrome Web Store also requires a 440×280 promotional tile and up to 5 screenshots. These belong in a separate `store-assets/` directory at the repo root, not in `public/`.
+
+### _locales/ — Internationalization
+
+```
+_locales/
+  en/
+    messages.json          # English strings (required, used as fallback)
+  es/
+    messages.json
+  fr/
+    messages.json
+  ja/
+    messages.json
+```
+
+The `_locales/` directory must be copied verbatim to `dist/` by the build tool. It is not processed — the WebExtensions runtime reads it directly. Configure your bundler to copy `_locales/` as a static asset.
+
+### dist/ — Build Output
+
+```
+dist/
+  manifest.json            # Copied from root, possibly with env substitutions
+  background.js            # Compiled service worker bundle
+  content.js               # Compiled content script bundle
+  content.css              # Compiled content script stylesheet
+  popup/
+    index.html
+    popup.js
+    popup.css
+  options/
+    index.html
+    options.js
+    options.css
+  icons/                   # Copied from public/icons/
+  _locales/                # Copied from source _locales/
+```
+
+The directory structure in `dist/` must match what `manifest.json` references in its `background.service_worker`, `content_scripts`, and `action.default_popup` fields. Mismatches cause silent failures — the extension loads but the referenced scripts do not execute.
+
+### tests/ Structure
+
+```
+tests/
+  unit/
+    shared/                # Tests for shared utility functions
+    background/            # Unit tests for background handlers
+    content/               # Unit tests for content script logic
+  integration/
+    background.test.ts     # Chrome extension API mocked integration tests
+    popup.test.ts
+  e2e/
+    extension.spec.ts      # Playwright tests with real extension loaded
+```
+
+Test files mirror the source structure. Unit tests for `src/shared/storage.ts` live in `tests/unit/shared/storage.test.ts`. Integration and e2e tests live at their own level because they span multiple contexts.
+
+### Configuration Files at Root
+
+Keep build and tooling configuration files at the root, not inside `src/`:
+
+```
+vite.config.ts             # Multi-entry Vite build config
+tsconfig.json              # Base TypeScript config
+tsconfig.content.json      # Context-specific tsconfig for content scripts (lib: DOM)
+tsconfig.background.json   # Context-specific tsconfig (lib: WebWorker)
+.eslintrc.json
+.prettierrc
+web-ext-config.yml         # web-ext tool configuration for dev/testing
+```
+
+Context-specific `tsconfig` files are important: the service worker uses the `WebWorker` lib (not `DOM`), while content scripts and popup use the `DOM` lib. A single tsconfig targeting both will produce incorrect type checking.

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

@@ -0,0 +1,107 @@
+---
+name: browser-extension-requirements
+description: User permissions model, store policies (Chrome Web Store, AMO), accessibility requirements, and performance budgets for browser extensions
+topics: [browser-extension, requirements, permissions, store-policies, accessibility, performance]
+---
+
+Browser extension requirements differ fundamentally from web app requirements because the extension operates inside a user's browser with elevated trust and broad access to browsing data. Every permission requested must be justified, every store policy must be understood before writing code, and performance budgets must be set early because extensions run on every page a user visits — regressions directly degrade the entire browsing experience.
+
+## Summary
+
+Browser extension requirements center on four domains: permissions (request only what the feature requires, justify each in the store listing), store policies (Chrome Web Store and AMO have distinct review timelines and policy sets that affect architecture decisions), accessibility (popup UIs must meet WCAG 2.1 AA, keyboard-only operation is mandatory), and performance budgets (content scripts add parse time to every page load, service workers must stay under memory limits). Lock these down before implementation to avoid costly store rejections or permission refactors.
+
+## Deep Guidance
+
+### User Permissions Model
+
+The permissions model is the most consequential requirement decision. Every permission granted to an extension represents a promise to the user and a liability in the store review process.
+
+**Permission categories in Manifest V3:**
+
+- `permissions` — Declared API access that is always active (e.g., `storage`, `tabs`, `alarms`, `contextMenus`). Granted at install time with no per-use prompt.
+- `host_permissions` — Access to specific origins or all origins (`<all_urls>`). Triggers a prominent install-time warning. In MV3, these can be made optional via `optional_host_permissions`.
+- `optional_permissions` — APIs requested at runtime via `chrome.permissions.request()`. Prefer optional for features that not all users need.
+
+**Principle of least privilege — apply strictly:**
+
+- Never request `<all_urls>` if you only need `https://api.example.com/*`. Broad host permissions trigger stricter review and user concern.
+- Request `tabs` only if you need tab URL, title, or favicon. If you only need the active tab's content, use `activeTab` instead — it requires no persistent permission and is granted only on explicit user gesture.
+- Audit permissions on every sprint. Remove any permission no longer used by shipping features.
+
+**Sensitive permissions that trigger enhanced review:**
+
+- `webRequest` / `declarativeNetRequest` — Modifying network requests is the highest-scrutiny permission. Justify it explicitly in your store listing.
+- `history` — Access to browsing history requires strong justification.
+- `cookies` — Access to cookies including session tokens requires explicit user-facing documentation of what data is accessed and why.
+- `nativeMessaging` — Communicates with native applications; triggers manual review on CWS.
+
+**Communicating permissions to users:**
+
+- Write a clear Privacy Policy linked in the store listing before submission. Extensions that access user data without a privacy policy are rejected.
+- The store listing description must explain every permission in plain language. "This extension requires access to all websites to block ads" is better than silence.
+
+### Chrome Web Store Policies
+
+The Chrome Web Store (CWS) review process is automated for most submissions but involves manual review for sensitive permissions or policy violations.
+
+**Key policies affecting architecture:**
+
+- **Single purpose policy**: An extension must have a single, clearly described purpose. A "productivity suite" that does 10 unrelated things will be rejected. Define the purpose before writing code.
+- **No remote code execution**: Extensions cannot load and execute remote JavaScript. All logic must be bundled at submission time. This directly prohibits `eval()`, `new Function()`, and dynamic `<script>` injection from remote URLs.
+- **Data use transparency**: Any data collected or transmitted must be disclosed in the Privacy Policy and the Data Use section of the developer console.
+- **Deceptive behavior**: Extensions must not alter user settings (search engine, homepage, new tab page) without explicit opt-in. Implementing a new tab override requires a first-run setup flow where the user explicitly enables it.
+
+**Review timelines:**
+
+- New extensions: 1–3 business days for automated review; manual review can take 1–2 weeks.
+- Updates to existing extensions: typically 24–72 hours.
+- Permission changes in updates trigger re-review and may prompt existing users to re-approve.
+
+**CWS rejection common causes:**
+
+- Requesting permissions not used by any feature in the submitted version.
+- Missing or incomplete Privacy Policy for extensions that access user data.
+- Violating the remote code execution policy (using `eval` in content scripts).
+- Deceptive store listing (screenshots that do not match actual functionality).
+
+### Mozilla Add-ons (AMO) Policies
+
+AMO (addons.mozilla.org) has a more developer-friendly review process but with distinct requirements:
+
+- **Source code review**: AMO reviewers may request the unminified source code for manual inspection. Always submit source maps or the raw source alongside minified builds.
+- **No obfuscation**: Obfuscated code is not permitted. Minification is fine; intentional obfuscation is grounds for rejection.
+- **Listed vs. self-distributed**: AMO-listed extensions receive a full review. Self-distributed (signed but unlisted) extensions receive only automated signing. Most extensions should target listed status.
+- **WebExtensions API compliance**: AMO does not support Manifest V3 features that Chrome added post-specification. Use `webextension-polyfill` and test against the current Firefox ESR.
+
+### Accessibility Requirements
+
+Extension popup UIs are full web interfaces and must meet WCAG 2.1 AA:
+
+- **Keyboard navigation**: Every interactive element must be reachable and operable via keyboard alone. Tab order must be logical. Focus must be visible at all times.
+- **Color contrast**: Text must meet 4.5:1 contrast ratio for normal text, 3:1 for large text. Dark-mode-only extensions are exempt from light-mode contrast checks but must still pass in their target mode.
+- **ARIA roles**: Use semantic HTML first. Add ARIA roles only where semantic HTML is insufficient. Popup UIs are typically small enough that semantic HTML covers all cases.
+- **Screen reader compatibility**: Test with NVDA + Firefox and VoiceOver + Chrome. Extension popups open in a context that screen readers handle differently from regular web pages — verify announce behavior on open.
+
+Content scripts that inject UI into host pages must not break the host page's existing accessibility tree. Use `aria-hidden` on injected containers where appropriate and avoid stealing focus unexpectedly.
+
+### Performance Budgets
+
+Extensions impose a cost on every page load and every browser session. Set explicit budgets before implementation:
+
+**Content script budgets:**
+- Parse + execute time: under 50 ms on a mid-range device for the combined content script bundle.
+- DOM manipulation: defer DOM modifications until `DOMContentLoaded` or later. Synchronous DOM work in `document_start` blocks page render.
+- Bundle size: content script bundle under 100 KB (uncompressed). Prefer tree-shaken, purpose-built code over importing full utility libraries.
+
+**Service worker budgets:**
+- Background service workers are terminated after ~30 seconds of inactivity in Chrome. Design for stateless, event-driven operation.
+- Memory ceiling: Chrome enforces a per-extension memory limit. Keep the service worker footprint under 50 MB. Use `chrome.storage` for persistent state rather than in-memory caches.
+
+**Popup UI budgets:**
+- Popup open-to-interactive: under 300 ms. Popups that block on slow network requests before rendering anything will feel broken.
+- Bundle size: popup bundle under 200 KB. Users open and close popups frequently; fast load matters.
+
+**Measurement:**
+- Profile content scripts with Chrome DevTools Performance panel on a cold-cache page load.
+- Use `chrome.runtime.getBackgroundPage()` (MV2) or service worker `self.performance` metrics to measure background processing time.
+- Run Lighthouse on the popup HTML file directly to catch performance regressions in the UI.