Merge pull request #7 from atomantic/dev

v0.7.x: Migration Map, AI Discovery Dismiss, Debug Endpoints

Author: atomantic

.changelog/v0.7.x.md

@@ -0,0 +1,46 @@
+# Release v0.7.x - Migration Map, AI Discovery Improvements
+
+Released: Unreleased
+
+## Overview
+
+This release improves the AI Discovery feature with dismiss functionality, debugging capabilities, and better CLI integration.
+
+## New Features
+
+### AI Discovery Dismiss Functionality (v0.7.0)
+- Dismiss AI-discovered candidates to exclude them from future discoveries
+- Batch dismiss all unselected candidates at once
+- View dismissed candidates with original AI reasoning and tags
+- Undo dismiss to restore candidates
+- Clear all dismissed candidates for a database
+- Dismissed candidates stored in SQLite with `discovery_dismissed` table
+- API endpoints: POST `/dismiss`, POST `/dismiss-batch`, GET `/dismissed`, DELETE `/dismissed/:personId`, DELETE `/dismissed`
+
+### AI Discovery Debug Endpoints (v0.7.0)
+- New debug endpoints for troubleshooting AI run failures
+- GET `/api/ai-discovery/debug/runs` - list recent AI runs with metadata
+- GET `/api/ai-discovery/debug/runs/:runId` - detailed run info including prompt preview and output
+- Error details capture (last 10 lines of stderr/stdout) stored on failed runs
+
+### Migration Map Visualization (v0.7.x)
+- New 6th tree view mode: "Migration Map" plots ancestors on an interactive world map
+- Leaflet.js map with OpenStreetMap/CartoDB dark tiles
+- Lineage-colored markers (paternal=blue, maternal=red) with generation depth variation
+- Migration polylines connecting parent birth to child birth locations
+- Time range slider for filtering by birth year
+- Paternal/Maternal layer toggle checkboxes
+- Geocoding via Nominatim with permanent SQLite cache (`place_geocode` table)
+- Progressive geocode broadening: strips specific locality parts to resolve historical place names
+- User-initiated batch geocoding with SSE progress streaming (EventSource)
+- Sparse tree map page at `/favorites/sparse-tree/:dbId/map`
+- API: `GET /api/map/:dbId/:personId`, `GET /api/map/:dbId/sparse`, `GET /api/map/geocode/stream`
+
+## Bug Fixes
+
+### CLI Provider Integration (v0.7.0)
+- Fixed large prompt handling via stdin piping for CLI providers (codex, claude-code)
+- Added `-` flag detection in provider args to enable stdin mode
+- Fixed JSON parsing to find LAST valid JSON array in noisy CLI output
+- Handles CLI banners and headers that could interfere with response parsing
+- Improved error capture with `errorDetails` field for debugging failures

PLAN.md

