feat: show TLE epoch age per source with styled tooltip

Replace cache age display with average TLE epoch age per data source.
Hovering shows a detailed breakdown (newest, P25, median, average, P75,
oldest) plus fetch time when available. Add reusable tooltip Svelte
action (use:tooltip) with HTML support, replacing native title attrs.

Author: sandrwich

src/app.ts

@@ -31,7 +31,7 @@ import { fetchTLEData, parseSatelliteDataParallel, warmupTLEWorkers, evictExpire
 import { cachePut, cleanupLocalStorage } from './data/cache-db';
 import { getSatellitesByFreqRange } from './data/satnogs';
 import { loadStdmag, loadSatnogs, applyStdmag, onStdmagRefresh } from './data/catalog';
-import { sourcesStore, type TLESourceConfig } from './stores/sources.svelte';
+import { sourcesStore, type TLESourceConfig, type EpochAgeStats } from './stores/sources.svelte';
 import { timeStore } from './stores/time.svelte';
 import { uiStore } from './stores/ui.svelte';
 import { beamStore } from './stores/beam.svelte';
@@ -567,6 +567,23 @@ export class App {
     this.mergeAndApply(enabledIdSet);
   }
 
+  private computeEpochAge(satellites: Satellite[]): EpochAgeStats | undefined {
+    if (satellites.length === 0) return undefined;
+    const nowUnix = Date.now() / 1000;
+    const ages = satellites.map(s => (nowUnix - epochToUnix(s.epochDays)) * 1000);
+    ages.sort((a, b) => a - b);
+    const sum = ages.reduce((a, b) => a + b, 0);
+    const p = (frac: number) => ages[Math.min(Math.floor(frac * ages.length), ages.length - 1)];
+    return {
+      avgMs: sum / ages.length,
+      newestMs: ages[0],
+      oldestMs: ages[ages.length - 1],
+      p25Ms: p(0.25),
+      p50Ms: p(0.5),
+      p75Ms: p(0.75),
+    };
+  }
+
   private async fetchSource(src: TLESourceConfig) {
     sourcesStore.setLoadState(src.id, { satCount: 0, status: 'loading' });
     try {
@@ -575,7 +592,7 @@ export class App {
         const result = await fetchTLEData(src.group!);
         satellites = result.satellites;
         const age = result.cacheAge;
-        sourcesStore.setLoadState(src.id, { satCount: satellites.length, status: 'loaded', cacheAge: age });
+        sourcesStore.setLoadState(src.id, { satCount: satellites.length, status: 'loaded', cacheAge: age, epochAge: this.computeEpochAge(satellites) });
       } else if (src.type === 'url') {
         const controller = new AbortController();
         const timeout = setTimeout(() => controller.abort(), 10000);
@@ -585,11 +602,11 @@ export class App {
         const text = await resp.text();
         satellites = await parseSatelliteDataParallel(text);
         await cachePut('tlescope_tle_custom_' + src.id, { ts: Date.now(), data: text, count: satellites.length });
-        sourcesStore.setLoadState(src.id, { satCount: satellites.length, status: 'loaded' });
+        sourcesStore.setLoadState(src.id, { satCount: satellites.length, status: 'loaded', epochAge: this.computeEpochAge(satellites) });
       } else {
         const text = await sourcesStore.getCustomText(src.id);
         satellites = await parseSatelliteDataParallel(text);
-        sourcesStore.setLoadState(src.id, { satCount: satellites.length, status: 'loaded' });
+        sourcesStore.setLoadState(src.id, { satCount: satellites.length, status: 'loaded', epochAge: this.computeEpochAge(satellites) });
       }
       this.sourceData.set(src.id, satellites);
     } catch (e) {

src/stores/sources.svelte.ts

@@ -12,10 +12,20 @@ export interface TLESourceConfig {
   builtin: boolean; // true = CelesTrak, can't delete
 }
 
+export interface EpochAgeStats {
+  avgMs: number;       // average epoch age in ms
+  oldestMs: number;    // oldest (max age) epoch in ms
+  newestMs: number;    // newest (min age) epoch in ms
+  p25Ms: number;       // 25th percentile
+  p50Ms: number;       // median
+  p75Ms: number;       // 75th percentile
+}
+
 export interface SourceLoadState {
   satCount: number;
   status: 'idle' | 'loading' | 'loaded' | 'error';
   cacheAge?: number;
+  epochAge?: EpochAgeStats;
   error?: string;
 }
 

src/ui/DataSourcesWindow.svelte

@@ -6,8 +6,8 @@
   import Input from './shared/Input.svelte';
   import { uiStore } from '../stores/ui.svelte';
   import { sourcesStore, type TLESourceConfig, type SourceType } from '../stores/sources.svelte';
-  // getCacheAge is now async (IndexedDB) — we use loadState.cacheAge instead
   import { ICON_DATA_SOURCES, ICON_DOWNLOAD, ICON_EDIT, ICON_CLOSE } from './shared/icons';
+  import { tooltip } from './shared/tooltip';
   import VirtualList from './shared/VirtualList.svelte';
   import { textToRecords, ommToJson, type DataFormat } from '../data/omm-formats';
 
@@ -153,12 +153,29 @@
     return `${days}d`;
   }
 
-  function getCacheInfo(src: { id: string; group?: string; type: string }): string | null {
+  function epochRow(label: string, ms: number): string {
+    return `  ${label}  <span class="val">${formatAge(ms)}</span>`;
+  }
+
+  function getEpochAgeInfo(src: { id: string }): { label: string; tooltip: string } | null {
     const state = sourcesStore.loadStates.get(src.id);
-    if (state?.status === 'loaded' && state.cacheAge != null) {
-      return formatAge(state.cacheAge);
+    if (state?.status !== 'loaded' || !state.epochAge) return null;
+    const ea = state.epochAge;
+    const label = formatAge(ea.avgMs);
+    const lines = [
+      `<b>Epoch age</b> <span class="dim">(TLE freshness)</span>`,
+      epochRow('Newest ', ea.newestMs),
+      epochRow('P25    ', ea.p25Ms),
+      epochRow('Median ', ea.p50Ms),
+      epochRow('Average', ea.avgMs),
+      epochRow('P75    ', ea.p75Ms),
+      epochRow('Oldest ', ea.oldestMs),
+    ];
+    let html = lines.join('\n');
+    if (state.cacheAge != null) {
+      html += `<div class="sep"></div>Fetched <span class="val">${formatAge(state.cacheAge)}</span> ago`;
     }
-    return null;
+    return { label, tooltip: html };
   }
 
   function openPasteModal() {
@@ -266,7 +283,7 @@
       <div class="section-header">CelesTrak{#if filterQuery} <span class="filter-count">({filteredBuiltins.length})</span>{/if}</div>
       <div class="source-list">
         {#each filteredBuiltins as src}
-          {@const cached = getCacheInfo(src)}
+          {@const epochInfo = getEpochAgeInfo(src)}
           {@const enabled = sourcesStore.enabledIds.has(src.id)}
           <label class="source-row">
             <Checkbox size="sm"
@@ -276,8 +293,8 @@
             {#if enabled}
               <span class="source-count">{getStatus(src.id)}</span>
             {/if}
-            {#if cached}
-              <span class="cache-age" title="Cached {cached} ago">{cached}</span>
+            {#if epochInfo}
+              <span class="epoch-age" use:tooltip={{ html: epochInfo.tooltip }}>{epochInfo.label}</span>
             {/if}
             {#if hasCachedData(src)}
               <button class="action-btn" title="Download" onclick={(e) => { e.preventDefault(); downloadSource(src); }}>{@html ICON_DOWNLOAD}</button>
@@ -293,6 +310,7 @@
       {#if customSources.length > 0}
         <div class="source-list custom-list">
           {#each customSources as src}
+            {@const epochInfo = getEpochAgeInfo(src)}
             <label class="source-row">
               <Checkbox size="sm"
                 checked={sourcesStore.enabledIds.has(src.id)}
@@ -301,6 +319,9 @@
               {#if sourcesStore.enabledIds.has(src.id)}
                 <span class="source-count">{getStatus(src.id)}</span>
               {/if}
+              {#if epochInfo}
+                <span class="epoch-age" use:tooltip={{ html: epochInfo.tooltip }}>{epochInfo.label}</span>
+              {/if}
               {#if hasCachedData(src)}
                 <button class="action-btn" title="Download" onclick={(e) => { e.preventDefault(); downloadSource(src); }}>{@html ICON_DOWNLOAD}</button>
                 <button class="action-btn" title="Edit" onclick={(e) => { e.preventDefault(); openEditModal(src); }}>{@html ICON_EDIT}</button>
@@ -488,10 +509,12 @@
     color: var(--text-ghost);
     flex-shrink: 0;
   }
-  .cache-age {
+  .epoch-age {
     font-size: 10px;
     color: var(--text-faint);
     flex-shrink: 0;
+    white-space: pre-line;
+    cursor: default;
   }
   .action-btn {
     background: none;

src/ui/shared/tooltip.ts

@@ -0,0 +1,172 @@
+/** Svelte action for styled tooltips. Replaces native `title` attributes.
+ *
+ * Usage:
+ *   use:tooltip={'Simple text'}
+ *   use:tooltip={{ text: 'Hello', placement: 'top' }}
+ *   use:tooltip={{ html: '<b>Bold</b> text', placement: 'bottom' }}
+ */
+
+export type TooltipPlacement = 'top' | 'bottom';
+
+export interface TooltipOptions {
+  text?: string;
+  html?: string;
+  placement?: TooltipPlacement;
+}
+
+type TooltipParam = string | TooltipOptions | null | undefined;
+
+interface ParsedTooltip {
+  content: string;
+  isHtml: boolean;
+  placement: TooltipPlacement;
+}
+
+const GAP = 6;
+const VIEWPORT_PAD = 8;
+
+let activeEl: HTMLElement | null = null;
+let tipEl: HTMLDivElement | null = null;
+let hideTimeout: ReturnType<typeof setTimeout> | null = null;
+
+function ensureStyle() {
+  if (document.getElementById('_tooltip-style')) return;
+  const style = document.createElement('style');
+  style.id = '_tooltip-style';
+  style.textContent = `
+    ._tooltip {
+      position: fixed;
+      z-index: 99999;
+      background: var(--tooltip-bg, #111);
+      border: 1px solid var(--border, #333);
+      color: var(--text-dim, #aaa);
+      font-family: 'Overpass Mono', monospace;
+      font-size: 11px;
+      line-height: 1.5;
+      padding: 6px 10px;
+      border-radius: 3px;
+      box-shadow: 0 4px 12px rgba(0,0,0,0.5);
+      pointer-events: none;
+      white-space: pre;
+      max-width: min(360px, calc(100vw - ${VIEWPORT_PAD * 2}px));
+      opacity: 0;
+      transition: opacity 80ms ease-in;
+    }
+    ._tooltip.visible { opacity: 1; }
+    ._tooltip b { color: var(--text, #e3e3e3); font-weight: 600; }
+    ._tooltip .dim { color: var(--text-muted, #666); }
+    ._tooltip .val { color: var(--text, #e3e3e3); }
+    ._tooltip .sep {
+      display: block;
+      height: 0;
+      border-top: 1px solid var(--border, #333);
+      margin: 4px 0 6px;
+      line-height: 0;
+      font-size: 0;
+    }
+  `;
+  document.head.appendChild(style);
+}
+
+function show(node: HTMLElement, parsed: ParsedTooltip) {
+  hide();
+  ensureStyle();
+
+  activeEl = node;
+  const el = document.createElement('div');
+  el.className = '_tooltip';
+  if (parsed.isHtml) {
+    el.innerHTML = parsed.content;
+  } else {
+    el.textContent = parsed.content;
+  }
+  document.body.appendChild(el);
+  tipEl = el;
+
+  // Position after layout
+  requestAnimationFrame(() => {
+    if (tipEl !== el) return;
+    const rect = node.getBoundingClientRect();
+    const tipRect = el.getBoundingClientRect();
+
+    // Horizontal: center on trigger, clamp to viewport
+    let left = rect.left + rect.width / 2 - tipRect.width / 2;
+    left = Math.max(VIEWPORT_PAD, Math.min(left, window.innerWidth - tipRect.width - VIEWPORT_PAD));
+
+    // Vertical: prefer requested placement, flip if no room
+    let top: number;
+    if (parsed.placement === 'bottom') {
+      top = rect.bottom + GAP;
+      if (top + tipRect.height > window.innerHeight - VIEWPORT_PAD) {
+        top = rect.top - tipRect.height - GAP;
+      }
+    } else {
+      top = rect.top - tipRect.height - GAP;
+      if (top < VIEWPORT_PAD) {
+        top = rect.bottom + GAP;
+      }
+    }
+
+    el.style.left = `${left}px`;
+    el.style.top = `${top}px`;
+    el.classList.add('visible');
+  });
+}
+
+function hide() {
+  if (hideTimeout) { clearTimeout(hideTimeout); hideTimeout = null; }
+  if (tipEl) { tipEl.remove(); tipEl = null; }
+  activeEl = null;
+}
+
+function parse(param: TooltipParam): ParsedTooltip | null {
+  if (!param) return null;
+  if (typeof param === 'string') return { content: param, isHtml: false, placement: 'top' };
+  const content = param.html ?? param.text;
+  if (!content) return null;
+  return { content, isHtml: !!param.html, placement: param.placement ?? 'top' };
+}
+
+export function tooltip(node: HTMLElement, param: TooltipParam) {
+  let opts = parse(param);
+
+  // Strip native title to prevent double-tooltip
+  const origTitle = node.getAttribute('title');
+  if (origTitle) node.removeAttribute('title');
+
+  function onEnter() {
+    if (!opts) return;
+    if (hideTimeout) { clearTimeout(hideTimeout); hideTimeout = null; }
+    show(node, opts);
+  }
+
+  function onLeave() {
+    if (activeEl !== node) return;
+    hideTimeout = setTimeout(hide, 60);
+  }
+
+  node.addEventListener('pointerenter', onEnter);
+  node.addEventListener('pointerleave', onLeave);
+  node.addEventListener('pointerdown', hide);
+
+  return {
+    update(newParam: TooltipParam) {
+      opts = parse(newParam);
+      if (activeEl === node && tipEl && opts) {
+        if (opts.isHtml) {
+          tipEl.innerHTML = opts.content;
+        } else {
+          tipEl.textContent = opts.content;
+        }
+      } else if (activeEl === node && !opts) {
+        hide();
+      }
+    },
+    destroy() {
+      node.removeEventListener('pointerenter', onEnter);
+      node.removeEventListener('pointerleave', onLeave);
+      node.removeEventListener('pointerdown', hide);
+      if (activeEl === node) hide();
+    },
+  };
+}