Pre-release cleanup and README update for v1.0.0

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: mariofaranda

.gitignore

@@ -27,6 +27,9 @@ data/
 # Private documentation (kept locally)
 docs/
 
+# Archived unused source files (kept locally)
+archive/
+
 # Environment variables
 .env.local
 .vercel

README.md

@@ -11,6 +11,7 @@ Lightpath calculates the flight trajectory between any two airports and visualiz
 ## What it does
 
 - **Great circle routing** — Plots the shortest path between airports on a 3D globe
+- **Real flight trajectories** — Look up any flight by callsign to trace its actual route using historical flight data
 - **Solar illumination mapping** — Color-codes flight segments by daylight, twilight (civil/nautical/astronomical), and darkness
 - **Time animation** — Watch flights move through changing light as Earth rotates
 - **Astronomical accuracy** — Uses NOAA equations for solar declination and Jean Meeus algorithms for solar position
@@ -21,7 +22,7 @@ Lightpath calculates the flight trajectory between any two airports and visualiz
 
 - **React 19** + **Three.js** for 3D rendering
 - **Vite** for build tooling
-- **solar-calculator** (NOAA) + **suncalc** (Jean Meeus) for astronomical calculations
+- **solar-calculator** (NOAA) + **suncalc** for astronomical calculations
 - **Custom GLSL shaders** for twilight visualization
 
 ---
@@ -30,26 +31,35 @@ Lightpath calculates the flight trajectory between any two airports and visualiz
 
 - Real-time solar position calculation
 - Latitude-dependent twilight width modeling
+- Two search modes: airport-to-airport routing (Great Circle Routes) and flight number lookup
 - Animated flight playback with sun position sync
 - Color and black-and-white visualization modes
 - Shareable flight URLs
+- Optional overlays: airport dots, graticule, timezone boundaries, twilight lines
 
 ---
 
 ## Project structure
 ```
 src/
-├── App.jsx              # Main component
+├── App.jsx              # Main component (3D scene, state, non-panel UI)
 ├── App.css              # All styles
 ├── components/
 │   ├── AirportSearchInput.jsx
 │   ├── FlightInputPanel.jsx
-│   └── AnimationControls.jsx
+│   ├── AnimationControls.jsx
+│   └── ShareButton.jsx
+├── services/
+│   └── fr24.js          # FlightRadar24 API client
 └── utils/
-    ├── geoUtils.js      # Coordinate conversion
+    ├── geoUtils.js      # Coordinate conversion + flight scaling
     ├── solarUtils.js    # Solar position calculations
     ├── sceneUtils.js    # Label texture generation
-    └── animationUtils.js # Fade animations
+    ├── animationUtils.js # Fade animations
+    ├── routeInterpolation.js # Timestamp interpolation along arc-length
+    ├── captureUtils.js  # Screenshot capture for share cards
+    ├── cardGenerator.js # Share card image generation
+    └── shareUtils.js    # Web Share API wrapper
 
 scripts/
 └── build-airports.js    # OurAirports CSV → airports.json
@@ -59,7 +69,7 @@ public/
 ├── earth-texture.png    # Custom Earth texture
 ├── graticule-10.geojson # Latitude/longitude grid
 ├── timezones.geojson    # Timezone boundaries
-└── icons/               # SVG icons
+└── fonts/               # ABC Repro, ABC Repro Mono
 ```
 
 ---
