@meri-imperiumi/signalk-passage-briefing 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,101 @@
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-03
+
+### Added
+
+- Sail changes are scheduled when the crew can act on them:
+  recommendation-driven canvas changes anchor to the *previous watch
+  handover* when a watch schedule is running (signalk-watch-schedule;
+  boundaries are extrapolated across the forecast horizon from the
+  rotation cycle, and the watch boundary wins over sunlight),
+  otherwise to the next sunrise/sunset. Several detections between
+  boundaries collapse into one change carrying the last suggested
+  state, no-op re-rigs are dropped, and the timeline says which
+  anchor applied ("watch change" / "at dusk" / "at dawn"). Tacks and
+  gybes stay at their tactical times.
+- Unified passage timeline: a new `<passage-timeline>` component and
+  `mergeTimeline()` view model render every event source — sail
+  changes, planned tacks and gybes, convective risk, macro sea state,
+  territorial waters transitions, sky events and hazard notes — as
+  one chronological list with a time gutter, kind glyph and severity
+  colour. The tactical dashboard renders the 24 h slice, the
+  strategic outlook the whole passage; the per-type blocks (Sail
+  Work, Convective Risk, Macro Sea State, Sky Notes) and the tactical
+  hazard banners are replaced by it. The exception view now carries
+  the whole-route hazard list in `passageSummary.hazards` (the 24 h
+  `next24h.sailChanges` and `next24h.hazards` slices are gone — the
+  timeline slices itself).
+- Sail-change events in the timeline carry the forecast conditions
+  at the change point (nearest simulated hour): true wind, sea state
+  and Sereno comfort tier — "Main 1 reef — 14.2 kn TWS · Hs 1.5 m ·
+  coffee" — so the crew knows what they are rigging into. The
+  simulation's hourly rows now include wave height and period.
+- Ship's time display: the webapp reads the vessel's published
+  timezone (`environment.time.timezoneOffset` / `.timezoneRegion`, as
+  served by signalk-ships-time) over the REST API and the delta
+  stream, and renders briefing stamps in ship's time (`MM-DD HH:MM
+  +13`) instead of UTC, falling back to UTC `Z` when no offset is
+  published. The offset rides on every stamp so a zone crossing
+  mid-passage reads honestly; a header pill names the zone (IANA
+  region when known, else the offset).
+- Weather source selection (`weather_source`: `auto` / `weather-api` /
+  `open-meteo`, default `auto`): when the server has the Weather API
+  and a provider answers — signalk-weather-router-plus serving its
+  decoded ECMWF run — waypoint forecasts for the here and route
+  briefing windows are read from it in-process (`app.weatherApi`)
+  instead of Open-Meteo, so the briefing reasons from the same
+  forecast the router planned with and offshore fetches stay local.
+  Provider responses (Signal K units) map onto the payload
+  conventions (knots, degrees true, hPa); combined sea only — swell
+  and wind-sea partitions and the upper-air fields behind the
+  convective warnings degrade to absent. A failed Weather API fetch
+  falls back to Open-Meteo for that window; the forced choices never
+  fall back.
+
+### Changed
+
+- Convective warnings read as episodes, not hourly spam: consecutive
+  anomalies (and steep-sea anomalies alike) merge into one timeline
+  event with a time range and peak values — "CAPE 713 J/kg · K 28.6 ·
+  until 10-05 05:38Z". Severity follows the peak: CAPE ≥ 400 J/kg (the
+  bar where weather services start coloring the index) or K-index ≥ 30
+  is a red alert, while the unstable-air band below it (K ≥ 28 with
+  low CAPE) still shows as an orange warning with units and sane
+  precision instead of being dropped or inflated.
+
+### Fixed
+
+- The webapp flags stale cached briefings: when a served payload was
+  compiled more than a day ago, a banner above the briefing shows the
+  compile stamp and age with a Fetch now affordance, instead of
+  presenting a multi-day-old timeline's `+Xh` labels as upcoming.
+- The plugin re-fetches stale briefings without waiting for an edge
+  trigger: the oneshot fires only when the internet state changes and
+  cron windows only run while moored and charged, so a server that
+  stays up for days while the machine sits in STANDBY_OFFSHORE kept
+  serving a briefing sliding into the past. The one-minute ticker now
+  re-fetches (trigger `stale`) when online and the cached briefing
+  (active route, else last briefed, else here) is older than the
+  route TTL — at most once per six hours, and only when something is
+  actually cached.
+
+- Bulletin geography now resolves named synoptic features in area
+  bounds: `SOUTH OF 09S AND WEST OF CF` and `SOUTH OF 10S, BETWEEN
+  150W AND CF` compose a polygon from the cold front's defining
+  chain (clipped to the stated latitude bounds, closed across the
+  antimeridian with a margin so western-Pacific vessels stay in
+  west-of-front areas) instead of falling back to a hemisphere-wide
+  box that matched every vessel south of the bound.
+
+- Coordinate chains accept the Fiji/NFFN bulletin conventions the
+  strict parser dropped: the dateline written as bare `180` (`TROUGH
+  T3 12S 175E 14S 180 15S 177W`) and the equator written as `EQT`
+  (`EQT 177E`). Prose numbers (`280600 UTC`, `20 TO 30 KNOTS`) are
+  still rejected, and a rejected span no longer swallows a following
+  coordinate pair.
+
 ## [0.3.0] - 2026-09-28
 
 ### Added

package/README.md

@@ -3,12 +3,7 @@
 Offshore passage daily briefing webapp for Signal K: a plugin that plans
 and reviews passages for a cruising sailing vessel.
 
-The plugin fetches multi-model weather along the planned route (online,
-or via a GRIB/text spool when offline offshore), runs a step-forward
-isochrone simulation with a monohull comfort model, learns the crew's
-sail preferences from the electronic logbook, and serves a two-screen
-webapp: a 24-hour tactical dashboard and a strategic passage summary.
-See [SPEC.md](SPEC.md) for the full design.
+The plugin fetches weather along the planned route — from the server's Weather API when a provider answers, Open-Meteo otherwise; fetched online, or via a GRIB/text spool when offline offshore. It runs a step-forward isochrone simulation with a monohull comfort model, learns the crew's sail preferences from the electronic logbook, and serves a two-screen webapp: a 24-hour tactical dashboard and a strategic passage summary. See [SPEC.md](SPEC.md) for the full design.
 
 Part of the Lille Ø offshore suite, alongside
 [@meri-imperiumi/signalk-energy-predictor](https://github.com/meri-imperiumi/signalk-energy-predictator)
@@ -38,11 +33,34 @@ and [@meri-imperiumi/signalk-logbook](https://github.com/meri-imperiumi/signalk-
 - [signalk-logbook](https://github.com/meri-imperiumi/signalk-logbook)
   store — crewed sail events (reefs, sail changes) that train the
   preference matrix
+- [signalk-ships-time](https://github.com/meri-imperiumi/signalk-ships-time)
+  — `environment.time.timezoneOffset` / `.timezoneRegion`, the
+  vessel's published timezone: briefing stamps render in ship's time
+  when available (the offset rides on every stamp), falling back to
+  UTC `Z` when nothing is published
+- [signalk-watch-schedule](https://github.com/hoeken/signalk-watch-schedule)
+  — `watch.state.onWatch`, `watch.state.startedAt`, `watch.system` and
+  `watch.schedule`: the running watch rotation. While a watch is
+  running, planned sail changes anchor to the previous watch handover
+  (both teams awake) instead of sunrise/sunset; boundaries are
+  extrapolated across the forecast horizon from the rotation cycle
 - [@signalk/sailsconfiguration](https://www.npmjs.com/package/@signalk/sailsconfiguration)
   — sail inventory used to filter free-text noise out of log entries
+- Weather API (`app.weatherApi`) — waypoint forecasts from the
+  registered provider, the preferred source (`weather_source: auto`)
+  whenever one answers; [signalk-weather-router-plus](https://github.com/motamman/signalk-weather-router-plus)
+  serves it from its decoded ECMWF run, so briefing numbers match what
+  the router planned with. That source carries combined sea only:
+  swell/wind-sea partitions and the upper-air fields behind the
+  convective warnings degrade to absent rather than being invented
 
 ### External
 
+The Open-Meteo entries below are the fallback weather source: used
+when no Weather API provider answers (or `weather_source` is
+`open-meteo`), and the only source of the partition and upper-air
+fields the Weather API providers don't publish.
+
 - [Open-Meteo Forecast API](https://open-meteo.com/en/docs) — surface
   wind, gusts, MSL pressure, CAPE and the pressure-layer fields behind
   the K-index (best-match model)
@@ -70,6 +88,24 @@ and [@meri-imperiumi/signalk-logbook](https://github.com/meri-imperiumi/signalk-
 All external fetches are online-gated and cached to the plugin data
 directory, so the last payloads survive the offline hours.
 
+## Pairing with Weather Router Plus
+
+[signalk-weather-router-plus](https://github.com/motamman/signalk-weather-router-plus)
+plans the passage: isochrone routing against the vessel's polar on the ECMWF open-data run it keeps decoded on disk, with map overlays, tides and currents. Activate the route it publishes to the Resources API, and this plugin briefs it — `navigation.course.activeRoute` wins over the last briefed route at the next fetch window, and with `weather_source: auto` (the default) the briefing reads its forecasts from the router's Weather API provider. One forecast on board, planner and briefing in agreement: the router for planning and visualization, the briefing for the underway daily routine (comfort, sail changes, bulletins, energy).
+
+## Pairing with Watch Schedule
+
+[signalk-watch-schedule](https://github.com/hoeken/signalk-watch-schedule)
+runs the crew's watch rotation and publishes it under `watch.*`. When a
+watch is running, this plugin reads the schedule at app load and moves
+planned sail changes (reefs, canvas work) to the *previous* watch
+handover — the moment both teams are awake on deck — rather than
+sunrise/sunset; tacks and gybes stay at their tactical times, since
+course work can't wait for a handover. The watch boundary wins over
+sunlight. Without a running watch, canvas work anchors to the next
+sunrise/sunset. Webapp-side only: no configuration, and the briefing
+works unchanged when the plugin is absent.
+
 ## Acknowledgments
 
 The comfort model and the whole idea of "what will each departure

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meri-imperiumi/signalk-passage-briefing",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Offshore passage daily briefing webapp for Signal K",
   "main": "plugin/index.js",
   "scripts": {
@@ -34,6 +34,10 @@
       "@meri-imperiumi/signalk-energy-predictor",
       "@meri-imperiumi/signalk-internet",
       "signalk-polar-management"
+    ],
+    "recommends": [
+      "signalk-watch-schedule",
+      "signalk-ships-time"
     ]
   },
   "engines": {

package/plugin/bulletin-engine.js

@@ -167,23 +167,49 @@ function hemisphereDegrees(value, hemisphere) {
 }
 
 /**
- * Parses coordinate chains like `16S 170E 20S 178W` into a GeoJSON
- * ring (lon/lat pairs, unclosed input closed automatically).
+ * Extracts every coordinate pair from a block as lon/lat points,
+ * without the ring bookkeeping. Hemisphere letters are optional to
+ * accept the bulletin shorthand the strict form misses: the dateline
+ * written as a bare `180` (`14S 180`, east by convention) and the
+ * equator written as `EQT` (`EQT 177E`). Pairs where both letters
+ * are missing are prose numbers ("280600 UTC", "20 TO 30 KNOTS")
+ * and rejected.
  *
  * @param {string} text
- * @returns {number[][]|null} [[lon, lat], …] closed, or null
+ * @returns {number[][]} [[lon, lat], …] (possibly empty)
  */
-function parseCoordinateChain(text) {
-  const pair = /(\d+(?:\.\d+)?)\s*([NS])[,\s]+(\d+(?:\.\d+)?)\s*([EW])/gi;
-  const ring = [];
+function parseCoordinatePoints(text) {
+  const pair = /(\d+(?:\.\d+)?|EQT)\s*([NS])?[,\s]+(\d+(?:\.\d+)?)\s*([EW])?/gi;
+  const points = [];
   let match;
   while ((match = pair.exec(text)) !== null) {
-    const lat = hemisphereDegrees(match[1], match[2].toUpperCase());
-    const lon = hemisphereDegrees(match[3], match[4].toUpperCase());
+    const equator = match[1].toUpperCase() === "EQT";
+    const latHemi = match[2]?.toUpperCase();
+    const lonHemi = match[4]?.toUpperCase();
+    if (!equator && !latHemi && !lonHemi) {
+      // Prose numbers, not coordinates — resume inside the rejected
+      // span so it cannot swallow a following real coordinate pair
+      pair.lastIndex = match.index + 1;
+      continue;
+    }
+    const lat = equator ? 0 : hemisphereDegrees(match[1], latHemi ?? "N");
+    const lon = hemisphereDegrees(match[3], lonHemi ?? "E");
     if (Number.isFinite(lat) && Number.isFinite(lon)) {
-      ring.push([lon, lat]);
+      points.push([lon, lat]);
     }
   }
+  return points;
+}
+
+/**
+ * Parses coordinate chains like `16S 170E 20S 178W` into a GeoJSON
+ * ring (lon/lat pairs, unclosed input closed automatically).
+ *
+ * @param {string} text
+ * @returns {number[][]|null} [[lon, lat], …] closed, or null
+ */
+function parseCoordinateChain(text) {
+  const ring = parseCoordinatePoints(text);
   if (ring.length < 2) {
     return null;
   }
@@ -283,6 +309,206 @@ function parseCardinalBounds(text) {
   return found ? [minLon, minLat, maxLon, maxLat] : null;
 }
 
+/**
+ * Synoptic feature declarations the named-bound resolution
+ * recognizes: `TROUGH T1`, `COLD FRONT CF`, `LOW PRESSURE L`, … The
+ * name must carry a digit or be one of the conventional CF, L, H so
+ * prose ("TROUGH AXIS") is not mistaken for a name.
+ */
+const FEATURE_DECLARATION =
+  /^(?:TROUGH|COLD FRONT|WARM FRONT|SHEAR LINE|RIDGE|LOW(?:\s+PRESSURE)?|HIGH)\s+([A-Z]\d+|CF|L|H)\b/i;
+
+/** Name-shaped token referenced by cardinal bounds. */
+const FEATURE_NAME = "(CF|L|H|[A-Z]\\d+)";
+
+/**
+ * Collects named synoptic features from a full bulletin: blocks that
+ * declare a feature and carry its defining coordinate chain —
+ * `COLD FRONT CF 16S 150W 20S 140W 25S 132W` — mapped name →
+ * chain. Later blocks reference these by name in their bounds
+ * ("WEST OF CF", "BETWEEN 150W AND CF").
+ *
+ * @param {string} text - Cleaned bulletin text
+ * @returns {Map<string, number[][]>} name → [[lon, lat], …]
+ */
+function collectFeatures(text) {
+  const features = new Map();
+  for (const block of segmentBlocks(text)) {
+    const match = block.trim().match(FEATURE_DECLARATION);
+    if (!match || features.has(match[1].toUpperCase())) {
+      continue;
+    }
+    const points = parseCoordinatePoints(block);
+    if (points.length > 0) {
+      features.set(match[1].toUpperCase(), points);
+    }
+  }
+  return features;
+}
+
+/**
+ * Clips a polyline to a latitude band, interpolating where segments
+ * cross the band edges, so composed feature polygons never extend
+ * past the block's stated latitude bounds. A chain entirely outside
+ * the band is kept unchanged (its ends still anchor the caps).
+ *
+ * @param {number[][]} pts - [[lon, lat], …]
+ * @param {number} minLat
+ * @param {number} maxLat
+ * @returns {number[][]} Clipped chain
+ */
+function clipChainToLatBand(pts, minLat, maxLat) {
+  if (pts.length === 0) {
+    return pts;
+  }
+  const inside = (lat) => lat <= maxLat && lat >= minLat;
+  const out = [];
+  if (inside(pts[0][1])) {
+    out.push(pts[0]);
+  }
+  for (let i = 1; i < pts.length; i++) {
+    const a = pts[i - 1];
+    const b = pts[i];
+    if (inside(a[1]) !== inside(b[1])) {
+      const bound = inside(b[1])
+        ? a[1] > maxLat
+          ? maxLat
+          : minLat
+        : b[1] > maxLat
+          ? maxLat
+          : minLat;
+      const t = (bound - a[1]) / (b[1] - a[1]);
+      out.push([a[0] + (b[0] - a[0]) * t, bound]);
+    }
+    if (inside(b[1])) {
+      out.push(b);
+    }
+  }
+  return out.length > 0 ? out : pts;
+}
+
+/**
+ * Builds the polygon for bounds that reference a named feature
+ * instead of a longitude — `SOUTH OF 09S AND WEST OF CF`, `SOUTH OF
+ * 10S, BETWEEN 150W AND CF`. The feature's chain forms the slanted
+ * edge, clipped to the block's latitude bounds; the open side closes
+ * on the BETWEEN meridian when one is given, otherwise on the
+ * antimeridian extended a margin past the seam so areas west of a
+ * front still match vessels in the western Pacific. The front's
+ * trend south of its last point is approximated by its end meridian.
+ *
+ * @param {string} text - Block text
+ * @param {Map<string, number[][]>} features - `collectFeatures` map
+ * @returns {{type: "polygon", coordinates: number[][]}|null} Closed
+ *   ring, or null when no known feature is referenced (caller falls
+ *   back to the numeric bbox path)
+ */
+function composeFeatureBounds(text, features) {
+  const southOf = text.match(/SOUTH OF\s+(\d+(?:\.\d+)?)\s*([NS])/i);
+  const northOf = text.match(/NORTH OF\s+(\d+(?:\.\d+)?)\s*([NS])/i);
+  if (!southOf && !northOf) {
+    return null; // Feature refs come as area phrases with a lat bound
+  }
+  const maxLat = southOf
+    ? hemisphereDegrees(southOf[1], southOf[2].toUpperCase())
+    : 90;
+  const minLat = northOf
+    ? hemisphereDegrees(northOf[1], northOf[2].toUpperCase())
+    : -90;
+
+  // Which side of which feature: WEST OF/EAST OF name, or BETWEEN a
+  // meridian and a name (the name is then the opposite bound).
+  const westOf = text.match(new RegExp(`WEST OF\\s+${FEATURE_NAME}\\b`, "i"));
+  const eastOf = text.match(new RegExp(`EAST OF\\s+${FEATURE_NAME}\\b`, "i"));
+  const betweenMeridianName = text.match(
+    new RegExp(
+      `BETWEEN\\s+\\d+(?:\\.\\d+)?\\s*[EW]\\s+AND\\s+${FEATURE_NAME}\\b`,
+      "i",
+    ),
+  );
+  const betweenNameMeridian = text.match(
+    new RegExp(
+      `BETWEEN\\s+${FEATURE_NAME}\\s+AND\\s+\\d+(?:\\.\\d+)?\\s*[EW]`,
+      "i",
+    ),
+  );
+  const meridianMatch = text.match(/BETWEEN\s+(\d+(?:\.\d+)?)\s*([EW])/i);
+
+  let feature = null;
+  let side = null; // Region lies on this side of the feature
+  let meridian = null; // Explicit meridian closing the open side
+  if (westOf && features.has(westOf[1].toUpperCase())) {
+    feature = features.get(westOf[1].toUpperCase());
+    side = "west";
+  } else if (eastOf && features.has(eastOf[1].toUpperCase())) {
+    feature = features.get(eastOf[1].toUpperCase());
+    side = "east";
+  } else if (
+    betweenMeridianName &&
+    features.has(betweenMeridianName[1].toUpperCase())
+  ) {
+    feature = features.get(betweenMeridianName[1].toUpperCase());
+    side = "west";
+    meridian = hemisphereDegrees(
+      meridianMatch[1],
+      meridianMatch[2].toUpperCase(),
+    );
+  } else if (
+    betweenNameMeridian &&
+    features.has(betweenNameMeridian[1].toUpperCase())
+  ) {
+    feature = features.get(betweenNameMeridian[1].toUpperCase());
+    side = "east";
+    meridian = hemisphereDegrees(
+      meridianMatch[1],
+      meridianMatch[2].toUpperCase(),
+    );
+  }
+  if (!feature) {
+    return null; // Unknown name: fall back to the numeric bbox path
+  }
+
+  // Unwrap the chain into a contiguous frame and orient it
+  // north-end-first so the caps attach to the right ends
+  const lons = [feature[0][0]];
+  for (let i = 1; i < feature.length; i++) {
+    lons.push(unwrapLon(feature[i][0], lons[i - 1]));
+  }
+  let pts = feature.map(([, lat], i) => [lons[i], lat]);
+  if (pts.length > 1 && pts[0][1] < pts[pts.length - 1][1]) {
+    pts = [...pts].reverse();
+  }
+  pts = clipChainToLatBand(pts, minLat, maxLat);
+  const first = pts[0];
+  const last = pts[pts.length - 1];
+  const center = (Math.min(...lons) + Math.max(...lons)) / 2;
+  let openLon;
+  if (meridian != null) {
+    openLon = unwrapLon(meridian, center);
+  } else if (side === "west") {
+    // West of the front reaches across the seam: the antimeridian
+    // plus a margin so 170E–180E vessels stay inside the area
+    openLon = unwrapLon(-180, center) - 60;
+  } else {
+    openLon = unwrapLon(180, center) + 60;
+  }
+
+  const ring = [
+    [first[0], maxLat],
+    ...pts,
+    [last[0], minLat],
+    [openLon, minLat],
+    [openLon, maxLat],
+  ];
+  if (
+    ring[0][0] !== ring[ring.length - 1][0] ||
+    ring[0][1] !== ring[ring.length - 1][1]
+  ) {
+    ring.push([...ring[0]]);
+  }
+  return { type: "polygon", coordinates: ring };
+}
+
 /**
  * Extracts the geographic geometry of a block: coordinate chain
  * first (polygon), cardinal bounds second (bbox). Front/trough
@@ -291,11 +517,16 @@ function parseCardinalBounds(text) {
  * distance the geometry carries `bufferNm` so the intersection test
  * expands to the band instead of the bare line.
  *
+ * Bounds referencing a named feature collected by `collectFeatures`
+ * ("WEST OF CF") resolve to a composed polygon; with no such feature
+ * known they fall back to the numeric bbox path.
+ *
  * @param {string} blockText
+ * @param {Map<string, number[][]>} [features] - `collectFeatures` map
  * @returns {{type: "polygon", coordinates: number[][], bufferNm?: number}|
  *   {type: "bbox", coordinates: number[]}|null}
  */
-function extractGeometry(blockText) {
+function extractGeometry(blockText, features = new Map()) {
   const bandMatch = blockText.match(
     /WITHIN\s+(\d+(?:\.\d+)?)\s*(?:NM|NAUTICAL\s+MILES?)\b/i,
   );
@@ -310,6 +541,10 @@ function extractGeometry(blockText) {
       ...(bufferNm != null ? { bufferNm } : {}),
     };
   }
+  const featurePolygon = composeFeatureBounds(blockText, features);
+  if (featurePolygon) {
+    return featurePolygon;
+  }
   const bbox = parseCardinalBounds(blockText);
   if (bbox) {
     return { type: "bbox", coordinates: bbox };
@@ -532,10 +767,11 @@ function filterBulletin({
     return null;
   }
   const cleaned = stripBoilerplate(rawText);
+  const features = collectFeatures(cleaned);
   const header = cleaned.split(/\r?\n/, 1)[0]?.trim() ?? "";
   const blocks = segmentBlocks(cleaned)
     .map((blockText) => {
-      const geometry = extractGeometry(blockText);
+      const geometry = extractGeometry(blockText, features);
       if (!intersectsTrack(geometry, track)) {
         return null; // Discard rule: not on our waters
       }
@@ -732,8 +968,11 @@ module.exports = {
   segmentBlocks,
   ukhoBlocksFromWarnings,
   hemisphereDegrees,
+  parseCoordinatePoints,
   parseCoordinateChain,
   parseCardinalBounds,
+  collectFeatures,
+  composeFeatureBounds,
   extractGeometry,
   unwrapLon,
   ringContains,