# Contributing to Pocketdex

Thanks for taking the time. This is a small, framework-free codebase and
easy to get into.

## Ground rules

- **No copyrighted assets.** Don't commit Pokémon sprites, artwork, audio,
  ROMs or save files. Everything visual is fetched at runtime from PokéAPI.
  PRs that add such files will be asked to remove them.
- **Non-commercial.** No ads, analytics, telemetry, paid tiers, affiliate
  links or "sign in" flows.
- **Stay framework-free.** No React/Vue/Svelte/etc., and no new runtime
  dependencies without discussing it in an issue first. Build-time dev
  dependencies are a lower bar but still worth raising.
- **Offline-first stays true.** The list, search, sort, filters and game
  switching must keep working with no network. New always-needed data goes
  in the snapshot, not a runtime fetch.
- **Be kind.** Assume good faith in issues and reviews.

## Getting set up

Requires **Node 20+**.

```bash
npm install
npm run snapshot      # build src/data/snapshot.json from PokéAPI (git-ignored)
npm run dev           # http://localhost:5173
```

To exercise the service worker, offline behaviour or the install prompt,
you need a real build:

```bash
npm run build && npm run preview
```

## Where things live

See the **Project layout** and **How it works** sections in
[README.md](README.md). In short:

- `src/views/<Name>.js` — one file per route, an `async` function returning
  a DOM node. Register it in `src/router.js`.
- `src/components/` — reusable pieces (`Card`, `Sprite`, `TypeChip`, …).
- `src/store/` — `createStore()`-backed reactive state, persisted to
  `localStorage` under `pdx.*`.
- `src/lib/` — framework-y helpers with no app knowledge (`dom`, `anim`,
  `damage-calc`, `savedex`, …).
- `src/data/` — the snapshot loader, the Pokédex resolver, the lazy PokéAPI
  client, the type chart, natures.
- `scripts/build-snapshot.mjs` — the only thing that talks to PokéAPI at
  build time.

## Code style

There's no linter or formatter config yet — **match the surrounding
code**:

- 2-space indent, semicolons, single quotes, trailing commas in
  multi-line literals (an `.editorconfig` covers whitespace).
- Build DOM with the `el()` helper from `src/lib/dom.js`, not template
  strings or `innerHTML` (except the deliberate `html:` prop for trusted
  inline SVG).
- Stores: `set(fn)` **replaces** state — spread `...s` yourself. Read with
  `get()`, react with `subscribe()`, and unsubscribe in the view's
  teardown (`onTeardown(view, off)`).
- Keep comments about _why_, not _what_. Match the existing density.
- Respect `prefersReducedMotion()` for any new animation.
- Keep everything game-aware: if you touch typings, type effectiveness,
  learnsets or evolution, honour the selected game's generation
  (`typesForGen`, `multiplier(atk, def, gen)`, `past_values`, …).

## Common tasks

**Add a setting** — add the key + default to `src/store/settings.js`
(and `applyTheme()` if it affects the document), then a field in
`src/views/SettingsView.js`. Add it to the export payload if it should
survive a backup.

**Add a snapshot field** — add it in `scripts/build-snapshot.mjs`, run
`npm run snapshot -- --force`, and consume it via `loadSnapshot()`. Keep
the snapshot small; it's precached on every install.

**Add a route** — new file in `src/views/`, one entry in the `routes`
array in `src/router.js`. Add a skeleton if the view does async work
before it can render.

## Testing your change

There's no automated suite. Before opening a PR, manually check:

- The **dex grid** — filters, sort, the progress ring, catching from a
  card.
- **Switching games** (the Games sheet) — regional numbers, era typings,
  and per-game seen/caught all update.
- A **detail page** — every tab, form switching, the track buttons.
- **`npm run build`** succeeds, and `npm run preview` still works offline
  (DevTools → Network → Offline, then reload).
- Light **and** dark theme, and a narrow (mobile) viewport.

Describe what you tested in the PR.

## Commits & pull requests

- Branch off `main`. One focused change per PR.
- Imperative commit subjects ("Add …", "Fix …"), with a body explaining
  the _why_ when it isn't obvious.
- Don't commit `dist/` or `src/data/snapshot.json` (both git-ignored).
- Fill in the PR template. Screenshots or a short clip for anything
  visual.
- It's fine to open a draft PR early to discuss direction.

## Reporting bugs

Open an issue with: what you did, what you expected, what happened, the
browser/OS, and the selected game if it's relevant. A screenshot or the
console output helps a lot.

## License

By contributing you agree that your contributions are licensed under the
[MIT License](LICENSE).