# Contributing to Navigator

Thanks for contributing! This file covers how to build, test, and verify changes
to the Navigator web app before opening a PR or pushing.

## Project layout (quick map)

```
scripts/osm-data.mjs     # Overpass API data fetch -> static/data/<area>.geojson
scripts/osm-dump.mjs     # .osm.pbf dump ingestion -> POIs + routable road graph
src/lib/routing.ts       # pure routing math (A*, POI avoidance, turn-by-turn)
src/lib/routing.worker.ts# Web Worker entry that runs route() off the UI thread
src/lib/prefs.ts         # unit-system preference (localStorage)
src/lib/savedPoints.ts   # browser-local Saved Points store + export/import (merge)
src/lib/components/      # MapView, DirectionsPanel, LocationDialog, …
src/routes/+page.svelte  # top-level page (loads the manifest)
```

## Setup

```bash
npm install

# Fetch & build all static data (Overpass + dump). Uses committed data if you
# only need the frontend; see below for data-only commands.
npm run build

# For frontend work without re-fetching over the network:
npm run build:static     # rebuilds just the static site from existing static/data
npm run dev              # Vite dev server
```

Data-only commands (they hit Overpass / download .pbf — be mindful of rate
limits):

```bash
npm run build:data       # Overpass fetch -> static/data/*.geojson
npm run build:dump       # .osm.pbf ingestion -> *-poi.geojson + *-graph.json
```

## Running the automated checks

Run all three before considering a change done:

```bash
npm run check            # svelte-check (types + Svelte diagnostics) — 0 errors/warnings
npm test                 # 33k+ offline regression checks (data, routing, saved points)
npm run build:static     # static site must build cleanly
```

These run offline (no Overpass/Nominatim) and are exactly what CI runs on every
push. **If any of these fail, fix before pushing.**

## Continuous Integration

- CI runs on every push/PR via Gitea Actions (`.gitea/workflows/ci.yml`).
- It runs `npm ci`, `npm run check`, `npm test`, `npm run build:static`, and
  verifies `build/index.html` + `build/data` exist.
- Requires a registered runner with the `host` label (host-mode, no Docker).

## Manual QA checklist

The automated tests cover the data and routing logic. Because this sandbox's
browser tooling only reaches public URLs (and cloud browsers are intentionally not
used), the **visual/interaction layer needs a manual local pass**. Open the app
locally (`npm run dev`, or serve `build/` with any static server) and verify:

1. **Empty-map click** opens a context dialog with **"Save point…"** — it does
   **not** auto-save or auto-start routing.
2. **Existing-point click** (a POI/zone/path) opens the dialog showing its info
   and a **"Directions from here"** action.
3. **"Directions from here"** pins the origin, opens the Directions panel, and
   lets you pick a destination.
4. **Second-point click** offers **"Directions to here"**, which sets it as the
   destination.
5. The **Directions** top-bar button and the top **"Data sources"** bar are
   **gone** (routes start only via the context dialog).
6. **Saved Points** toggle in the legend shows/hides the purple saved-point pins.
7. **Preferences** → **Export / Import** round-trips saved points; import
   **merges** (dedupes by id) rather than replacing.
8. Route computation shows a **live progress bar** and the UI stays responsive
   (Web Worker is off the main thread).
9. **Drive mode** shows **turn-by-turn** steps (Head north / Turn right /
   Arrive at destination); Walk mode shows distance + time without turn steps.

### Reporting an issue

If a checklist item fails, note:
- The step number and what you did.
- Expected vs. actual behavior.
- Any console errors (browser dev tools → Console).
- Screenshot if helpful.

Then either file it or paste the details here for a fix.

## Commit conventions

Angular-style, e.g.:

```
feat(directions): run route in a Web Worker with live progress
fix(ui): open context dialog on map click instead of auto-saving
refactor(prefs): drop redundant unit override
docs: document the context-dialog interaction
```

Commit small, logical units (often one per task) and keep CI green on each.