# CLAUDE.md — worldmap-viewer

Map server + browser viewer for worldgen worlds (globe and flat views, tiles, deep zoom, pins, regions, export).
Terse everywhere. Private notes (tasks, specs, area maps) are kept outside this repo; never add them here (see
`.gitignore`). Overview, CLI table and layout: `README.md`.

## Layout
- Python server: `serve.py` (HTTP API, `env_defaults` = `WORLDMAP_<OPTION>`), `tiles.py`, `refine.py`, `rivers.py`,
  `seafloor.py`, `servecache.py`, `export.py`, `h3par.py`, `mapview.py` (CLI), `worldgen_path.py` (finds `mapgen`)
- Deploy: `deploy.py`, `dedupe.py`, `tilecap.py`, `deploy/` (Containerfile, server README)
- `viewer/` — browser app (`js/`, `tests/` node unit tests, `tools/smoke/` headless browser smoke, `vendor/` three.js:
  never edit); `tests/` — Python unittest (`tests/helpers.py`: small in-process mapgen grid, no world folder)

## Build / test
- Needs worldgen (the `mapgen` package): `$WORLDGEN`, `../worldgen` or `./worldgen`. Python deps (numpy, scipy, h3,
  pillow) are not in system python: a `.venv` with them (worldgen's works: `ln -sfn ../worldgen/.venv .venv`).
  In a git worktree link the main tree's `.venv` and `worldgen` (`.venv` and `/worldgen` are ignored without
  trailing slash: they may be links).
- Verify: `.venv/bin/python -m unittest discover -s tests -t .` (≈ 4 min; slow: test_tiles, test_serve,
  test_export) and `cd viewer && node --test tests/*.test.mjs` (≈ 3 s).
- Browser smoke: `WORLD=<world dir> PYTHON=.venv/bin/python viewer/tools/smoke.sh viewer/tools/smoke/core.mjs`.

## Git
- Work in a git worktree on a branch (`.worktrees/<topic>`), not in the main tree; ff-merge when green.