fix: stronger cache hash (FNV-1a 64-bit) and GeoIP abort on timeout

.claudedocs/sentry-triage/2026-02-19.md

@@ -0,0 +1,32 @@
+# Sentry Triage — 2026-02-19
+
+Commit: `09174fd` on `main`
+
+## Issues Triaged (5)
+
+### ACTIONABLE — Fixed in Code
+
+| ID | Title | Events | Users | Fix |
+|---|---|---|---|---|
+| WORLDMONITOR-1G | `Error: ML request unload-model timed out after 120000ms` | 30 | 27 | Wrapped `unloadModel()` in try/catch; timeout no longer leaks as unhandled rejection. Cleans up `loadedModels` set on failure. |
+| WORLDMONITOR-1F | `Error: ML request unload-model timed out after 120000ms` | 9 | 9 | Same root cause as 1G (different release build hash). |
+| WORLDMONITOR-1K | `TypeError: this.player.playVideo is not a function` | 1 | 1 | Added optional chaining (`playVideo?.()`, `pauseVideo?.()`) in `LiveNewsPanel.ts`. YT IFrame API player object may not have methods ready during initialization race. |
+
+### NOISE — Filtered
+
+| ID | Title | Events | Users | Filter |
+|---|---|---|---|---|
+| WORLDMONITOR-1J | `InternalError: too much recursion` | 1 | 1 | i18next internal `translate -> extractFromKey` cycle on Firefox 147. Added `/too much recursion/` to `ignoreErrors`. |
+| WORLDMONITOR-1H | `TypeError: Cannot read properties of null (reading 'id')` | 1 | 1 | maplibre-gl internal render crash (`_drawLayers -> renderLayers`). Extended `beforeSend` regex to suppress null `id`/`type` when stack is in map chunk. |
+
+## Files Modified
+
+| File | Change |
+|---|---|
+| `src/services/ml-worker.ts` | `unloadModel()`: try/catch around `this.request()`, clean `loadedModels` on failure |
+| `src/components/LiveNewsPanel.ts` | Optional chaining on `playVideo?.()` and `pauseVideo?.()` |
+| `src/main.ts` | Added `/too much recursion/` to `ignoreErrors`; extended maplibre `beforeSend` filter for null `id`/`type` |
+
+## Sentry Status
+
+All 5 issues marked **resolved (in next release)** via API. They will auto-reopen if errors recur after deployment.

.env.example

