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

package/CHANGELOG.md

@@ -2,10 +2,101 @@
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-28
+
+### Added
+
+- ETA percentile rows in the strategic outlook flag night arrivals
+  with a moon marker: arrival day/night is computed at the
+  destination for each of P10/P50/P90.
+
+- "No sails" stretches now say why the canvas is down: `No sails -
+  drifting` when the plan drifts below the motoring wind threshold,
+  `Motoring` when the engine pushes — reconciling the sail-work
+  queue with a zero engine-hours plan (drift mode).
+
+### Changed
+
+- Strategic outlook layout: motor hours and fuel use the shared
+  stat styling, and the sail-work queue renders as cards (tack/gybe
+  highlighted) like the tactical action queue.
+
+- "Warnings On Your Waters" and the synoptic surface-analysis chart
+  now also appear on the tactical dashboard, not just the strategic
+  view; the chart's night palette follows the document mode via its
+  own observation (it previously never inverted when embedded).
+  Shared card/stat styles moved into the common shadow-DOM base
+  stylesheet.
+
+- Sail-change events no longer flap when the forecast sits on a
+  matrix bin edge: a suggested state must hold through a full
+  simulation step before it enters the sail-work queue.
+
+- Fuel is handled in liters end to end (SI — no imperial units):
+  the motor burn rate is configurable as `Motor Fuel Consumption
+  (liters per hour)` with a 1.8 l/h default, and the strategic ETA
+  table shows e.g. `72.0 l` instead of gallons.
+
+- The tactical "Next 24 Hours" hero readout is labeled `AWS` and
+  shows its unit: `AWS 17.0 kn` instead of a bare number. (Signal K
+  carries wind in SI m/s internally; the briefing displays the
+  nautical kn.)
+
+- Sail-change cards in the tactical dashboard and the sail-work
+  timeline in the strategic outlook render the canonical sail-state
+  keys as human-readable labels: `GENOA_1_30_FURLED_MAIN_1_REEF`
+  reads "Genoa 1 30% furled + Main 1 reef", `NO_SAILS` reads "No
+  sails". Unparseable keys still fall back to the raw form.
+
+### Fixed
+
+- A scheduled (oneshot/cron) refresh no longer fails forever when
+  the last briefed route has been deleted from resources: the stale
+  `last-route` pointer is removed and the refresh falls back to
+  keeping conditions-here fresh. Previously every cycle died with
+  `Briefing refresh failed (oneshot): Resource not found!`.
+
+- The scheduled (oneshot/cron) route refresh no longer pulls the
+  bulletin stack twice per cycle: the briefing refresh already
+  fetches bulletins and synoptics for the track, so the outer
+  duplicate pass is gone.
+
+- SWPC solar-weather timestamps are UTC but carry no offset, so
+  they were parsed in the server's local timezone: on a boat far
+  from Greenwich the entire Kp forecast window shifted and aurora
+  alerts degraded. Offsetless timestamps are now read as UTC.
+
+- Switching the route selector between "Conditions here" and a route
+  now actually swaps the view: the tactical/strategic shell is
+  rebuilt for the served mode (previously the tabbed views never
+  came back after visiting conditions-here, so route selection
+  appeared to do nothing). Stale model data from the previous
+  selection is dropped instead of flashing.
+
+- Selecting "Conditions here" in the route picker now actually
+  serves conditions-here: the briefing API treated an empty `route`
+  parameter as "serve the route being sailed", so the selection
+  silently returned the same route view. An explicit `?route=`
+  (even empty) now selects; only a fully omitted parameter falls
+  back to the active route.
+
+- The webapp shows a loading state while a briefing loads or
+  refreshes (compiles can take tens of seconds on a slow link —
+  silence read as a broken app), and timed-out requests say the
+  server is busy and to retry instead of surfacing the cryptic
+  engine abort text. Rapid mode switching can no longer apply a
+  stale response after a newer one.
+
+## [0.2.1] - 2026-09-28
+
 ## [0.2.0] - 2026-09-28
 
 ### Fixed
 
