# Pokédex PWA

A responsive, offline-capable Pokédex reference built on
[PokéAPI](https://pokeapi.co/). Vanilla JS + Vite + Workbox — no UI
framework.

## Two headline features

| Feature | How it works |
| --- | --- |
| **Game series selection** | Pick a *game* (PokéAPI version group, e.g. Scarlet & Violet). If it has more than one regional dex (Paldea / Kitakami / Blueberry) a sub-dex switcher appears. The choice drives which species show, their regional numbering, and which version's flavor text the detail page uses. Stored in `localStorage`. |
| **Unified Pokémon selection** | One tracking record per Pokémon, keyed by **National Dex id**. Mark Pikachu once and every game's view reflects it — each dex computes its own "Seen / Caught" totals by intersecting its species list with that single map. The active Pokémon is also a single deep-linkable route (`#/pokemon/25`). |

## Data & storage split

- **Preferences + tracking state** → `localStorage` (`pdx.settings`, `pdx.selection`). Tiny, synchronous, restored on reload.
- **Build-time snapshot** (`src/data/snapshot.json`, ~150 KB) → generated by `npm run snapshot` from PokéAPI: every species (id, name, generation, types), all regional Pokédex lists, and all version groups. Precached by the service worker, so the list / search / game switching work on the first offline launch.
- **Detail data** (stats, abilities, flavor text, evolution) → fetched lazily from `pokeapi.co` per Pokémon, then cached by the service worker (stale-while-revalidate, 30-day TTL).
- **Sprites** → cache-first with a capped LRU.

Export / import of `settings` + `selection` as JSON lives in **Settings**.

## Scripts

```bash
npm install
npm run snapshot     # fetch data from PokéAPI -> src/data/snapshot.json (run once; refreshes if >30 days old)
npm run dev          # vite dev server
npm run build        # runs snapshot (prebuild) then vite build
npm run preview      # serve the production build (needed to exercise the service worker)
```

Deploying under a sub-path (e.g. GitHub Pages project site): `BASE_PATH=/repo-name/ npm run build`.

## Project layout

```
scripts/build-snapshot.mjs   PokéAPI -> snapshot.json
src/
  main.js                    boot: theme, nav, router, SW registration
  router.js                  hash router (#/, #/pokemon/:id, #/games, #/search, #/settings)
  sw.js                      Workbox service worker (injectManifest)
  store/                     createStore + settings + selection (localStorage)
  data/                      snapshot loader, pokedex resolver, lazy API client
  components/                Card, Sprite, TypeChip, StatBar, ProgressHeader, Nav
  views/                     DexGrid, PokemonDetail, GamePicker, SearchView, SettingsView
  styles/                    tokens.css (palette, type colors, light/dark), layout.css
```

## Status

Scaffold — build steps 1–5 of the design are in place: responsive shell,
snapshot pipeline, dex grid with per-dex progress, game picker, lazy detail
page, offline search, settings with export/import, and the service worker.

Not yet done: evolution chain, version-exclusive badges, richer filters
(type/generation/legendary — the snapshot would need legendary flags),
skeleton loaders, install-prompt handling, PNG/maskable raster icons
(currently an SVG icon only), and a Lighthouse PWA pass.

## Notes

- `npm audit` reports the known esbuild dev-server advisory via Vite 5. It
  affects the local dev server only, not the production build. Vite 8 (which
  fixes it) requires a newer Node than this environment has.
- Data and images © Nintendo / Game Freak / The Pokémon Company, served via
  PokéAPI. This project is a non-commercial reference tool.