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.