@meri-imperiumi/signalk-passage-briefing 0.12.2 → 0.12.4

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [0.12.4] - 2026-10-17
+
+### Fixed
+- The tropical-cyclone notification flapped on/off 27 times in ~45 min (logbook 2026-10-16, TC ONE-26): every ticker republish sent a fresh value (re-alarming boards), a GDACS dip outlasted the 2-minute clear grace and the return re-raised, and the exposure envelope tightened whenever a compile switched the reference. Four layers of anti-flap: notifications publish through a three-tier gate (raise = first publish or state change, visual+sound; amendment = same state, new GDACS figures, visual only so sounders stay quiet; identical = silence); once raised, a cyclone notification latches — it stays warnable while the storm exists in the GDACS envelope at any alert level (the wide green filter feeds a new `retainLatched` carry-over) and clears only after an hour out of the matrix; the hazard filter admits via either envelope (1000 nm from the vessel or 500 nm off the route) instead of letting the closer reference tighten the band; and acknowledgements are level- and distance-aware, persisted on disk (`hazards-state.json`, 7-day prune) so restarts stay quiet — only a strictly higher level (orange → red) or a storm closed to half the acked distance re-alarms. GDACS refreshes now amend the notification text in place rather than clearing and re-raising.
+- A `weather_source: "weather-api"` configuration on a server without the Weather API provider crashed `start()` outright — taking the warnings console, the bulletins and the hazard escalation down with it. The misconfiguration now degrades to Open-Meteo for the session and logs the error, so the rest of the plugin keeps working.
+- Graceful-degradation regression suite (`tests/plugin-degradation.test.js`): the plugin boots and serves empty states on a bare server — position available, but no Weather API provider (auto falls back to Open-Meteo and briefs), no active route (here mode), no energy predictor (empty `energyHourly`/`energyEvents` ride the payload), no polar management (`/api/polar` serves null, webapp falls back), no Resources API (`/api/routes` serves 501), link never online (refresh 503, briefing `cached: false`), and the hazard escalation stays quiet over empty caches.
+- A TC Wati storm warning (FQPS01 NFFN 2026-10-16 fixture) parsed geometry-less and was dropped whole by the track filter — the one bulletin the console must never miss. Four parsing gaps fixed: the GMDSS section anchor matched any line starting with "FORECAST" (the warning's own "FORECAST POSITION NEAR…" line split the warning section in half, leaving gale headers and cancel notices floating unanchored), so the bare `FORECAST`/`WARNINGS`/`SYNOPSIS` anchors now require heading-only lines; NFFN spells the hemispheres out in cyclone positions ("NEAR 12.1 SOUTH 163.0 WEST", line-wrapped anywhere), which defeated both the NEAR extraction and the coordinate parser — the paired lat+lon form is now contracted to the letter form in boilerplate stripping, leaving prose ("5 SOUTH OF T1") untouched; storm-declaration detection runs per paragraph inside the block, so a coalesced block leading with the "PART 1 : WARNING STORM WARNING 012" header still types as its storm's point (kept on any track) instead of merging into a geometry-less discard; and quadrant wind-radii lines ("WITHIN 95 NAUTICAL MILES IN SE QUADRANT") coalesce onto the storm's point anchor rather than the nearest area, so the full wind field rides with the warning. The result: a vessel far outside the warning areas still reads the complete storm warning, a vessel inside the gale polygon reads it whole (header, area, cancel notice), and "WITHIN 300 NAUTICAL MILES OF TROPICAL CYCLONE WATI CENTER" resolves through the collected feature instead of stopping at "OF TROPICAL".
+- The `S OF`/`N OF` latitude abbreviations matched mid-word — "BETWEEN OF 16S" read as "…BETWEEn OF 16S" and clamped the band to 16S — so NFFN's stray-"OF" latitude-band phrasing ("IN THE AREA BETWEEN OF 16S AND 22S AND BETWEEN 156W AND 169W") widened to a pole-to-pole band. The abbreviations now require a word boundary, and the BETWEEN latitude pair parses as the band it states (16S–22S).
+
+### Changed
+- The energy predictor and polar management moved from the Signal K metadata's `requires` to `recommends`: the plugin consumes them purely through Signal K paths and the resources API, and the degradation suite proves it briefs, serves and escalates without either (built-in fallback polar, empty energy outlook). `signalk-internet` stays required — the online window drives every fetch gate.
+
+## [0.12.3] - 2026-10-16
+
 ## [0.12.2] - 2026-10-16
 
 ### Changed
@@ -9,7 +23,7 @@
 
 ### Fixed
 - The webapp console logged three requests that could never succeed (work doc #40/#30 session report): the "Next" compile pill and the sea-legs day checkpoints called `/api/api/status` and `/api/api/sea-legs` — a stray `api/` segment doubled into the plugin base ever since those two UI pieces shipped, 404ing on every load and silently hiding both features. The URLs now match the registered routes. The critical-hazard banner polled the Signal K REST notifications subtree (`vessels/self/notifications/navigation/briefing/hazards`), which 404s whenever no notification was ever raised on the server; the escalation's active list now also serves from the plugin's own `GET /api/hazards/active` (same data the delta stream carries, empty list when nominal) and the banner polls that.
-- The route briefing had no manual refresh affordance on a fresh cache: the "Update now" button only existed in the no-cached strip and the outdated banner, so the crew couldn't regenerate an up-to-date-looking briefing (e.g. to pick up the throttled payload shape or a fresher forecast) — while conditions-here always carried its card-head button. The tactical view's "Next 24 Hours" card head now carries the same "Update now" in the same place, wired to the route refresh and disabled offline like its here-mode twin.
+- The route briefing had no manual refresh affordance on a fresh cache: the "Update now" button only existed in the no-cached strip and the outdated banner, so the crew couldn't regenerate an up-to-date-looking briefing (e.g. to pick up the throttled payload shape or a fresher forecast) — while conditions-here always carried its card-head button. The tactical view's "Next 24 Hours" card head now carries the same "Update now" in the same place, wired to the route refresh and disabled offline like its here-mode twin. The root also imports the components it instantiates — its connectedCallback runs during customElements.define, so the first renderRoute created an un-upgraded tactical-dashboard whose methods did not exist yet, aborting the boot with `tactical?.setOnline is not a function` on pages that loaded only the root module first.
 
 ## [0.12.1] - 2026-10-16
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meri-imperiumi/signalk-passage-briefing",
-  "version": "0.12.2",
+  "version": "0.12.4",
   "description": "Offshore passage daily briefing webapp for Signal K",
   "main": "plugin/index.js",
   "scripts": {
@@ -31,11 +31,11 @@
       "doc/here-brief.png"
     ],
     "requires": [
-      "@meri-imperiumi/signalk-energy-predictor",
-      "@meri-imperiumi/signalk-internet",
-      "signalk-polar-management"
+      "@meri-imperiumi/signalk-internet"
     ],
     "recommends": [
+      "@meri-imperiumi/signalk-energy-predictor",
+      "signalk-polar-management",
       "signalk-watch-schedule",
       "@meri-imperiumi/signalk-ships-time"
     ]

package/plugin/bulletin-engine.js

@@ -71,7 +71,7 @@ const RETAINED_SUBJECTS = "ABE";
  * leading-dot NWS style (`.WARNINGS.`, `.SYNOPSIS AND FORECAST.`)
  * is tolerated alongside the GMDSS `PART 1` headings. */
 const SECTION_ANCHORS =
-  /^\.?\s*(PARTS?\s+\d+\b.*(?:WARNING|SYNOPSIS|FORECAST)|WARNINGS?|SYNOPSIS(?:\s+AND\s+FORECAST)?|FORECAST)\b/i;
+  /^(?:\.?\s*PARTS?\s+\d+\b.*(?:WARNING|SYNOPSIS|FORECAST)\b|\.?\s*(?:WARNINGS?|SYNOPSIS(?:\s+AND\s+FORECAST)?|FORECAST)\s*\.?\s*$)/i;
 
 /**
  * Strips transmission routing boilerplate: NAVTEX `ZCZC`/`NNNN`
@@ -134,6 +134,16 @@ function stripBoilerplate(text) {
       // all-caps bulletins, and an unparsed latitude bound widens the
       // area to pole-to-pole
       .replace(/\bO(?=\d)/g, "0")
+      // NFFN spells the hemispheres out in cyclone positions ("NEAR
+      // 12.1 SOUTH 163.0 WEST", line-wrapped anywhere): contracted to
+      // the letter form the coordinate and NEAR parsers expect. Only
+      // the paired lat+lon form is rewritten, so prose like "5 SOUTH
+      // OF T1" is left alone.
+      .replace(
+        /\b(\d+(?:\.\d+)?)\s+(NORTH|SOUTH)\s+(\d+(?:\.\d+)?)\s+(EAST|WEST)\b/gi,
+        (_text, lat, latWord, lon, lonWord) =>
+          `${lat}${latWord[0].toUpperCase()} ${lon}${lonWord[0].toUpperCase()}`,
+      )
       .replace(/\n{3,}/g, "\n\n")
       .trim()
   );
@@ -267,9 +277,14 @@ function isWarningSection(sectionBlocks) {
  */
 function coalesceWarningBlocks(sectionBlocks, features = new Map()) {
   const anchored = [];
+  const pointAnchors = [];
   sectionBlocks.forEach((block, i) => {
-    if (extractGeometry(block, features) != null) {
+    const geometry = extractGeometry(block, features);
+    if (geometry != null) {
       anchored.push(i);
+      if (geometry.type === "point") {
+        pointAnchors.push(i);
+      }
     }
   });
   if (anchored.length === 0) {
@@ -280,6 +295,10 @@ function coalesceWarningBlocks(sectionBlocks, features = new Map()) {
   // nearest anchor, ties to the earlier one — a trailer describes the
   // area above it. Coordinate-bearing blocks that place to null stay
   // unowned: they emit as their own blocks, never merged.
+  // Quadrant wind-radii lines ("WITHIN 95 NAUTICAL MILES IN SE
+  // QUADRANT") describe the storm, not the nearest area: they prefer
+  // a declared storm's point anchor so they keep or drop with the
+  // warning they belong to.
   const owner = new Map();
   for (const i of anchored) {
     owner.set(i, i);
@@ -288,7 +307,11 @@ function coalesceWarningBlocks(sectionBlocks, features = new Map()) {
     if (owner.has(i) || parseCoordinatePoints(sectionBlocks[i]).length > 0) {
       continue;
     }
-    const target = anchored.reduce((best, candidate) =>
+    const candidates =
+      /QUADRANT/i.test(sectionBlocks[i]) && pointAnchors.length > 0
+        ? pointAnchors
+        : anchored;
+    const target = candidates.reduce((best, candidate) =>
       Math.abs(candidate - i) < Math.abs(best - i) ? candidate : best,
     );
     owner.set(i, target);
@@ -431,16 +454,29 @@ function parseCardinalBounds(text) {
   // full word is matched first so the abbreviation cannot swallow it
   // (an unmatched N OF left the band pole-to-pole and a North Pacific
   // synopsis intersected every water on its longitude band).
-  const southOf = text.match(/(?:SOUTH|S)\s+OF\s+(\d+(?:\.\d+)?)\s*([NS])/i);
+  const southOf = text.match(/\b(?:SOUTH|S)\s+OF\s+(\d+(?:\.\d+)?)\s*([NS])/i);
   if (southOf) {
     maxLat = hemisphereDegrees(southOf[1], southOf[2].toUpperCase());
     found = true;
   }
-  const northOf = text.match(/(?:NORTH|N)\s+OF\s+(\d+(?:\.\d+)?)\s*([NS])/i);
+  const northOf = text.match(/\b(?:NORTH|N)\s+OF\s+(\d+(?:\.\d+)?)\s*([NS])/i);
   if (northOf) {
     minLat = hemisphereDegrees(northOf[1], northOf[2].toUpperCase());
     found = true;
   }
+  // NFFN states the latitude band as a pair — with the occasional
+  // stray "OF" ("IN THE AREA BETWEEN OF 16S AND 22S"). Longitude
+  // BETWEEN pairs (EW) are matched separately below.
+  const latBand = text.match(
+    /BETWEEN\s+(?:OF\s+)?(\d+(?:\.\d+)?)\s*([NS])\s+AND\s+(\d+(?:\.\d+)?)\s*([NS])/i,
+  );
+  if (latBand) {
+    const a = hemisphereDegrees(latBand[1], latBand[2].toUpperCase());
+    const b = hemisphereDegrees(latBand[3], latBand[4].toUpperCase());
+    minLat = Math.max(minLat, Math.min(a, b));
+    maxLat = Math.min(maxLat, Math.max(a, b));
+    found = true;
+  }
   // The equator is a real bound in NWS area headers ("NORTH PACIFIC
   // EQUATOR TO 30N BETWEEN 140W AND 180W"), not a poleward default —
   // without this the area line parses to a pole-to-pole box that
@@ -606,14 +642,23 @@ function resolveNamedEndpoints(text, features) {
  * block's first coordinate pair. Null when the block declares a
  * system but carries no position.
  *
+ * The anchored-per-paragraph test (not the whole-block test) keeps
+ * coalesced warning blocks working: they lead with the "PART 1 :
+ * WARNING STORM WARNING 012" header, and a whole-block anchored test
+ * would type the merged block geometry-less — dropping the whole
+ * storm warning for any vessel outside the forecast line.
+ *
  * @param {string} text - Block text
  * @returns {number[]|null} [lon, lat]
  */
 function stormDeclarationPoint(text) {
-  if (!STORM_DECLARATION.test(String(text ?? "").trim())) {
+  const declaring = String(text ?? "")
+    .split(/\n\n/)
+    .find((paragraph) => STORM_DECLARATION.test(paragraph.trim()));
+  if (!declaring) {
     return null;
   }
-  const near = text.match(
+  const near = declaring.match(
     /NEAR\s+(\d+(?:\.\d+)?)\s*([NS])\s+(\d+(?:\.\d+)?)\s*([EW])/i,
   );
   if (near) {
@@ -622,7 +667,7 @@ function stormDeclarationPoint(text) {
       hemisphereDegrees(near[1], near[2].toUpperCase()),
     ];
   }
-  const points = parseCoordinatePoints(text);
+  const points = parseCoordinatePoints(declaring);
   return points.length > 0 ? points[0] : null;
 }
 
@@ -643,7 +688,10 @@ function stormReferenceGeometry(text, features, bufferNm) {
     return null;
   }
   const match = text.match(
-    new RegExp(`\\b(?:OF|AROUND)\\s+(${FEATURE_REFERENCE})\\b`, "i"),
+    new RegExp(
+      `\\b(?:OF|AROUND)\\s+(?:(?:SEVERE\\s+)?TROPICAL\\s+(?:CYCLONE|STORM|DEPRESSION|HURRICANE|TYPHOON)\\s+)?(${FEATURE_REFERENCE})\\b`,
+      "i",
+    ),
   );
   if (!match) {
     return null;
@@ -887,12 +935,13 @@ function composeFeatureBounds(text, features) {
  */
 function extractGeometry(blockText, features = new Map()) {
   // A storm declaration block is its own geometry: the analysed
-  // position of the named system, typed "point"
-  if (STORM_DECLARATION.test(blockText.trim())) {
-    const point = stormDeclarationPoint(blockText);
-    if (point) {
-      return { type: "point", coordinates: point };
-    }
+  // position of the named system, typed "point". Declarations are
+  // found per paragraph, so a coalesced block leading with the
+  // "PART 1 : WARNING STORM WARNING 012" header still types as its
+  // storm's point.
+  const stormPoint = stormDeclarationPoint(blockText);
+  if (stormPoint) {
+    return { type: "point", coordinates: stormPoint };
   }
   const bandMatch = blockText.match(
     /WITHIN\s+(\d+(?:\.\d+)?)\s*(?:NM|NAUTICAL\s+MILES?)\b/i,

package/plugin/hazard-alerts.js

@@ -39,6 +39,10 @@ const STATE = { emergency: "emergency", error: "error" };
  */
 const MOORED_STATES = new Set(["moored", "anchored"]);
 
+/** GDACS alert-level ranks (duplicated from hazard-source.js; this
+ * module stays dependency-free). */
+const ALERT_RANK = { green: 0, orange: 1, red: 2 };
+
 /**
  * Classifies one refresh's warning stream into notifications.
  *
@@ -70,15 +74,23 @@ function escalateHazards({
     typeof navigationState === "string" && MOORED_STATES.has(navigationState);
 
   // Tropical cyclone: GDACS TC at Red or Orange — the compile filters
-  // established impact (near vessel or route)
+  // established impact (near vessel or route). The notification is
+  // marked `latch` (held through source dips, work doc #30) and
+  // carries the alert level so an acknowledgement can be level-aware:
+  // orange ack silences orange, a later red re-alarms.
   for (const event of gdacsEvents ?? []) {
     if (
       event?.type === "TC" &&
-      (event.alertLevel === "red" || event.alertLevel === "orange")
+      (event.alertLevel === "red" ||
+        event.alertLevel === "orange" ||
+        event.latched === true)
     ) {
       notifications.push({
         id: `gdacs-${event.id}`,
         eventId: event.id,
+        level: event.alertLevel ?? null,
+        distanceNm: event.distanceNm ?? null,
+        latch: true,
         state: STATE.emergency,
         message: `Tropical cyclone: ${event.title ?? event.type} — ${event.distanceNm ?? "?"} nm from the vessel`,
       });
@@ -141,11 +153,99 @@ function escalateHazards({
   return notifications;
 }
 
+/**
+ * Warnability carry-over for latched tropical-cyclone notifications
+ * (work doc #30 anti-flap): once a cyclone notification is raised, it
+ * stays warnable while the cyclone still exists in the GDACS envelope
+ * — even when its alert level dips below the fresh-escalation floor.
+ * GDACS recomputes with every model run and borderline systems flap
+ * orange/green; the vessel should not re-alarm on each flap. Fresh
+ * escalations still need the configured minimum level; ids held
+ * active by the hysteresis ride at any level the feed carries.
+ *
+ * @param {object} params
+ * @param {Array<object>} [params.events] - GDACS events filtered at
+ *   the wide (green) level, distances computed
+ * @param {Map<string, object>} [params.previous] - Previously active
+ *   notifications by id (the hysteresis state)
+ * @param {string} [params.minLevel="orange"] - Fresh-escalation floor
+ * @returns {Array<object>} Events to escalate this cycle
+ */
+function retainLatched({ events, previous, minLevel = "orange" }) {
+  const minRank = ALERT_RANK[String(minLevel).toLowerCase()] ?? 1;
+  const latched = new Set(
+    [...(previous ?? new Map())]
+      .filter(([, notification]) => notification?.latch === true)
+      .map(([id]) => id),
+  );
+  const kept = [];
+  const seen = new Set();
+  for (const event of events ?? []) {
+    const id = `gdacs-${event?.id}`;
+    if (seen.has(id)) {
+      continue;
+    }
+    seen.add(id);
+    const rank = ALERT_RANK[String(event?.alertLevel ?? "").toLowerCase()];
+    if (rank >= minRank) {
+      kept.push(event);
+    } else if (latched.has(id)) {
+      kept.push({ ...event, latched: true });
+    }
+  }
+  return kept;
+}
+
+/**
+ * Whether one escalation may raise (or re-raise) its notification,
+ * given the recorded acknowledgement (work doc #30 anti-flap): an ack
+ * silences the same alert level and below — a strictly higher level
+ * (orange acked, red now) escalates through and re-alarms. So does a
+ * cyclone that has closed to half the distance it was at ack time:
+ * the situation materially changed even at the same level.
+ * Notifications without a level (bulletin direct-hits, CAP) suppress
+ * on any ack, as before.
+ *
+ * @param {object} params
+ * @param {object} params.notification - The current escalation
+ * @param {{level: string|null, distanceNm: number|null,
+ *   at: string}|undefined} params.ack - The recorded acknowledgement,
+ *   if any
+ * @returns {boolean}
+ */
+function shouldRaise({ notification, ack }) {
+  if (!ack) {
+    return true;
+  }
+  const level = String(notification?.level ?? "").toLowerCase();
+  if (!(level in ALERT_RANK)) {
+    return false; // Level-less notification: any ack suppresses
+  }
+  const ackRank = ALERT_RANK[String(ack?.level ?? "").toLowerCase()];
+  if (ALERT_RANK[level] > (ackRank ?? -1)) {
+    return true; // Escalation: orange acked, red now
+  }
+  const ackDistance = Number(ack?.distanceNm);
+  const distance = Number(notification?.distanceNm);
+  if (
+    Number.isFinite(ackDistance) &&
+    ackDistance > 0 &&
+    Number.isFinite(distance) &&
+    distance <= ackDistance / 2
+  ) {
+    return true; // Closed to half the acked distance: materially closer
+  }
+  return false;
+}
+
 /**
  * Suppression hysteresis (work doc #30): a notification that dips out
  * of the matrix for one refresh cycle does not flap the alarm — it
  * clears only after `missesToClear` consecutive cycles without
- * qualifying. Pure function over the previous active set.
+ * qualifying. Pure function over the previous active set. Latched
+ * notifications (tropical cyclones) clear only after
+ * `latchMissesToClear` — GDACS dips are minutes long, and a clear
+ * followed by a re-raise re-alarms the crew for the same storm.
  *
  * @param {object} params
  * @param {Map<string, object>} params.previous - Previously active
@@ -154,10 +254,18 @@ function escalateHazards({
  * @param {Map<string, number>} [params.missCounts] - Per-id
  *   consecutive miss counters (mutated)
  * @param {number} [params.missesToClear=2]
+ * @param {number} [params.latchMissesToClear=60] - Cycles a latched
+ *   notification survives before clearing
  * @returns {{active: Map<string, object>, cleared: string[]}} The new
  *   active set and the ids that cleared this cycle
  */
-function applyHysteresis({ previous, current, missCounts, missesToClear = 2 }) {
+function applyHysteresis({
+  previous,
+  current,
+  missCounts,
+  missesToClear = 2,
+  latchMissesToClear = 60,
+}) {
   const misses = missCounts ?? new Map();
   const active = new Map();
   const cleared = [];
@@ -167,14 +275,17 @@ function applyHysteresis({ previous, current, missCounts, missesToClear = 2 }) {
     active.set(notification.id, notification);
   }
   // Previously active ids that dipped out: carry them through the
-  // miss grace period (borderline geometry must not flap the alarm)
+  // miss grace period (borderline geometry must not flap the alarm);
+  // latched notifications earn the long grace
   for (const [id, notification] of previous ?? []) {
     if (currentIds.has(id)) {
       continue;
     }
+    const threshold =
+      notification?.latch === true ? latchMissesToClear : missesToClear;
     const count = (misses.get(id) ?? 0) + 1;
     misses.set(id, count);
-    if (count >= missesToClear) {
+    if (count >= threshold) {
       cleared.push(id);
       misses.delete(id);
     } else {
@@ -191,6 +302,9 @@ function applyHysteresis({ previous, current, missCounts, missesToClear = 2 }) {
 module.exports = {
   STATE,
   MOORED_STATES,
+  ALERT_RANK,
   escalateHazards,
+  retainLatched,
+  shouldRaise,
   applyHysteresis,
 };

package/plugin/hazard-source.js

@@ -361,39 +361,53 @@ function filterHazards({
     if (rank == null || rank < minRank) {
       continue;
     }
-    // Distance and bearing from the vessel, then from the nearest
-    // route sample — the better (closer) reference admits the event
-    let best = null;
-    if (vessel && Number.isFinite(vessel.lat) && Number.isFinite(vessel.lon)) {
-      best = {
-        distanceNm: distanceNm(vessel.lat, vessel.lon, event.lat, event.lon),
-        bearingDeg: bearingDeg(vessel.lat, vessel.lon, event.lat, event.lon),
-        from: "vessel",
-      };
-    }
+    // Either envelope admits: the vessel's ahead-radius or the route
+    // corridor. The old best-reference-wins rule let the closer
+    // reference tighten the envelope — a compile switching the
+    // exposure reference (here mode admits at 1000 nm from the
+    // vessel, route mode at 500 nm off the nearest sample) tipped a
+    // stationary cyclone out of the matrix and back, flapping the
+    // notification without the storm moving an inch.
+    const vesselRef =
+      vessel && Number.isFinite(vessel.lat) && Number.isFinite(vessel.lon)
+        ? {
+            distanceNm: distanceNm(
+              vessel.lat,
+              vessel.lon,
+              event.lat,
+              event.lon,
+            ),
+            bearingDeg: bearingDeg(
+              vessel.lat,
+              vessel.lon,
+              event.lat,
+              event.lon,
+            ),
+          }
+        : null;
+    let routeRef = null;
     for (const point of route) {
       const d = distanceNm(point.lat, point.lon, event.lat, event.lon);
-      if (!best || d < best.distanceNm) {
-        best = {
+      if (routeRef === null || d < routeRef.distanceNm) {
+        routeRef = {
           distanceNm: d,
           bearingDeg: bearingDeg(point.lat, point.lon, event.lat, event.lon),
-          from: "route",
         };
       }
     }
-    if (!best) {
-      continue;
-    }
     const within =
-      (best.from === "vessel" && best.distanceNm <= aheadRadiusNm) ||
-      (best.from === "route" && best.distanceNm <= offRouteRadiusNm);
+      (vesselRef !== null && vesselRef.distanceNm <= aheadRadiusNm) ||
+      (routeRef !== null && routeRef.distanceNm <= offRouteRadiusNm);
     if (!within) {
       continue;
     }
+    // Report vessel-centric distance and bearing when the vessel is
+    // known — the crew thinks in distance from the boat
+    const ref = vesselRef ?? routeRef;
     surviving.push({
       ...event,
-      distanceNm: Math.round(best.distanceNm * 10) / 10,
-      bearingDeg: Math.round(best.bearingDeg),
+      distanceNm: Math.round(ref.distanceNm * 10) / 10,
+      bearingDeg: Math.round(ref.bearingDeg),
     });
   }
   return surviving.sort((a, b) =>

package/plugin/hazard-state.js

@@ -0,0 +1,73 @@
+/**
+ * On-disk acknowledgement state for critical hazard notifications
+ * (work doc #30 anti-flap): the ack must survive plugin and server
+ * restarts, or every restart re-alarms the crew for a cyclone they
+ * already acknowledged. Acks are keyed by notification id and record
+ * the alert level they silenced, so a later escalation to a strictly
+ * higher level (orange → red) re-alarms while same-level refreshes
+ * stay quiet.
+ *
+ * Entries age out after a week: a cyclone acknowledged today should
+ * still be silent next restart, but ack memory must not grow
+ * unbounded, and a week-old hazard id is stale by any measure.
+ *
+ * @file hazard-state.js
+ */
+
+const { readFileSync, renameSync, writeFileSync } = require("node:fs");
+const { join } = require("node:path");
+
+const ACK_FILE = "hazards-state.json";
+const ACK_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * Loads the acknowledgement map, pruning stale entries.
+ *
+ * @param {string} dataDir - Plugin data directory
+ * @returns {Map<string, {level: string|null, at: string}>} Ack by
+ *   notification id; empty when no state exists yet or the file is
+ *   corrupt (a crashed read must not take the escalation down —
+ *   re-alarms are annoying, a dead plugin is worse)
+ */
+function loadHazardAcks(dataDir) {
+  const acks = new Map();
+  try {
+    const raw = JSON.parse(readFileSync(join(dataDir, ACK_FILE), "utf8"));
+    const now = Date.now();
+    for (const [id, record] of Object.entries(raw?.acked ?? {})) {
+      const at = new Date(record?.at).getTime();
+      if (Number.isFinite(at) && now - at < ACK_TTL_MS) {
+        acks.set(id, record);
+      }
+    }
+  } catch {
+    // No state yet (first boot) or unreadable file: start empty
+  }
+  return acks;
+}
+
+/**
+ * Saves the acknowledgement map, pruning stale entries and writing
+ * atomically (tmp file + rename, so a crash mid-write cannot leave a
+ * half-read JSON behind).
+ *
+ * @param {string} dataDir - Plugin data directory
+ * @param {Map<string, {level: string|null, at: string}>} acks
+ * @returns {void}
+ */
+function saveHazardAcks(dataDir, acks) {
+  const acked = {};
+  const now = Date.now();
+  for (const [id, record] of acks ?? []) {
+    const at = new Date(record?.at).getTime();
+    if (Number.isFinite(at) && now - at < ACK_TTL_MS) {
+      acked[id] = record;
+    }
+  }
+  const path = join(dataDir, ACK_FILE);
+  const tmp = `${path}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify({ acked }, null, 2)}\n`);
+  renameSync(tmp, path);
+}
+
+module.exports = { loadHazardAcks, saveHazardAcks, ACK_FILE, ACK_TTL_MS };