flowchart TD
    A["new App(containerId)"] --> B["constructor()"]
    B --> B1["Variant detection"]
    B --> B2["Panel order migration"]
    B --> B3["URL state parsing"]
    B --> B4["Mobile detection"]
    B --> B5["Disabled sources loading"]

    B --> C["init()"]
    C --> C1["initDB()"]
    C1 --> C2["initI18n()"]
    C2 --> C3["mlWorker.init()"]
    C3 --> C4["AIS config check"]
    C4 --> C5["renderLayout()"]
    C5 --> C6["Setup handlers"]
    C6 --> C7["preloadCountryGeometry()"]
    C7 --> C8["loadAllData()"]

    C8 --> D["Post-load"]
    D --> D1["startLearning()"]
    D --> D2["setupRefreshIntervals()"]
    D --> D3["setupSnapshotSaving()"]
    D --> D4["cleanOldSnapshots()"]
    D --> D5["handleDeepLinks()"]
    D --> D6["checkForUpdate() (desktop)"]

flowchart LR
    Fetch["Service fetch"] --> Process["App method processes response"]
    Process --> State["Update private properties"]
    State --> Component["Call component update methods"]
    Component --> DOM["DOM updates"]

private allNews: NewsItem[] = [];
private newsByCategory: Record<string, NewsItem[]> = {};
private latestPredictions: PredictionMarket[] = [];
private latestMarkets: MarketData[] = [];
private latestClusters: ClusteredEvent[] = [];
private currentTimeRange: TimeRange = '7d';
private monitors: Monitor[];
private panelSettings: Record<string, PanelConfig>;
private mapLayers: MapLayers;
private cyberThreatsCache: CyberThreat[] | null = null;

private map: MapContainer | null = null;
private panels: Record<string, Panel> = {};
private newsPanels: Record<string, NewsPanel> = {};
private signalModal: SignalModal | null = null;
private playbackControl: PlaybackControl | null = null;
private statusPanel: StatusPanel | null = null;
private exportPanel: ExportPanel | null = null;
private languageSelector: LanguageSelector | null = null;
private searchModal: SearchModal | null = null;
private mobileWarningModal: MobileWarningModal | null = null;
private pizzintIndicator: PizzIntIndicator | null = null;
private countryBriefPage: CountryBriefPage | null = null;
private countryTimeline: CountryTimeline | null = null;
private findingsBadge: IntelligenceGapBadge | null = null;
private criticalBannerEl: HTMLElement | null = null;

private isPlaybackMode = false;          // playback / historical mode toggle
private isMobile: boolean;               // detected at construction
private initialLoadComplete = false;     // first data load complete flag
private isIdle = false;                  // idle detection state
private isDestroyed = false;             // cleanup flag
private readonly isDesktopApp: boolean;  // Tauri runtime detection

private initialUrlState: ParsedMapUrlState | null = null;
private inFlight: Set<string> = new Set();             // currently-running fetch keys
private seenGeoAlerts: Set<string> = new Set();         // deduplicate geo alerts
private disabledSources: Set<string> = new Set();       // user-disabled news sources
private mapFlashCache: Map<string, number> = new Map(); // cooldown for map flash animations
private pendingDeepLinkCountry: string | null = null;   // URL deep-link target
private briefRequestToken = 0;                          // cancellation token for async ops

private snapshotIntervalId: ReturnType<typeof setInterval> | null = null;
private refreshTimeoutIds: Map<string, ReturnType<typeof setTimeout>> = new Map();
private idleTimeoutId: ReturnType<typeof setTimeout> | null = null;

private boundKeydownHandler: ((e: KeyboardEvent) => void) | null = null;
private boundFullscreenHandler: (() => void) | null = null;
private boundResizeHandler: (() => void) | null = null;
private boundVisibilityHandler: (() => void) | null = null;
private boundIdleResetHandler: (() => void) | null = null;

private readonly PANEL_ORDER_KEY = 'panel-order';
private readonly IDLE_PAUSE_MS = 2 * 60 * 1000;          // 2 minutes
private readonly MAP_FLASH_COOLDOWN_MS = 10 * 60 * 1000;  // 10 minutes

private static COUNTRY_BOUNDS: Record<string, { n: number; s: number; e: number; w: number }>;
private static COUNTRY_ALIASES: Record<string, string[]>;
private static otherCountryTermsCache: Map<string, string[]> = new Map();

stateDiagram-v2
    [*] --> Construct: new App()
    Construct --> Init: init()
    Init --> Loading: loadAllData()
    Loading --> Running: data loaded
    Running --> Idle: 2 min no interaction
    Idle --> Running: user interaction
    Running --> Destroyed: destroy()
    Idle --> Destroyed: destroy()
    Destroyed --> [*]

    state Running {
        [*] --> Refreshing
        Refreshing --> Waiting: fetch complete
        Waiting --> Refreshing: interval fires
    }