@@ -0,0 +1,123 @@
+# ============================================
+# World Monitor — Environment Variables
+# ============================================
+# Copy this file to .env.local and fill in the values you need.
+# All keys are optional — the dashboard works without them,
+# but the corresponding features will be disabled.
+#
+#   cp .env.example .env.local
+#
+# ============================================
+
+
+# ------ AI Summarization (Vercel) ------
+
+# Groq API (primary — 14,400 req/day on free tier)
+# Get yours at: https://console.groq.com/
+GROQ_API_KEY=
+
+# OpenRouter API (fallback — 50 req/day on free tier)
+# Get yours at: https://openrouter.ai/
+OPENROUTER_API_KEY=
+
+
+# ------ Cross-User Cache (Vercel — Upstash Redis) ------
+
+# Used to deduplicate AI calls and cache risk scores across visitors.
+# Create a free Redis database at: https://upstash.com/
+UPSTASH_REDIS_REST_URL=
+UPSTASH_REDIS_REST_TOKEN=
+
+
+# ------ Market Data (Vercel) ------
+
+# Finnhub (primary stock quotes — free tier available)
+# Register at: https://finnhub.io/
+FINNHUB_API_KEY=
+
+
+# ------ Energy Data (Vercel) ------
+
+# U.S. Energy Information Administration (oil prices, production, inventory)
+# Register at: https://www.eia.gov/opendata/
+EIA_API_KEY=
+
+
+# ------ Economic Data (Vercel) ------
+
+# FRED (Federal Reserve Economic Data)
+# Register at: https://fred.stlouisfed.org/docs/api/api_key.html
+FRED_API_KEY=
+
+
+# ------ Aircraft Tracking (Vercel) ------
+
+# Wingbits aircraft enrichment (owner, operator, type)
+# Contact: https://wingbits.com/
+WINGBITS_API_KEY=
+
+
+# ------ Conflict & Protest Data (Vercel) ------
+
+# ACLED (Armed Conflict Location & Event Data — free for researchers)
+# Register at: https://acleddata.com/
+ACLED_ACCESS_TOKEN=
+
+
+# ------ Internet Outages (Vercel) ------
+
+# Cloudflare Radar API (requires free Cloudflare account with Radar access)
+CLOUDFLARE_API_TOKEN=
+
+
+# ------ Satellite Fire Detection (Vercel) ------
+
+# NASA FIRMS (Fire Information for Resource Management System)
+# Register at: https://firms.modaps.eosdis.nasa.gov/
+NASA_FIRMS_API_KEY=
+
+
+# ------ Railway Relay (scripts/ais-relay.cjs) ------
+# The relay server handles AIS vessel tracking and OpenSky aircraft data.
+# Deploy on Railway with: node scripts/ais-relay.cjs
+
+# AISStream API key for live vessel positions
+# Get yours at: https://aisstream.io/
+AISSTREAM_API_KEY=
+
+# OpenSky Network OAuth2 credentials (higher rate limits for cloud IPs)
+# Register at: https://opensky-network.org/
+OPENSKY_CLIENT_ID=
+OPENSKY_CLIENT_SECRET=
+
+
+# ------ Railway Relay Connection (Vercel → Railway) ------
+
+# Server-side URL (https://) — used by Vercel edge functions to reach the relay
+WS_RELAY_URL=
+
+# Client-side URL (wss://) — used by the browser to connect via WebSocket
+VITE_WS_RELAY_URL=
+
+
+# ------ Public Data Sources (no keys required) ------
+
+# UCDP (Uppsala Conflict Data Program) — public API, no auth
+# UNHCR (UN Refugee Agency) — public API, no auth (CC BY 4.0)
+# Open-Meteo — public API, no auth (processes Copernicus ERA5)
+# WorldPop — public API, optional key for higher rate limits
+# WORLDPOP_API_KEY=
+
+
+# ------ Site Configuration ------
+
+# Site variant: "full" (worldmonitor.app) or "tech" (tech.worldmonitor.app)
+VITE_VARIANT=full
+
+# Client-side Sentry DSN (optional). Leave empty to disable error reporting.
+VITE_SENTRY_DSN=
+
+# Map interaction mode:
+# - "flat" keeps pitch/rotation disabled (2D interaction)
+# - "3d" enables pitch/rotation interactions (default)
+VITE_MAP_INTERACTION_MODE=3d

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,88 @@
+name: Bug Report
+description: Report a bug in World Monitor
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please fill out the sections below so we can reproduce and fix it.
+
+  - type: dropdown
+    id: variant
+    attributes:
+      label: Variant
+      description: Which variant are you using?
+      options:
+        - worldmonitor.app (Full / Geopolitical)
+        - tech.worldmonitor.app (Tech / Startup)
+        - finance.worldmonitor.app (Finance)
+        - Desktop app (Windows)
+        - Desktop app (macOS)
+        - Desktop app (Linux)
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Affected area
+      description: Which part of the app is affected?
+      options:
+        - Map / Globe
+        - News panels / RSS feeds
+        - AI Insights / World Brief
+        - Market Radar / Crypto
+        - Service Status
+        - Trending Keywords
+        - Country Brief pages
+        - Live video streams
+        - Desktop app (Tauri)
+        - Settings / API keys
+        - Settings / LLMs (Ollama, Groq, OpenRouter)
+        - Live webcams
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug description
+      description: A clear description of what the bug is.
+      placeholder: Describe the bug...
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: Steps to reproduce the behavior.
+      placeholder: |
+        1. Go to '...'
+        2. Click on '...'
+        3. Scroll down to '...'
+        4. See error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What you expected to happen.
+    validations:
+      required: true
+
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: Screenshots / Console errors
+      description: If applicable, add screenshots or paste browser console errors.
+
+  - type: input
+    id: browser
+    attributes:
+      label: Browser & OS
+      description: e.g. Chrome 120 on Windows 11, Safari 17 on macOS Sonoma
+      placeholder: Chrome 120 on Windows 11

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Documentation
+    url: https://github.com/koala73/worldmonitor/blob/main/docs/DOCUMENTATION.md
+    about: Read the full documentation before opening an issue
+  - name: Discussions
+    url: https://github.com/koala73/worldmonitor/discussions
+    about: Ask questions and share ideas in Discussions

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,55 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Have an idea for World Monitor? We'd love to hear it!
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Feature area
+      description: Which area does this feature relate to?
+      options:
+        - Map / Globe / Data layers
+        - News panels / RSS feeds
+        - AI / Intelligence analysis
+        - Market data / Crypto
+        - Desktop app
+        - UI / UX
+        - API / Backend
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: A clear description of the feature you'd like.
+      placeholder: I'd like to see...
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem it solves
+      description: What problem does this feature address? What's the use case?
+      placeholder: This would help with...
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Have you considered any alternative solutions or workarounds?
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Any mockups, screenshots, links, or references that help illustrate the idea.

.github/ISSUE_TEMPLATE/new_data_source.yml

@@ -0,0 +1,69 @@
+name: New Data Source
+description: Suggest a new RSS feed, API, or map layer
+labels: ["data-source"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        World Monitor aggregates 100+ feeds and data layers. Suggest a new one!
+
+  - type: dropdown
+    id: type
+    attributes:
+      label: Source type
+      description: What kind of data source is this?
+      options:
+        - RSS / News feed
+        - API integration
+        - Map layer (geospatial data)
+        - Live video stream
+        - Status page
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: variant
+    attributes:
+      label: Target variant
+      description: Which variant should this appear in?
+      options:
+        - Full (Geopolitical)
+        - Tech (Startup)
+        - Finance
+        - All variants
+    validations:
+      required: true
+
+  - type: input
+    id: source-name
+    attributes:
+      label: Source name
+      description: Name of the source or organization.
+      placeholder: e.g. RAND Corporation, CoinDesk, USGS
+    validations:
+      required: true
+
+  - type: input
+    id: url
+    attributes:
+      label: Feed / API URL
+      description: Direct URL to the RSS feed, API endpoint, or data source.
+      placeholder: https://example.com/rss
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Why add this source?
+      description: What value does this source bring? What does it cover that existing sources don't?
+      placeholder: This source provides coverage of...
+    validations:
+      required: true
+
+  - type: textarea
+    id: notes
+    attributes:
+      label: Additional notes
+      description: Any details about rate limits, authentication requirements, data format, or category placement.