map: altitude legend, buoys drawn as buoys, aircraft panel on phones

QA follow-ups on the ADS-B/AIS overlays:
- Legend gains an aircraft altitude key (tar1090 ramp) while the Aircraft
  overlay is on (closes #185).
- AIS aids to navigation (MMSI 99xxxxxxx) render as small yellow buoy
  diamonds labelled 'Aid to navigation', no speed; vessels get a 22px
  outlined hull, and heading 511/360 ('not available') no longer
  rotates the icon (closes #186).
- Aircraft details panel becomes a bottom sheet above the incident drawer
  below md, instead of fighting the layers control at the top right.

Verified: tsc --noEmit clean (node:20 on radio-box).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

drb-c2-core/app/routers/telemetry.py

@@ -1,5 +1,6 @@
-from datetime import datetime, timezone
+import asyncio
-from typing import List, Optional
+from datetime import datetime, timedelta, timezone
+from typing import Dict, List, Optional, Tuple
 
 from fastapi import APIRouter, Depends, HTTPException
 from pydantic import BaseModel
@@ -10,6 +11,20 @@ from app.internal.logger import logger
 
 router = APIRouter(prefix="/telemetry", tags=["telemetry"])
 
+# Flight trail: every position change is also written to
+# aircraft/{icao}/positions/{epoch_ms}, so clicking an aircraft on the map can
+# draw the path heard so far. Points expire via a Firestore TTL policy on
+# expire_at (infra/firestore/firestore.indexes.json fieldOverrides).
+POSITIONS_SUBCOLLECTION = "positions"
+POSITION_TTL = timedelta(hours=24)
+
+# Last position written per icao, so an aircraft reported unchanged across
+# several 10s uploads (readsb holds a position until a new one decodes)
+# doesn't get a duplicate point each time. Process-local and lossy by design:
+# after a restart the worst case is one duplicate point per aircraft.
+_last_position: Dict[str, Tuple[float, float]] = {}
+_LAST_POSITION_MAX = 5000
+
 
 class AircraftReport(BaseModel):
     icao: str
@@ -32,8 +47,8 @@ async def upload_adsb(
 ):
     """
     Node-initiated: a second-SDR ADS-B decoder (node-26#9) periodically posts
-    its current aircraft snapshot here. One doc per icao, last-seen-wins —
+    its current aircraft snapshot here. One doc per icao, last-seen-wins,
-    this is a live-map overlay, not a flight history.
+    plus one trail point per position change (see POSITIONS_SUBCOLLECTION).
     """
     node_id = decoded.get("node_id")
     if not node_id:
@@ -43,7 +58,11 @@ async def upload_adsb(
     org_id = node.get("org_id") if node else None
     now = datetime.now(timezone.utc).isoformat()
 
+    expire_at = datetime.now(timezone.utc) + POSITION_TTL
+    epoch_ms = int(datetime.now(timezone.utc).timestamp() * 1000)
+
     writes = []
+    trail = []
     for ac in body.aircraft:
         if not ac.icao:
             continue
@@ -62,12 +81,33 @@ async def upload_adsb(
             doc["org_id"] = org_id
         writes.append(("aircraft", ac.icao, doc))
 
-    for collection, doc_id, doc in writes:
+        if ac.lat is None or ac.lon is None:
+            continue
+        pos = (ac.lat, ac.lon)
+        if _last_position.get(ac.icao) == pos:
+            continue
+        _last_position[ac.icao] = pos
+        point = {
+            "lat": ac.lat,
+            "lon": ac.lon,
+            "altitude_ft": ac.altitude_ft,
+            "t": now,
+            "expire_at": expire_at,
+        }
+        trail.append((f"aircraft/{ac.icao}/{POSITIONS_SUBCOLLECTION}", str(epoch_ms), point))
+
+    if len(_last_position) > _LAST_POSITION_MAX:
+        _last_position.clear()
+
+    async def _write(collection: str, doc_id: str, doc: dict) -> None:
         try:
             await fstore.doc_set(collection, doc_id, doc, merge=True)
         except Exception as e:
             logger.warning(f"Failed to upsert {collection}/{doc_id} from node {node_id}: {e}")
 
+    # Concurrent: a busy sky is dozens of aircraft, two writes each, every 10s.
+    await asyncio.gather(*(_write(*w) for w in writes + trail))
+
     return {"ok": True, "count": len(writes)}
 
 

drb-c2-core/tests/test_telemetry.py

@@ -24,6 +24,11 @@ def _override(decoded: dict):
 
 def teardown_function():
     app.dependency_overrides.pop(require_node_service_or_firebase_token, None)
+    telemetry._last_position.clear()
+
+
+def _writes_to(mock_set, collection_prefix: str):
+    return [c for c in mock_set.await_args_list if c.args[0].startswith(collection_prefix)]
 
 
 def test_service_token_without_node_id_is_rejected():
@@ -41,8 +46,9 @@ def test_node_upload_upserts_and_stamps_org_id():
         })
     assert resp.status_code == 200
     assert resp.json() == {"ok": True, "count": 1}
-    mock_set.assert_awaited_once()
+    snapshot = [c for c in mock_set.await_args_list if c.args[0] == "aircraft"]
-    (collection, doc_id, doc), kwargs = mock_set.await_args
+    assert len(snapshot) == 1
+    (collection, doc_id, doc), kwargs = snapshot[0]
     assert collection == "aircraft"
     assert doc_id == "A1B2C3"
     assert doc["node_id"] == "node-1"
@@ -92,3 +98,38 @@ def test_ais_node_upload_skips_entries_missing_mmsi():
     assert resp.status_code == 200
     assert resp.json() == {"ok": True, "count": 0}
     mock_set.assert_not_awaited()
+
+
+def _post_adsb(aircraft):
+    with patch.object(telemetry.fstore, "doc_get_cached", AsyncMock(return_value={"org_id": "org-A"})), \
+         patch.object(telemetry.fstore, "doc_set", AsyncMock()) as mock_set:
+        resp = client.post("/telemetry/adsb", json={"aircraft": aircraft})
+    assert resp.status_code == 200
+    return mock_set
+
+
+def test_position_writes_trail_point_with_ttl():
+    _override({"node": True, "node_id": "node-1"})
+    mock_set = _post_adsb([{"icao": "A1B2C3", "lat": 41.1, "lon": -73.8, "altitude_ft": 3000}])
+    trail = _writes_to(mock_set, "aircraft/A1B2C3/positions")
+    assert len(trail) == 1
+    (_, doc_id, point), _ = trail[0]
+    assert doc_id.isdigit()
+    assert (point["lat"], point["lon"], point["altitude_ft"]) == (41.1, -73.8, 3000)
+    assert point["expire_at"] > telemetry.datetime.now(telemetry.timezone.utc)
+
+
+def test_unchanged_position_is_not_rewritten_to_trail():
+    _override({"node": True, "node_id": "node-1"})
+    _post_adsb([{"icao": "A1B2C3", "lat": 41.1, "lon": -73.8}])
+    again = _post_adsb([{"icao": "A1B2C3", "lat": 41.1, "lon": -73.8}])
+    moved = _post_adsb([{"icao": "A1B2C3", "lat": 41.2, "lon": -73.8}])
+    assert _writes_to(again, "aircraft/A1B2C3/positions") == []
+    assert len(_writes_to(moved, "aircraft/A1B2C3/positions")) == 1
+
+
+def test_aircraft_without_position_gets_no_trail_point():
+    _override({"node": True, "node_id": "node-1"})
+    mock_set = _post_adsb([{"icao": "A1B2C3", "callsign": "UAL123"}])
+    assert _writes_to(mock_set, "aircraft/A1B2C3/positions") == []
+    assert len(_writes_to(mock_set, "aircraft")) == 1

drb-frontend/components/MapView.tsx

@@ -1,6 +1,7 @@
 "use client";
 
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
 import {
   FeatureGroup,
   LayersControl,
@@ -9,13 +10,16 @@ import {
   Polyline,
   Popup,
   TileLayer,
+  Tooltip,
   useMap,
+  useMapEvents,
 } from "react-leaflet";
 import L from "leaflet";
-import type { CallRecord, IncidentRecord, NodeRecord, NodeStatus } from "@/lib/types";
+import type { AircraftTrack, CallRecord, IncidentRecord, NodeRecord, NodeStatus } from "@/lib/types";
 import { isKnownSeverity, SEVERITY_COLORS, SEVERITY_LABEL, type Severity } from "@/lib/severity";
 import { MachineOutputNotice } from "@/components/ui/MachineOutputNotice";
 import { useAircraft } from "@/lib/useAircraft";
+import { useAircraftTrail } from "@/lib/useAircraftTrail";
 import { useVessels } from "@/lib/useVessels";
 
 // ── Leaflet icon fix ──────────────────────────────────────────────────────────
@@ -92,47 +96,186 @@ function nodeIcon(status: NodeStatus): L.DivIcon {
   });
 }
 
-// ── Aircraft icon — node-26#9 second-SDR ADS-B overlay ────────────────────────
+// ── Aircraft — node-26#9 second-SDR ADS-B overlay ─────────────────────────────
-function aircraftIcon(trackDeg: number | null): L.DivIcon {
+// Styled after ADS-B Exchange / tar1090: a sized airliner silhouette with a
-  const size = 16;
+// dark outline, filled by altitude on tar1090's hue ramp, so height reads at a
-  const rotation = trackDeg ?? 0;
+// glance and the icon stands out from OSM's own (purple) airport symbols.
+const ALT_HUE_STOPS: [number, number][] = [
+  [0, 20], [2000, 32.5], [4000, 43], [6000, 54], [8000, 72], [9000, 85], [11000, 140], [40000, 300],
+];
+
+function altitudeColor(altFt: number | null): string {
+  if (altFt == null) return "hsl(0, 0%, 55%)";
+  if (altFt <= 0) return "hsl(0, 0%, 45%)"; // on the ground
+  let hue = ALT_HUE_STOPS[ALT_HUE_STOPS.length - 1][1];
+  for (let i = 1; i < ALT_HUE_STOPS.length; i++) {
+    const [a1, h1] = ALT_HUE_STOPS[i];
+    if (altFt <= a1) {
+      const [a0, h0] = ALT_HUE_STOPS[i - 1];
+      hue = h0 + ((h1 - h0) * (altFt - a0)) / (a1 - a0);
+      break;
+    }
+  }
+  return `hsl(${hue.toFixed(0)}, 88%, 48%)`;
+}
+
+// Legend ticks for the altitude ramp, evenly spaced (the ramp itself isn't linear).
+const ALTITUDE_LEGEND_TICKS: [number, string][] = [
+  [1000, "1k"], [4000, "4k"], [10000, "10k"], [20000, "20k"], [40000, "40k"],
+];
+
+const AIRLINER_PATH =
+  "M32 2 C34.2 2 35.2 5 35.2 8 L35.2 23 L61 37.5 L61 42 L35.2 35 L34.2 51 L42.5 57.5 L42.5 61 L32 58.5 " +
+  "L21.5 61 L21.5 57.5 L29.8 51 L28.8 35 L3 42 L3 37.5 L28.8 23 L28.8 8 C28.8 5 29.8 2 32 2 Z";
+
+function aircraftIcon(trackDeg: number | null, altFt: number | null, selected: boolean): L.DivIcon {
+  const size = selected ? 36 : 30;
+  const outline = selected ? "#ffffff" : "#000000";
+  const shadow = selected ? "drop-shadow(0 0 3px #000)" : "drop-shadow(0 1px 1px rgba(0,0,0,.45))";
   return L.divIcon({
     className: "",
-    html: `<div style="width:${size}px;height:${size}px;transform:rotate(${rotation}deg)"><svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="var(--accent)" stroke="var(--surface)" stroke-width="1"><path d="M12 2 L15 11 L22 15 L15 15.5 L14 21 L17 22.5 L12 21.5 L7 22.5 L10 21 L9 15.5 L2 15 L9 11 Z"/></svg></div>`,
+    html:
+      `<div style="width:${size}px;height:${size}px;transform:rotate(${trackDeg ?? 0}deg);filter:${shadow}">` +
+      `<svg width="${size}" height="${size}" viewBox="0 0 64 64"><path d="${AIRLINER_PATH}" ` +
+      `fill="${altitudeColor(altFt)}" stroke="${outline}" stroke-width="${selected ? 3 : 2}" stroke-linejoin="round"/></svg></div>`,
     iconSize: [size, size],
     iconAnchor: [size / 2, size / 2],
   });
 }
 
-function AircraftLayer() {
+function AircraftTrail({ icao, current }: { icao: string; current: AircraftTrack }) {
-  const { aircraft } = useAircraft();
+  const trail = useAircraftTrail(icao);
+  // Extend to the live position so the path always meets the icon.
+  const points = [...trail];
+  if (current.lat != null && current.lon != null) {
+    points.push({ lat: current.lat, lon: current.lon, altitude_ft: current.altitude_ft, t: current.last_seen });
+  }
+  // One segment per leg, colored by altitude like tar1090's track.
   return (
     <>
-      {aircraft
+      {points.slice(1).map((p, i) => (
-        .filter((a) => a.lat != null && a.lon != null)
+        <Polyline
-        .map((a) => (
+          key={`${icao}-${i}`}
-          <Marker key={a.icao} position={[a.lat as number, a.lon as number]} icon={aircraftIcon(a.track_deg)}>
+          positions={[[points[i].lat, points[i].lon], [p.lat, p.lon]]}
-            <Popup minWidth={160}>
+          pathOptions={{ color: altitudeColor(p.altitude_ft), weight: 3, opacity: 0.9, lineCap: "round" }}
-              <div className="space-y-1">
+          interactive={false}
-                <div className="font-semibold">{a.callsign || a.icao}</div>
+        />
-                <div className="text-xs text-ink-muted">ICAO {a.icao}</div>
+      ))}
-                {a.altitude_ft != null && <div className="text-xs">Altitude: {Math.round(a.altitude_ft)} ft</div>}
+    </>
-                {a.ground_speed_kt != null && <div className="text-xs">Speed: {Math.round(a.ground_speed_kt)} kt</div>}
+  );
-              </div>
+}
-            </Popup>
+
-          </Marker>
+function Stat({ label, value }: { label: string; value: string }) {
-        ))}
+  return (
+    <div>
+      <div className="text-[10px] uppercase tracking-wide text-ink-muted">{label}</div>
+      <div className="text-ink font-medium tabular-nums">{value}</div>
+    </div>
+  );
+}
+
+// Details dock at the right edge (bottom sheet on phones, above the incident
+// drawer) instead of a popup over the plane, so the trail stays visible and
+// the map can be panned to follow it.
+function AircraftPanel({ a, onClose }: { a: AircraftTrack; onClose: () => void }) {
+  const ref = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    // The panel is portaled into the Leaflet container, whose native listeners
+    // would otherwise treat clicks/scrolls here as map clicks (deselect) or zoom.
+    if (!ref.current) return;
+    L.DomEvent.disableClickPropagation(ref.current);
+    L.DomEvent.disableScrollPropagation(ref.current);
+  }, []);
+  const fmt = (n: number | null, unit: string) => (n == null ? "—" : `${Math.round(n).toLocaleString()} ${unit}`);
+  return (
+    <div
+      ref={ref}
+      className="absolute left-3 right-3 bottom-12 md:left-auto md:bottom-auto md:top-[5.5rem] md:right-3 md:w-60 z-[1002] bg-surface/95 backdrop-blur-sm border border-line rounded-lg shadow-lg text-xs"
+    >
+      <div className="flex items-start justify-between gap-2 px-3 pt-2.5 pb-2 border-b border-line">
+        <div className="min-w-0">
+          <div className="flex items-center gap-1.5">
+            <span className="inline-block w-2.5 h-2.5 rounded-full shrink-0" style={{ background: altitudeColor(a.altitude_ft) }} />
+            <span className="text-ink font-semibold text-sm truncate">{a.callsign || a.icao}</span>
+          </div>
+          <div className="text-ink-muted mt-0.5">ICAO {a.icao}</div>
+        </div>
+        <button onClick={onClose} aria-label="Close aircraft details" className="text-ink-muted hover:text-ink px-1 leading-none text-base">
+          ×
+        </button>
+      </div>
+      <div className="grid grid-cols-2 gap-x-3 gap-y-2 px-3 py-2.5">
+        <Stat label="Altitude" value={fmt(a.altitude_ft, "ft")} />
+        <Stat label="Speed" value={fmt(a.ground_speed_kt, "kt")} />
+        <Stat label="Heading" value={a.track_deg == null ? "—" : `${Math.round(a.track_deg)}°`} />
+        <Stat label="Last heard" value={timeAgo(new Date(a.last_seen))} />
+      </div>
+    </div>
+  );
+}
+
+function AircraftLayer() {
+  const map = useMap();
+  const { aircraft } = useAircraft();
+  const [selected, setSelected] = useState<string | null>(null);
+  const positioned = aircraft.filter((a) => a.lat != null && a.lon != null);
+  const selectedTrack = positioned.find((a) => a.icao === selected);
+
+  // Clicking empty map deselects; marker clicks don't reach the map.
+  useMapEvents({ click: () => setSelected(null) });
+
+  return (
+    <>
+      {selectedTrack && <AircraftTrail icao={selectedTrack.icao} current={selectedTrack} />}
+      {selectedTrack &&
+        createPortal(<AircraftPanel a={selectedTrack} onClose={() => setSelected(null)} />, map.getContainer())}
+      {positioned.map((a) => (
+        <Marker
+          key={a.icao}
+          position={[a.lat as number, a.lon as number]}
+          icon={aircraftIcon(a.track_deg, a.altitude_ft, a.icao === selected)}
+          zIndexOffset={a.icao === selected ? 1000 : 0}
+          eventHandlers={{ click: () => setSelected((cur) => (cur === a.icao ? null : a.icao)) }}
+        >
+          <Tooltip direction="top" offset={[0, -14]}>
+            {a.callsign || a.icao}
+            {a.altitude_ft != null && ` · ${Math.round(a.altitude_ft).toLocaleString()} ft`}
+          </Tooltip>
+        </Marker>
+      ))}
     </>
   );
 }
 
 // ── Vessel icon — node-26#9 second-SDR AIS overlay ─────────────────────────────
+// MMSI 99xxxxxxx is an aid to navigation (buoy, beacon, light), not a vessel —
+// on the Hudson most of what a node hears is buoys (server-26#186).
+function isAidToNavigation(mmsi: string): boolean {
+  return /^99\d{7}$/.test(mmsi);
+}
+
+// AIS reports heading 511 (and course 360) for "not available".
+function aisHeading(deg: number | null): number | null {
+  return deg == null || deg >= 360 ? null : deg;
+}
+
 function vesselIcon(headingDeg: number | null): L.DivIcon {
-  const size = 14;
+  const size = 22;
-  const rotation = headingDeg ?? 0;
   return L.divIcon({
     className: "",
-    html: `<div style="width:${size}px;height:${size}px;transform:rotate(${rotation}deg)"><svg width="${size}" height="${size}" viewBox="0 0 24 24" fill="var(--accent)" stroke="var(--surface)" stroke-width="1"><path d="M12 2 L18 14 L18 20 L6 20 L6 14 Z"/></svg></div>`,
+    html:
+      `<div style="width:${size}px;height:${size}px;transform:rotate(${aisHeading(headingDeg) ?? 0}deg);filter:drop-shadow(0 1px 1px rgba(0,0,0,.45))">` +
+      `<svg width="${size}" height="${size}" viewBox="0 0 24 24"><path d="M12 2 L18 12 L18 21 L6 21 L6 12 Z" fill="hsl(190, 80%, 42%)" stroke="#000" stroke-width="1.25" stroke-linejoin="round"/></svg></div>`,
+    iconSize: [size, size],
+    iconAnchor: [size / 2, size / 2],
+  });
+}
+
+function aidToNavigationIcon(): L.DivIcon {
+  const size = 12;
+  return L.divIcon({
+    className: "",
+    html: `<svg width="${size}" height="${size}" viewBox="0 0 12 12"><rect x="2" y="2" width="8" height="8" transform="rotate(45 6 6)" fill="hsl(50, 95%, 55%)" stroke="#000" stroke-width="1"/></svg>`,
     iconSize: [size, size],
     iconAnchor: [size / 2, size / 2],
   });
@@ -144,17 +287,25 @@ function VesselLayer() {
     <>
       {vessels
         .filter((v) => v.lat != null && v.lon != null)
-        .map((v) => (
+        .map((v) => {
-          <Marker key={v.mmsi} position={[v.lat as number, v.lon as number]} icon={vesselIcon(v.heading_deg)}>
+          const aton = isAidToNavigation(v.mmsi);
-            <Popup minWidth={160}>
+          return (
-              <div className="space-y-1">
+            <Marker
-                <div className="font-semibold">{v.name || v.mmsi}</div>
+              key={v.mmsi}
-                <div className="text-xs text-ink-muted">MMSI {v.mmsi}</div>
+              position={[v.lat as number, v.lon as number]}
-                {v.speed_kt != null && <div className="text-xs">Speed: {Math.round(v.speed_kt)} kt</div>}
+              icon={aton ? aidToNavigationIcon() : vesselIcon(v.heading_deg)}
-              </div>
+              zIndexOffset={aton ? -100 : 0}
-            </Popup>
+            >
-          </Marker>
+              <Popup minWidth={160}>
-        ))}
+                <div className="space-y-1">
+                  <div className="font-semibold">{aton ? `Aid to navigation${v.name ? ` ${v.name}` : ""}` : v.name || v.mmsi}</div>
+                  <div className="text-xs text-ink-muted">MMSI {v.mmsi}</div>
+                  {!aton && v.speed_kt != null && <div className="text-xs">Speed: {Math.round(v.speed_kt)} kt</div>}
+                </div>
+              </Popup>
+            </Marker>
+          );
+        })}
     </>
   );
 }