const PANEL_SPANS_KEY = 'worldmonitor-panel-spans';

// Stored as Record<string, number> — panel ID → grid span (1–4)
function loadPanelSpans(): Record<string, number> {
  const stored = localStorage.getItem(PANEL_SPANS_KEY);
  return stored ? JSON.parse(stored) : {};
}

function savePanelSpan(panelId: string, span: number): void {
  const spans = loadPanelSpans();
  spans[panelId] = span;
  localStorage.setItem(PANEL_SPANS_KEY, JSON.stringify(spans));
}

function heightToSpan(height: number): number {
  if (height >= 500) return 4;
  if (height >= 350) return 3;
  if (height >= 250) return 2;
  return 1;
}

export const STORAGE_KEYS = {
  panels:        'worldmonitor-panels',
  monitors:      'worldmonitor-monitors',
  mapLayers:     'worldmonitor-layers',
  disabledFeeds: 'worldmonitor-disabled-feeds',
} as const;

// Read stored preference (falls back to 'dark')
getStoredTheme(): Theme

// Read current DOM theme (from data-theme attribute)
getCurrentTheme(): Theme

// Full theme switch: DOM + cache invalidation + persist + meta + event
setTheme(theme: Theme): void

// Early bootstrap: sets data-theme + meta only (no events)
applyStoredTheme(): void

sequenceDiagram
    participant User
    participant setTheme
    participant DOM
    participant ColorCache
    participant localStorage
    participant Window

    User->>setTheme: setTheme('light')
    setTheme->>DOM: data-theme = 'light'
    setTheme->>ColorCache: invalidateColorCache()
    setTheme->>localStorage: setItem('worldmonitor-theme', 'light')
    setTheme->>DOM: meta[theme-color].content = '#f8f9fa'
    setTheme->>Window: dispatchEvent('theme-changed')

const colorCache = new Map<string, string>();
let cacheTheme = '';

export function getCSSColor(varName: string): string {
  const currentTheme = document.documentElement.dataset.theme || 'dark';
  if (currentTheme !== cacheTheme) {
    colorCache.clear();
    cacheTheme = currentTheme;
  }
  // ...read from cache or compute
}

export function invalidateColorCache(): void {
  colorCache.clear();
  cacheTheme = '';
}

// Push new observation, trim to 30-day window, recalculate averages
updateBaseline(key: string, currentCount: number): Promise<BaselineEntry>

// Calculate z-score deviation level
calculateDeviation(current: number, baseline: BaselineEntry): {
  zScore: number;
  percentChange: number;
  level: 'normal' | 'elevated' | 'spike' | 'quiet';
}

saveSnapshot(snapshot: DashboardSnapshot): Promise<void>
getSnapshots(fromTime?, toTime?): Promise<DashboardSnapshot[]>
getSnapshotAt(timestamp: number): Promise<DashboardSnapshot | null>  // nearest ±15 min
cleanOldSnapshots(): Promise<void>  // removes entries older than 7 days
getSnapshotTimestamps(): Promise<number[]>

export async function initDB(): Promise<IDBDatabase> {
  // Opens or creates worldmonitor_db v1
  // Creates 'baselines' store (keyPath: 'key')
  // Creates 'snapshots' store (keyPath: 'timestamp', index: 'by_time')
}

flowchart TD
    subgraph Write Path
        A["Service fetches data"] --> B["App.updateBaseline()"]
        B --> C["storage.updateBaseline()"]
        C --> D["IDB baselines store"]

        E["Snapshot interval fires"] --> F["App.saveSnapshot()"]
        F --> G["storage.saveSnapshot()"]
        G --> H["IDB snapshots store"]
    end

    subgraph Read Path
        I["Anomaly check"] --> J["storage.calculateDeviation()"]
        J --> K["Read from baselines"]

        L["Playback mode"] --> M["storage.getSnapshotAt()"]
        M --> N["Read from snapshots"]
    end

export interface ParsedMapUrlState {
  view?: MapView;
  zoom?: number;
  lat?: number;
  lon?: number;
  timeRange?: TimeRange;
  layers?: MapLayers;
  country?: string;
}

const LAYER_KEYS: (keyof MapLayers)[] = [
  'conflicts', 'bases', 'cables', 'pipelines', 'hotspots', 'ais',
  'nuclear', 'irradiators', 'sanctions', 'weather', 'economic',
  'waterways', 'outages', 'cyberThreats', 'datacenters', 'protests',
  'flights', 'military', 'natural', 'spaceports', 'minerals', 'fires',
  'ucdpEvents', 'displacement', 'climate', 'startupHubs', 'cloudRegions',
  'accelerators', 'techHQs', 'techEvents',
];

