Merge branch 'main' into cctv-florida-stills

src/data/analystEngine.js

@@ -27,6 +27,7 @@
 import { feedProvenanceEnvelope } from './layerSnapshot.js';
 import { pointInRing } from './naturalEarthRegions.js';
 import { VOICE_LAYER_MANIFEST, voiceLayer } from '../voice/layerManifest.js';
+import { greatCircleKm } from '../geoDistance.js';
 
 /**
  * Layers the engine understands, with the fields queries may reference,
@@ -98,17 +99,9 @@ function toEpochMs(value) {
   return Date.parse(text);
 }
 
-const EARTH_R_KM = 6371;
-
-/** Great-circle distance in km. */
+/** @deprecated Use geoDistance.greatCircleKm with `{ lat, lon }` points. */
 export function haversineKm(lat1, lon1, lat2, lon2) {
-  const d2r = Math.PI / 180;
-  const dLat = (lat2 - lat1) * d2r;
-  const dLon = (lon2 - lon1) * d2r;
-  const a =
-    Math.sin(dLat / 2) ** 2 +
-    Math.cos(lat1 * d2r) * Math.cos(lat2 * d2r) * Math.sin(dLon / 2) ** 2;
-  return 2 * EARTH_R_KM * Math.asin(Math.min(1, Math.sqrt(a)));
+  return greatCircleKm({ lat: lat1, lon: lon1 }, { lat: lat2, lon: lon2 });
 }
 
 /**

src/data/dataCredits.js

@@ -313,7 +313,10 @@ export const DATA_CREDITS = [
     html:
       'Bikeshare availability: GBFS operator feeds ' +
       '(e.g. Austin BCycle; Bike Share Toronto, operated by the Toronto Parking Authority; Bike Itaú and Tembici Bogotá, operated by Tembici; ' +
-      'Bicing, Barcelona City Council (B:SM); AMBici, Àrea Metropolitana de Barcelona, operated by nextbike)',
+      'Bicing, Barcelona City Council (B:SM); AMBici, Àrea Metropolitana de Barcelona, operated by nextbike; ' +
+      'BiciMAD, <a href="https://www.emtmadrid.es" target="_blank" rel="noopener">Powered by EMT de Madrid</a>; ' +
+      'Bizi Zaragoza; BIKI, AUVASA (Valladolid); BiciCoruña; Dbizi (Donostia-San Sebastián); ' +
+      'Bilbao Bizi, Bilbao City Council; BicinRivas, Rivas-Vaciamadrid City Council)',
   },
   {
     key: 'urbansharing-gbfs',
@@ -332,7 +335,7 @@ export const DATA_CREDITS = [
   {
     key: 'jcdecaux-gbfs',
     html:
-      'City bikes (Lillestrøm): Bysykkel Lillestrøm, JCDecaux — ' +
+      'City bikes (Lillestrøm, Valencia, Seville): Bysykkel Lillestrøm, Valenbisi, Sevici, JCDecaux — ' +
       '<a href="https://developer.jcdecaux.com/files/Open-Licence-fr.pdf" target="_blank" rel="noopener">Licence Ouverte</a>',
   },
   {

src/data/naturalEarthRegions.js

@@ -18,8 +18,8 @@
 
 import { loadBundledJson } from './bundledJson.js';
 import { createRetryableLoader } from './retryableLoad.js';
+import { EARTH_RADIUS_KM, greatCircleKm } from '../geoDistance.js';
 
-const EARTH_RADIUS_KM = 6371;
 const toRad = (d) => (d * Math.PI) / 180;
 
 /** Spherical-excess ring area (km²) — same family as turf/geojson-area. */
@@ -36,15 +36,6 @@ function ringAreaKm2(ring) {
   return Math.abs((sum * EARTH_RADIUS_KM * EARTH_RADIUS_KM) / 2);
 }
 
