@zigrivers/scaffold 3.8.0 → 3.9.1

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

@@ -0,0 +1,202 @@
+---
+name: browser-extension-security
+description: Content Security Policy for extensions, prohibitions on eval and inline scripts, host permissions principle of least privilege, and XSS prevention in extension UIs
+topics: [browser-extension, security, csp, xss, permissions, least-privilege, eval]
+---
+
+Browser extensions run with elevated browser privileges compared to ordinary web pages. A compromised extension can read browsing history, intercept network requests, steal cookies, and inject content into any page it has permission to access. Security is not optional — it is a first-class requirement enforced by the browser, the store review process, and the trust of every user who installs the extension.
+
+## Summary
+
+Manifest V3 enforces a strict Content Security Policy by default that prohibits `eval()`, `new Function()`, and inline scripts — comply with this unconditionally. Never request more host permissions than features require; prefer `activeTab` over broad host permissions. Extension UI pages (popup, options) are vulnerable to XSS if they render untrusted content — sanitize all dynamic HTML, prefer textContent over innerHTML, and use a trusted types policy where supported. Regularly audit permissions and remove any that are no longer needed.
+
+## Deep Guidance
+
+### Content Security Policy for Extensions
+
+Manifest V3 enforces a strict default CSP for extension pages (popup, options, background):
+
+```
+script-src 'self'; object-src 'self'
+```
+
+This means:
+- No inline `<script>` blocks in popup or options HTML.
+- No `eval()`, `setTimeout("string")`, `new Function("string")`, or any other string-to-code evaluation.
+- No scripts loaded from external URLs.
+- All scripts must be bundled into extension package files referenced by `src=` attributes.
+
+**Customizing the extension CSP** (only add what is absolutely necessary):
+
+```json
+// manifest.json
+{
+  "content_security_policy": {
+    "extension_pages": "script-src 'self'; object-src 'none'",
+    "sandbox": "sandbox allow-scripts; script-src 'self' 'unsafe-eval'"
+  }
+}
+```
+
+`"sandbox"` is a separate policy for sandboxed extension pages. If you need `eval` for a legitimate reason (e.g., a code editor that evaluates JavaScript), use a sandboxed page — `chrome.runtime.getURL('sandbox.html')` — which is isolated from the extension's privileged context.
+
+**Inline scripts prohibition — practical implications:**
+
+```html
+<!-- PROHIBITED — inline script blocked by CSP -->
+<button onclick="doThing()">Click me</button>
+<script>window.onload = function() { init(); }</script>
+
+<!-- CORRECT — event listeners in external JS file -->
+<button id="my-btn">Click me</button>
+<!-- popup.js (bundled, loaded as external file) -->
+```
+
+```typescript
+// popup.ts — attach all event handlers here
+document.getElementById('my-btn')?.addEventListener('click', doThing);
+document.addEventListener('DOMContentLoaded', init);
+```
+
+**Audit your build output:** Run a build in production mode and inspect the output. If your popup HTML contains any `<script>` tags with inline content or `onclick` attributes, your bundler is misconfigured.
+
+### Prohibiting eval and String-to-Code Patterns
+
+`eval()` and related patterns are the primary mechanism for code injection attacks. Manifest V3 prohibits them in extension pages — but you must also avoid them in content scripts (where they would be prohibited by the host page's CSP in `document_start` injection, and represent a security risk in any injection mode).
+
+**Patterns to avoid:**
+
+```typescript
+// PROHIBITED
+eval('doThing()');
+setTimeout('doThing()', 1000);  // String argument form only
+setInterval('doThing()', 1000);
+new Function('return doThing()')();
+document.write('<script>doThing()</script>'); // DOM-based code injection
+
+// Safe alternative
+setTimeout(doThing, 1000);  // Function reference
+setInterval(doThing, 1000);
+```
+
+**Dynamic template rendering without eval:**
+
+If you need to render dynamic content (e.g., user-defined templates), use a CSP-compliant template engine that does not use `eval`. Mustache, Handlebars (with the `noEscape` option disabled), or a custom string-interpolation function all work without `eval`.
+
+### Host Permissions: Principle of Least Privilege
+
+Every host permission you declare expands the attack surface of the extension. A compromised extension with `<all_urls>` can inject code into banking websites, steal session cookies from any domain, and exfiltrate browsing history.
+
+**Permission escalation order (prefer the lowest that works):**
+
+1. **No host permission** — Works for extensions that only modify the browser UI (new tab page, toolbar button with popup) without touching page content.
+2. **`activeTab`** — Grants access to the current tab's URL and content only when the user explicitly invokes the extension. No install-time warning. No persistent access. Best for "apply this action to the current page" use cases.
+3. **Specific origins** — `"host_permissions": ["https://api.example.com/*"]` — Access only to the declared origins. For extensions that call a specific backend API from content scripts.
+4. **Pattern-based** — `"https://*.github.com/*"` — All subdomains of a specific domain. For extensions that enhance a specific service.
+5. **`<all_urls>`** — Access to every URL. Only justifiable for: ad blockers, password managers, developer tools, reading mode, and similar utilities that genuinely need to operate on any site.
+
+**Optional host permissions for progressive disclosure:**
+
+```json
+// manifest.json
+{
+  "optional_host_permissions": ["https://*.github.com/*", "https://*.gitlab.com/*"]
+}
+```
+
+```typescript
+// Request GitHub permission when user enables GitHub integration
+async function enableGitHubIntegration(): Promise<boolean> {
+  return chrome.permissions.request({
+    origins: ['https://*.github.com/*'],
+  });
+}
+
+// Check before using
+async function isGitHubAccessGranted(): Promise<boolean> {
+  return chrome.permissions.contains({
+    origins: ['https://*.github.com/*'],
+  });
+}
+```
+
+Progressive permission requests reduce the number of users who abandon the install due to scary permission warnings, and follow the principle of least privilege by only requesting what the user actively needs.
+
+### XSS Prevention in Extension UIs
+
+Extension popup and options pages are HTML documents that can render dynamic content. If that content includes unsanitized user-controlled strings or data from web pages, XSS is possible — and in an extension context, XSS in a privileged page means XSS with full `chrome.*` API access.
+
+**The core rule: never use innerHTML with untrusted content.**
+
+```typescript
+// DANGEROUS — XSS if pageTitle contains <script> or event handlers
+element.innerHTML = `<div class="title">${pageTitle}</div>`;
+
+// Safe — textContent is never interpreted as HTML
+const titleEl = document.createElement('div');
+titleEl.className = 'title';
+titleEl.textContent = pageTitle;
+element.appendChild(titleEl);
+
+// Also safe — explicit sanitization
+import DOMPurify from 'dompurify';
+element.innerHTML = DOMPurify.sanitize(htmlContent);
+```
+
+**DOMPurify for legitimate HTML rendering:**
+
+When you genuinely need to render HTML from a trusted but potentially malicious source (e.g., a page's meta description):
+
+```typescript
+import DOMPurify from 'dompurify';
+
+// Sanitize before rendering
+const clean = DOMPurify.sanitize(userHtml, {
+  ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'p', 'br'],
+  ALLOWED_ATTR: [],  // No attributes — prevents event handler injection
+});
+element.innerHTML = clean;
+```
+
+**Content retrieved from web pages:** Any data that comes from a web page — tab title, page content, metadata, cookies — must be treated as potentially malicious. Apply the same sanitization discipline you would apply to user input in a web application.
+
+**Message data from postMessage:** Content received via `window.postMessage` from page scripts must be treated as untrusted. Never render raw postMessage data as HTML.
+
+### Securing Cross-Context Communication
+
+**Validate message senders:**
+
+```typescript
+chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+  // Reject messages from web pages (non-extension senders)
+  if (!sender.id || sender.id !== chrome.runtime.id) {
+    console.warn('Message from unexpected sender:', sender);
+    return;
+  }
+
+  // Process message from known extension context
+  handleMessage(message, sender, sendResponse);
+});
+```
+
+**Be cautious with tabs.sendMessage targets:**
+
+When using `chrome.tabs.sendMessage` to push data to a content script, a malicious page may have replaced the content script's context. Validate the sender in the content script:
+
+```typescript
+// Content script — validate incoming messages from background
+chrome.runtime.onMessage.addListener((message, sender) => {
+  // Only accept messages from the extension itself
+  if (sender.id !== chrome.runtime.id) return;
+  handleBackgroundMessage(message);
+});
+```
+
+### Secrets and API Keys
+
+Never bundle API secrets or private keys in extension source code:
+
+- Extension source code is accessible to any user who installs it (via `chrome://extensions` → source in developer mode, or by unpacking the CRX/ZIP file).
+- The Chrome Web Store stores submitted ZIP files — assume the contents are readable.
+- Use a backend proxy service for API calls requiring secret credentials. The extension authenticates to your backend; your backend authenticates to the third-party API.
+- If a third-party API supports per-user OAuth tokens, use `chrome.identity.getAuthToken()` or the full OAuth2 flow — user tokens are not bundled secrets.

package/content/knowledge/browser-extension/browser-extension-service-workers.md

@@ -0,0 +1,265 @@
+---
+name: browser-extension-service-workers
+description: Extension service worker lifecycle (install/activate), event-driven programming model, alarms API for recurring tasks, and persistent state via chrome.storage
+topics: [browser-extension, service-worker, lifecycle, alarms, chrome-storage, event-driven, background]
+---
+
+The Manifest V3 background service worker is the most architecturally disruptive change from MV2. The persistent background page that could hold state indefinitely is gone. Service workers are event-driven and ephemeral — Chrome terminates them when idle and restarts them when events arrive. Every design decision for background logic must account for this constraint.
+
+## Summary
+
+Extension service workers follow a lifecycle of install, activate, and per-event wake-up/terminate cycles. All persistent state must be in `chrome.storage` — never rely on module-level variables surviving between events. Use `chrome.alarms` for recurring background tasks (never `setInterval`). Listen for `chrome.runtime.onInstalled` to perform first-run setup and migration. Structure the service worker as a pure event dispatcher that routes to handler functions, keeping the top-level script lean so it parses and registers listeners quickly on each wake-up.
+
+## Deep Guidance
+
+### Service Worker Lifecycle
+
+The extension service worker has three lifecycle phases:
+
+**1. Install**
+
+Fires once when the extension is first installed or when an update changes the service worker script. This is where you set default state:
+
+```typescript
+chrome.runtime.onInstalled.addListener(async ({ reason, previousVersion }) => {
+  switch (reason) {
+    case chrome.runtime.OnInstalledReason.INSTALL:
+      // First-time install — set defaults
+      await chrome.storage.sync.set({
+        enabled: true,
+        theme: 'auto',
+        blocklist: [],
+      });
+      // Open onboarding page
+      await chrome.tabs.create({
+        url: chrome.runtime.getURL('options/index.html?onboarding=true'),
+      });
+      break;
+
+    case chrome.runtime.OnInstalledReason.UPDATE:
+      // Extension updated — run migration if needed
+      if (previousVersion && isOlderThan(previousVersion, '2.0.0')) {
+        await migrateV1ToV2();
+      }
+      break;
+
+    case chrome.runtime.OnInstalledReason.CHROME_UPDATE:
+      // Chrome updated — rarely needs handling
+      break;
+  }
+});
+```
+
+**2. Activate**
+
+For extension service workers, `activate` fires immediately after `install`. In the web service worker model, `activate` is used for cache cleanup; extension service workers rarely need custom `activate` logic. Chrome handles the transition automatically.
+
+**3. Event-driven execution**
+
+After install/activate, the service worker is idle. Chrome terminates it after 30 seconds of inactivity. It is restarted when:
+- A message arrives via `chrome.runtime.onMessage` or a port connection via `chrome.runtime.onConnect`.
+- An alarm fires via `chrome.alarms.onAlarm`.
+- A browser event fires: `chrome.tabs.onActivated`, `chrome.tabs.onUpdated`, `chrome.storage.onChanged`, etc.
+- The user clicks the extension action (toolbar button).
+
+**Critical implication:** Every event handler must be registered at the top level of the service worker script, not inside async callbacks or deferred initialization. Chrome only keeps the service worker alive long enough to process the current event — if a listener is registered in a `setTimeout` or inside a `Promise.then`, it may never execute because the service worker was terminated before the deferred code ran.
+
+### Event-Driven Architecture Pattern
+
+The service worker entry point should be a lean dispatcher. Heavy logic belongs in imported handler modules:
+
+```typescript
+// background/index.ts — the service worker entry point
+
+// Import handlers (all imports resolve synchronously at parse time)
+import { handleMessage } from './message-router';
+import { handleAlarm } from './alarm-handlers';
+import { handleTabUpdate } from './tab-handlers';
+import { handleInstalled } from './install';
+
+// Register ALL event listeners at the TOP LEVEL immediately
+// Chrome requires listeners to be registered synchronously during
+// the service worker's initial execution
+chrome.runtime.onInstalled.addListener(handleInstalled);
+chrome.runtime.onMessage.addListener(handleMessage);
+chrome.alarms.onAlarm.addListener(handleAlarm);
+chrome.tabs.onUpdated.addListener(handleTabUpdate);
+
+// DO NOT do this — the listener may never be registered
+async function init() {
+  await loadConfig(); // ← If this takes time, Chrome may terminate the SW first
+  chrome.runtime.onMessage.addListener(handleMessage); // ← Never reached
+}
+init();
+```
+
+**Message router pattern:**
+
+```typescript
+// background/message-router.ts
+export function handleMessage(
+  message: ExtensionMessage,
+  sender: chrome.runtime.MessageSender,
+  sendResponse: (response?: unknown) => void,
+): boolean | undefined {
+  switch (message.type) {
+    case Messages.POPUP_GET_STATUS:
+      getStatus().then(sendResponse);
+      return true; // Async response
+
+    case Messages.POPUP_TOGGLE_ENABLED:
+      toggleEnabled(message.payload.enabled).then(() => sendResponse());
+      return true;
+
+    case Messages.CONTENT_PAGE_LOADED:
+      handlePageLoaded(message.payload, sender.tab?.id);
+      // No response needed — fall through (returns undefined → synchronous)
+      break;
+
+    default:
+      console.warn('Unhandled message type:', message.type);
+  }
+}
+```
+
+### Avoiding State Loss on Service Worker Termination
+
+**Anti-pattern — in-memory cache:**
+
+```typescript
+// WRONG — this cache is lost when the service worker is terminated
+const configCache = new Map<string, SiteConfig>();
+
+chrome.runtime.onMessage.addListener((message) => {
+  if (message.type === Messages.CONTENT_REQUEST_CONFIG) {
+    // May return undefined if SW was terminated and cache was cleared
+    return configCache.get(message.payload.url);
+  }
+});
+```
+
+**Correct pattern — always read from storage:**
+
+```typescript
+// CORRECT — storage persists across service worker terminations
+chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {
+  if (message.type === Messages.CONTENT_REQUEST_CONFIG) {
+    getConfigForUrl(message.payload.url).then(sendResponse);
+    return true;
+  }
+});
+
+async function getConfigForUrl(url: string): Promise<SiteConfig | null> {
+  const { sitesConfig } = await chrome.storage.sync.get('sitesConfig');
+  return sitesConfig?.find((c: SiteConfig) => urlMatches(url, c.pattern)) ?? null;
+}
+```
+
+**chrome.storage.session for within-session state:**
+
+Chrome 102+ provides `chrome.storage.session` — storage that persists across service worker restarts within a browser session but is cleared when the browser closes:
+
+```typescript
+// Track whether we're mid-operation, survives SW restart within session
+await chrome.storage.session.set({ processingTabId: tabId });
+
+// On SW restart, check if interrupted work needs resuming
+const { processingTabId } = await chrome.storage.session.get('processingTabId');
+if (processingTabId) {
+  await resumeProcessing(processingTabId);
+}
+```
+
+### Alarms API for Recurring Tasks
+
+`setInterval` and `setTimeout` do not survive service worker termination. Use `chrome.alarms` for any recurring background work.
+
+**Registering alarms (must be idempotent):**
+
+```typescript
+// Register in onInstalled AND when the service worker starts up
+// (In case alarms were cleared by a browser update)
+async function ensureAlarmsRegistered(): Promise<void> {
+  const existing = await chrome.alarms.get('sync-check');
+  if (!existing) {
+    chrome.alarms.create('sync-check', {
+      periodInMinutes: 15,
+      delayInMinutes: 1, // First fire after 1 minute
+    });
+  }
+
+  const existingDaily = await chrome.alarms.get('daily-cleanup');
+  if (!existingDaily) {
+    chrome.alarms.create('daily-cleanup', {
+      periodInMinutes: 60 * 24,
+      when: Date.now() + 60 * 60 * 1000, // First fire in 1 hour
+    });
+  }
+}
+
+// Call on install and at service worker startup
+chrome.runtime.onInstalled.addListener(ensureAlarmsRegistered);
+// Also call when SW starts (in case alarms were lost)
+ensureAlarmsRegistered();
+```
+
+**Alarm handler:**
+
+```typescript
+chrome.alarms.onAlarm.addListener(async (alarm) => {
+  switch (alarm.name) {
+    case 'sync-check':
+      await performSyncCheck();
+      break;
+    case 'daily-cleanup':
+      await performDailyCleanup();
+      break;
+    default:
+      console.warn('Unknown alarm:', alarm.name);
+  }
+});
+```
+
+**Minimum alarm interval:** Chrome enforces a minimum alarm interval of 1 minute (or 30 seconds in some contexts). Do not attempt sub-minute recurring tasks with alarms — use a polling loop within a single alarm handler if sub-minute work is needed, and be aware this will keep the service worker alive.
+
+### Keeping the Service Worker Alive for Long Operations
+
+For long-running operations that must not be interrupted (e.g., downloading and processing a large file), use strategies to prevent premature termination:
+
+**Strategy 1 — Chain promises to stay active:**
+
+Chrome extends the service worker's lifetime as long as there are pending promises created within the current event handler. Keep a promise chain alive for the duration of the work:
+
+```typescript
+chrome.runtime.onMessage.addListener((_msg, _sender, sendResponse) => {
+  // The returned `true` and the pending `sendResponse` keep the SW alive
+  runLongOperation()
+    .then(result => sendResponse({ success: true, result }))
+    .catch(err => sendResponse({ success: false, error: err.message }));
+  return true;
+});
+```
+
+**Strategy 2 — Use the service worker's `waitUntil` equivalent:**
+
+Extension service workers do not have `event.waitUntil()` like web service workers. The closest equivalent is to keep an event's `sendResponse` callback pending, or to hold a port connection open.
+
+**Strategy 3 — Checkpoint progress to storage:**
+
+For operations that genuinely need more time than the service worker lifetime allows, checkpoint progress to `chrome.storage.session` and resume on the next alarm or message:
+
+```typescript
+async function processInChunks(items: Item[]): Promise<void> {
+  const { processedIndex = 0 } = await chrome.storage.session.get('processedIndex');
+
+  for (let i = processedIndex; i < items.length; i++) {
+    await processItem(items[i]);
+    // Checkpoint every 10 items in case SW is terminated
+    if (i % 10 === 0) {
+      await chrome.storage.session.set({ processedIndex: i });
+    }
+  }
+
+  await chrome.storage.session.remove('processedIndex');
+}
+```

package/content/knowledge/browser-extension/browser-extension-store-submission.md

@@ -0,0 +1,155 @@
+---
+name: browser-extension-store-submission
+description: Chrome Web Store review process, AMO submission, screenshot and promotional image requirements, listing optimization, and managing version updates
+topics: [browser-extension, store-submission, chrome-web-store, amo, listing-optimization, review-process, screenshots]
+---
+
+Store submission is the deployment step for browser extensions. Unlike web applications where you push to a server, extensions must pass store review before reaching users. Review timelines, policy requirements, and listing quality directly affect user acquisition and approval success. Understanding the process before writing the first line of code prevents costly late-stage pivots.
+
+## Summary
+
+Chrome Web Store review takes 1–3 days for automated review, up to 2 weeks for manual review triggered by sensitive permissions. AMO (Mozilla Add-ons) requires source code submission alongside minified builds and enforces a no-obfuscation policy. Store listing quality (screenshots, descriptions, icon) significantly affects organic search and conversion. Version updates that add or change permissions trigger re-review. Prepare all store assets before the first submission to avoid resubmission delays.
+
+## Deep Guidance
+
+### Chrome Web Store Review Process
+
+The Chrome Web Store has a two-tier review system:
+
+**Automated review (most extensions):**
+- Triggered for extensions without sensitive permissions.
+- Typically completes in 1–3 business days.
+- Checks for policy violations: remote code execution, deceptive behavior, malware patterns.
+- An extension that passes automated review is published automatically.
+
+**Manual review (sensitive permissions or policy concerns):**
+- Triggered by: `webRequest`, `nativeMessaging`, `history`, `cookies`, `unlimitedStorage`, `<all_urls>` or very broad host patterns, and any permission not commonly seen.
+- Also triggered by: policy violation flags, user reports, or random sampling of extensions.
+- Takes 1–4 weeks. During this period, your extension is "pending review" and not publicly accessible.
+- Reviewers may request additional justification via email. Respond within 5 business days or the review is cancelled.
+
+**New developer accounts** face stricter scrutiny. New accounts submitting extensions with sensitive permissions often go to manual review regardless of the permissions requested. Plan for a 2-week review window for a new developer account's first submission.
+
+**Preparing for review:**
+- Write a detailed "Single Purpose" description in the "Developer Notes" field in the developer console. Explain exactly what each permission is used for.
+- Every permission must be clearly mentioned in the public store description.
+- The extension must work as described. Reviewers install and test extensions.
+- If the extension requires authentication or a specific URL to function, provide test credentials in the Developer Notes.
+
+### AMO (Mozilla Add-ons) Submission
+
+AMO review differs significantly from Chrome's process:
+
+**Source code submission:**
+- When submitting a minified/bundled extension, AMO requires the corresponding source code so reviewers can audit the logic.
+- Submit a ZIP of your source code alongside the extension ZIP.
+- Include a `build.md` with exact instructions to reproduce the submitted build from source.
+- Reviewers execute your build instructions and compare the output to the submitted artifacts. If the build does not reproduce, the submission is rejected.
+
+**No obfuscation policy:**
+- Minification (whitespace removal, variable shortening) is acceptable.
+- Obfuscation (intentionally making code unreadable with tools like obfuscator.io) is grounds for rejection.
+- Webpack/Vite production builds are acceptable — their output is minified but not obfuscated.
+
+**Review timeline:**
+- New extensions: 1–2 weeks for full review.
+- Updates to reviewed extensions: Can be faster if no new permissions are added.
+- Extensions with high install counts receive priority review for security updates.
+
+**Listing vs. self-distribution:**
+- AMO-listed extensions are reviewed, signed, and discoverable in the Firefox add-ons store.
+- Self-distributed extensions are signed by Mozilla (required for permanent install in Firefox) but not reviewed or listed.
+- Choose "Listed" for all consumer-facing extensions. "Self-distributed" is for enterprise or internal extensions.
+
+### Extension Icon Requirements
+
+Store icons must meet specific requirements to avoid rejection or poor presentation:
+
+**Manifest icons (required):**
+- 16×16 — Toolbar button (the most important size — must be recognizable at this scale).
+- 32×32 — Windows HiDPI toolbar; extension management page.
+- 48×48 — Extension management page (`chrome://extensions`).
+- 128×128 — Chrome Web Store listing page.
+
+**Chrome Web Store store icon:**
+- 128×128 PNG — Separate from the manifest icon, uploaded in the developer console.
+- Must not have rounded corners (Chrome applies rounding in the store UI).
+- Must not contain text if the text is too small to read at 128×128.
+
+**Firefox icon:**
+- AMO accepts PNG or SVG for the store icon.
+- Recommended: submit SVG for the store icon; PNG for manifest icons.
+
+**Design for legibility at 16×16:** The toolbar icon at 16×16 is the primary user-facing brand element of your extension. A complex illustration or thin text will be unrecognizable. Use simple, bold shapes and high contrast. Test actual rendering at 16×16 before finalizing.
+
+### Screenshots and Promotional Assets
+
+Screenshots are the single biggest factor in store listing conversion rates — they are the first thing users see when evaluating your extension.
+
+**Chrome Web Store requirements:**
+- 1280×800 or 640×400 PNG or JPEG screenshots.
+- Minimum 1 screenshot, maximum 5.
+- Screenshots must accurately represent the extension's UI and behavior. Staged screenshots are fine; misleading screenshots are grounds for removal.
+
+**Promotional tile (Chrome Web Store):**
+- Small tile: 440×280 PNG — Required for "Featured" promotion.
+- Large tile: 920×680 PNG — Optional.
+- Marquee banner: 1400×560 PNG — Optional, for featured placement.
+
+**AMO screenshot requirements:**
+- Any resolution PNG or JPEG.
+- Recommended: 1280×800.
+- Up to 10 screenshots.
+
+**Screenshot best practices:**
+- Show the extension's core value proposition in the first screenshot.
+- Use real content, not placeholder text.
+- Include captions (add them in the developer console, not in the image) explaining what is shown.
+- Show both the extension UI and the page it is enhancing — side by side or with the popup visible over the page.
+- Provide dark mode screenshots if the extension supports dark mode.
+
+### Store Listing Optimization
+
+**Title:**
+- Chrome: 45 characters max.
+- Include the primary keyword users would search for. "Ad Blocker for Chrome" ranks for "ad blocker".
+- Do not use competitor brand names in the title.
+
+**Short description (Chrome / AMO summary):**
+- Chrome: 132 characters. This appears in search results.
+- Lead with the primary benefit: "Block ads, trackers, and popups on every website."
+- Avoid generic phrasing: "A great extension for better browsing" is not helpful.
+
+**Full description:**
+- Explain every permission in plain language.
+- List key features as bullet points — users scan, not read.
+- Include keywords that describe the use case naturally. Do not keyword-stuff.
+- Link to privacy policy, support page, and source code repository.
+
+**Privacy Policy:**
+- Required for any extension that collects, processes, or transmits user data.
+- Even if the extension stores data only locally, provide a privacy policy that states this.
+- Host the privacy policy at a stable URL (not a GitHub README — it can be moved; use a dedicated page).
+
+### Managing Version Updates
+
+**Version number requirements:**
+- Each update must have a strictly higher version number than the previous published version.
+- Chrome uses the four-part format: `MAJOR.MINOR.PATCH.BUILD` (e.g., `1.2.3.0`).
+- Once a version number is used, it cannot be reused even if the submission was rejected.
+
+**Permission changes in updates:**
+- Adding new permissions to an existing extension triggers re-review.
+- Users with the extension installed are shown a permission update prompt — they must re-approve before the extension updates.
+- This is a significant UX disruption. Batch permission additions into major version updates and communicate the changes clearly.
+- Never remove permissions without considering whether existing features depend on them — silent feature breakage is worse than a permission prompt.
+
+**Update rollout:**
+- Chrome supports staged rollouts: publish to a percentage of users and increase over time.
+- Configure this in the developer console under "Distribution" after submitting the update.
+- Use staged rollout for major updates or updates with new permissions to catch issues before full release.
+
+**Expedited review:**
+- The Chrome Web Store provides an "expedite review" option in the developer console for critical security fixes.
+- Use sparingly — you are granted approximately two expedited reviews per year per developer account.
+- Include a detailed explanation of the security issue and urgency in the expedite request.