sequenceDiagram
    participant URL
    participant Constructor
    participant Init
    participant Map

    URL->>Constructor: window.location.search
    Constructor->>Constructor: parseMapUrlState(search, fallbackLayers)
    Constructor->>Constructor: Store as initialUrlState
    Note over Constructor: Apply layers override if present

    Constructor->>Init: init()
    Init->>Init: parseMapUrlState() again for pendingDeepLinkCountry
    Init->>Init: setupUrlStateSync()
    Init->>Map: Apply view, zoom, center from initialUrlState

buildMapUrl(baseUrl: string, state: {
  view: MapView;
  zoom: number;
  center?: { lat: number; lon: number } | null;
  timeRange: TimeRange;
  layers: MapLayers;
  country?: string;
}): string

export type RuntimeSecretKey =
  | 'GROQ_API_KEY'
  | 'OPENROUTER_API_KEY'
  | 'FRED_API_KEY'
  | 'EIA_API_KEY'
  | 'CLOUDFLARE_API_TOKEN'
  | 'ACLED_ACCESS_TOKEN'
  | 'URLHAUS_AUTH_KEY'
  | 'OTX_API_KEY'
  | 'ABUSEIPDB_API_KEY'
  | 'WINGBITS_API_KEY'
  | 'WS_RELAY_URL'
  | 'VITE_OPENSKY_RELAY_URL'
  | 'OPENSKY_CLIENT_ID'
  | 'OPENSKY_CLIENT_SECRET'
  | 'AISSTREAM_API_KEY'
  | 'FINNHUB_API_KEY'
  | 'NASA_FIRMS_API_KEY'
  | 'UC_DP_KEY';

export type RuntimeFeatureId =
  | 'aiGroq'          | 'aiOpenRouter'
  | 'economicFred'    | 'energyEia'
  | 'internetOutages' | 'acledConflicts'
  | 'abuseChThreatIntel' | 'alienvaultOtxThreatIntel'
  | 'abuseIpdbThreatIntel' | 'wingbitsEnrichment'
  | 'aisRelay'        | 'openskyRelay'
  | 'finnhubMarkets'  | 'nasaFirms';

flowchart TD
    subgraph Desktop
        A["OS Keychain (Tauri IPC)"] -->|secrets| B["RuntimeConfig"]
        C["localStorage"] -->|feature toggles| B
    end

    subgraph Web
        D["Environment vars / Vercel"] -->|secrets| E["RuntimeConfig"]
        F["Not applicable"] -.->|feature toggles| E
    end

export interface RuntimeFeatureDefinition {
  id: RuntimeFeatureId;
  name: string;
  description: string;
  requiredSecrets: RuntimeSecretKey[];
  desktopRequiredSecrets?: RuntimeSecretKey[];
  fallback: string;
}

export interface ActivityState {
  seenIds: Set<string>;                    // Items user has "seen"
  firstSeenTime: Map<string, number>;      // When items first appeared
  newCount: number;                        // Unseen items count
  lastInteraction: number;                 // Last user interaction timestamp
}

// Initialize tracking for a panel
register(panelId: string): void

// Update items and compute new count — returns array of new item IDs
updateItems(panelId: string, itemIds: string[]): string[]

// Mark all items as seen (user interacted with panel)
markAsSeen(panelId: string): void

stateDiagram-v2
    [*] --> New: First observed
    New --> Highlighted: 0–30 sec
    Highlighted --> Tagged: 30 sec–2 min
    Tagged --> Seen: markAsSeen() or 2 min elapsed
    Seen --> [*]: Item removed from feed

    note right of Highlighted: Glow effect active
    note right of Tagged: "NEW" badge visible

private readonly IDLE_PAUSE_MS = 2 * 60 * 1000; // 2 minutes
private isIdle = false;
private idleTimeoutId: ReturnType<typeof setTimeout> | null = null;
private boundIdleResetHandler: (() => void) | null = null;

stateDiagram-v2
    [*] --> Active: App starts
    Active --> Idle: No interaction for 2 min
    Idle --> Active: User interaction detected

    note right of Active: Full refresh rate, animations on
    note right of Idle: Reduced refresh, animations paused

type CacheEnvelope<T> = {
  key: string;
  updatedAt: number;
  data: T;
};

flowchart TB
    subgraph "Persistent Storage"
        LS["localStorage"]
        IDB["IndexedDB (worldmonitor_db)"]
        KC["OS Keychain (desktop only)"]
    end

    subgraph "Volatile State"
        APP["App.ts private properties"]
        COMP["Component instances"]
        TRACK["ActivityTracker"]
    end

    subgraph "Entry Points"
        URL["URL query params"]
        ENV["Environment variables"]
    end

    URL -->|"parseMapUrlState()"| APP
    ENV -->|"runtime-config"| APP
    LS -->|"loadFromStorage()"| APP
    IDB -->|"initDB() / getBaseline()"| APP
    KC -->|"Tauri IPC"| APP

    APP -->|"saveToStorage()"| LS
    APP -->|"updateBaseline() / saveSnapshot()"| IDB
    APP --> COMP
    APP --> TRACK

    COMP -->|"savePanelSpan()"| LS