@zigrivers/scaffold 3.8.0 → 3.9.1

package/README.md

@@ -29,7 +29,7 @@ Either way, Scaffold constructs the prompt and the target AI tool does the work.
 
 **Assembly engine** — At execution time, Scaffold builds a 7-section prompt from: system metadata, the meta-prompt, knowledge base entries, project context (artifacts from prior steps), methodology settings, layered instructions, and depth-specific execution guidance.
 
-**Knowledge base** — 158 domain expertise entries in `content/knowledge/` organized in thirteen categories (core, product, review, validation, finalization, execution, tools, game, web-app, backend, cli, library, mobile-app) covering testing strategy, domain modeling, API design, security best practices, eval craft, TDD execution, task claiming, worktree management, release management, rendering strategies, data stores, CLI patterns, game engines, library bundling, mobile deployment, and more. These get injected into prompts based on each step's `knowledge-base` frontmatter field. Knowledge files with a `## Deep Guidance` section are optimized for CLI assembly — only the deep guidance content is loaded, avoiding redundancy with the prompt text. Teams can add project-local overrides in `.scaffold/knowledge/` that layer on top of the global entries.
+**Knowledge base** — 194 domain expertise entries in `content/knowledge/` organized in sixteen categories (core, product, review, validation, finalization, execution, tools, game, web-app, backend, cli, library, mobile-app, data-pipeline, ml, browser-extension) covering testing strategy, domain modeling, API design, security best practices, eval craft, TDD execution, task claiming, worktree management, release management, rendering strategies, data stores, CLI patterns, game engines, library bundling, mobile deployment, batch and streaming pipelines, model training and serving, browser extension manifests and service workers, and more. These get injected into prompts based on each step's `knowledge-base` frontmatter field. Knowledge files with a `## Deep Guidance` section are optimized for CLI assembly — only the deep guidance content is loaded, avoiding redundancy with the prompt text. Teams can add project-local overrides in `.scaffold/knowledge/` that layer on top of the global entries.
 
 **Methodology presets** — Three built-in presets control which steps run and how deep the analysis goes:
 - **deep** (depth 5) — all steps enabled, exhaustive analysis
@@ -368,7 +368,7 @@ Every `scaffold init` wizard question can be answered via CLI flags, making scaf
 | `--depth` | 1-5 | Custom methodology depth (requires `--methodology custom`) |
 | `--adapters` | comma-sep | AI adapters: claude-code, codex, gemini |
 | `--traits` | comma-sep | Project traits: web, mobile |
-| `--project-type` | string | web-app, mobile-app, backend, cli, library, game |
+| `--project-type` | string | web-app, mobile-app, backend, cli, library, game, data-pipeline, ml, browser-extension |
 | `--auto` | boolean | Non-interactive mode (uses Zod defaults for unset flags) |
 
 #### Web-App Config Flags (require `--project-type web-app` or auto-set it)
@@ -417,6 +417,34 @@ Every `scaffold init` wizard question can be answered via CLI flags, making scaf
 | `--mobile-offline` | string | none, cache, offline-first |
 | `--mobile-push-notifications` | boolean | `--mobile-push-notifications` / `--no-mobile-push-notifications` |
 
+#### Data Pipeline Config Flags (require `--project-type data-pipeline` or auto-set it)
+
+| Flag | Type | Values |
+|------|------|--------|
+| `--pipeline-processing` | string | batch, streaming, hybrid |
+| `--pipeline-orchestration` | string | none, dag-based, event-driven, scheduled |
+| `--pipeline-quality` | string | none, validation, testing, observability |
+| `--pipeline-schema` | string | none, schema-registry, contracts |
+| `--pipeline-catalog` | boolean | `--pipeline-catalog` / `--no-pipeline-catalog` |
+
+#### ML Config Flags (require `--project-type ml` or auto-set it)
+
+| Flag | Type | Values |
+|------|------|--------|
+| `--ml-phase` | string | training, inference, both |
+| `--ml-model-type` | string | classical, deep-learning, llm |
+| `--ml-serving` | string | none, batch, realtime, edge |
+| `--ml-experiment-tracking` | boolean | `--ml-experiment-tracking` / `--no-ml-experiment-tracking` |
+
+#### Browser Extension Config Flags (require `--project-type browser-extension` or auto-set it)
+
+| Flag | Type | Values |
+|------|------|--------|
+| `--ext-manifest` | string | 2, 3 |
+| `--ext-ui-surfaces` | comma-sep | popup, options, newtab, devtools, sidepanel |
+| `--ext-content-script` | boolean | `--ext-content-script` / `--no-ext-content-script` |
+| `--ext-background-worker` | boolean | `--ext-background-worker` / `--no-ext-background-worker` |
+
 #### Game Config Flags (require `--project-type game` or auto-set it)
 
 | Flag | Type | Values |