-function haversineKm(lon1, lat1, lon2, lat2) {
-  const dLat = toRad(lat2 - lat1);
-  const dLon = toRad(lon2 - lon1);
-  const h =
-    Math.sin(dLat / 2) ** 2 +
-    Math.cos(toRad(lat1)) * Math.cos(toRad(lat2)) * Math.sin(dLon / 2) ** 2;
-  return 2 * EARTH_RADIUS_KM * Math.asin(Math.min(1, Math.sqrt(h)));
-}
-
 /**
  * Normalize a query/name for matching: lowercase, strip diacritics and
  * punctuation, collapse whitespace, strip a leading "the ".
@@ -157,7 +148,10 @@ function buildEntries(pack, kind) {
       polygons,
       areaKm2,
       bbox: [minLon, minLat, maxLon, maxLat],
-      bboxDiagonalKm: haversineKm(minLon, minLat, maxLon, maxLat),
+      bboxDiagonalKm: greatCircleKm(
+        { lat: minLat, lon: minLon },
+        { lat: maxLat, lon: maxLon },
+      ),
     });
   }
   return out;

src/data/naturalEarthRegions.test.mjs

@@ -3,6 +3,7 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { statSync, readFileSync } from 'node:fs';
 import { findNaturalRegion, listRegions, lookupNaturalRegionOutline, pointInRing } from './naturalEarthRegions.js';
+import { greatCircleKm } from '../geoDistance.js';
 
 const PACK_DIR = new URL('./local_data/natural_earth/', import.meta.url);
 
@@ -19,6 +20,16 @@ test('marquee ranges resolve with sane areas (owner acceptance: Alps + Rockies)'
   assert.ok(rockies.areaKm2 >= 700_000 && rockies.areaKm2 < 1_500_000,
     `Rockies area sane (got ${Math.round(rockies.areaKm2)} km²)`);
   assert.ok(rockies.bboxDiagonalKm > 2000, 'Rockies span thousands of km');
+  const coordinates = rockies.polygons.flat();
+  const minLon = Math.min(...coordinates.map(([lon]) => lon));
+  const minLat = Math.min(...coordinates.map(([, lat]) => lat));
+  const maxLon = Math.max(...coordinates.map(([lon]) => lon));
+  const maxLat = Math.max(...coordinates.map(([, lat]) => lat));
+  assert.equal(
+    rockies.bboxDiagonalKm,
+    greatCircleKm({ lat: minLat, lon: minLon }, { lat: maxLat, lon: maxLon }),
+    'Natural Earth bbox conversion maps [lon, lat] data into { lat, lon } points',
+  );
 });
 
 test('aliases and articles: "the Alps", "Rockies", "Sahara Desert", "Himalaya"', async () => {

src/data/regionalModel.js

@@ -1,3 +1,5 @@
+import { greatCircleMeters } from '../geoDistance.js';
+
 const MAX_ARTICLES = 5;
 
 function cleanText(value, maxLength = 180) {
@@ -153,19 +155,8 @@ export function weatherCodeLabel(code) {
 
 /** Great-circle distance used to avoid refetching a regional brief every animation frame. */
 export function regionalDistanceM(from, to) {
-  if (
-    ![from?.latitude, from?.longitude, to?.latitude, to?.longitude].every(
-      Number.isFinite,
-    )
-  ) {
-    return Infinity;
-  }
-  const phi1 = (from.latitude * Math.PI) / 180;
-  const phi2 = (to.latitude * Math.PI) / 180;
-  const deltaPhi = ((to.latitude - from.latitude) * Math.PI) / 180;
-  const deltaLambda = ((to.longitude - from.longitude) * Math.PI) / 180;
-  const a =
-    Math.sin(deltaPhi / 2) ** 2 +
-    Math.cos(phi1) * Math.cos(phi2) * Math.sin(deltaLambda / 2) ** 2;
-  return 6371000 * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+  return greatCircleMeters(
+    { lat: from?.latitude, lon: from?.longitude },
+    { lat: to?.latitude, lon: to?.longitude },
+  );
 }

src/data/regionalProxy.test.mjs

