Release v0.2.x: Multi-Platform Linking & Tree Views

.changelog/README.md

@@ -0,0 +1,119 @@
+# Release Changelogs
+
+This directory contains **all** release notes for SparseTree. Unlike traditional projects that maintain a root `CHANGELOG.md` file, we use version-specific files that evolve with development and automatically archive on release.
+
+**No root CHANGELOG.md needed** - all changelog content lives in this directory.
+
+## Structure
+
+Each minor version series has its own markdown file following the naming convention:
+
+```
+v{major}.{minor}.x.md
+```
+
+The "x" is a literal character, not a placeholder - it represents the entire minor version series (e.g., all 0.2.x releases share `v0.2.x.md`).
+
+Examples:
+- `v0.1.x.md` - Used for releases 0.1.1, 0.1.2, 0.1.3, etc.
+- `v0.2.x.md` - Used for releases 0.2.1, 0.2.2, 0.2.3, etc.
+- `v1.0.x.md` - Used for releases 1.0.1, 1.0.2, 1.0.3, etc.
+
+## Format
+
+Each changelog file should follow this structure:
+
+```markdown
+# Release v{major}.{minor}.x - {Descriptive Title}
+
+Released: YYYY-MM-DD
+
+## Overview
+
+A brief summary of the release, highlighting the main theme or most important changes.
+
+## 🎉 New Features
+
+### Feature Category 1
+- Feature description with technical details
+- Another feature in this category
+
+## 🐛 Bug Fixes
+
+### Fix Category
+- Description of what was fixed
+- Impact and technical details
+
+## 🔧 Improvements
+
+### Improvement Category
+- What was improved
+- Why it matters
+
+## 🗑️ Removed
+
+### Deprecated Features
+- What was removed
+- Why it was removed
+
+## 📦 Installation
+
+\`\`\`bash
+git clone https://github.com/atomantic/SparseTree.git
+cd SparseTree
+npm run install:all
+pm2 start ecosystem.config.cjs
+\`\`\`
+
+## 🔗 Full Changelog
+
+**Full Diff**: https://github.com/atomantic/SparseTree/compare/v{prev}...v{major}.{minor}.x
+```
+
+## Workflow
+
+### During Development
+
+Update `.changelog/v0.2.x.md` **every time** you add features and fixes:
+- Add entries under appropriate emoji sections (🎉 Features, 🐛 Fixes, 🔧 Improvements)
+- Keep the version in the file as `v0.2.x` (literal x)
+- Don't worry about the final patch number - it will be substituted automatically
+
+### Before Merging to Main
+
+Final review before release:
+- Ensure all changes are documented
+- Add release date (update "YYYY-MM-DD" to actual date)
+- Review and polish the content
+- Commit the changelog file
+
+### On Release
+
+The GitHub Actions workflow automatically:
+1. Reads `.changelog/v0.2.x.md`
+2. Replaces all instances of `0.2.x` with the actual version (e.g., `0.2.5`)
+3. Creates the GitHub release with the substituted changelog
+4. Renames `v0.2.x.md` → `v0.2.5.md` (preserves git history)
+5. Bumps dev to next minor version
+
+### After Release
+
+- Create a new `v0.3.x.md` for the next minor version
+- Copy the previous version as a template
+
+## Best Practices
+
+### Do:
+- Update the changelog file **as you work** (not just before release)
+- Use clear, descriptive section headings
+- Group related changes together
+- Include technical details where helpful
+- Explain the "why" not just the "what"
+- Use emoji section headers for visual organization
+
+### Don't:
+- Create a root `CHANGELOG.md` file
+- Use vague descriptions like "various improvements"
+- Include internal implementation details users don't care about
+- Leave placeholder or TODO content
+- Change the version from `v0.2.x` to specific patch numbers during development

.changelog/v0.1.x.md

@@ -1,22 +1,42 @@
-# Release v0.1.x
+# Release v0.1.x - Initial Release
 
-## Features
+Released: 2026-01-20
 
+## Overview
+
+Initial release of SparseTree - a genealogy toolkit for creating local databases of your family tree with sparse tree visualizations.
+
+## 🎉 New Features
+
+### Core Functionality
 - Local web UI enhancement of FamilySearchFinder
 - Multi-platform genealogy provider support (FamilySearch, Ancestry, WikiTree, 23andMe)
 - Browser-based scraping with Playwright automation
 - Provider login credentials with encrypted storage for auto-authentication