@@ -439,9 +467,9 @@ Every `scaffold init` wizard question can be answered via CLI flags, making scaf
 
 - **Flag > auto > interactive**: Flags always take highest precedence. `--auto --engine unreal` uses defaults for everything except engine.
 - **Partial flags + interactive**: Provide some flags and the wizard asks only the remaining questions. `scaffold init --project-type game --engine unreal` prompts interactively for multiplayer, platforms, etc.
-- **Type-specific flags auto-set project type**: `--engine unity` automatically sets `--project-type game`, `--web-rendering ssr` sets `--project-type web-app`, `--backend-api-style rest` sets `--project-type backend`, `--cli-interactivity hybrid` sets `--project-type cli`, `--lib-visibility public` sets `--project-type library`, `--mobile-platform ios` sets `--project-type mobile-app`. Error if conflicting type.
-- **Cannot mix flag families**: `--web-rendering ssr --backend-api-style rest` is an error. Each flag family is exclusive.
-- **Validation**: `--depth` requires `--methodology custom`. `--online-services` requires `--multiplayer online` or `hybrid`. SSR/hybrid rendering is incompatible with static deploy target. Session auth requires server state (not static).
+- **Type-specific flags auto-set project type**: `--engine unity` automatically sets `--project-type game`, `--web-rendering ssr` sets `--project-type web-app`, `--backend-api-style rest` sets `--project-type backend`, `--cli-interactivity hybrid` sets `--project-type cli`, `--lib-visibility public` sets `--project-type library`, `--mobile-platform ios` sets `--project-type mobile-app`, `--pipeline-processing batch` sets `--project-type data-pipeline`, `--ml-phase training` sets `--project-type ml`, `--ext-manifest 3` sets `--project-type browser-extension`. Error if conflicting type.
+- **Cannot mix flag families**: `--web-rendering ssr --backend-api-style rest` is an error. Each flag family (`--web-*`, `--backend-*`, `--cli-*`, `--lib-*`, `--mobile-*`, `--pipeline-*`, `--ml-*`, `--ext-*`, game) is exclusive.
+- **Validation**: `--depth` requires `--methodology custom`. `--online-services` requires `--multiplayer online` or `hybrid`. SSR/hybrid rendering is incompatible with static deploy target. Session auth requires server state (not static). ML inference projects must specify a serving pattern. Browser extensions must declare at least one capability (UI surface, content script, or background worker).
 
 #### CI Examples
 
@@ -493,6 +521,35 @@ scaffold init --auto --methodology deep --project-type mobile-app \
 scaffold init --auto --methodology mvp --project-type mobile-app \
   --mobile-platform ios --mobile-distribution private
 
+# Streaming data pipeline with event-driven orchestration
+scaffold init --auto --methodology deep --project-type data-pipeline \
+  --pipeline-processing streaming --pipeline-orchestration event-driven \
+  --pipeline-quality observability --pipeline-schema schema-registry
+
+# Batch ETL pipeline with DAG orchestration
+scaffold init --auto --methodology mvp --project-type data-pipeline \
+  --pipeline-processing batch --pipeline-orchestration dag-based \
+  --pipeline-quality validation
+
+# LLM inference service with realtime serving
+scaffold init --auto --methodology deep --project-type ml \
+  --ml-phase inference --ml-model-type llm --ml-serving realtime
+
+# Classical ML training pipeline (no serving)
+scaffold init --auto --methodology mvp --project-type ml \
+  --ml-phase training --ml-model-type classical \
+  --no-ml-experiment-tracking
+
+# MV3 browser extension with popup and content script
+scaffold init --auto --methodology deep --project-type browser-extension \
+  --ext-manifest 3 --ext-ui-surfaces popup,options \
+  --ext-content-script --ext-background-worker
+
+# Devtools-only browser extension
+scaffold init --auto --methodology mvp --project-type browser-extension \
+  --ext-manifest 3 --ext-ui-surfaces devtools \
+  --no-ext-content-script
+
 # Multiplayer mobile game with Unity
 scaffold init --project-type game --methodology deep --auto \
   --engine unity --multiplayer online --target-platforms ios,android \
