web-extension 0.0.0-stage → 2.0.0

package/AI.md

@@ -0,0 +1,270 @@
+# web-extension: AI & Agent System Specification
+
+This document provides a deterministic, complete, and unambiguous specification of the `web-extension` CLI. It is structured specifically for AI models, automated agents, and code generators to reason about and execute without guesswork.
+
+---
+
+## 1. System Overview & Invariants
+
+- **Package Name:** `web-extension`
+- **Binary Name:** `web-extension`
+- **Runtime Target:** Node.js >= 20, Bun >= 1.0.0
+- **CLI Architecture:** TypeScript source compiled via `tsup` to a single ESM bundle at `dist/index.js` with shebang `#!/usr/bin/env node`.
+- **Primary Subcommand:** `init`
+- **Default Subcommand Alias:** When invoked without a subcommand (or when the first argument is not recognized as a registered subcommand), the CLI implicitly routes to `init`. For example, `web-extension my-app --lang ts` is identical to `web-extension init my-app --lang ts`.
+- **Top-Level Flags:** `--help` / `-h` and `--version` / `-v` are processed immediately and do not enter the `init` pipeline.
+
+---
+
+## 2. CLI Execution Modes & Contracts
+
+### 2.1 Non-TTY (Scripted / CI) Contract
+- If stdin or stdout is not a TTY (`!process.stdin.isTTY || !process.stdout.isTTY`), interactive prompts cannot be shown.
+- Every required decision that lacks an explicit CLI flag or `--yes` default causes an immediate error with exit code `1`.
+- When `--yes` (or `-y`) is provided, all omitted options fall back to their documented default values.
+
+### 2.2 Interactive Contract
+- Uses `@clack/prompts`.
+- Any user cancellation (`Ctrl+C` or escape) invokes `p.cancel('Cancelled.')` and immediately terminates process with exit code `0`.
+- If an option was supplied via CLI flag, its corresponding interactive prompt is skipped.
+
+---
+
+## 3. Flag Parsing & Parameter Matrix
+
+All flags can be provided in kebab-case.
+
+| Flag | Type | Allowed Values | Default Value (`--yes`) | Notes |
+|---|---|---|---|---|
+| `[dir]` | string (positional) | Any valid path or slug | `my-extension` | First positional argument after subcommand. |
+| `--name` | string | Valid npm package name | Basename of `[dir]` or `my-extension` | Must be lowercase, no spaces, valid regex. |
+| `--if-exists` | string | `cancel`, `overwrite`, `merge` | `cancel` | Action when target directory is not empty. |
+| `--overwrite` | boolean | `true`, `false` | `false` | Convenience alias for `--if-exists overwrite`. |
+| `--lang` | string | `ts`, `js` | `ts` | TypeScript or JavaScript. |
+| `--type` | string | `full`, `content-only` | `full` | Full extension or headless content-script only. |
+| `--browser` | string (repeatable/comma) | `chrome`, `firefox`, `safari` | `chrome` | Target browsers. `chromium` maps to `chrome`. |
+| `--firefox-mv` | number / string | `2`, `3` | `3` | Firefox manifest version. |
+| `--safari-mv` | number / string | `2`, `3` | `3` | Safari manifest version. |
+| `--features` | string (comma) | `background`, `content`, `popup`, `options`, `sidepanel`, `dnr`, `devtools`, `newtab`, `none` | `background,content` | Available only in `full` mode. |
+| `--matches` | string (comma) | WebExtension match patterns | `https://*/*` | Required pattern(s) when `content` is enabled. |
+| `--run-at` | string | `document_start`, `document_end`, `document_idle` | `document_idle` | Content script execution timing. |
+| `--world` | string | `ISOLATED`, `MAIN` | `ISOLATED` | MV3 only. Not permitted with MV2 targets. |
+| `--css` / `--no-css` | boolean | `true`, `false` | `true` | Generate CSS stylesheet for content script. |
+| `--extras` | string (comma) | `contextmenu`, `commands`, `omnibox`, `storage`, `none` | `none` | Additional helpers and boilerplate. |
+| `--pm` | string | `npm`, `pnpm`, `yarn`, `bun` | Auto-detected | Force package manager selection. |
+| `--install` / `--no-install` | boolean | `true`, `false` | `true` | Whether to automatically install dependencies. |
+| `--git` / `--no-git` | boolean | `true`, `false` | `true` | Initialize a Git repository. |
+| `--yes`, `-y` | boolean | `true`, `false` | `false` | Bypass prompts using default values. |
+| `--help`, `-h` | boolean | `true`, `false` | `false` | Display help output and exit `0`. |
+| `--version`, `-v` | boolean | `true`, `false` | `false` | Display package version and exit `0`. |
+
+---
+
+## 4. Validation Rules & Exit Behavior
+
+The CLI enforces strict validation with exit code `1` upon invalid inputs or incompatible combinations:
+
+### 4.1 Fatal Errors (Exit Code 1)
+1. **Unrecognized Flag Value:** Any value outside the allowed set (e.g. `--browser edge` or `--lang ruby`) aborts with an error listing accepted values.
+2. **Content-Only with Features/Extras:** Supplying `--type content-only` with `--features` or `--extras` is invalid. Content-only extensions contain only content scripts.
+3. **Safari-Only Side Panel:** Specifying `--features sidepanel` when `--browser safari` is the only target is fatal because Safari does not support side panels.
+4. **DNR with Manifest V2:** Specifying `--features dnr` while any target is MV2 is fatal.
+5. **Extras without Background:** Specifying `--extras contextmenu`, `commands`, or `omnibox` without `background` in `--features` is fatal.
+6. **Main World with Manifest V2:** Specifying `--world MAIN` while any target is MV2 is fatal.
+7. **Directory Conflict:** Target directory exists and contains files, but `--if-exists` is `cancel` or unhandled.
+8. **Invalid Package Name:** Package name does not conform to npm package naming rules (`/^(?:@[a-z0-9-*~][a-z0-9-*._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/`).
+9. **Invalid Match Pattern:** Pattern does not start with `http://`, `https://`, `*://`, `file://`, or `<all_urls>`.
+
+### 4.2 Non-Fatal Warnings
+The CLI prints warnings to stderr but continues execution when:
+- `--firefox-mv` is passed without `firefox` in `--browser`.
+- `--safari-mv` is passed without `safari` in `--browser`.
+- Content script flags (`--matches`, `--run-at`, `--world`, `--css`) are passed when `content` feature is absent.
+- `--git` is requested but the target directory is already inside an existing Git repository.
+
+---
+
+## 5. Browser Capabilities & Target Resolution
+
+For each selected browser, the generator maps targets:
+- `chrome` -> `chrome-mv3` (outDir: `dist/chrome-mv3`)
+- `firefox` (MV3) -> `firefox-mv3` (outDir: `dist/firefox-mv3`)
+- `firefox` (MV2) -> `firefox-mv2` (outDir: `dist/firefox-mv2`)
+- `safari` (MV3) -> `safari-mv3` (outDir: `dist/safari-mv3`)
+- `safari` (MV2) -> `safari-mv2` (outDir: `dist/safari-mv2`)
+
+### 5.1 Capability Matrix
+
+```text
+Target         MV  Worker  Scripts  Popup           SidePanel       DNR    WorldMain
+------------------------------------------------------------------------------------
+chrome-mv3     3   Yes     No       action          side_panel      Yes    Yes
+firefox-mv3    3   No      Yes      action          sidebar_action  Yes    Yes
+firefox-mv2    2   No      Yes      browser_action  sidebar_action  No     No
+safari-mv3     3   Yes     No       action          None            Yes    Yes
+safari-mv2     2   No      Yes      browser_action  None            No     No
+```
+
+### 5.2 Manifest Structure Invariants
+- **Chromium MV3:**
+  - `background.service_worker = "src/background/index.(ts|js)"`
+  - `action.default_popup = "src/popup/index.html"`
+  - `side_panel.default_path = "src/sidepanel/index.html"`
+  - `permissions` includes `"sidePanel"` when sidepanel feature is enabled.
+- **Firefox MV3:**
+  - `background.scripts = ["src/background/index.(ts|js)"]`
+  - `action.default_popup = "src/popup/index.html"`
+  - `sidebar_action.default_panel = "src/sidepanel/index.html"`
+  - `browser_specific_settings.gecko.id = "<name>@example.com"`
+  - `browser_specific_settings.gecko.strict_min_version = "109.0"`
+  - Does NOT include `"sidePanel"` in `permissions`.
+- **Firefox MV2:**
+  - `manifest_version = 2`
+  - `background.scripts = ["src/background/index.(ts|js)"]`, `background.persistent = false`
+  - `browser_action.default_popup = "src/popup/index.html"`
+  - `sidebar_action.default_panel = "src/sidepanel/index.html"`
+  - `browser_specific_settings.gecko.id = "<name>@example.com"`
+  - `browser_specific_settings.gecko.strict_min_version = "58.0"`
+  - No `action`, `host_permissions`, or `declarative_net_request` keys.
+- **Content-Only Mode:**
+  - `manifest.content_scripts` is populated.
+  - Manifest contains no `background`, `action`, `browser_action`, `options_ui`, or UI entries.
+  - Contains no `permissions` array unless explicitly demanded.
+
+---
+
+## 6. Build Pipelines: MV3 vs MV2
+
+Generated projects employ dual-mode packaging:
+
+### 6.1 MV3 Pipeline (CRXJS)
+- Handled by `@crxjs/vite-plugin` (`crx({ manifest: manifestConfig, browser })`).
+- Full support for Vite HMR in popup, options, sidepanel, and content scripts on Chromium.
+- Dev command: `vite` (or `vite build --watch` for Firefox/Safari).
+
+### 6.2 MV2 Pipeline (Custom Standalone Bundler)
+- `@crxjs/vite-plugin` is designed strictly for Manifest V3. When an MV2 target is active, the project does NOT pass MV2 manifests to CRXJS.
+- Instead, the generator writes `build/mv2.(ts|js)` and registers `buildMv2Plugin` in `vite.config`.
+- Build behavior:
+  1. Compiles HTML entry points (`popup.html`, `options.html`, `devtools.html`, etc.) via Rollup inputs.
+  2. Compiles content scripts and background scripts as standalone IIFE bundles (`formats: ['iife']`) so they can execute in classic MV2 runtimes without ES module loading limitations.
+  3. Emits `dist/<target>/manifest.json` dynamically from `manifest.config`.
+
+---
+
+## 7. Package Manager Resolution Priority
+
+When `--pm` is not explicitly supplied, package manager detection follows this deterministic order:
+
+1. `process.env.npm_config_user_agent`:
+   - Matches regex `/(npm|pnpm|yarn|bun)\/([^\s]+)/`.
+   - Confident: `true`.
+2. `packageManager` field:
+   - Recursively scans parent directories for `package.json` with a valid `packageManager` entry (e.g. `pnpm@8.15.0`).
+   - Confident: `true`.
+3. Single Lockfile:
+   - Recursively scans parent directories for lockfiles in priority: `bun.lock`/`bun.lockb` -> `pnpm-lock.yaml` -> `yarn.lock` -> `package-lock.json`.
+   - If exactly one type is found: Confident: `true`.
+   - If multiple competing lockfiles exist: picks highest priority with Confident: `false`.
+4. Global Binary Path:
+   - Inspects `process.argv[1]` for known global tool paths (`.bun`, `pnpm/global`, `Roaming/npm`, etc.).
+   - Confident: `false`.
+5. Bun Runtime Environment:
+   - `typeof (globalThis as any).Bun !== 'undefined'`.
+   - Confident: `false`.
+6. Fallback:
+   - Default: `npm`.
+   - Confident: `false`.
+
+When Confident is `false` in an interactive TTY session without `--pm`, the user is prompted to select their package manager with the detected value as the default.
+
+---
+
+## 8. Generated Project Structure
+
+### Full Mode (TypeScript)
+```text
+my-extension/
+├── public/
+│   ├── icons/ (16.png, 48.png, 128.png)
+│   └── rules/rules.json (if DNR enabled)
+├── src/
+│   ├── background/index.ts (if background enabled)
+│   ├── content/
+│   │   ├── index.ts (if content enabled)
+│   │   └── style.css (if css enabled)
+│   ├── popup/
+│   │   ├── index.html
+│   │   ├── main.ts
+│   │   └── style.css
+│   ├── options/
+│   │   ├── index.html
+│   │   ├── main.ts
+│   │   └── style.css
+│   ├── sidepanel/
+│   │   ├── index.html
+│   │   ├── main.ts
+│   │   └── style.css
+│   ├── devtools/
+│   │   ├── devtools.html
+│   │   ├── devtools.ts
+│   │   └── panel.html
+│   ├── newtab/
+│   │   ├── index.html
+│   │   ├── main.ts
+│   │   └── style.css
+│   └── lib/
+│       ├── browser.ts (Universal API accessor)
+│       └── storage.ts (if storage extra enabled)
+├── build/
+│   └── mv2.ts (present if any target is MV2)
+├── env.d.ts
+├── manifest.config.ts
+├── targets.config.ts
+├── vite.config.ts
+├── tsconfig.json
+├── tsconfig.app.json
+├── tsconfig.background.json (isolated worker types)
+├── tsconfig.node.json
+├── package.json
+├── .gitignore
+└── README.md
+```
+
+### Content-Only Mode (TypeScript)
+```text
+my-extension/
+├── public/
+│   └── icons/ (16.png, 48.png, 128.png)
+├── src/
+│   ├── content/
+│   │   ├── index.ts (DOM Hack / MutationObserver)
+│   │   └── style.css (if css enabled)
+│   └── lib/
+│       └── browser.ts
+├── env.d.ts
+├── manifest.config.ts
+├── targets.config.ts
+├── vite.config.ts
+├── tsconfig.json
+├── tsconfig.app.json
+├── tsconfig.node.json
+├── package.json
+├── .gitignore
+└── README.md
+```
+
+---
+
+## 9. Verification & Invariant Testing
+
+Automated testing must verify:
+1. `bun run typecheck`: Strict compilation across all sources without errors.
+2. `bun run test`: Vitest unit tests verifying arg parsing, validation, targets, manifests, and package manager heuristics.
+3. `bun run test:smoke`: End-to-end smoke test suite executing five suites:
+   - Suite A: Chromium MV3 (Full features, TS, DNR, extras).
+   - Suite B: Firefox MV2 (JS, background scripts, `build/mv2`).
+   - Suite C: Multi-browser (Chrome MV3, Firefox MV3, Safari MV2).
+   - Suite D: Content-only TS (Chrome, Firefox).
+   - Suite E: Content-only JS (Firefox MV2).
+