@@ -38,6 +38,7 @@ High-level project roadmap. For detailed phase documentation, see [docs/roadmap.
 | 15.19 | Normalize FamilySearch as downstream provider | ✅ |
 | 15.20 | Relationship linking (parents, spouses, children) | 📋 |
 | 15.22 | Ancestry free hints automation | ✅ |
+| 15.23 | Migration Map visualization | ✅ |
 | 16 | Multi-platform sync architecture | 📋 |
 | 17 | Real-time event system (Socket.IO) | 📋 |
 
@@ -561,6 +562,63 @@ UI Button (ProviderDataTable)
 - `POST /api/ancestry-hints/:dbId/cancel` - Cancel running operation
 - `GET /api/ancestry-hints/status` - Check if running
 
+### Phase 15.23: Migration Map Visualization ✅
+
+A 6th tree view mode plotting ancestors on an interactive Leaflet.js map with lineage-colored markers, parent-child migration lines, time filtering, and layer controls.
+
+**Features:**
+- **Migration Map view mode** - Available in the tree view mode dropdown alongside Fan, Horizontal, Vertical, Columns, Focus
+- **Leaflet.js map** with OpenStreetMap tiles (light) and CartoDB dark tiles (dark theme)
+- **Lineage-colored markers** - Paternal (blue/teal), Maternal (red/coral), Self (purple)
+- **Migration polylines** connecting parent birth locations to child birth locations
+- **Time range slider** filtering ancestors by birth year
+- **Paternal/Maternal layer toggles** for lineage filtering
+- **Auto-fit bounds** on data load
+- **Click popups** with person name, lifespan, places, and link to person detail
+- **Geocoding service** using Nominatim with 1100ms rate limiting and permanent SQLite cache
+- **Geocode progress bar** with SSE streaming for batch geocoding
+- **Sparse tree map page** at `/favorites/sparse-tree/:dbId/map`
+
+**Architecture:**
+```
+Database: place_geocode table (SQLite cache)
+    → Geocode Service (Nominatim + cache)
+    → Map Service (tree data + coordinate joining)
+    → Map Routes (REST + SSE geocode stream)
+    → MigrationMapView (Leaflet + react-leaflet)
+```
+
+**Routes:**
+- `/tree/:dbId/:personId/map` - Ancestry tree migration map
+- `/favorites/sparse-tree/:dbId/map` - Sparse tree (favorites) migration map
+
+**API Endpoints:**
+- `GET /api/map/:dbId/:personId` - Ancestry tree map data
+- `GET /api/map/:dbId/sparse` - Sparse tree map data
+- `GET /api/map/geocode/stream` - Batch geocode via SSE (EventSource)
+- `GET /api/map/geocode/stats` - Geocode cache statistics
+- `POST /api/map/geocode/reset-not-found` - Reset failed entries for retry
+
+**Files Created:**
+- `server/src/db/migrations/006_place_geocode.ts` - Place geocode cache table
+- `server/src/services/geocode.service.ts` - Nominatim geocoding + SQLite cache
+- `server/src/services/map.service.ts` - Map data assembly
+- `server/src/routes/map.routes.ts` - REST + SSE endpoints
+- `client/src/components/ancestry-tree/views/MigrationMapView.tsx` - Leaflet map component
+- `client/src/components/favorites/SparseTreeMapPage.tsx` - Sparse tree map page
+- `client/src/components/map/GeocodeProgressBar.tsx` - Geocode progress UI
+- `client/src/components/map/mapUtils.ts` - Marker/line utilities
+
+**Files Modified:**
+- `server/src/db/migrations/index.ts` - Register migration 006
+- `server/src/db/schema.sql` - Add place_geocode table
+- `server/src/index.ts` - Mount mapRouter
+- `shared/src/index.ts` - MapCoords, MapPerson, MapData, GeocodeProgress types
+- `client/package.json` - leaflet, react-leaflet, @types/leaflet deps
+- `client/src/services/api.ts` - Map API methods
+- `client/src/components/ancestry-tree/AncestryTreeView.tsx` - Add 'map' view mode
+- `client/src/App.tsx` - Sparse tree map route
+
 ### Phase 16: Multi-Platform Sync (Remaining Items)
 
 - ~~Provider cache structure~~ (completed in 15.11)

README.md

@@ -2,6 +2,10 @@
 
 A genealogy toolkit for creating local databases of your family tree, curating favorites, and generating sparse family tree visualizations.
 
+## Origins
+
+This project is a web-based UI enhancement that evolved from the creator's early explorations into learning more about his ancestry using a CLI-based tool: [FamilySearchFinder](https://github.com/atomantic/FamilySearchFinder).
+
 ## What is SparseTree?
 
 SparseTree connects to genealogy providers (FamilySearch, Ancestry, WikiTree, 23andMe) to download and store your ancestry data locally. Once you have your data, you can:

client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fsf/client",
-  "version": "0.6.33",
+  "version": "0.7.12",
   "type": "module",
   "scripts": {
     "dev": "vite --port 6373",
@@ -10,17 +10,20 @@
   "dependencies": {
     "@fsf/shared": "*",
     "d3": "^7.9.0",
+    "leaflet": "^1.9.4",
     "lucide-react": "^0.562.0",
     "portos-ai-toolkit": "^0.1.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-hot-toast": "^2.6.0",
+    "react-leaflet": "^4.2.1",
     "react-router-dom": "^7.1.1",
     "socket.io-client": "^4.8.3",
     "zustand": "^5.0.2"
   },
   "devDependencies": {
     "@types/d3": "^7.4.3",
+    "@types/leaflet": "^1.9.21",
     "@types/react": "^18.3.18",
     "@types/react-dom": "^18.3.5",
     "@vitejs/plugin-react": "^4.3.4",

client/src/App.tsx

@@ -13,6 +13,7 @@ import { BrowserSettingsPage } from './pages/BrowserSettingsPage';
 import { ReportsPage } from './pages/ReportsPage';
 import { FavoritesPage } from './components/favorites/FavoritesPage';
 import { SparseTreePage } from './components/favorites/SparseTreePage';
+import { SparseTreeMapPage } from './components/favorites/SparseTreeMapPage';
 import { DatabaseFavoritesPage } from './components/favorites/DatabaseFavoritesPage';
 import { IntegrityPage } from './components/integrity/IntegrityPage';
 import { AncestryUpdatePage } from './components/ancestry-update';
@@ -41,6 +42,7 @@ function App() {
         <Route path="tools/gedcom" element={<GedcomPage />} />
         <Route path="favorites" element={<FavoritesPage />} />
         <Route path="favorites/sparse-tree/:dbId" element={<SparseTreePage />} />
+        <Route path="favorites/sparse-tree/:dbId/map" element={<SparseTreeMapPage />} />
         <Route path="db/:dbId/favorites" element={<DatabaseFavoritesPage />} />
         <Route path="db/:dbId/integrity" element={<IntegrityPage />} />
         <Route path="db/:dbId/integrity/:tab" element={<IntegrityPage />} />