@@ -519,7 +576,7 @@ Scaffold supports **project-type overlays** — domain-specific knowledge and pi
 
 - **Injects domain knowledge** into existing pipeline steps (e.g., SSR caching strategies into `tech-stack`, API pagination patterns into `coding-standards`)
 
-The game overlay additionally adjusts step enablement, remaps artifact references, and adds dependency overrides (because game development has fundamentally different artifacts). The web-app, backend, CLI, library, and mobile-app overlays are **knowledge-only** — they inject domain expertise into existing steps without changing which steps run or how they depend on each other.
+The game overlay additionally adjusts step enablement, remaps artifact references, and adds dependency overrides (because game development has fundamentally different artifacts). The web-app, backend, CLI, library, mobile-app, data-pipeline, ML, and browser-extension overlays are **knowledge-only** — they inject domain expertise into existing steps without changing which steps run or how they depend on each other.
 
 Overlays are composable with methodology presets. An MVP web-app gets fewer steps at lower depth; a deep backend project gets exhaustive analysis of every architectural decision.
 
@@ -530,6 +587,9 @@ Overlays are composable with methodology presets. An MVP web-app gets fewer step
 | `cli` | `cli-overlay.yml` | 10 entries (argument parsing, config management, output formatting, distribution, testing, error handling) | Interactivity model, distribution channels, structured output |
 | `library` | `library-overlay.yml` | 12 entries (API design, bundling, type definitions, versioning, documentation, testing, security) | Visibility, runtime target, bundle format, type definitions, documentation level |
 | `mobile-app` | `mobile-app-overlay.yml` | 12 entries (architecture, offline patterns, push notifications, deployment, distribution, testing, security) | Platform, distribution model, offline support, push notifications |
+| `data-pipeline` | `data-pipeline-overlay.yml` | 12 entries (architecture, batch and streaming patterns, orchestration, schema management, quality, testing, security) | Processing model, orchestration, data quality strategy, schema management, data catalog |
+| `ml` | `ml-overlay.yml` | 12 entries (architecture, training and serving patterns, experiment tracking, model evaluation, observability, testing, security) | Project phase, model type, serving pattern, experiment tracking |
+| `browser-extension` | `browser-extension-overlay.yml` | 12 entries (architecture, manifest configuration, service workers, content scripts, cross-browser, store submission, testing, security) | Manifest version, UI surfaces, content script, background worker |
 | `game` | `game-overlay.yml` | 24 entries (engines, networking, audio, VR/AR, economy, save systems, certification) | Engine, multiplayer, platforms, economy, narrative, and 6 more |
 
 ### Game Development
@@ -1224,7 +1284,7 @@ scaffold dashboard
 
 ## Knowledge System
 