+
+### Visualization
 - FamilySearch-style ancestry tree visualization
 - Favorites system with sparse tree visualization
-- GEDCOM import/export support
 - Path finding between ancestors (shortest/longest/random)
+
+### Data Management
+- GEDCOM import/export support
 - Light/dark theme support
 
-## Installation
+### Infrastructure (v0.1.1)
+- Browser status polling replaced with SSE
+- CDP browser integration for indexer
+- Ancestry tree line improvements
+
+## 📦 Installation
 
 ```bash
 git clone https://github.com/atomantic/SparseTree.git
 cd SparseTree
 npm run install:all
 pm2 start ecosystem.config.cjs
 ```
+
+## 🔗 Full Changelog
+
+**Full Diff**: https://github.com/atomantic/SparseTree/releases/tag/v0.1.x

.changelog/v0.2.x.md

@@ -0,0 +1,99 @@
+# Release v0.2.x - Multi-Platform Linking & Tree Views
+
+Released: YYYY-MM-DD
+
+## Overview
+
+Major enhancements to the ancestry tree visualization with four view modes and lazy loading for deep ancestry. Added multi-platform genealogy linking with Ancestry.com and WikiTree integration.
+
+## 🎉 New Features
+
+### Multiple Tree View Modes
+- **Focus Navigator**: Navigate one person at a time with breadcrumb trail
+- **Pedigree Chart**: Classic vertical tree with expandable generations
+- **Generational Columns**: Horizontal columns organized by generation
+- **Classic**: Original SVG-based tree with zoom/pan
+
+### Lazy Loading for Deep Ancestry
+- Initial load of 10 generations for columns view
+- "Load 5 more" button appears when more ancestors are available
+- Successfully tested loading 21 generations with 17,000+ ancestors
+
+### View Mode URL Persistence
+- Tree view mode saved in URL query params (`?view=columns`)
+
+### Ancestry.com Linking
+- Link persons to their Ancestry.com profiles with automatic photo extraction
+- Browser-based scraping with auto-login support using saved credentials
+- Srcset parsing to extract highest resolution photos (5x = maxside=1800)
+- Auto-launches/connects browser when needed
+
+### WikiTree Linking
+- Link persons to their WikiTree profiles with photo extraction
+- HTTP-based scraping (no auth required for public profiles)
+- Extracts profile photo and description
+
+### Manual Photo Selection
+- "Use Photo" button for each linked platform
+- Separated linking from photo fetching for user control
+- Support for FamilySearch, Wikipedia, Ancestry, and WikiTree photos
+- Photos stored locally with platform-specific naming (`{personId}-ancestry.jpg`, etc.)
+
+### Unified Platforms UI
+- Consolidated all platform links into single "Platforms" section in PersonDetail
+- FamilySearch, Wikipedia, Ancestry, WikiTree all shown together
+- Link and "Use Photo" buttons for each platform
+
+### Sample Database
+- Included sample genealogy database (G849-MHS) for new users to explore the app
+- Medieval Swiss nobility lineage (920-968 AD) with 4 persons
+- Sample databases load automatically and are marked with `isSample` flag
+- Cannot be deleted (protected from accidental removal)
+
+## 🔧 Improvements
+
+### Genealogy Providers
+- All 8 supported genealogy providers (FamilySearch, Ancestry, WikiTree, MyHeritage, Geni, FindMyPast, Find A Grave, 23andMe) are now pre-populated on first launch
+- No more manually adding each provider - just enable and configure the ones you want to use
+
+### Tree Visualization
+- **Simplified Generation Labels**: Gen 3+ shows "1st/2nd/3rd Great-Grandparents" instead of verbose labels
+- **Columns View Optimization**: Only displays known ancestors (hides unknown placeholders)
+- **Header Styling**: Fixed transparent header in columns view to prevent text collision when scrolling
+
+### Photo Priority
+- Updated sparse tree view to use photos in order:
+  1. Ancestry (highest priority)
+  2. WikiTree
+  3. Wikipedia
+  4. FamilySearch scraped (lowest priority)
+
+### Data Model
+- Added `photoUrl` field to PlatformReference to store discovered photo URLs before downloading
+- Added support for structured name fields:
+  - `birthName`: Birth/maiden name when display name differs (e.g., married name is preferred)
+  - `marriedNames`: Array of names taken after marriage
+  - `aliases`: Array of "also known as" names (nicknames, alternate spellings)
+  - Maintains backwards-compatible `alternateNames` array
+
+## 🐛 Bug Fixes
+
+- Browser auto-connects when linking Ancestry profiles (no more "Browser not connected" errors)
+- Ancestry photo now appears in sparse tree view
+- Indexer now handles network timeouts gracefully with retry logic instead of crashing
+  - ETIMEDOUT, ECONNRESET, and other transient errors automatically retry up to 3 times
+  - Exponential backoff (5s, 10s, 20s) between retries
+  - Failed fetches skip the person and continue indexing instead of exiting
+
+## 📦 Installation
+
+```bash
+git clone https://github.com/atomantic/SparseTree.git
+cd SparseTree
+npm run install:all
+pm2 start ecosystem.config.cjs
+```
+
+## 🔗 Full Changelog
+
+**Full Diff**: https://github.com/atomantic/SparseTree/compare/v0.1.x...v0.2.x