@@ -59,9 +59,13 @@ test('new data proxies install the same routes in dev and preview servers', () =
 
 test('Launch Library uses a 15-minute cache and optional server-side token header', () => {
   assert.equal(LL2_CACHE_TTL_MS, 15 * 60_000);
-  assert.deepEqual(launchLibraryRequestHeaders(''), { Accept: 'application/json' });
-  assert.deepEqual(launchLibraryRequestHeaders(' secret '), {
+  const headers = {
     Accept: 'application/json',
+    'User-Agent': 'gods-eye-view-launch-library-proxy/1.0 (+https://github.com/bilawalsidhu/gods-eye-view)',
+  };
+  assert.deepEqual(launchLibraryRequestHeaders(''), headers);
+  assert.deepEqual(launchLibraryRequestHeaders(' secret '), {
+    ...headers,
     Authorization: 'Token secret',
   });
 });

src/data/routePlausible.js

@@ -10,19 +10,9 @@
  * low → its destination should be nearby).
  */
 
-const D2R = Math.PI / 180;
-const R_KM = 6371;
+import { EARTH_RADIUS_KM, greatCircleKm, isGeoPoint } from '../geoDistance.js';
 
-/** Haversine great-circle distance in km. */
-export function greatCircleKm(lat1, lon1, lat2, lon2) {
-  const p1 = lat1 * D2R;
-  const p2 = lat2 * D2R;
-  const dp = (lat2 - lat1) * D2R;
-  const dl = (lon2 - lon1) * D2R;
-  const a =
-    Math.sin(dp / 2) ** 2 + Math.cos(p1) * Math.cos(p2) * Math.sin(dl / 2) ** 2;
-  return R_KM * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
-}
+const D2R = Math.PI / 180;
 
 function bearingRad(lat1, lon1, lat2, lon2) {
   const p1 = lat1 * D2R;
@@ -36,10 +26,11 @@ function bearingRad(lat1, lon1, lat2, lon2) {
 
 /** Signed cross-track distance (km) of point from the great circle p1→p2. */
 export function crossTrackKm(lat, lon, lat1, lon1, lat2, lon2) {
-  const d13 = greatCircleKm(lat1, lon1, lat, lon) / R_KM;
+  const d13 =
+    greatCircleKm({ lat: lat1, lon: lon1 }, { lat, lon }) / EARTH_RADIUS_KM;
   const b13 = bearingRad(lat1, lon1, lat, lon);
   const b12 = bearingRad(lat1, lon1, lat2, lon2);
-  return Math.asin(Math.sin(d13) * Math.sin(b13 - b12)) * R_KM;
+  return Math.asin(Math.sin(d13) * Math.sin(b13 - b12)) * EARTH_RADIUS_KM;
 }
 
 const NEAR_ENDPOINT_KM = 130;
@@ -65,14 +56,14 @@ export function routePlausible({
   origin = null,
   destination = null,
 }) {
-  const haveO = Number.isFinite(origin?.lat) && Number.isFinite(origin?.lon);
-  const haveD =
-    Number.isFinite(destination?.lat) && Number.isFinite(destination?.lon);
+  const position = { lat: latDeg, lon: lonDeg };
+  if (!isGeoPoint(position)) return true;
+  const haveO = isGeoPoint(origin);
+  const haveD = isGeoPoint(destination);
   if (!haveO && !haveD) return true; // no coordinates — cannot judge, do not hide
 
   // (a) Geographic consistency: near an endpoint, or roughly on the path.
-  const near = (pt) =>
-    greatCircleKm(latDeg, lonDeg, pt.lat, pt.lon) < NEAR_ENDPOINT_KM;
+  const near = (point) => greatCircleKm(position, point) < NEAR_ENDPOINT_KM;
   let geomOk = (haveO && near(origin)) || (haveD && near(destination));
   if (!geomOk && haveO && haveD) {
     geomOk =
@@ -99,17 +90,10 @@ export function routePlausible({
     Math.abs(verticalRateMps) > VERT_TREND_MPS
   ) {
     if (verticalRateMps > 0) {
-      if (
-        haveO &&
-        greatCircleKm(latDeg, lonDeg, origin.lat, origin.lon) > LOCAL_AIRPORT_KM
-      )
+      if (haveO && greatCircleKm(position, origin) > LOCAL_AIRPORT_KM)
         return false; // departing — origin should be local
     } else {
-      if (
-        haveD &&
-        greatCircleKm(latDeg, lonDeg, destination.lat, destination.lon) >
-          LOCAL_AIRPORT_KM
-      )
+      if (haveD && greatCircleKm(position, destination) > LOCAL_AIRPORT_KM)
         return false; // arriving — destination should be local
     }
   }

src/data/routePlausible.test.mjs

@@ -1,14 +1,15 @@
 // src/data/routePlausible.test.mjs
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { routePlausible, greatCircleKm } from './routePlausible.js';
+import { greatCircleKm } from '../geoDistance.js';
+import { routePlausible } from './routePlausible.js';
 
 const SFO = { lat: 37.6188, lon: -122.3754 };
 const LAX = { lat: 33.9416, lon: -118.4085 };
 const JFK = { lat: 40.6413, lon: -73.7781 };
 
 test('greatCircleKm sanity: SFO→LAX ≈ 543 km', () => {
-  const d = greatCircleKm(SFO.lat, SFO.lon, LAX.lat, LAX.lon);
+  const d = greatCircleKm(SFO, LAX);
   assert.ok(Math.abs(d - 543) < 15, `got ${d}`);
 });
 
@@ -41,4 +42,8 @@ test('missing data never hides a route (cannot judge → allow)', () => {
     latDeg: 51.5, lonDeg: -0.12,
     origin: { lat: null, lon: null }, destination: null,
   }), true);
+  assert.equal(routePlausible({
+    latDeg: 95, lonDeg: 0,
+    origin: SFO, destination: LAX,
+  }), true);
 });

src/data/spaceProviderRequests.js

@@ -7,10 +7,12 @@ export function celestrakTleUrl(group) {
 }
 
 export function launchLibraryRecentUrl(end) {
-  const start = new Date(end.getTime() - 30 * 86400000);
+  // Stable minute boundaries let different installations share LL2's cache.
+  const roundedEnd = new Date(Math.floor(end.getTime() / 60000) * 60000);
+  const start = new Date(roundedEnd.getTime() - 30 * 86400000);
   const url = new URL('https://ll.thespacedevs.com/2.3.0/launches/');
   url.searchParams.set('net__gte', start.toISOString());
-  url.searchParams.set('net__lte', end.toISOString());
+  url.searchParams.set('net__lte', roundedEnd.toISOString());
   url.searchParams.set('limit', '100');
   url.searchParams.set('mode', 'detailed');
   return url;

src/data/trafficBounds.js

@@ -13,31 +13,11 @@
  * @module data/trafficBounds
  */
 
-/** @const {number} Mean Earth radius in km (spherical approximation). */
-const EARTH_RADIUS_KM = 6371;
+import { EARTH_RADIUS_KM, greatCircleKm, isGeoPoint } from '../geoDistance.js';
 
 const toRad = (deg) => (deg * Math.PI) / 180;
 const toDeg = (rad) => (rad * 180) / Math.PI;
 
-/**
- * Great-circle distance between two lat/lon points (haversine).
- *
- * @param {number} lat1 - First point latitude (degrees).
- * @param {number} lon1 - First point longitude (degrees).
- * @param {number} lat2 - Second point latitude (degrees).
- * @param {number} lon2 - Second point longitude (degrees).
- * @returns {number} Distance in kilometres.
- */
-export function greatCircleKm(lat1, lon1, lat2, lon2) {
-  const p1 = toRad(lat1);
-  const p2 = toRad(lat2);
-  const dp = toRad(lat2 - lat1);
-  const dl = toRad(lon2 - lon1);
-  const a =
-    Math.sin(dp / 2) ** 2 + Math.cos(p1) * Math.cos(p2) * Math.sin(dl / 2) ** 2;
-  return 2 * EARTH_RADIUS_KM * Math.asin(Math.min(1, Math.sqrt(a)));
-}
-
 /**
  * Initial bearing (radians) from point 1 toward point 2 along the great circle.
  *
@@ -111,10 +91,13 @@ export function deriveFetchCenter({
   hitLon,
   maxPullKm = 12,
 }) {
-  if (!Number.isFinite(hitLat) || !Number.isFinite(hitLon)) {
+  if (!isGeoPoint({ lat: hitLat, lon: hitLon })) {
     return { lat: nadirLat, lon: nadirLon, source: 'nadir' };
   }
-  const distKm = greatCircleKm(nadirLat, nadirLon, hitLat, hitLon);
+  const distKm = greatCircleKm(
+    { lat: nadirLat, lon: nadirLon },
+    { lat: hitLat, lon: hitLon },
+  );
   if (distKm <= maxPullKm) {
     return { lat: hitLat, lon: hitLon, source: 'hit' };
   }

src/data/trafficBounds.test.mjs

@@ -1,8 +1,8 @@
 // src/data/trafficBounds.test.mjs
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
+import { greatCircleKm } from '../geoDistance.js';
 import {
-  greatCircleKm,
   deriveFetchCenter,
   clampBoundsAroundCenter,
 } from './trafficBounds.js';
@@ -11,7 +11,7 @@ import {
 const NADIR = { lat: 30.2672, lon: -97.7431 };
 
 test('greatCircleKm sanity: Austin -> ~5 km north', () => {
-  const d = greatCircleKm(NADIR.lat, NADIR.lon, NADIR.lat + 0.045, NADIR.lon);
+  const d = greatCircleKm(NADIR, { lat: NADIR.lat + 0.045, lon: NADIR.lon });
   assert.ok(Math.abs(d - 5.0) < 0.1, `got ${d}`);
 });
 
@@ -41,14 +41,14 @@ test('oblique look within 12 km: uses the hit point verbatim', () => {
 test('horizon gaze: far hit is pulled back to 12 km along the bearing', () => {
   // Hit ~100 km due east of nadir.
   const hit = { lat: NADIR.lat, lon: NADIR.lon + 1.041 };
-  assert.ok(greatCircleKm(NADIR.lat, NADIR.lon, hit.lat, hit.lon) > 90, 'precondition: far hit');
+  assert.ok(greatCircleKm(NADIR, hit) > 90, 'precondition: far hit');
   const c = deriveFetchCenter({
     nadirLat: NADIR.lat, nadirLon: NADIR.lon,
     hitLat: hit.lat, hitLon: hit.lon,
     maxPullKm: 12,
   });
   assert.equal(c.source, 'pulled');
-  const d = greatCircleKm(NADIR.lat, NADIR.lon, c.lat, c.lon);
+  const d = greatCircleKm(NADIR, c);
   assert.ok(Math.abs(d - 12) < 0.05, `pulled distance ${d} km, expected ~12`);
   // Due-east bearing: latitude stays ~constant, longitude moves east but well
   // short of the hit.
@@ -64,12 +64,12 @@ test('pull cap is honored for other maxPullKm values', () => {
     maxPullKm: 5,
   });
   assert.equal(c.source, 'pulled');
-  const d = greatCircleKm(NADIR.lat, NADIR.lon, c.lat, c.lon);
+  const d = greatCircleKm(NADIR, c);
   assert.ok(Math.abs(d - 5) < 0.05, `pulled distance ${d} km, expected ~5`);
 });
 
-test('pickEllipsoid failure (non-finite hit): falls back to the camera nadir', () => {
-  for (const [hitLat, hitLon] of [[NaN, NaN], [undefined, undefined], [30.3, undefined]]) {
+test('invalid ground hit falls back to the camera nadir', () => {
+  for (const [hitLat, hitLon] of [[NaN, NaN], [undefined, undefined], [30.3, undefined], [91, -97], [30, 181]]) {
     const c = deriveFetchCenter({
       nadirLat: NADIR.lat, nadirLon: NADIR.lon,
       hitLat, hitLon,

src/data/transitFeeds.js

@@ -1,3 +1,5 @@
+import { greatCircleKm } from '../geoDistance.js';
+
 /**
  * @module transitFeeds
  * @description Registry of keyless, openly licensed GTFS-Realtime
@@ -773,7 +775,8 @@ export function getRegisteredTransitFeed(id) {
 }
 
 /**
- * Great-circle distance in km.
+ * Great-circle distance in km. Retained for compatibility with existing
+ * transit consumers; new shared spatial code should use `greatCircleKm`.
  * @param {number} aLat
  * @param {number} aLon
  * @param {number} bLat
@@ -781,13 +784,7 @@ export function getRegisteredTransitFeed(id) {
  * @returns {number}
  */
 export function haversineKm(aLat, aLon, bLat, bLon) {
-  const toRad = (deg) => (deg * Math.PI) / 180;
-  const dLat = toRad(bLat - aLat);
-  const dLon = toRad(bLon - aLon);
-  const h =
-    Math.sin(dLat / 2) ** 2 +
-    Math.cos(toRad(aLat)) * Math.cos(toRad(bLat)) * Math.sin(dLon / 2) ** 2;
-  return 2 * 6371 * Math.asin(Math.min(1, Math.sqrt(h)));
+  return greatCircleKm({ lat: aLat, lon: aLon }, { lat: bLat, lon: bLon });
 }
 
 /**

src/data/vesselLabels.js

@@ -5,6 +5,9 @@
  */
 
 import { t, msg } from '../i18n/index.js';
+import { normalizeVesselType } from './vesselTypes.js';
+
+export { normalizeVesselType };
 
 export const VESSEL_OVERLAY_SOURCE_ID = 'ais-live-vessels';
 /** Existing selector grid size; one ambient winner is retained per cell. */
@@ -43,31 +46,6 @@ const TYPE_STYLES = [
 ];
 const DEFAULT_STYLE = { css: '#39d5ff', accent: '57, 213, 255' };
 
-const NUMERIC_TYPE_SPECIALS = {
-  30: 'FISHING',
-  31: 'TOWING',
-  32: 'TOWING',
-  33: 'DREDGER',
-  34: 'DIVE OPS',
-  35: 'MILITARY',
-  36: 'SAILING',
-  37: 'PLEASURE',
-  50: 'PILOT',
-  51: 'SAR',
-  52: 'TUG',
-  53: 'PORT TENDER',
-  54: 'ANTI-POLLUTION',
-  55: 'LAW ENFORCE',
-  58: 'MEDICAL',
-};
-const NUMERIC_TYPE_FAMILIES = {
-  4: 'HIGH-SPEED',
-  6: 'PASSENGER',
-  7: 'CARGO',
-  8: 'TANKER',
-  9: 'OTHER',
-};
-
 // Card text for the type tokens above. The tokens stay English: TYPE_STYLES
 // and tests match on them.
 const TYPE_DISPLAY_KEYS = Object.freeze({
@@ -104,21 +82,6 @@ export function displayVesselType(type) {
   return key ? t(key) : normalized;
 }
 
-/**
- * Resolve an AIS type to display text: bare numeric ship-type codes map to
- * family names ("71" → "CARGO"); text types pass through unchanged.
- * @param {string} type Raw AIS type.
- * @returns {string}
- */
-export function normalizeVesselType(type) {
-  const text = String(type || '').trim();
-  if (!text || !/^\d{1,2}$/.test(text)) return text;
-  const code = Number(text);
-  if (code <= 0) return '';
-  if (NUMERIC_TYPE_SPECIALS[code]) return NUMERIC_TYPE_SPECIALS[code];
-  return NUMERIC_TYPE_FAMILIES[Math.floor(code / 10)] || 'OTHER';
-}
-
 /** AIS ship type → CSS hex hue for the billboard chevron. */
 export function vesselTypeCss(type) {
   return styleForType(type).css;

src/data/vesselLabels.test.mjs

@@ -29,6 +29,8 @@ test('normalizeVesselType preserves text and degrades unknown codes', () => {
   assert.equal(normalizeVesselType('Crude Oil Tanker'), 'Crude Oil Tanker');
   assert.equal(normalizeVesselType('0'), '');
   assert.equal(normalizeVesselType('25'), 'OTHER');
+  assert.equal(normalizeVesselType('100'), '');
+  assert.equal(normalizeVesselType('255'), '');
   assert.equal(normalizeVesselType(undefined), '');
 });
 

src/data/vesselTypes.js

@@ -0,0 +1,47 @@
+/**
+ * @module vesselTypes
+ * @description AIS ship-type codes (ITU-R M.1371) to family names, with no
+ * browser or i18n dependencies so the server-side query tools can use it.
+ */
+
+const NUMERIC_TYPE_SPECIALS = {
+  30: 'FISHING',
+  31: 'TOWING',
+  32: 'TOWING',
+  33: 'DREDGER',
+  34: 'DIVE OPS',
+  35: 'MILITARY',
+  36: 'SAILING',
+  37: 'PLEASURE',
+  50: 'PILOT',
+  51: 'SAR',
+  52: 'TUG',
+  53: 'PORT TENDER',
+  54: 'ANTI-POLLUTION',
+  55: 'LAW ENFORCE',
+  58: 'MEDICAL',
+};
+const NUMERIC_TYPE_FAMILIES = {
+  4: 'HIGH-SPEED',
+  6: 'PASSENGER',
+  7: 'CARGO',
+  8: 'TANKER',
+  9: 'OTHER',
+};
+
+/**
+ * Resolve an AIS type to display text: bare numeric ship-type codes map to
+ * family names ("71" → "CARGO"); text types pass through unchanged. Code 0
+ * ("not available") and the reserved codes 100 to 255 name no type and
+ * resolve to "".
+ * @param {string} type Raw AIS type.
+ * @returns {string}
+ */
+export function normalizeVesselType(type) {
+  const text = String(type || '').trim();
+  if (!text || !/^\d+$/.test(text)) return text;
+  const code = Number(text);
+  if (code <= 0 || code >= 100) return '';
+  if (NUMERIC_TYPE_SPECIALS[code]) return NUMERIC_TYPE_SPECIALS[code];
+  return NUMERIC_TYPE_FAMILIES[Math.floor(code / 10)] || 'OTHER';
+}