+- The route simulation crashed with `startTime.getTime is not a
+  function` when the caller passed the payload's ISO timestamp
+  string instead of a Date — simulatePassage now accepts both.
+
 - The plotter widget HTML and JS are cache-busted with the plugin
   version, so widget updates actually reach the host's iframe —
   a stale cached copy was showing a removed Open button.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meri-imperiumi/signalk-passage-briefing",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Offshore passage daily briefing webapp for Signal K",
   "main": "plugin/index.js",
   "scripts": {
@@ -14,7 +14,7 @@
   },
   "keywords": [
     "signalk-node-server-plugin",
-    "signalk-category-utility",
+    "signalk-category-weather",
     "signalk-webapp"
   ],
   "author": "Henri Bergius <henri.bergius@iki.fi>",
@@ -26,7 +26,7 @@
   "signalk-plugin-enabled-by-default": false,
   "signalk": {
     "displayName": "Passage Briefing",
-    "appIcon": "./icon.png",
+    "appIcon": "./icon-256.png",
     "screenshots": [
       "doc/here-brief.png"
     ],

package/plugin/celestial-source.js

@@ -87,7 +87,13 @@ function parseKpForecast(json, { from = new Date(), hours = 24 } = {}) {
   const end = start + hours * 3600000;
   const entries = [];
   for (const row of json) {
-    const t = new Date(row?.time_tag).getTime();
+    // SWPC time_tag is UTC but offsetless: parsing it bare would
+    // interpret it in the server's timezone and shift the whole
+    // window (a UTC+13 boat must see the same forecast as a UTC one)
+    const raw = typeof row?.time_tag === "string" ? row.time_tag : "";
+    const t = new Date(
+      /[Zz]|[+-]\d\d:?\d\d$/.test(raw) ? raw : `${raw}Z`,
+    ).getTime();
     const kp = row?.kp;
     if (!Number.isFinite(t) || typeof kp !== "number" || !Number.isFinite(kp)) {
       continue;

package/plugin/index.js

@@ -20,7 +20,7 @@
 
 const { join } = require("node:path");
 const { homedir } = require("node:os");
-const { mkdir, readFile, writeFile } = require("node:fs/promises");
+const { mkdir, readFile, unlink, writeFile } = require("node:fs/promises");
 
 const { PassageStateMachine } = require("./state-machine.js");
 const { PassageDatabase } = require("./sqlite-db.js");
@@ -125,6 +125,7 @@ const HERE_TTL_MS = 3 * 60 * 60 * 1000;
 const DEFAULTS = {
   motoring_tws_threshold: 3.5,
   drift_mode_enabled: true,
+  motor_fuel_l_per_hour: 1.8,
   waterline_length_m: 9.4,
   spool_directory: join(homedir(), ".signalk", "spool", "passage-outlook"),
   k_heel: 0.35,
@@ -168,6 +169,7 @@ module.exports = (app) => {
   let simulationConfig = {
     motoring_tws_threshold: DEFAULTS.motoring_tws_threshold,
     drift_mode_enabled: DEFAULTS.drift_mode_enabled,
+    motor_fuel_l_per_hour: DEFAULTS.motor_fuel_l_per_hour,
     waterline_length_m: DEFAULTS.waterline_length_m,
     k_heel: DEFAULTS.k_heel,
     k_pitch: DEFAULTS.k_pitch,
@@ -631,7 +633,12 @@ module.exports = (app) => {
     }
     let coordinates;
     if (typeof app.resourcesApi?.getResource === "function") {
-      const route = await app.resourcesApi.getResource("routes", routeId);
+      let route;
+      try {
+        route = await app.resourcesApi.getResource("routes", routeId);
+      } catch (error) {
+        throw new Error(`Route ${routeId} not found (${error.message})`);
+      }
       coordinates = route?.feature?.geometry?.coordinates;
     }
     if (!Array.isArray(coordinates) || coordinates.length < 2) {
@@ -687,6 +694,12 @@ module.exports = (app) => {
    * trigger). The multi-endpoint fetch lands in the briefing refresh;
    * the outcome is surfaced through the plugin status.
    *
+   * The route being sailed wins; otherwise the last briefed one is
+   * re-briefed. A route that has vanished from resources (deleted
+   * after it was briefed) is skipped instead of failing every future
+   * refresh — with no route left, conditions-here stays fresh (work
+   * doc #7).
+   *
    * @param {"oneshot"|"cron"} trigger
    */
   async function runFetch(trigger) {
@@ -694,41 +707,41 @@ module.exports = (app) => {
       setStatus(`Fetch skipped while offline (${trigger})`);
       return;
     }
-    // The route being sailed wins; otherwise re-brief the last one;
-    // with no route at all keep conditions-here fresh (work doc #7)
-    let routeId = activeRouteId(observations[ACTIVE_ROUTE_PATH]);
-    if (!routeId) {
-      try {
-        routeId = (
-          await readFile(
-            join(app.getDataDirPath(), "weather", "last-route"),
-            "utf8",
-          )
-        ).trim();
-      } catch (_error) {
-        routeId = null;
-      }
+    const lastRouteFile = join(app.getDataDirPath(), "weather", "last-route");
+    let lastRouteId = null;
+    try {
+      lastRouteId = (await readFile(lastRouteFile, "utf8")).trim();
+    } catch (_error) {
+      lastRouteId = null;
     }
-    if (!routeId) {
+    const activeId = activeRouteId(observations[ACTIVE_ROUTE_PATH]);
+    const candidates = [...new Set([activeId, lastRouteId].filter(Boolean))];
+    for (const routeId of candidates) {
       try {
-        const here = await refreshHere();
-        setStatus(`Conditions here cached at ${here.cachedAt} (${trigger})`);
+        const result = await refreshBriefing(routeId);
+        setStatus(
+          `Briefing for ${routeId} cached at ${result.fetchedAt} (${trigger})`,
+        );
+        return;
       } catch (error) {
-        app.error(`Here refresh failed (${trigger}): ${error.message}`);
-        setError(`Here refresh failed (${trigger}): ${error.message}`);
+        if (!/not found/i.test(error.message)) {
+          app.error(`Briefing refresh failed (${trigger}): ${error.message}`);
+          setError(`Briefing refresh failed (${trigger}): ${error.message}`);
+          return;
+        }
+        // Route deleted since it was briefed: try the next candidate
+        app.debug?.(`Route ${routeId} no longer exists (${trigger})`);
+        if (routeId === lastRouteId && routeId !== activeId) {
+          await unlink(lastRouteFile).catch(() => {});
+        }
       }
-      return;
     }
     try {
-      const result = await refreshBriefing(routeId);
-      // Bulletins ride the same online window (work doc #4 §1)
-      await refreshBulletinsOnline(trigger, result.waypoints);
-      setStatus(
-        `Briefing for ${routeId} cached at ${result.fetchedAt} (${trigger})`,
-      );
+      const here = await refreshHere();
+      setStatus(`Conditions here cached at ${here.cachedAt} (${trigger})`);
     } catch (error) {
-      app.error(`Briefing refresh failed (${trigger}): ${error.message}`);
-      setError(`Briefing refresh failed (${trigger}): ${error.message}`);
+      app.error(`Here refresh failed (${trigger}): ${error.message}`);
+      setError(`Here refresh failed (${trigger}): ${error.message}`);
     }
   }
 
@@ -951,6 +964,14 @@ module.exports = (app) => {
           title: "Enable Drift Mode (Zero Fuel / Current Drift)",
           default: DEFAULTS.drift_mode_enabled,
         },
+        motor_fuel_l_per_hour: {
+          type: "number",
+          title: "Motor Fuel Consumption (liters per hour)",
+          description:
+            "Burn rate of the auxiliary at its passage speed, used when " +
+            "drift mode is off and the wind is below the motoring threshold.",
+          default: DEFAULTS.motor_fuel_l_per_hour,
+        },
         waterline_length_m: {
           type: "number",
           title: "Waterline Length (meters)",
@@ -1034,6 +1055,7 @@ module.exports = (app) => {
       simulationConfig = {
         motoring_tws_threshold: config.motoring_tws_threshold,
         drift_mode_enabled: config.drift_mode_enabled,
+        motor_fuel_l_per_hour: config.motor_fuel_l_per_hour,
         waterline_length_m: config.waterline_length_m,
         k_heel: config.k_heel,
         k_pitch: config.k_pitch,
@@ -1247,10 +1269,14 @@ module.exports = (app) => {
        * everything else is here mode.
        */
       router.get("/api/briefing", async (req, res) => {
-        const routeId =
-          typeof req.query.route === "string" ? req.query.route : "";
+        // An explicit ?route= (even empty) selects the mode — the
+        // route picker's "Conditions here" entry requests exactly
+        // that. With no param at all the route being sailed wins,
+        // falling back to here when none (work doc #7)
+        const explicitRoute = typeof req.query.route === "string";
+        const routeId = explicitRoute ? req.query.route.trim() : "";
         const activeId = activeRouteId(observations[ACTIVE_ROUTE_PATH]);
-        const effectiveRoute = routeId || activeId;
+        const effectiveRoute = routeId || (explicitRoute ? "" : activeId);
         if (!effectiveRoute) {
           const here = await loadHere();
           if (!here) {

package/public/components/models.mjs

@@ -88,16 +88,16 @@ export function fmtKn(knots) {
 }
 
 /**
- * Formats fuel in gallons with one decimal.
+ * Formats fuel in liters with one decimal (SI — never imperial).
  *
- * @param {number|null|undefined} gallons
+ * @param {number|null|undefined} liters
  * @returns {string} Empty string when unset/invalid
  */
-export function fmtGal(gallons) {
-  if (gallons == null || !Number.isFinite(gallons)) {
+export function fmtLiters(liters) {
+  if (liters == null || !Number.isFinite(liters)) {
     return "";
   }
-  return `${gallons.toFixed(1)} gal`;
+  return `${liters.toFixed(1)} l`;
 }
 
 /**
@@ -300,19 +300,148 @@ export function tacticalNow(exceptions) {
   };
 }
 
+/**
+ * Sail-type words that mark the start of a new sail component inside
+ * a canonical sail-state key. Reef/furl bits always terminate their
+ * component, so only consecutive *full* sails are ambiguous without
+ * the vessel's sail inventory — this small dictionary of common sail
+ * types closes the gap (e.g. `GENOA_1_MAIN` is two sails, not one
+ * named "Genoa 1 Main").
+ */
+const SAIL_COMPONENT_WORDS = new Set([
+  "MAIN",
+  "GENOA",
+  "JIB",
+  "STAYSAIL",
+  "FORESAIL",
+  "MIZZEN",
+  "SPINNAKER",
+  "GENNAKER",
+  "YANKEE",
+  "FOCK",
+  "CODE",
+  "DRIFTER",
+  "SPIN",
+]);
+
+/**
+ * Human-readable label for a canonical sail-state key (as built by
+ * `logbook-source.js` `sailStateKey`): `GENOA_1_30_FURLED_MAIN_1_REEF`
+ * reads as `Genoa 1 30% furled + Main 1 reef`, `NO_SAILS` as
+ * `No sails`. A trailing `@side` (maneuver states) is ignored.
+ *
+ * @param {string|null|undefined} key - Canonical key, e.g. `MAIN_1_REEF`
+ * @returns {string} Label, or the raw input when nothing parses
+ */
+export function sailStateLabel(key) {
+  const raw = String(key ?? "").trim();
+  if (!raw) {
+    return "";
+  }
+  const combination = raw.split("@")[0];
+  if (!combination || combination === "?") {
+    return raw;
+  }
+  if (combination === "NO_SAILS") {
+    return "No sails";
+  }
+
+  const components = [];
+  let words = [];
+  let reefs = null;
+  let furled = null;
+  const flush = () => {
+    if (words.length > 0 || reefs != null || furled != null) {
+      components.push({ words, reefs, furled });
+    }
+    words = [];
+    reefs = null;
+    furled = null;
+  };
+
+  const tokens = combination.split("_");
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    const value = /^\d+$/.test(token) ? Number(token) : null;
+    const next = tokens[i + 1];
+    if (value != null && (next === "REEF" || next === "FURLED")) {
+      // Bit run `N REEF` / `N FURLED`: ends the component name run
+      if (next === "REEF") {
+        reefs = value;
+      } else {
+        furled = value;
+      }
+      i++;
+      continue;
+    }
+    if (
+      words.length > 0 &&
+      (reefs != null || furled != null || SAIL_COMPONENT_WORDS.has(token))
+    ) {
+      flush();
+    }
+    words.push(token);
+  }
+  flush();
+
+  if (components.length === 0) {
+    return raw;
+  }
+  return components
+    .map(({ words: sailWords, reefs: nReef, furled: nFurled }) => {
+      const name = sailWords
+        .map((word) =>
+          /^\d/.test(word)
+            ? word
+            : word.charAt(0) + word.slice(1).toLowerCase(),
+        )
+        .join(" ");
+      const bits = [];
+      if (nReef != null) {
+        bits.push(`${nReef} reef${nReef === 1 ? "" : "s"}`);
+      }
+      if (nFurled != null) {
+        bits.push(`${nFurled}% furled`);
+      }
+      return [name, ...bits].filter(Boolean).join(" ");
+    })
+    .join(" + ");
+}
+
+/**
+ * Label for one sail-change event: bare "No sails" says WHY the
+ * canvas is down — the plan drifts (`No sails - drifting`) or the
+ * engine pushes (`Motoring`) — instead of implying bare-pole sailing.
+ *
+ * @param {{sailState: string|null, propulsion?: string|null}} event
+ * @returns {string} Human label
+ */
+function sailEventLabel(event) {
+  const label = sailStateLabel(event.sailState);
+  if (label === "No sails") {
+    if (event.propulsion === "adrift") {
+      return "No sails - drifting";
+    }
+    if (event.propulsion === "motor") {
+      return "Motoring";
+    }
+  }
+  return label;
+}
+
 /**
  * Sail action cards for the tactical dashboard, oldest first.
  * Maneuver events (work doc #5) carry `maneuver`, `toTack` and the
  * expected TWS so the cards can read "Tack to starboard ~14:20, 12 kt".
  *
  * @param {object|null} exceptions
- * @returns {Array<{hoursFromNow: number, stamp: string, sailState: string, night: boolean, maneuver: string|null, toTack: string|null, twsKnots: number|null}>}
+ * @returns {Array<{hoursFromNow: number, stamp: string, label: string, night: boolean, maneuver: string|null, toTack: string|null, twsKnots: number|null}>}
  */
 export function sailActionCards(exceptions) {
   return (exceptions?.next24h?.sailChanges ?? []).map((e) => ({
     hoursFromNow: e.hoursFromNow,
     stamp: fmtUtc(e.timestamp),
-    sailState: e.sailState ?? "?",
+    label: sailEventLabel(e) || "?",
     night: Boolean(e.night),
     maneuver: e.maneuver ?? null,
     toTack: e.toTack ?? null,
@@ -330,10 +459,10 @@ export function sailActionCards(exceptions) {
 export function sailWorkTimeline(exceptions) {
   return (exceptions?.passageSummary?.sailChanges ?? []).map((e) => {
     const state = String(e.sailState ?? "?");
-    const [combination, tack] = state.split("@");
+    const [, tack] = state.split("@");
     const label = e.maneuver
       ? `${e.maneuver === "tack" ? "Tack" : "Gybe"} to ${e.toTack ?? tack ?? "?"}`
-      : combination || state;
+      : sailEventLabel(e) || state;
     const detail = [
       e.distanceFromStartNm != null
         ? `${Math.round(e.distanceFromStartNm)} nm`
@@ -359,14 +488,28 @@ export function sailWorkTimeline(exceptions) {
  */
 export function etaTable(exceptions) {
   const summary = exceptions?.passageSummary ?? {};
+  const night = summary.etaNight ?? {};
   return {
     rows: [
-      { label: "P10", stamp: fmtUtc(summary.etaP10) },
-      { label: "P50", stamp: fmtUtc(summary.etaP50) },
-      { label: "P90", stamp: fmtUtc(summary.etaP90) },
+      {
+        label: "P10",
+        stamp: fmtUtc(summary.etaP10),
+        night: night.p10 === true,
+      },
+      {
+        label: "P50",
+        stamp: fmtUtc(summary.etaP50),
+        night: night.p50 === true,
+      },
+      {
+        label: "P90",
+        stamp: fmtUtc(summary.etaP90),
+        night: night.p90 === true,
+      },
     ],
     motorHours:
       summary.totalMotorHours != null ? fmtHours(summary.totalMotorHours) : "",
-    fuel: summary.totalFuelGal != null ? fmtGal(summary.totalFuelGal) : "",
+    fuel:
+      summary.totalFuelLiters != null ? fmtLiters(summary.totalFuelLiters) : "",
   };
 }