@meri-imperiumi/signalk-passage-briefing 0.13.0 → 0.13.2

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## [Unreleased]
 
+## [0.13.2] - 2026-10-19
+
+### Fixed
+- Briefing refresh crashed with 502 `Cannot read properties of undefined (reading '1')` when the course provider reported the vessel navigating the briefed route while still heading to its first waypoint (`navigation.course.activeRoute.pointIndex` 0, forward — e.g. just after engaging a route): the progress trim read `raw[pointIndex - 1]` for a last passed waypoint that does not exist yet. Forward pointIndex 0 now trims to the vessel position with nothing trimmed off (`trimmedFromNm` 0), and without a known vessel position the full untrimmed plan serves.
+
+## [0.13.1] - 2026-10-19
+
+### Changed
+- The warnings the resources carry are now one canonical set, published against the union of the vessel's position and the active route (work doc #48): every publish pass — fetch windows and page loads alike — previously filtered AND pruned against its own trigger's track, so a here-mode page load (position only) wiped the route's warnings and a route compile wiped the position's: the boat saw one bounding-box region while the cyclone, its 300-nautical-mile wind circle and the troughs rode the console unseen, then nothing at all. The publication track is now the union of both — and a page load that serves a cached briefing (no compile ran in the process) publishes from that briefing's own waypoints, so a restart plus a page load is enough to fill the plotter. Content-addressed ids make the re-publish idempotent, and unchanged warning sets write nothing to disk. The wider-area severe warnings — the off-track context the console never shows — publish too, as `coverage: "wider"` regions: plotters show the gale 300 nautical miles off, and the briefing map draws them from the resources muted, exactly as it drew them from the payload before. The map's payload-drawn warning layers are gone: only the route ribbon, the timeline event pins and the cyclone graphic (whose per-ring thresholds and forecast track the regions schema cannot carry) remain payload-driven, and the cyclone's own region rings yield to that graphic.
+- The published regions now split at the antimeridian (work doc #48): the parsed warning chains carry raw coordinates (166E → 180 → 170W on this week's convergence zone), and plotters that do not unwrap — Freeboard draws the raw ring — would render a seam-crossing warning across the wrong hemisphere. Every published ring — parsed areas, corridor bands, cyclone quadrant rings, CAP polygons — now unfolds into a continuous frame and clips against the seam, publishing a MultiPolygon of spec-clean parts (the convergence zone became 166..180E plus 180..152W), so both the briefing map and any other plotter draw the same honest shape. Bounds-boxes split the same way and did already.
+
+### Added
+- The NFFN storm warnings' quadrant wind fields now parse (work doc #48 session): RSMC Nadi spells the wind areas out in prose — "EXPECT WINDS OVER 47 KNOTS WITHIN 50 NAUTICAL MILES IN NE QUADRANT AND WITHIN 60 NAUTICAL MILES IN SE QUADRANT …" — a format the NHC advisory parser never accepted, so a tropical cyclone announced this way was a lone point everywhere: no wind rings on the map's cyclone graphic and no region on the chart plotter. Each threshold's four quadrant radii now build the same great-circle rings the advisory fields carry, on the same `storm.fields` structure — the map graphic and the published regions read both formats alike, and the 33-knot gale ring and the 47-knot storm ring publish as a MultiPolygon region beside the declaration's point note.
+- Warning shapes on the chart plotter (work doc #48): the METAREA and CAP warnings already publish as georeferenced notes, but the notes schema carries a single point — the gale area, the corridor band and the CAP polygon collapsed to their nearest-vertex marker. The plugin now registers a `regions` resource provider alongside the server's built-in one (the resources API merges providers, so user-created regions are untouched) and publishes a region beside each shaped warning's note: bounding boxes as ring polygons (antimeridian-crossing boxes split into two spec-clean rectangles), parsed polygons as-is, trough axis bands expanded into the same corridor rings the briefing map draws, and tropical-cyclone advisories as the MultiPolygon of their present wind/seas quadrant rings. Each paired note links to its region via `href` — the exact link Freeboard's region panel lists related notes by — and provenance (issuer, zone, subject, derivation) rides the feature properties. GDACS hazards stay note-only (points); axis lines without a stated band and text-only storm declarations have no area on the map either.
+- The briefing's warnings map draws the published resources (work doc #47 session): the hand-drawn warning-shapes layer — bulletin block shapes, CAP polygons, GDACS pins — is replaced by the same `/resources/notes` and `/resources/regions` the plotter sees, so the map and Freeboard render one set of warnings and any third-party resource provider's notes and regions appear for free. Severity coloring re-derives from the warning text with the console's own highlighter (ours and third-party alike); the dashed-bbox honesty cue and the console click-through stay ours-only, matched by the block text the resources carry verbatim; a note whose region draws stays hidden so a shaped warning renders once. What stays payload-driven on purpose: the route ribbon, the timeline event pins, the cyclone graphic (per-ring thresholds and the forecast track are not representable in the regions schema) and the muted wider-area set, which keeps its muting and stays off other plotters. Third-party resources never drive the fit — the view stays anchored on the vessel's waters.
+
+### Fixed
+- The METAREA notes pass pruned the whole shared notes store, erasing GDACS hazard notes, CAP notes and any client-written notes on every bulletin publish. All three feeds now prune scoped to their own id prefixes (`metarea-`, `hazard-`, `cap-`), so notes from the other feeds and notes written by other clients survive every pass.
+
 ## [0.13.0] - 2026-10-18
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meri-imperiumi/signalk-passage-briefing",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Offshore passage daily briefing webapp for Signal K",
   "main": "plugin/index.js",
   "scripts": {

package/plugin/bulletin-engine.js

@@ -1358,6 +1358,66 @@ function advisorySeverityLabel(maxWindKt) {
  * @returns {object|null} Structured storm, null when the text is not
  *   the advisory family
  */
+/**
+ * A tropical-cyclone declaration's quadrant wind radii (work doc #48
+ * session): the RSMC NFFN storm warnings spell the wind fields out in
+ * prose — "EXPECT WINDS OVER 47 KNOTS WITHIN 50 NAUTICAL MILES IN NE
+ * QUADRANT AND WITHIN 60 NAUTICAL MILES IN SE QUADRANT …" — a format
+ * the NHC advisory parser never sees. Each threshold's quadrant
+ * radii build the same great-circle rings the advisory fields carry,
+ * so the map's cyclone graphic and the published regions read the
+ * same parsed structure for both formats. Null when the text names no
+ * radii set.
+ *
+ * @param {string} text - Block text
+ * @param {number[][]|null} coordinates - The declaration point
+ *   ([lon, lat]) the radii centre on
+ * @returns {object|null} A partial advisory shape ({center, fields,
+ *   forecastPoints}) — the fields the map graphic and the region
+ *   publisher already consume
+ */
+function declarationStorm(text, coordinates) {
+  if (
+    !Array.isArray(coordinates) ||
+    coordinates.length !== 2 ||
+    !coordinates.every(Number.isFinite)
+  ) {
+    return null;
+  }
+  const [lon, lat] = coordinates;
+  if (!Number.isFinite(lat) || !Number.isFinite(lon)) {
+    return null;
+  }
+  const fields = [];
+  // One set per threshold: "OVER 47 KNOTS" followed by its quadrant
+  // radii chain — the chain breaks at the next "EXPECT ... KNOTS"
+  const setRe =
+    /OVER\s+(\d{1,3})\s*KNOTS((?:\s+AND)?\s+WITHIN\s+\d+\s*NAUTICAL\s*MILES\s+IN\s+(?:NE|SE|SW|NW)\s+QUADRANT)+/gi;
+  const quadRe =
+    /WITHIN\s+(\d+)\s*NAUTICAL\s*MILES\s+IN\s+(NE|SE|SW|NW)\s+QUADRANT/gi;
+  for (const setMatch of text.matchAll(setRe)) {
+    const threshold = Number.parseInt(setMatch[1], 10);
+    const radiiNm = { ne: 0, se: 0, sw: 0, nw: 0 };
+    for (const quadMatch of setMatch[0].matchAll(quadRe)) {
+      radiiNm[quadMatch[2].toLowerCase()] = Number.parseInt(quadMatch[1], 10);
+    }
+    const geometry = quadrantRing({ lat, lon, radiiNm });
+    if (geometry) {
+      fields.push({
+        label: `${threshold} KT`,
+        threshold,
+        kind: "wind",
+        radiiNm,
+        geometry,
+      });
+    }
+  }
+  if (fields.length === 0) {
+    return null;
+  }
+  return { center: { lat, lon }, fields, forecastPoints: [] };
+}
+
 function parseAdvisory(text) {
   if (
     typeof text !== "string" ||
@@ -1578,11 +1638,20 @@ function filterBulletin({
       if (!geometry && !hasSevereKeyword(blockText)) {
         return null;
       }
+      // A storm declaration whose text spells out quadrant wind
+      // radii carries the same parsed fields the advisory family
+      // does — the cyclone's wind rings become map graphic and
+      // published region, not just a point (work doc #48 session)
+      const storm =
+        geometry?.type === "point"
+          ? declarationStorm(blockText, geometry.coordinates)
+          : null;
       return {
         text: blockText,
         subject: subject ?? null,
         geometryType: geometry ? geometry.type : null,
         geometry: geometry ?? null,
+        ...(storm ? { storm } : {}),
         source,
       };
     })

package/plugin/index.js

@@ -59,8 +59,13 @@ const ephemeris = require("./celestial-ephemeris.js");
 const { registerPlotterExtension } = require("./brief-ext.js");
 const { registerStatusTileExamples } = require("./statustilesexamples.js");
 const { createNotesStore, registerNotesProvider } = require("./notes-store.js");
+const {
+  createRegionsStore,
+  registerRegionsProvider,
+} = require("./regions-store.js");
 const {
   clearNotes,
+  clearRegions,
   publishNotes,
   publishHazardNotes,
   publishCapAlertNotes,
@@ -316,6 +321,8 @@ module.exports = (app) => {
   let teardownPlotterExt = null;
   let teardownStatusTiles = null;
   let teardownNotesProvider = null;
+  let regionsStore = null;
+  let teardownRegionsProvider = null;
   let notesStore = null;
   /** Route-list cache (bergie session perf pass): the resources
    * listing is seconds-slow per call and the list changes rarely —
@@ -557,12 +564,25 @@ module.exports = (app) => {
     ) {
       return null; // Not past the first point, or an index we cannot use
     }
+    const target = raw[pointIndex];
+    const vessel = vesselPosition();
+    // Heading to the first waypoint (forward pointIndex 0): no leg of
+    // the plan is behind the boat, so there is no last passed waypoint
+    // to anchor the trim distance on. The plan starts at the vessel
+    // when known (nothing trimmed off, 0 nm in), else serves in full.
+    if (!reverse && pointIndex === 0) {
+      if (!vessel) {
+        return null;
+      }
+      return {
+        coordinates: [[vessel.lon, vessel.lat], ...raw],
+        trimmedFromNm: 0,
+      };
+    }
     // Travel order decides what remains: forward navigates toward
     // higher indices, reverse toward lower ones (the course provider's
     // `reverse` flag). The start point is the vessel's actual position
     // when available, else the last passed waypoint.
-    const target = raw[pointIndex];
-    const vessel = vesselPosition();
     const start = vessel
       ? [vessel.lon, vessel.lat]
       : reverse
@@ -572,7 +592,8 @@ module.exports = (app) => {
       ? raw.slice(0, pointIndex + 1).reverse()
       : raw.slice(pointIndex);
     // Distance along the stored plan from its start to the trim point:
-    // the boat sits between the target and the last passed point
+    // the boat sits between the target and the last passed point (the
+    // forward pointIndex 0 case returned above, so this is defined)
     const reference = reverse ? target : raw[pointIndex - 1];
     const anchorSlice = reverse
       ? raw.slice(0, pointIndex + 1)
@@ -933,12 +954,80 @@ module.exports = (app) => {
   /**
    * Publishes the filtered bulletin blocks as georeferenced server
    * notes (work doc #12). Local-only: not gated on the internet
-   * state, so spool-sourced warnings publish the same way.
+   * state, so spool-sourced warnings publish the same way. Also runs
+   * at serve time (trigger "serve", work doc #48): the refiltered
+   * bulletin the console renders is what the resources must carry.
    *
-   * @param {"here"|"route"} trigger
+   * @param {"here"|"route"|"serve"} trigger
    * @param {object|null} bulletin - metareaBulletin with blocks
    * @param {Array<{lat: number, lon: number}>} waypoints
    */
+  /**
+   * The publication track (work doc #48): the vessel's position first
+   * (it anchors the nearest-point note placement), then the route
+   * waters — the caller's track hint (the served briefing's own
+   * waypoints) when one exists, else the most recent route compile's.
+   * The union of the two is the set of waters the passage touches —
+   * the notes and regions the plotter sees must not depend on which
+   * view triggered the last publish, nor on whether a compile ran in
+   * this process at all (a cached-briefing page load never compiles).
+   *
+   * @param {Array<{lat: number, lon: number}>|null} [hint] - The
+   *   served briefing's waypoints when available
+   * @returns {Array<{lat: number, lon: number}>}
+   */
+  function publicationTrack(hint = null) {
+    const track = [];
+    const seen = new Set();
+    const push = (lat, lon) => {
+      const key = `${lat},${lon}`;
+      if (Number.isFinite(lat) && Number.isFinite(lon) && !seen.has(key)) {
+        seen.add(key);
+        track.push({ lat, lon });
+      }
+    };
+    const position = vesselPosition();
+    if (position) {
+      push(position.lat, position.lon);
+    }
+    for (const waypoint of hint ?? lastRouteWaypoints ?? []) {
+      push(waypoint.lat, waypoint.lon);
+    }
+    return track;
+  }
+
+  /**
+   * The canonical publication pass (work doc #48): one set of notes
+   * and regions for the plotter, filtered against the publication
+   * track — the vessel's position plus the active route — regardless
+   * of which view or fetch window triggered it. A per-trigger filter
+   * (here: position-only, route: route-only) would have each pass
+   * prune the other's warnings; the union track ends the fight. An
+   * empty result clears this feed's resources: expiry is part of the
+   * feature.
+   *
+   * @param {string} trigger - for the debug line
+   * @param {Array<{lat: number, lon: number}>|null} [hint] - The
+   *   served briefing's waypoints when available
+   */
+  async function publishWarningsFor(trigger, hint = null) {
+    if (!publishNotesEnabled) {
+      return;
+    }
+    const track = publicationTrack(hint);
+    if (track.length === 0) {
+      return;
+    }
+    const bulletin = await bulletinForTrack(track);
+    await publishNotesFor(
+      trigger,
+      // Null bulletin (nothing on our waters) publishes an empty set:
+      // the scoped prune drops this feed's stale warnings
+      bulletin ?? { blocks: [], wider: [] },
+      track,
+    );
+  }
+
   async function publishNotesFor(trigger, bulletin, waypoints) {
     if (!publishNotesEnabled || !bulletin) {
       return;
@@ -956,15 +1045,24 @@ module.exports = (app) => {
     }
     const result = await publishNotes({
       store: notesStore,
+      regionsStore,
       bulletin,
       zone,
       synopticChartFor: () => chart,
       ref: waypoints.length > 0 ? [waypoints[0].lon, waypoints[0].lat] : null,
     });
-    if (result.published.length > 0 || result.pruned.length > 0) {
+    if (
+      result.published.length > 0 ||
+      result.pruned.length > 0 ||
+      result.regionsPublished.length > 0 ||
+      result.regionsPruned.length > 0
+    ) {
       app.debug?.(
         `Notes ${trigger}: ${result.published.length} published, ` +
-          `${result.pruned.length} expired`,
+          `${result.pruned.length} expired, ` +
+          `${result.regionsPublished.length} regions published, ` +
+          `${result.regionsPruned.length} regions expired, ` +
+          `${result.widerPublished.length} wider regions`,
       );
     }
   }
@@ -1098,6 +1196,16 @@ module.exports = (app) => {
    * @param {object} payload - Briefing payload, mutated in place
    * @returns {Promise<void>}
    */
+  /**
+   * Re-publishes the metarea warnings from the canonical publication
+   * track (work doc #48): the fetch-time publish ran against the
+   * track as it was when the bulletin arrived — the crew has moved
+   * since, and a page load must not wait for the next fetch window.
+   * Content-addressed ids make the re-publish idempotent, and
+   * unchanged sets write nothing.
+   *
+   * @param {{waypoints?: Array<{lat: number, lon: number}>}} payload
+   */
   async function refilterPayloadBulletin(payload) {
     if (!payload?.waypoints?.length) {
       return;
@@ -1106,6 +1214,12 @@ module.exports = (app) => {
     if (fresh) {
       payload.metareaBulletin = fresh;
     }
+    // The publication track is view-independent — the payload's own
+    // refiltered bulletin stays per-view for the console. The served
+    // briefing's waypoints ARE the route waters: a cached-payload page
+    // load publishes from them even when no compile ran in this
+    // process
+    await publishWarningsFor("serve", payload.waypoints);
   }
 
   /**
@@ -1187,12 +1301,20 @@ module.exports = (app) => {
     if (notesStore) {
       const result = await publishCapAlertNotes({
         store: notesStore,
+        regionsStore,
         alerts: payload.capAlerts,
       });
-      if (result.published.length > 0 || result.pruned.length > 0) {
+      if (
+        result.published.length > 0 ||
+        result.pruned.length > 0 ||
+        result.regionsPublished.length > 0 ||
+        result.regionsPruned.length > 0
+      ) {
         app.debug?.(
           `CAP notes: ${result.published.length} published, ` +
-            `${result.pruned.length} expired`,
+            `${result.pruned.length} expired, ` +
+            `${result.regionsPublished.length} regions published, ` +
+            `${result.regionsPruned.length} regions expired`,
         );
       }
     }
@@ -1274,7 +1396,7 @@ module.exports = (app) => {
     if (bulletin) {
       payload.metareaBulletin = bulletin;
     }
-    await publishNotesFor("here", bulletin, waypoints);
+    await publishWarningsFor("here");
     // Space weather rides the same online window (work doc #3);
     // degrades to an absent field when the endpoints fail. Phase-2
     // ephemeris events are local computation; the visibility gate
@@ -1506,6 +1628,7 @@ module.exports = (app) => {
     }
     const waypoints = sampleRoutePoints(coordinates);
     lastCompiledWaypoints = waypoints;
+    lastRouteWaypoints = waypoints;
     // Bulletins ride the same online window as the weather (SPEC §3.1
     // metareaBulletin): pulled first so this briefing carries them
     await refreshBulletinsOnline("briefing", waypoints);
@@ -1518,7 +1641,7 @@ module.exports = (app) => {
     if (bulletin) {
       payload.metareaBulletin = bulletin;
     }
-    await publishNotesFor("route", bulletin, waypoints);
+    await publishWarningsFor("route");
     // Space weather for the departure position (work doc #3):
     // fetched Phase-1 sources plus local Phase-2 ephemeris events,
     // all gated on the payload's own cloud cover; nightly moon and
@@ -1703,6 +1826,11 @@ module.exports = (app) => {
   /** Waypoints of the most recent compile (route or here): the
    * escalation's track reference between refreshes. */
   let lastCompiledWaypoints = null;
+  /** Waypoints of the most recent ROUTE compile: the publication
+   * track's route half (work doc #48) — warnings publish for the
+   * waters the plan crosses plus the vessel's position, whichever
+   * view triggered the pass. */
+  let lastRouteWaypoints = null;
 
   async function runFetch(trigger) {
     if (!isOnline()) {
@@ -2796,9 +2924,10 @@ module.exports = (app) => {
       modelsPromise.catch(() => {});
 
       // Notes lifecycle (work doc #12): when publication is disabled
-      // the store clears, so chart plotters stop seeing our warnings
+      // the stores clear, so chart plotters stop seeing our warnings
       if (!publishNotesEnabled) {
         clearNotes(notesStore).catch(() => {});
+        clearRegions(regionsStore).catch(() => {});
       }
 
       app.subscriptionmanager.subscribe(
@@ -2859,12 +2988,20 @@ module.exports = (app) => {
 
       // The server has no built-in notes provider: the plugin
       // registers as the notes resource provider (work doc #12) and
-      // serves the bulletin warnings plus any client-written notes
+      // serves the bulletin warnings plus any client-written notes.
+      // Regions (work doc #48) ride beside the built-in provider: the
+      // resources API merges providers per type, so user-created
+      // regions survive untouched
       notesStore = createNotesStore(app.getDataDirPath());
       teardownNotesProvider = registerNotesProvider(app, {
         id: PLUGIN_ID,
         store: notesStore,
       });
+      regionsStore = createRegionsStore(app.getDataDirPath());
+      teardownRegionsProvider = registerRegionsProvider(app, {
+        id: PLUGIN_ID,
+        store: regionsStore,
+      });
       // Acknowledge put clears the tile's NEW badge
       if (typeof app.registerPutHandler === "function") {
         app.registerPutHandler(
@@ -2913,6 +3050,10 @@ module.exports = (app) => {
         teardownNotesProvider();
         teardownNotesProvider = null;
       }
+      if (teardownRegionsProvider) {
+        teardownRegionsProvider();
+        teardownRegionsProvider = null;
+      }
       if (teardownStatusTiles) {
         teardownStatusTiles();
         teardownStatusTiles = null;