package/DEVELOPER.md

@@ -0,0 +1,122 @@
+# Developer Guide: web-extension
+
+This guide provides instructions and architectural details for developers contributing to the `web-extension` CLI.
+
+---
+
+## 1. Architecture Overview
+
+The codebase is organized into four main layers:
+
+```text
+src/
+├── index.ts               CLI entry point and top-level error handler
+├── cli/
+│   ├── args.ts            CLI flag parsing, aliases, and combination validation
+│   ├── context.ts         Shared TypeScript types, flags, and context interfaces
+│   └── prompts.ts         Interactive prompts (@clack/prompts) and cancel handling
+├── generate/
+│   ├── copy.ts            Template file copier, placeholder injector, and file renamer
+│   ├── index.ts           Main project generation coordinator
+│   ├── manifest.ts        Manifest V3 and Manifest V2 generator per target browser
+│   ├── pkgjson.ts         Dynamic package.json builder with target dependencies
+│   ├── targets.ts         Browser capability matrix and target resolver
+│   └── tsconfig.ts        TypeScript (tsconfig) and JavaScript (jsconfig) builder
+└── utils/
+    ├── exec.ts            Process execution, git detector, and command checks
+    ├── pm.ts              Multi-stage package manager detection heuristics
+    └── validate.ts        Validation for npm package names, URLs, and match patterns
+templates/
+├── base/                  Shared assets (icons, gitignore)
+├── features/              Feature-specific templates (background, content, popup, etc.)
+├── js/                    JavaScript library utilities
+└── ts/                    TypeScript library utilities
+test/                      Vitest unit test suites
+```
+
+---
+
+## 2. Prerequisites & Toolchain
+
+- **Node.js:** `>= 20.0.0`
+- **Bun:** `>= 1.0.0` (Bun is the designated package manager and runtime for this repository)
+- **Bundler:** `tsup` compiling `src/index.ts` to `dist/index.js` as an ES Module targeting `node20`.
+- **Testing:** `vitest` for fast unit tests, and Node/Bun runner for end-to-end smoke tests.
+
+---
+
+## 3. Development Workflow
+
+### 3.1 Install Dependencies
+```bash
+bun install
+```
+
+### 3.2 Watch Mode (Active Development)
+```bash
+bun run dev
+```
+
+### 3.3 Build Production Bundle
+```bash
+bun run build
+```
+
+### 3.4 Typecheck
+```bash
+bun run typecheck
+```
+
+### 3.5 Run Unit Tests
+```bash
+bun run test
+```
+
+### 3.6 Run Smoke Tests
+The smoke test suite verifies real extension generation, dependency installation, typechecking, and multi-browser builds across five distinct configurations:
+```bash
+bun run test:smoke
+```
+
+---
+
+## 4. Coding Conventions & Standards
+
+- **TypeScript Strictness:** Strict mode is enforced in `tsconfig.json`. Do not disable strict checks or introduce untyped `any` without explicit justification.
+- **Documentation:** Use JSDoc / TSDoc comments for exported functions, types, and interfaces. Avoid inline step comments or temporary notes in source files.
+- **No Decorative Symbols:** Do not use emojis, stickers, or decorative symbols in source code, console messages, or documentation.
+- **Binary Shebang:** The shebang `#!/usr/bin/env node` is declared at the top of `src/index.ts`. Do not duplicate it via bundler banners.
+- **Cross-Platform Compatibility:** Always handle Windows path separators and PowerShell execution nuances. For example, test file operations using `node:path` methods rather than hard-coded `/` or `\`.
+
+---
+
+## 5. Adding New Features or Browser Targets
+
+To extend the CLI with a new extension capability:
+
+1. **Context & Types (`src/cli/context.ts`):**
+   - Add new feature or extra keys to `FeatureKey` or `ExtraKey`.
+2. **Capability Matrix (`src/generate/targets.ts`):**
+   - Define whether the feature is supported by each browser target in `CAPABILITY_MATRIX`.
+3. **Manifest Generator (`src/generate/manifest.ts`):**
+   - Add the necessary manifest fields (permissions, keys, resources) for both MV3 and MV2.
+4. **Template Files (`templates/features/<feature>/`):**
+   - Provide template implementations for both TypeScript and JavaScript.
+5. **CLI Options (`src/cli/args.ts` & `src/cli/prompts.ts`):**
+   - Expose the corresponding CLI flags in `parseCliArgs` and help text.
+   - Add the interactive prompt option with support for skipping when the flag is supplied.
+6. **Tests (`test/`):**
+   - Add unit tests verifying argument parsing and manifest generation.
+   - Update `test-smoke.mjs` to validate end-to-end bundling.
+
+---
+
+## 6. Publishing Notes
+
+- **Package Verification:** Before publishing to npm, verify package contents and permissions:
+  ```bash
+  npm publish --dry-run
+  ```
+- **Automated Publishing:** A GitHub Actions workflow is configured at `.github/workflows/publish.yml` to automatically build, test, and publish to npm with `--provenance --access=public` whenever a new GitHub Release is published (`on: release`). Ensure the repository secret `NPM_TOKEN` is set up with publish permissions on npmjs.org.
+- **Unpublish History:** The package name `web-extension` has past unpublish records on the npm registry. Do not attempt live publishing without explicit clearance from the repository owner.
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TiwPhiraphan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,141 @@
-# Temporary Holding Version
+# web-extension
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Modern, flexible CLI tool to scaffold cross-browser extensions for Chromium (Chrome, Edge, Brave, Opera), Firefox, and Safari using **Vite** and **CRXJS**.
+
+---
+
+## Documentation
+
+- [Developer Guide](DEVELOPER.md) — Architecture, local development, testing, and contribution instructions.
+- [AI & Agent Specification](AI.md) — Complete behavioral contracts, machine-readable specifications, and capability matrices for AI agents and LLMs.
+
+---
+
+## Features
+
+- **Vite + CRXJS:** Ultra-fast bundling, live reloading, and HMR (Hot Module Replacement) where supported.
+- **Cross-Browser:** Supports Chromium (MV3), Firefox (MV3 & MV2), and Safari (MV3 & MV2).
+- **Modular Components:** Choose only what you need (Background service worker, Content scripts, Popup, Options page, Side panel, DevTools page, New Tab override, declarativeNetRequest rules).
+- **Content-Script Only Mode:** Purpose-built mode for DOM scrapers and injectors without unnecessary UI files.
+- **Automatic Type & Package Setup:** Installs browser-specific types (`@types/chrome`, `@types/firefox-webext-browser`) and auto-configures TypeScript (`tsconfig`) or JavaScript (`jsconfig`).
+- **Smart Package Manager Detection:** Automatically detects whether you ran via `bun`, `pnpm`, `npm`, or `yarn`.
+
+---
+
+## Quick Start
+
+Run the interactive generator using your preferred package manager:
+
+```bash
+# npm
+npx web-extension@latest init
+
+# pnpm
+pnpm dlx web-extension@latest init
+
+# bun
+bun x web-extension@latest init
+# or bunx
+bunx web-extension@latest init
+
+# yarn (Yarn 2+)
+yarn dlx web-extension@latest init
+
+# Or install globally
+npm install -g web-extension
+web-extension init
+```
+
+> **Windows + Bun:** On some Windows systems, `bunx` may not be registered in PowerShell by default. Use `bun x web-extension@latest init` instead.
+>
+> **Shortcut:** Invoking `web-extension` without a subcommand automatically routes to `init`. For example, `web-extension my-app` is equivalent to `web-extension init my-app`.
+
+---
+
+## Interactive Prompts & Flags
+
+Every interactive prompt has a corresponding CLI flag to enable scripted and non-interactive execution.
+
+| # | Prompt | Flag | Options / Accepted Values | Default (`--yes`) |
+|---|---|---|---|---|
+| 1 | Project name | `[dir]`, `--name <string>` | Target directory and npm package name | `my-extension` |
+| 1b | Directory not empty | `--if-exists <action>`, `--overwrite` | `cancel`, `overwrite`, `merge` | `cancel` |
+| 2 | Language | `--lang <ts\|js>` | `ts` (TypeScript), `js` (JavaScript) | `ts` |
+| 3 | Project type | `--type <full\|content-only>` | `full`, `content-only` | `full` |
+| 4 | Target browsers | `--browser <browsers>` | `chrome`, `firefox`, `safari` (comma-separated or repeated) | `chrome` |
+| 5 | Manifest version (Firefox) | `--firefox-mv <2\|3>` | `2`, `3` | `3` |
+| 5b | Manifest version (Safari) | `--safari-mv <2\|3>` | `2`, `3` | `3` |
+| 6 | Features (Full mode) | `--features <list>` | `background`, `content`, `popup`, `options`, `sidepanel`, `dnr`, `devtools`, `newtab` (or `none`) | `background,content` |
+| 7 | Content script: matches | `--matches <patterns>` | Comma-separated match patterns (`https://*/*`, etc.) | `https://*/*` |
+| 7 | Content script: run_at | `--run-at <timing>` | `document_start`, `document_end`, `document_idle` | `document_idle` |
+| 7 | Content script: world | `--world <world>` | `ISOLATED`, `MAIN` (MV3 only) | `ISOLATED` |
+| 7 | Content script: CSS | `--css` / `--no-css` | Generate CSS stylesheet for content script | `--css` |
+| 8 | Extras | `--extras <list>` | `contextmenu`, `commands`, `omnibox`, `storage` (or `none`) | `none` |
+| 9a | Package manager | `--pm <pm>` | `npm`, `pnpm`, `yarn`, `bun` | Auto-detected |
+| 9 | Install dependencies | `--install` / `--no-install` | Automatically run install | `--install` |
+| 10 | Git repository | `--git` / `--no-git` | Initialize git repo | `--git` |
+| - | Accept defaults | `--yes`, `-y` | Use defaults for any omitted options | - |
+| - | Help | `--help`, `-h` | Display help message and options | - |
+| - | Version | `--version`, `-v` | Display version | - |
+
+---
+
+## Common Recipes
+
+### 1. Full Chromium TypeScript Extension
+```bash
+web-extension my-chrome-ext --lang ts --browser chrome \
+  --features background,content,popup,options,sidepanel,dnr \
+  --extras storage,commands --yes
+```
+
+### 2. Firefox Manifest V2 JavaScript Extension
+```bash
+web-extension my-firefox-ext --lang js --browser firefox --firefox-mv 2 \
+  --features background,content,popup,options --yes
+```
+
+### 3. Headless Content-Script DOM Hacker
+```bash
+web-extension dom-injector --type content-only --browser chrome,firefox \
+  --matches "https://*.github.com/*" --yes
+```
+
+### 4. Cross-Browser Extension (Chrome, Firefox, Safari)
+```bash
+web-extension multi-browser-ext --lang ts --browser chrome,firefox,safari \
+  --firefox-mv 3 --safari-mv 2 --features background,content,popup --yes
+```
+
+---
+
+## Loading Your Extension into Browsers
+
+After creating your project, enter the directory and start the dev server:
+
+```bash
+cd my-extension
+npm run dev:chrome
+```
+
+### Chromium (Chrome, Edge, Brave, Opera)
+1. Navigate to `chrome://extensions`.
+2. Toggle on **Developer mode** in the top-right corner.
+3. Click **Load unpacked** and select the `dist/chrome-mv3` folder inside your project.
+
+### Firefox
+1. Navigate to `about:debugging#/runtime/this-firefox`.
+2. Click **Load Temporary Add-on...**.
+3. Select the `manifest.json` file inside `dist/firefox-mv3` (or `dist/firefox-mv2`).
+
+### Safari
+Convert the compiled web extension output into an Xcode project using Apple's built-in converter:
+```bash
+xcrun safari-web-extension-converter dist/safari-mv3
+```
+
+---
+
+## License
+
+[MIT](LICENSE)