HikeMap/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

KML Track Editor is a single-page web application for viewing, editing, and navigating KML/GPS tracks on an interactive map. The entire application is contained in index.html.

Development

To run locally, serve via HTTP (required for GPS geolocation API):

python -m http.server 8000

Then open http://localhost:8000

Architecture

Single-File Application

Everything is in index.html:

• Lines 1-325: CSS styles
• Lines 326-420: HTML structure (map, controls sidebar, overlays)
• Lines 421-end: JavaScript application code

Key Libraries (loaded from CDN)

• Leaflet.js 1.9.4: Map rendering and interaction
• leaflet-rotate 0.2.8: Map rotation for navigation mode

Core State Variables (around line 457-514)

• tracks[]: All loaded track objects with {id, name, coords, layer, color}
• selectedTracks[]: Currently selected tracks for multi-selection operations
• currentTool: Active editing tool ('select', 'draw', 'reshape', 'smooth', 'delete')
• navMode: Whether in navigation mode vs edit mode
• currentRoute: Pathfinding result for navigation

Major Feature Areas

Track Editing:

• Draw new tracks, reshape existing ones with rope physics, smooth brush tool
• Track snapping at endpoints (auto-splits target track at snap point)
• Multi-track selection and merge operations
• Undo system with 20-step history

Navigation Mode:

• Graph-based pathfinding using Dijkstra's algorithm across connected trails
• Trail intersections detected within 5 meters (INTERSECTION_THRESHOLD)
• Real-time route recalculation when user deviates >50m from path
• Map rotation to face direction of travel (uses map.setBearing())
• Auto-center on GPS position (toggleable)
• Destination persistence in localStorage

GPS Integration:

• Uses navigator.geolocation.watchPosition with backup polling every 3 seconds
• Requires HTTPS or localhost to function

File Loading

• Automatically loads default.kml on startup if present
• KML parsing via DOMParser extracting <Placemark> coordinates