@@ -80,9 +90,10 @@ npm run build
 ## Credits
 
 Airport data: [OurAirports](https://ourairports.com/data/)
-Astronomical calculations: [solar-calculator](https://www.npmjs.com/package/solar-calculator) (NOAA) and [suncalc](https://github.com/mourner/suncalc) (Jean Meeus)   
+Astronomical calculations: [solar-calculator](https://www.npmjs.com/package/solar-calculator) (NOAA) and [suncalc](https://github.com/mourner/suncalc) (Jean Meeus)
+Topography: [NASA](https://science.nasa.gov/earth/earth-observatory/blue-marble-next-generation/topography-bathymetry-maps/)
 
-Designed and developed by [Studio Folder](https:www.studiofolder.it)
+Designed and developed by [Studio Folder](https://www.studiofolder.it)
 
 
 ---

docs/fr24-integration-plan.md

@@ -3,8 +3,8 @@
 **Project**: Lightpath
 **Feature**: Historical Flight Route Tracking
 **Target**: v1.0.0 (currently v0.9.6)
-**Date**: 2026-03-20
-**Status**: Phase 4 complete (caching, deep links, date-independence implemented)
+**Date**: 2026-03-21
+**Status**: Phase 5 in progress (cleanup, error handling, UI polish started)
 **Alternative approach**: `api-plan-adsbexchange.md` (ADSBexchange via RapidAPI, Feb 2026)
 
 ---
@@ -589,12 +589,14 @@ Flight Summary Light is only needed to obtain the `fr24_id` and confirm the flig
 
 4. **Vite proxy `flight_ended` filter** — ✅ FIXED. The local dev Vite custom middleware (`vite.config.js`) now replicates the full `flight-lookup.js` logic including the `flight_ended === true` filter. Local dev behavior matches production. The only difference is no Upstash Redis cache locally — every search hits FR24 live.
 
-5. **Callsign resolved airports display styling** — The resolved FROM/TO airports in callsign mode use inline `fontFamily: 'monospace'` styling (lines 304, 321 of FlightInputPanel.jsx) which doesn't match the route mode styling. Should use the same CSS classes as route mode's airport code display. Cosmetic issue for UI polish phase.
+5. **Callsign resolved airports display styling** — ✅ FIXED (2026-03-21). Replaced inline `fontFamily: 'monospace'` with `.callsign-airport-code` CSS class matching route mode's `.airport-columns.route-mode .input-group input` styling (ABCReproMono, 48px, weight 300, letter-spacing 2px). BW mode override and mobile breakpoint added. Color set to `rgba(255, 255, 255, 0.85)` for dark mode.
 
 6. **`vercel.json` rewrite change** — Updated `/(.*) → /index.html` to `/((?!api/).*)` for `vercel dev` compatibility. This is a no-op in production (Vercel resolves functions before rewrites). Should be verified on production deploy.
 
 7. **Serverless functions use `export default` (ES modules)** — Changed from `module.exports` (CommonJS) to `export default` due to `"type": "module"` in package.json. Works with both Vercel deployment and `vercel dev`. Verified.
 
+8. **Flight mode shows great circle distance instead of real route distance** — ✅ FIXED (2026-03-20). In `handleCallsignStart()`, the displayed distance was computed as a great circle between origin/destination airports, identical to route mode. Now the real route distance is computed by sampling the CatmullRom curve (500 points via `getPointAt`) and summing haversine segment distances. The great circle distance is still used for camera positioning (`centerCameraOnFlight`) and plane icon scaling (`getFlightScale`), since those depend on the airport-to-airport span. The `results.distance` value now reflects the actual airway routing (typically 2–8% longer than great circle for transatlantic flights).
+
 ### Phase 4b: Caching & Date-Independence ✅
 
 - [x] Create `api/flight-lookup.js` — merged serverless function that handles both summary + events in a single call, with Upstash Redis cache layer (see §8.2). Uses `@upstash/redis` package.
@@ -615,17 +617,31 @@ Flight Summary Light is only needed to obtain the `fr24_id` and confirm the flig
 - [x] Ensure `handleCallsignStart()` updates URL with the user-selected date/time after rendering: `navigate(\`/flight/${callsignInput}/${dt.toFormat('yyyy-MM-dd')}/${dt.toFormat('HHmm')}\`, { replace: true })`
 - [x] Update `main.jsx` routes: `/flight/:segment1/:date/:time` and `/flight/:callsign`
 
-### Phase 5: Testing & Polish
+### Phase 5: Testing & Polish (in progress)
+
+**Completed (2026-03-21):**
+- [x] Delete legacy `api/flight-search.js` and `api/flight-events.js` — superseded by `api/flight-lookup.js`, no longer called by client
+- [x] CSS refinement: `.callsign-airport-code` class matching route mode styling (both color and B&W themes)
+- [x] Fix date field click area — `onClick` added directly on hidden date `<input>` instead of parent div (z-index conflict)
+- [x] Error differentiation — `fr24.js` now throws typed errors (`rate_limited`, `server_error`, `request_failed`); `handleCallsignSearch()` shows specific user-facing messages for 429 / 5xx / generic errors
+- [x] Remove dead `buildControlPoints()` from `routeInterpolation.js` — was unused, `handleCallsignStart` builds control points inline
+- [x] Fix `flightDurationMs` rounding inconsistency — rendering useEffect now reads exact `totalDurationMs` from `flightDataRef.current.flightDurationMs` instead of recomputing from rounded hours/minutes (eliminates ~30s precision loss)
+- [x] Graceful fallback when events are insufficient — if `< 2` events with lat/lon, falls back to great circle via `calculateFlight()`
+- [x] Loading indicator — FIND button shows `'...'` with pulsing animation (`calculate-pill--loading`) during search
+- [x] Callsign error state — inline styles extracted to CSS classes (`.callsign-error`, `.callsign-error-message`, `.callsign-error-dismiss`) with BW mode overrides
+- [x] Callsign input layout — inline styles extracted to CSS classes (`.callsign-input-columns`, `.callsign-input-column`, `.callsign-find-row`)
+- [x] Mode toggle redesign (partial) — pill-shaped ROUTE/FLIGHT toggle with sliding indicator replaces h3 text. Uses `<span>` elements (not `<button>`) to avoid browser focus styling. Indicator animates via `transform: translateX`. Both themes implemented.
 
+**In progress:**
+- [ ] Mode toggle header layout — three-element layout (h3 "Search" left, toggle centred, chevron right) not yet resolved; toggle positioning conflicts with collapse button placement
+
+**Remaining:**
 - [ ] Test with diverse flights (short-haul, long-haul, polar, domestic)
-- [ ] Tune CatmullRom tension parameter
+- [ ] Tune CatmullRom tension parameter (currently 0.0 default; `CATMULLROM_TENSION` constant extracted for easy tuning)
 - [ ] Verify visual quality at different zoom levels
 - [ ] Edge cases: diverted flights, cancelled flights, no events
 - [ ] Performance: verify no rendering regression
 - [ ] Capture/share: verify ShareButton works with event-based routes
-- [ ] CSS refinement for callsign mode UI elements (both color and B&W modes)
-- [ ] Graceful fallback when events are insufficient (great circle between Summary airports)
-- [ ] Error differentiation (429 rate limit vs 5xx API error vs not found)
 
 ### Phase 6: Credit Monitoring (Post-Launch)
 
@@ -747,29 +763,44 @@ On Explorer tier (30,000 credits/month): without cache, ~1,875 unique lookups. W
 
 ---
 
-## 9a. Complete File Inventory (as of 2026-03-20)
+## 9a. Complete File Inventory (as of 2026-03-21)
 
 ### New files created:
 ```
 api/flight-lookup.js           # Merged serverless function: summary + events + Upstash Redis cache (implemented)
-api/flight-search.js           # Legacy: Vercel serverless proxy → FR24 Flight Summary Light (deprecated, kept for reference)
-api/flight-events.js           # Legacy: Vercel serverless proxy → FR24 Historic Events Light (deprecated, kept for reference)
-src/services/fr24.js           # Client-side API calls (lookupFlight with in-memory cache)
-src/utils/routeInterpolation.js # buildControlPoints + interpolateTimestamp (with arc-length-aware interpolation)
+src/services/fr24.js           # Client-side API calls (lookupFlight with in-memory cache, typed errors)
+src/utils/routeInterpolation.js # interpolateTimestamp (with arc-length-aware interpolation)
 tests/fr24-sandbox-test.mjs    # Standalone sandbox API test (not committed)
 tests/fr24-production-test.mjs # Standalone production API test (not committed)
 ```
 
+### Deleted files:
+```
+api/flight-search.js           # Legacy: deleted 2026-03-21, superseded by flight-lookup.js
+api/flight-events.js           # Legacy: deleted 2026-03-21, superseded by flight-lookup.js
+```
+
 ### Modified files:
 ```
 src/App.jsx                    # searchMode state, callsign state/refs, handleCallsignSearch/Start,
                                # rendering branch (SLERP vs CatmullRom with getPointAt + sphere normalization),
                                # airportsIcao lookup, arc-length fractions, calculateFlight clears callsign refs,
                                # deep-link useEffect for /flight/:callsign/:date/:time,
                                # editable datetime pill in callsign mode,
-                               # relative timing model (user-chosen date + offsets)
-src/components/FlightInputPanel.jsx  # Header mode toggle, callsign input/FIND, resolved airports display,
-                               # error state, editable datetime pill, CALCULATE/START conditional text
+                               # relative timing model (user-chosen date + offsets),
+                               # error differentiation (rate_limited, server_error, request_failed),
+                               # flightDurationMs precision fix, graceful fallback for insufficient events,
+                               # CATMULLROM_TENSION constant
+src/App.css                    # .callsign-airport-code (matching route mode styling),
+                               # .callsign-error / .callsign-error-message / .callsign-error-dismiss,
+                               # .callsign-input-columns / .callsign-input-column / .callsign-find-row,
+                               # .calculate-pill--loading animation,
+                               # .mode-toggle / .mode-toggle-indicator / .mode-toggle-btn (pill toggle),
+                               # BW mode overrides for all new classes
+src/components/FlightInputPanel.jsx  # Pill-shaped mode toggle (ROUTE/FLIGHT with sliding indicator),
+                               # h3 "Search" title, callsign input/FIND, resolved airports display,
+                               # error state with CSS classes, editable datetime pill,
+                               # date picker onClick fix, loading indicator on FIND button
 vite.config.js                 # Custom configureServer middleware for local dev (/api/flight-lookup)
 vercel.json                    # SPA rewrite updated with negative lookahead to exclude /api/
 src/main.jsx                   # Routes: /, /flight/:segment1/:date/:time, /flight/:callsign

eslint.config.js

@@ -23,7 +23,7 @@ export default defineConfig([
       },
     },
     rules: {
-      'no-unused-vars': ['error', { varsIgnorePattern: '^[A-Z_]' }],
+      'no-unused-vars': ['error', { varsIgnorePattern: '^[A-Z_]', argsIgnorePattern: '^_' }],
     },
   },
 ])

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "lightpath",
-  "version": "0.9.6",
+  "version": "1.0.0",
   "private": true,
   "type": "module",
   "scripts": {

package.json

@@ -2,10 +2,14 @@
 - Airports: [OurAirports](https://github.com/davidmegginson/ourairports-data)
 - Timezones: [tz-lookup](https://github.com/darkskyapp/tz-lookup-oss)
 - Coastline: [GSHHG/NOAA](https://www.ngdc.noaa.gov/mgg/shorelines/shorelines.html)
+- Topography: [NASA](https://science.nasa.gov/earth/earth-observatory/blue-marble-next-generation/topography-bathymetry-maps/)
 - Graticule: [Natural Earth](https://www.naturalearthdata.com/)
 
+## Flights
+- Historic flight data: [Flightradar24](https://fr24api.flightradar24.com/)
+
 ## Libraries
-[Three.js](https://github.com/mrdoob/three.js/), [React](https://react.dev/), [Luxon](https://github.com/moment/luxon/), [SunCalc](https://cran.r-project.org/web/packages/SunCalcMeeus/index.html)
+[Luxon](https://github.com/moment/luxon/), [SunCalc](https://cran.r-project.org/web/packages/SunCalcMeeus/index.html), [Three.js](https://github.com/mrdoob/three.js/), [React](https://react.dev/)
 
 ## Typography
 [ABC Repro](https://abcdinamo.com/typefaces/repro), [LL Rephlex](https://lineto.com/typefaces/rephlex)