1

CONTRIBUTING.md

@@ -0,0 +1,138 @@
+# Contributing to Mimik
+
+Thanks for your interest in contributing! Bug reports, feature requests, PRs, and translations are all welcome.
+
+## Licensing
+
+By submitting a pull request or any contribution to this repository, you agree that your contribution will be licensed under the [MIT License](./LICENSE).
+
+You represent that you have the right to submit the contribution and that it does not infringe any third-party rights.
+
+## Development Setup
+
+### Prerequisites
+
+- Node.js 22+
+- [pnpm](https://pnpm.io) 10+
+- Chrome or Firefox (for testing)
+
+### Install
+
+```bash
+git clone https://github.com/westpoint-io/mimik.git
+cd mimik
+pnpm install
+```
+
+### Run in development
+
+```bash
+pnpm dev                   # Chrome (MV3) with HMR
+pnpm dev:firefox           # Firefox (MV3) with HMR
+```
+
+WXT launches a fresh browser instance with the extension loaded.
+
+### Build
+
+```bash
+pnpm build                 # Chrome → .output/chrome-mv3/
+pnpm build:firefox         # Firefox → .output/firefox-mv3/
+pnpm zip:all               # package both browsers
+```
+
+### Test
+
+```bash
+pnpm test                  # run all tests once
+pnpm test:watch            # watch mode
+pnpm test:cov              # coverage report
+```
+
+### Lint & format
+
+```bash
+pnpm lint                  # check
+pnpm lint:fix              # auto-fix
+pnpm format                # format only
+```
+
+## Project Layout
+
+```
+src/
+├── core/                    # Business logic (no UI dependencies)
+│   ├── capture/             # Recording pipeline (events, AI, DOM context)
+│   ├── blur/                # Smart blur (regex presets, DOM scanner, panel)
+│   ├── export/              # HTML, PDF, Markdown generators
+│   ├── guideme/             # Guide replay (finder, overlay, session)
+│   └── guides/              # Data layer (types, Dexie DB, CRUD)
+├── entrypoints/             # WXT extension entry points
+│   ├── background/          # Service worker: state machine + message handlers
+│   ├── content.ts           # Content script: event capture + rrweb
+│   ├── sidepanel/           # Side panel React mount
+│   ├── fullview/            # Full-page dashboard mount
+│   ├── onboarding/          # First-install wizard
+│   └── options/             # Settings page mount
+├── locales/                 # YAML translation files (en, es, pt-BR, fr)
+├── lib/                     # Shared utilities (messaging, port, browser API)
+├── stores/                  # Zustand state stores
+└── ui/                      # React components
+```
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Extension framework | [WXT](https://wxt.dev) (Manifest V3) |
+| Language | TypeScript |
+| UI | React 19 + Tailwind CSS v4 |
+| Components | [shadcn/ui](https://ui.shadcn.com) |
+| State (capture) | [XState](https://xstate.js.org) |
+| State (UI) | [Zustand](https://zustand-demo.pmnd.rs) |
+| Storage | [Dexie.js](https://dexie.org) (IndexedDB) |
+| Messaging | [webext-core](https://webext-core.aklinker1.io) |
+| Session recording | [rrweb](https://www.rrweb.io) |
+| Export | [jsPDF](https://github.com/parallax/jsPDF) + HTML/Markdown |
+| AI (optional) | [Vercel AI SDK](https://sdk.vercel.ai) (OpenAI, Anthropic) |
+| i18n | [@wxt-dev/i18n](https://wxt.dev) + YAML locales |
+| Testing | [Vitest](https://vitest.dev) + Testing Library |
+
+## Pull Request Guidelines
+
+1. Fork the repo and create a branch: `git checkout -b feat/your-feature`
+2. Make your changes and add tests where applicable
+3. Run the full check locally before pushing:
+   ```bash
+   pnpm lint && pnpm test && pnpm build && pnpm build:firefox
+   ```
+4. Use [Conventional Commits](https://www.conventionalcommits.org) for commit messages:
+   - `feat:` new feature
+   - `fix:` bug fix
+   - `docs:` documentation
+   - `test:` tests only
+   - `chore:` tooling/deps
+5. Open a PR with a clear description of what and why
+
+CI (`pr-test.yml`) will run lint, tests, and both browser builds on every PR.
+
+## Adding a Translation
+
+To add a new language:
+
+1. Create `src/locales/{lang-code}.yml` (e.g., `src/locales/de.yml`)
+2. Copy the structure from `src/locales/en.yml`
+3. Translate all values, keeping the keys identical
+4. Keep substitution placeholders (`$1`, `$2`) in the same positions
+5. Build and test: `pnpm build:firefox` (WXT generates types for new locale keys automatically)
+
+## Reporting Bugs
+
+Open an issue with:
+
+- What you expected to happen
+- What actually happened
+- Steps to reproduce
+- Browser + version (Chrome / Firefox)
+- Screenshots if relevant
+- Any errors from the extension console (`chrome://extensions` → Mimik → "service worker" → Console, or Firefox `about:debugging` → Inspect)