.gitignore

@@ -22,10 +22,12 @@ node_modules/
 server/dist/
 client/dist/
 shared/types/
+*.tsbuildinfo
 
 # IDE
 .vscode/
 .idea/
 
 # Screenshots (may contain personal family data)
-images/
+images/
+.playwright-mcp

CLAUDE.md

@@ -121,6 +121,46 @@ Persistent Chrome with CDP on port 9920:
 ```
 Profile data stored in `.browser/data/`. Connect via `ws://localhost:9920`.
 
+## Git Workflow
+
+- **dev**: Active development (auto-bumps patch on CI pass)
+- **main**: Production releases only
+- PR `dev → main` creates tagged release and preps next version
+- **Use `/gitup` to push** - The dev branch receives auto version bump commits from CI. Always use `git pull --rebase --autostash && git push` (or `/gitup`) instead of plain `git push`.
+- Update `.changelog/v{major}.{minor}.x.md` when making changes (see Release Changelog Process below)
+- **Commit after each feature or bug fix** - lint, commit, and push automatically to keep work safe
+
+## Release Changelog Process
+
+All release notes are maintained in `.changelog/v{major}.{minor}.x.md` files. Each minor version series has a single changelog file that accumulates changes throughout development. **No root CHANGELOG.md** - all changelog content lives in `.changelog/`.
+
+### During Development
+
+**Always update `.changelog/v0.2.x.md`** when you make changes:
+- Add entries under appropriate emoji sections (🎉 Features, 🐛 Fixes, 🔧 Improvements, 🗑️ Removed)
+- Keep the version as `v0.2.x` throughout development (don't change it to 0.2.2, 0.2.3, etc.)
+- Group related changes together for clarity
+- Explain the "why" not just the "what"
+
+### Before Releasing to Main
+
+Final review before merging `dev → main`:
+- Ensure all changes are documented in `.changelog/v0.2.x.md`
+- Add the release date (update "YYYY-MM-DD" to actual date)
+- Polish descriptions for clarity
+- Commit the changelog
+
+### On Release (Automated)
+
+When merging to `main`, the GitHub Actions workflow automatically:
+1. Reads `.changelog/v0.2.x.md`
+2. Replaces all instances of `0.2.x` with actual version (e.g., `0.2.5`)
+3. Creates the GitHub release with substituted changelog
+4. Renames `v0.2.x.md` → `v0.2.5.md` (preserves git history)
+5. Bumps dev to next minor version (e.g., 0.3.0)
+
+See `.changelog/README.md` for detailed format and best practices.
+
 ## Notes
 - The database has cyclic loop issues (people linked as their own ancestors) - use longest path method to detect these
 - ES modules (`"type": "module"` in package.json)

client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fsf/client",
-  "version": "1.0.0",
+  "version": "0.2.10",
   "type": "module",
   "scripts": {
     "dev": "vite --port 6373",