@@ -528,6 +679,21 @@ export default function MapView({ nodes, activeCalls, incidents = [], calls = []
   const [drawerOpen, setDrawerOpen] = useState(false);
   const [agoClock, setAgoClock] = useState(0);
   const [radarEpoch, setRadarEpoch] = useState(() => Date.now());
+  const [aircraftShown, setAircraftShown] = useState(false);
+
+  // The altitude key only belongs in the legend while the opt-in Aircraft
+  // overlay is actually on (server-26#185).
+  useEffect(() => {
+    if (!mapInstance) return;
+    const on = (e: L.LayersControlEvent) => e.name === "Aircraft" && setAircraftShown(true);
+    const off = (e: L.LayersControlEvent) => e.name === "Aircraft" && setAircraftShown(false);
+    mapInstance.on("overlayadd", on);
+    mapInstance.on("overlayremove", off);
+    return () => {
+      mapInstance.off("overlayadd", on);
+      mapInstance.off("overlayremove", off);
+    };
+  }, [mapInstance]);
 
   useEffect(() => {
     const id = setInterval(() => setAgoClock((t: number) => t + 1), 10_000);
@@ -718,6 +884,18 @@ export default function MapView({ nodes, activeCalls, incidents = [], calls = []
             </div>
           ))}
         </div>
+        {aircraftShown && (
+          <div className="border-t border-line pt-1.5 space-y-1">
+            <p className="text-ink-muted font-medium text-[10px] uppercase tracking-wide">Aircraft altitude</p>
+            <div
+              className="h-2 w-32 rounded-sm border border-line"
+              style={{ background: `linear-gradient(to right, ${ALTITUDE_LEGEND_TICKS.map(([ft], i) => `${altitudeColor(ft)} ${(i / (ALTITUDE_LEGEND_TICKS.length - 1)) * 100}%`).join(", ")})` }}
+            />
+            <div className="flex justify-between w-32 text-[10px] text-ink-2 tabular-nums">
+              {ALTITUDE_LEGEND_TICKS.map(([ft, label]) => <span key={ft}>{label}</span>)}
+            </div>
+          </div>
+        )}
         <div className="border-t border-line pt-1.5 space-y-1">
           <p className="text-ink-muted font-medium text-[10px] uppercase tracking-wide">Nodes</p>
           {([

drb-frontend/lib/types.ts

@@ -74,6 +74,14 @@ export interface AircraftTrack {
   last_seen: string;
 }
 
+/** One point of an aircraft's flight path — aircraft/{icao}/positions. */
+export interface AircraftTrailPoint {
+  lat: number;
+  lon: number;
+  altitude_ft: number | null;
+  t: string;
+}
+
 export interface VesselTrack {
   mmsi: string;
   org_id?: string;

drb-frontend/lib/useAircraftTrail.ts

@@ -0,0 +1,43 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { collection, onSnapshot, orderBy, query, where, FirestoreError } from "firebase/firestore";
+import { db } from "@/lib/firebase";
+import type { AircraftTrailPoint } from "@/lib/types";
+
+// Trail points live at aircraft/{icao}/positions (written by c2-core
+// telemetry.py on every position change, TTL-deleted after ~24h). The same
+// icao can fly several legs a day, so only the latest continuous stretch is
+// "this flight": a gap longer than FLIGHT_GAP_MS starts a new one.
+const LOOKBACK_MS = 6 * 60 * 60 * 1000;
+const FLIGHT_GAP_MS = 20 * 60 * 1000;
+
+function currentFlight(points: AircraftTrailPoint[]): AircraftTrailPoint[] {
+  let start = 0;
+  for (let i = 1; i < points.length; i++) {
+    if (new Date(points[i].t).getTime() - new Date(points[i - 1].t).getTime() > FLIGHT_GAP_MS) start = i;
+  }
+  return points.slice(start);
+}
+
+/** Live flight path for one aircraft; pass null to subscribe to nothing. */
+export function useAircraftTrail(icao: string | null) {
+  const [trail, setTrail] = useState<AircraftTrailPoint[]>([]);
+
+  useEffect(() => {
+    setTrail([]);
+    if (!icao) return;
+    // `t` is Python's isoformat() in UTC ("...T17:06:48.755123+00:00"), so it
+    // sorts and range-filters correctly as a string against toISOString()'s
+    // "...T17:06:48.755Z" down to the second — no composite index needed.
+    const since = new Date(Date.now() - LOOKBACK_MS).toISOString();
+    const q = query(collection(db, "aircraft", icao, "positions"), where("t", ">=", since), orderBy("t"));
+    return onSnapshot(
+      q,
+      (snap) => setTrail(currentFlight(snap.docs.map((d) => d.data() as AircraftTrailPoint))),
+      (err: FirestoreError) => console.error("useAircraftTrail:", err),
+    );
+  }, [icao]);
+
+  return trail;
+}

infra/firestore/firestore.indexes.json

@@ -77,5 +77,13 @@
       ]
     }
   ],
-  "fieldOverrides": []
+  "fieldOverrides": [
+    {
+      "//": "TTL: flight-trail points (aircraft/{icao}/positions, server-26 telemetry.py) are deleted ~24h after expire_at. indexes: [] because nothing queries on expire_at.",
+      "collectionGroup": "positions",
+      "fieldPath": "expire_at",
+      "ttl": true,
+      "indexes": []
+    }
+  ]
 }

infra/firestore/firestore.rules

@@ -98,6 +98,14 @@ service cloud.firestore {
     match /aircraft/{icao} {
       allow read: if docInMyOrg();
       allow write: if false;
+
+      // Flight trail points. Org is checked against the PARENT aircraft doc
+      // (one get() per query) so the map can query a trail by time alone,
+      // without an org_id filter and the composite index that would need.
+      match /positions/{pointId} {
+        allow read: if inOrg(get(/databases/$(database)/documents/aircraft/$(icao)).data.org_id);
+        allow write: if false;
+      }
     }
 
     match /vessels/{mmsi} {