-Scaffold ships with 134 domain expertise entries organized in eleven categories:
+Scaffold ships with 194 domain expertise entries organized in sixteen categories:
 
 - **core/** (26 entries) — eval craft, testing strategy, domain modeling, API design, database design, system architecture, ADR craft, security best practices, operations, task decomposition, user stories, UX specification, design system tokens, user story innovation, AI memory management, coding conventions, tech stack selection, project structure patterns, task tracking, CLAUDE.md patterns, multi-model review dispatch, review step template, dev environment, git workflow patterns, automated review tooling, vision craft
 - **product/** (5 entries) — PRD craft, PRD innovation, gap analysis, vision craft, vision innovation
@@ -1237,6 +1297,11 @@ Scaffold ships with 134 domain expertise entries organized in eleven categories:
 - **web-app/** (17 entries) — rendering strategies (SSR/SSG/SPA), state management, authentication, deploy targets, real-time patterns, PWA, performance, security, testing, session patterns, UX patterns, caching, API integration, accessibility
 - **backend/** (14 entries) — API design patterns, data store selection, authentication mechanisms, messaging/event systems, observability, deploy strategies, caching, rate limiting, error handling, database migrations, testing, security
 - **cli/** (10 entries) — argument parsing, config management, output formatting, distribution channels, testing patterns, error handling, plugin architecture, shell integration, structured output, interactive prompts
+- **library/** (12 entries) — visibility (public/internal), bundle formats (ESM/CJS/dual), type definitions, documentation levels, semver discipline, supply chain security, runtime targets
+- **mobile-app/** (12 entries) — platform-specific patterns (iOS/Android/cross-platform), distribution models (app store/enterprise), offline support, push notifications, mobile testing
+- **data-pipeline/** (12 entries) — batch/streaming/hybrid patterns, orchestration (DAG/event-driven/scheduled), data quality, schema management, lineage, pipeline testing
+- **ml/** (12 entries) — training and inference patterns, model types (classical/deep-learning/llm), serving patterns, experiment tracking, model evaluation, MLOps observability
+- **browser-extension/** (12 entries) — Manifest V3, content scripts, service workers, cross-browser compatibility, extension security, store submission
 
 Each pipeline step declares which knowledge entries it needs in its frontmatter. The assembly engine injects them automatically. Knowledge files with a `## Deep Guidance` section are optimized for the CLI — only the deep guidance content is loaded into the assembled prompt, skipping the summary to avoid redundancy with the prompt text.
 
@@ -1442,7 +1507,7 @@ All build inputs live under `content/`:
 content/
 ├── pipeline/         # 60 meta-prompts organized by 16 phases (phases 0-15, including build)
 ├── tools/            # 10 tool meta-prompts (stateless, category: tool)
-├── knowledge/        # 61 domain expertise entries (core, product, review, validation, finalization, execution, tools)
+├── knowledge/        # 194 domain expertise entries (core, product, review, validation, finalization, execution, tools, game, web-app, backend, cli, library, mobile-app, data-pipeline, ml, browser-extension)
 ├── methodology/      # 3 YAML presets (deep, mvp, custom)
 └── skills/           # Skill templates with {{markers}} for multi-platform resolution (includes mmr)
 ```

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

@@ -0,0 +1,195 @@
+---
+name: browser-extension-architecture
+description: Component isolation across content scripts, background service workers, and popup pages; message passing patterns; and state synchronization strategies
+topics: [browser-extension, architecture, message-passing, state-synchronization, service-worker, content-scripts]
+---
+
+Browser extension architecture is fundamentally different from web app architecture because the application is split across multiple isolated execution environments that cannot share memory directly. Content scripts run inside host pages but in an isolated JavaScript world. Service workers run in a separate context that is terminated and re-created between events. Popup pages are ephemeral — they exist only while the popup is open. These constraints drive every architectural decision: communication is via message passing, state must be externalized to `chrome.storage`, and every component must tolerate being initialized from scratch at any time.
+
+## Summary
+
+Browser extensions have three primary execution contexts: content scripts (run in page context, DOM access, restricted API), background service worker (runs in extension context, full API access, no DOM, terminated between events), and popup/options pages (full HTML pages, full API access, ephemeral lifecycle). Communication between contexts is via `chrome.runtime.sendMessage` (one-shot) or `chrome.runtime.connect` (persistent port). State is synchronized via `chrome.storage` as the single source of truth, with `chrome.storage.onChanged` listeners propagating changes to interested contexts.
+
+## Deep Guidance
+
+### Execution Context Isolation
+
+Understanding the isolation boundaries is the foundation of extension architecture. Bugs caused by violating these boundaries are subtle and hard to diagnose.
+
+**Content scripts:**
+- Execute in the context of a web page but in an isolated JavaScript world — they share the DOM with the page but do not share the JavaScript scope.
+- Can read and modify the DOM.
+- Can communicate with the host page via `window.postMessage` (crosses the world boundary).
+- Can call a limited subset of `chrome.*` APIs: `chrome.runtime.sendMessage`, `chrome.runtime.connect`, `chrome.storage`, `chrome.i18n`.
+- Cannot call `chrome.tabs`, `chrome.windows`, `chrome.browsingData`, or most other privileged APIs.
+- Multiple content scripts run as separate injected scripts — they share the isolated world and can communicate via DOM events or shared global state if needed.
+
+**Background service worker:**
+- Runs in the extension context — fully isolated from any web page.
+- Has access to the full `chrome.*` API surface.
+- Has no DOM — `document` and `window` are undefined.
+- Is event-driven: Chrome terminates the service worker when it is idle and restarts it when an event arrives. Never rely on in-memory state surviving between event handlers.
+- All persistent state must live in `chrome.storage.local`, `chrome.storage.sync`, or `IndexedDB`.
+
+**Popup and options pages:**
+- Full HTML pages loaded in the extension context.
+- Have full `chrome.*` API access and full DOM access.
+- Popup: exists only while the popup window is open. Closing the popup destroys all JavaScript state. Do not use the popup as a state manager.
+- Options page: persistent as long as the tab is open, but still an ephemeral page that should load its state from `chrome.storage` on mount.
+
+### Message Passing Architecture
+
+Message passing is the only way for isolated contexts to communicate. Design a clear message flow before writing handlers.
+
+**One-shot messages (chrome.runtime.sendMessage):**
+
+```typescript
+// Sender (popup or content script)
+const response = await chrome.runtime.sendMessage<RequestPayload, ResponsePayload>({
+  type: Messages.POPUP_GET_STATUS,
+  payload: undefined,
+});
+
+// Receiver (background service worker)
+chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+  if (message.type === Messages.POPUP_GET_STATUS) {
+    getStatus().then(sendResponse);
+    return true; // Required for async sendResponse
+  }
+});
+```
+
+**Key rules for sendMessage:**
+- The listener must `return true` if `sendResponse` will be called asynchronously. Failing to return `true` causes the message channel to close before the response arrives.
+- Wrap all `sendMessage` calls in try/catch — if no listener is registered (e.g., the service worker has not started yet), Chrome throws `"Could not establish connection. Receiving end does not exist."`.
+- One-shot messages are appropriate for request/response patterns: get current state, toggle a setting, trigger an action.
+
+**Persistent connections (chrome.runtime.connect):**
+
+```typescript
+// Content script — persistent port for streaming updates
+const port = chrome.runtime.connect({ name: 'content-state-stream' });
+
+port.onMessage.addListener((message) => {
+  applyStateUpdate(message);
+});
+
+port.onDisconnect.addListener(() => {
+  // Service worker was terminated or background closed the port
+  // Reconnect or degrade gracefully
+});
+
+// Background service worker
+chrome.runtime.onConnect.addListener((port) => {
+  if (port.name === 'content-state-stream') {
+    // Store port reference for pushing updates
+    activePorts.add(port);
+    port.onDisconnect.addListener(() => {
+      activePorts.delete(port);
+    });
+  }
+});
+```
+
+Use persistent ports for: real-time updates pushed from background to content, long-lived streams (e.g., streaming API responses), and cases where the overhead of repeated `sendMessage` calls is unacceptable.
+
+**Background-to-content communication:**
+
+Sending messages from the background to a content script requires knowing the tab ID:
+
+```typescript
+// Background → Content (requires tab ID)
+await chrome.tabs.sendMessage(tabId, {
+  type: Messages.BG_INJECT_OVERLAY,
+  payload: { data },
+});
+```
+
+The background cannot send to a content script without a tab ID. Obtain it from `sender.tab.id` in an incoming message, from `chrome.tabs.query()`, or from the `chrome.tabs.onActivated` event.
+
+### State Synchronization Architecture
+
+`chrome.storage` is the single source of truth for all extension state. Every context reads from and writes to storage; no context holds authoritative state in memory.
+
+**Storage tiers:**
+
+- `chrome.storage.sync` — Syncs across the user's browsers via their Google/Firefox account. Limited to 100 KB total, 8 KB per item. Use for user preferences and settings.
+- `chrome.storage.local` — Local to the device. 10 MB default limit (can request 5 GB with `unlimitedStorage` permission). Use for cached data, large state objects, per-device state.
+- `chrome.storage.session` — (Chrome 102+) — Cleared when the browser session ends. Use for ephemeral state that must survive service worker restarts within a session but not persist across browser restarts.
+
+**Typed storage wrapper pattern:**
+
+```typescript
+// src/shared/storage.ts
+export const StorageKeys = {
+  ENABLED: 'enabled',
+  SITES_CONFIG: 'sitesConfig',
+  LAST_ACTIVE: 'lastActive',
+} as const;
+
+export interface ExtensionState {
+  [StorageKeys.ENABLED]: boolean;
+  [StorageKeys.SITES_CONFIG]: SiteConfig[];
+  [StorageKeys.LAST_ACTIVE]: number;
+}
+
+export async function getState(): Promise<Partial<ExtensionState>> {
+  return chrome.storage.sync.get(null) as Promise<Partial<ExtensionState>>;
+}
+
+export async function setState(partial: Partial<ExtensionState>): Promise<void> {
+  return chrome.storage.sync.set(partial);
+}
+```
+
+**Reactive state propagation with onChanged:**
+
+```typescript
+// In popup or options page — react to storage changes in real time
+chrome.storage.onChanged.addListener((changes, area) => {
+  if (area === 'sync' && changes[StorageKeys.ENABLED]) {
+    const newValue = changes[StorageKeys.ENABLED].newValue as boolean;
+    setUIEnabled(newValue);
+  }
+});
+```
+
+This pattern ensures all open popup/options pages reflect state changes made by background or content scripts without requiring explicit message passing.
+
+### Popup Architecture
+
+The popup is stateless by design — it reads from storage on open and writes to storage on user interaction. The background reacts to storage changes.
+
+**Anti-pattern:** Popup sends message to background requesting action → background performs action → background sends message back to popup. This creates a request/response round trip that duplicates what storage-driven reactivity provides for free.
+
+**Correct pattern:** Popup writes to storage → background listens via `chrome.storage.onChanged` → background performs action → background writes result to storage → popup listens via `chrome.storage.onChanged` → popup updates UI.
+
+### Service Worker Lifecycle Management
+
+Because the service worker is terminated when idle, all setup that must survive restarts belongs in `chrome.storage`, not in module-level variables.
+
+**Install handler — first-run initialization:**
+
+```typescript
+chrome.runtime.onInstalled.addListener(async ({ reason }) => {
+  if (reason === chrome.runtime.OnInstalledReason.INSTALL) {
+    // Set default state
+    await chrome.storage.sync.set({
+      [StorageKeys.ENABLED]: true,
+      [StorageKeys.SITES_CONFIG]: [],
+    });
+    // Open onboarding tab
+    await chrome.tabs.create({ url: chrome.runtime.getURL('options/index.html') });
+  }
+  if (reason === chrome.runtime.OnInstalledReason.UPDATE) {
+    // Handle migration if schema changed
+    await migrateStorage();
+  }
+});
+```
+
+**Keeping the service worker active when needed:**
+
+For operations that must not be interrupted by service worker termination (e.g., a long-running fetch), use the Chrome alarms API to schedule a "keepalive" alarm, or use `chrome.storage.session` to track whether work is in progress and re-initiate it on service worker restart.
+
+Never use `setInterval` or `setTimeout` for recurring background work — they do not survive service worker termination. Use `chrome.alarms` instead.

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

@@ -0,0 +1,264 @@
+---
+name: browser-extension-content-scripts
+description: DOM manipulation from content scripts, isolated worlds, CSS injection, and communicating with the host page via postMessage
+topics: [browser-extension, content-scripts, dom-manipulation, isolated-worlds, css-injection, postmessage]
+---
+
+Content scripts are the extension's interface with the web page. They run inside the page's DOM but in an isolated JavaScript world — they see the same HTML and can manipulate the same elements, but they cannot access the page's JavaScript variables or prototype chain without explicitly crossing the world boundary. Understanding this isolation is essential for writing content scripts that are both functional and secure.
+
+## Summary
+
+Content scripts execute in an isolated JavaScript world by default (ISOLATED world): they have DOM access but no access to the page's JS globals. CSS is injected via manifest declarations or `chrome.scripting.insertCSS()`. Communication with the host page uses `window.postMessage()` (crosses the world boundary) with origin validation. Communication with the background service worker uses `chrome.runtime.sendMessage()`. Minimize DOM manipulation, use `MutationObserver` for dynamic pages, and always clean up injected elements and observers when the extension is disabled.
+
+## Deep Guidance
+
+### Isolated Worlds
+
+The isolated world is the security boundary between extension code and page code. It has important implications:
+
+**What content scripts can access:**
+- The full DOM (`document`, `window.location`, `document.querySelector`, all DOM methods).
+- The `window` object's properties that are reflected from the DOM (e.g., `window.location`, `window.document`).
+- `window.addEventListener` — content scripts and page scripts can both add listeners to the same DOM events.
+
+**What content scripts cannot access:**
+- JavaScript variables defined by the page script (`window.myApp`, `window.React`, page-defined globals).
+- DOM properties set by page scripts that are not reflected in the HTML (e.g., a React component's state stored in a closure).
+- Custom properties set on DOM elements by page scripts (e.g., `element._reactInternals` — the element is accessible but the custom property is set in the page world, not visible in the isolated world).
+
+**MAIN world execution** (when you need page-world access):
+
+```json
+// manifest.json
+"content_scripts": [
+  {
+    "matches": ["https://example.com/*"],
+    "js": ["content-main-world.js"],
+    "world": "MAIN"
+  }
+]
+```
+
+Or programmatically:
+
+```typescript
+await chrome.scripting.executeScript({
+  target: { tabId },
+  func: () => {
+    // This runs in the page's JavaScript world
+    return window.myPageGlobal?.someValue;
+  },
+  world: 'MAIN',
+});
+```
+
+Use MAIN world execution sparingly — it gives extension code full access to page variables, increasing the risk of interference and XSS if inputs are not sanitized.
+
+### DOM Manipulation Patterns
+
+**Safe element injection:**
+
+```typescript
+// Create a container that isolates extension styles from the page
+function injectOverlay(): void {
+  // Check for duplicate injection
+  if (document.getElementById('my-ext-overlay')) return;
+
+  const container = document.createElement('div');
+  container.id = 'my-ext-overlay';
+  container.setAttribute('role', 'complementary');
+  container.setAttribute('aria-label', 'My Extension');
+
+  // Use Shadow DOM for style isolation
+  const shadow = container.attachShadow({ mode: 'closed' });
+
+  const style = document.createElement('style');
+  style.textContent = overlayCSS; // Inline CSS string
+
+  const content = document.createElement('div');
+  content.className = 'overlay-content';
+
+  shadow.appendChild(style);
+  shadow.appendChild(content);
+  document.body.appendChild(container);
+}
+```
+
+**Why Shadow DOM:** Shadow DOM provides style encapsulation. Extension styles do not leak into the host page, and host page styles do not affect extension UI. This is the correct approach for injecting interactive UI elements. If you only need to inject non-interactive content or annotations, direct DOM insertion is acceptable.
+
+**Cleanup on disable:**
+
+```typescript
+function cleanup(): void {
+  const overlay = document.getElementById('my-ext-overlay');
+  overlay?.remove();
+  observer?.disconnect();
+  window.removeEventListener('message', messageHandler);
+}
+
+// Listen for cleanup signal from background
+chrome.runtime.onMessage.addListener((message) => {
+  if (message.type === Messages.BG_CLEAR_STATE) {
+    cleanup();
+  }
+});
+```
+
+Always implement cleanup. Users who disable the extension expect the page to return to its original state without requiring a refresh.
+
+### Handling Dynamic Pages (SPA and Infinite Scroll)
+
+Modern web apps modify the DOM after initial load. `document_idle` injection runs once — if the relevant content loads asynchronously, the content script misses it.
+
+**MutationObserver for dynamic content:**
+
+```typescript
+function observeForTargetElements(): void {
+  const observer = new MutationObserver((mutations) => {
+    for (const mutation of mutations) {
+      for (const node of mutation.addedNodes) {
+        if (node.nodeType !== Node.ELEMENT_NODE) continue;
+        const el = node as Element;
+
+        if (el.matches('.target-class')) {
+          processElement(el);
+        }
+        // Also check descendants
+        el.querySelectorAll('.target-class').forEach(processElement);
+      }
+    }
+  });
+
+  observer.observe(document.body, {
+    childList: true,
+    subtree: true,
+  });
+}
+```
+
+**Performance consideration:** `MutationObserver` callbacks run synchronously after DOM mutations. Heavy work in the callback (complex selectors, network requests) will block the page's rendering. Defer expensive work:
+
+```typescript
+const deferredWork = debounce((elements: Element[]) => {
+  elements.forEach(processElement);
+}, 100);
+
+const observer = new MutationObserver((mutations) => {
+  const targets = mutations
+    .flatMap(m => [...m.addedNodes])
+    .filter(n => n.nodeType === Node.ELEMENT_NODE)
+    .flatMap(el => [...(el as Element).querySelectorAll('.target-class')]);
+
+  if (targets.length > 0) deferredWork(targets);
+});
+```
+
+**URL change detection (for SPA navigation):**
+
+SPAs change the URL via `history.pushState` without triggering a page load. Content scripts do not automatically re-run on SPA navigation:
+
+```typescript
+let lastUrl = location.href;
+
+const urlObserver = new MutationObserver(() => {
+  if (location.href !== lastUrl) {
+    lastUrl = location.href;
+    onNavigate(location.href);
+  }
+});
+
+urlObserver.observe(document, { subtree: true, childList: true });
+```
+
+### CSS Injection
+
+**Method 1 — Manifest declaration (preferred for always-on styles):**
+
+```json
+"content_scripts": [
+  {
+    "matches": ["https://example.com/*"],
+    "css": ["content.css"]
+  }
+]
+```
+
+Injected stylesheets receive the lowest specificity among author styles. Host page styles with equal or higher specificity will override them. Use high-specificity selectors or `!important` (sparingly) on extension-injected styles that must not be overridden.
+
+**Method 2 — Programmatic injection:**
+
+```typescript
+// From background service worker
+await chrome.scripting.insertCSS({
+  target: { tabId },
+  files: ['content.css'],
+});
+
+// Remove previously injected CSS
+await chrome.scripting.removeCSS({
+  target: { tabId },
+  files: ['content.css'],
+});
+```
+
+Programmatic injection allows toggling styles on demand. Use it when the extension can be enabled/disabled per site.
+
+**Method 3 — Inline style element (for dynamic styles):**
+
+```typescript
+const style = document.createElement('style');
+style.id = 'my-ext-styles';
+style.textContent = generateDynamicCSS(userPreferences);
+document.head.appendChild(style);
+```
+
+### Communication with the Host Page via postMessage
+
+Content scripts and page scripts cannot call each other's functions directly due to world isolation. `window.postMessage` is the crossing mechanism.
+
+**Sending from content script to page script:**
+
+```typescript
+// Content script — send message to page
+window.postMessage(
+  { source: 'my-extension', type: 'INIT', payload: { version: '1.0' } },
+  window.location.origin, // MUST restrict origin — never use '*' for extension messages
+);
+```
+
+**Receiving in page script:**
+
+```javascript
+// Page script
+window.addEventListener('message', (event) => {
+  // ALWAYS validate source origin
+  if (event.origin !== window.location.origin) return;
+  if (!event.data || event.data.source !== 'my-extension') return;
+
+  handleExtensionMessage(event.data);
+});
+```
+
+**Receiving in content script from page:**
+
+```typescript
+// Content script — receive messages from page script
+function messageHandler(event: MessageEvent): void {
+  if (event.origin !== window.location.origin) return;
+  if (!event.data || event.data.source !== 'my-page-app') return;
+
+  // Forward to background service worker
+  chrome.runtime.sendMessage({
+    type: Messages.CONTENT_PAGE_LOADED,
+    payload: event.data.payload,
+  });
+}
+
+window.addEventListener('message', messageHandler);
+```
+
+**Security rules for postMessage:**
+- Always specify the target origin — never use `'*'`. Malicious pages at other origins could otherwise intercept extension messages.
+- Always validate `event.origin` in receivers.
+- Always validate a `source` field on the message object to distinguish extension messages from other `postMessage` traffic on the page.
+- Never pass sensitive data (auth tokens, PII) via `postMessage` — the host page receives these messages too.