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

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [0.12.2] - 2026-10-16
+
+### Changed
+- Briefing payloads stopped carrying every forecast hour at every waypoint: the waypoints now ride an ETA-window throttle (a 15-waypoint / 7-day route went from ~1 MB to ~340 KB of JSON with no rendering change). The window opens 12 h before the arrival a fast boat (10 kn) would make and closes 48 h after the arrival a slow boat (2.5 kn) would make — steps outside are dropped, since the boat reads its neighbouring waypoints' data then — and inside the window the hourly steps beyond the first 24 h collapse to every third hour, the wave models' own native resolution (`weatherAt` interpolates). The horizon's last step always rides along (the simulator clamps to it), a guaranteed minimum span keeps coverage when the speed estimate is badly wrong, and the throttle applies to both source paths (Open-Meteo and the Weather API provider).
+
+### 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.
+
 ## [0.12.1] - 2026-10-16
 
 ### Fixed

package/package.json

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

package/plugin/fetch-engine.js

@@ -59,6 +59,39 @@ const DEFAULT_FORECAST_DAYS = 7;
  */
 const KEEP_SNAPSHOTS = 8;
 
+/**
+ * One hour in milliseconds.
+ */
+const HOUR_MS = 3600000;
+
+/**
+ * Throttle speed bracket: the fastest arrival the window must cover
+ * (window opens before it).
+ */
+const THROTTLE_FAST_KN = 10;
+
+/**
+ * Throttle speed bracket: the slowest arrival the window must cover
+ * (window closes after it, plus the tail margin).
+ */
+const THROTTLE_SLOW_KN = 2.5;
+
+/**
+ * Throttle window: opens this long before the fastest arrival.
+ */
+const THROTTLE_LEAD_HOURS = 12;
+
+/**
+ * Throttle window: closes this long after the slowest arrival.
+ */
+const THROTTLE_TAIL_HOURS = 48;
+
+/**
+ * Throttle resolution: hourly steps inside the first span of the
+ * window, every third hour after.
+ */
+const THROTTLE_HOURLY_HOURS = 24;
+
 const FORECAST_URL = "https://api.open-meteo.com/v1/forecast";
 const MARINE_URL = "https://marine-api.open-meteo.com/v1/marine";
 
@@ -614,6 +647,7 @@ async function fetchWeatherAlongTrack({
     models.push("marine:smoc_currents");
   }
   const fetchedAt = new Date().toISOString();
+  throttleWaypointForecasts(payloadWaypoints, fetchedAt);
   return {
     metadata: {
       fetchedAt,
@@ -633,6 +667,83 @@ async function fetchWeatherAlongTrack({
   };
 }
 
+/**
+ * ETA-window throttle for waypoint forecasts (briefing size, bergie
+ * session: a 15-waypoint / 7-day route carried every hour of the full
+ * horizon at every waypoint — over a megabyte of JSON to render a few
+ * KB of page). The boat is at waypoint i only around its arrival, and
+ * the arrival time depends on boat speed — so the window opens
+ * `THROTTLE_LEAD_HOURS` before the arrival a fast boat would make and
+ * closes `THROTTLE_TAIL_HOURS` after the arrival a slow boat would
+ * make; steps outside are dropped. Inside the window the hourly steps
+ * beyond the first `THROTTLE_HOURLY_HOURS` collapse to every third
+ * hour: the wave models underneath are 3-hourly anyway, and
+ * `weatherAt` interpolates between steps. A guaranteed minimum span
+ * keeps coverage even when the estimate is badly wrong, and the
+ * horizon's last step always rides along (the sim clamps to it).
+ *
+ * @param {Array<{distanceFromStartNm: number, forecasts: Array<object>}>}
+ *   payloadWaypoints - Mutated in place
+ * @param {string|number|Date} fetchedAt - The fetch instant the
+ *   estimates anchor to (the payload's `fetchedAt`)
+ * @returns {Array} The same waypoints, forecasts throttled
+ */
+function throttleWaypointForecasts(payloadWaypoints, fetchedAt) {
+  const startMs = new Date(fetchedAt).getTime();
+  if (!Array.isArray(payloadWaypoints) || !Number.isFinite(startMs)) {
+    return payloadWaypoints ?? [];
+  }
+  for (const waypoint of payloadWaypoints) {
+    const steps = waypoint?.forecasts;
+    if (!Array.isArray(steps) || steps.length === 0) {
+      continue;
+    }
+    const times = steps.map((step) => new Date(step.timestamp).getTime());
+    const firstMs = times[0];
+    const lastMs = times[times.length - 1];
+    const distNm = Number.isFinite(waypoint.distanceFromStartNm)
+      ? Math.max(0, waypoint.distanceFromStartNm)
+      : 0;
+    let windowStart = Math.max(
+      firstMs,
+      startMs +
+        (distNm / THROTTLE_FAST_KN) * HOUR_MS -
+        THROTTLE_LEAD_HOURS * HOUR_MS,
+    );
+    const windowEnd = Math.min(
+      lastMs,
+      startMs +
+        (distNm / THROTTLE_SLOW_KN) * HOUR_MS +
+        THROTTLE_TAIL_HOURS * HOUR_MS,
+    );
+    // Guaranteed minimum span: a wildly wrong speed estimate must not
+    // strip a waypoint bare
+    if (windowEnd - windowStart < 48 * HOUR_MS) {
+      windowStart = Math.max(firstMs, windowEnd - 48 * HOUR_MS);
+    }
+    const inWindow = steps.filter(
+      (_step, i) => times[i] >= windowStart && times[i] <= windowEnd,
+    );
+    if (inWindow.length === 0) {
+      continue;
+    }
+    const baseMs = new Date(inWindow[0].timestamp).getTime();
+    const lastInWindow = inWindow.length - 1;
+    waypoint.forecasts = inWindow.filter((step, i) => {
+      // The horizon's last step always rides along: weatherAt clamps
+      // to it, so a dropped tail would freeze the sim on stale values
+      if (i === lastInWindow) {
+        return true;
+      }
+      const hours = Math.round(
+        (new Date(step.timestamp).getTime() - baseMs) / HOUR_MS,
+      );
+      return hours < THROTTLE_HOURLY_HOURS || hours % 3 === 0;
+    });
+  }
+  return payloadWaypoints;
+}
+
 /**
  * Cache directory for a data dir.
  *
@@ -774,6 +885,7 @@ module.exports = {
   normalizeLocations,
   buildTimeSteps,
   fetchWeatherAlongTrack,
+  throttleWaypointForecasts,
   savePayload,
   loadPayload,
   listCachedRoutes,

package/plugin/index.js

@@ -2873,6 +2873,25 @@ module.exports = (app) => {
       // the notification returns to nominal for every connected
       // client, and the escalation does not re-raise the event until
       // it leaves the matrix and returns
+      // Active critical-hazard notifications (work doc #30): the
+      // same list the escalation publishes over the Signal K stream,
+      // served here so the webapp banner doesn't have to poll the
+      // REST notifications subtree (absent path = noisy 404)
+      router.get("/api/hazards/active", (_req, res) => {
+        const notifications = [];
+        for (const [id, notification] of activeHazardNotifications) {
+          if (acknowledgedHazards.has(id)) {
+            continue; // Acked: suppressed until the event returns
+          }
+          notifications.push({
+            id,
+            state: notification.state,
+            message: notification.message,
+          });
+        }
+        res.json({ notifications });
+      });
+
       router.post("/api/hazards/ack", async (req, res) => {
         const id = typeof req.body?.id === "string" ? req.body.id : null;
         if (!id) {

package/plugin/weather-source.js

@@ -31,7 +31,10 @@
  * @file weather-source.js
  */
 
-const { fetchWeatherAlongTrack } = require("./fetch-engine.js");
+const {
+  fetchWeatherAlongTrack,
+  throttleWaypointForecasts,
+} = require("./fetch-engine.js");
 
 /**
  * Meters per second to knots.
@@ -177,6 +180,7 @@ function buildApiPayload(waypoints, forecastsByWaypoint) {
     };
   });
   const fetchedAt = new Date().toISOString();
+  throttleWaypointForecasts(payloadWaypoints, fetchedAt);
   return {
     metadata: {
       fetchedAt,

package/public/components/passage-outlook.js

@@ -515,13 +515,13 @@ class PassageOutlook extends HTMLElement {
       // The next scheduled compile window rides /api/status (the same
       // state-machine field the checklist reads); its absence degrades
       // the Next pill to hidden, never to an invented stamp
-      this._nextCron = await fetchJson(`${PLUGIN_API}/api/status`, 8000)
+      this._nextCron = await fetchJson(`${PLUGIN_API}/status`, 8000)
         .then((status) => status?.nextCronRun ?? null)
         .catch(() => null);
       // Sea legs (work doc #40): the passage day context. Absent or
       // failed lookups degrade to null — the timeline checkpoints
       // simply don't render, never invented
-      this._seaLegs = await fetchJson(`${PLUGIN_API}/api/sea-legs`, 8000)
+      this._seaLegs = await fetchJson(`${PLUGIN_API}/sea-legs`, 8000)
         .then((s) => s?.passageStartedAt ?? null)
         .catch(() => null);
       this._briefing = await fetchJson(`${PLUGIN_API}/briefing${query}`, 20000);
@@ -830,6 +830,14 @@ class PassageOutlook extends HTMLElement {
       ? "<strategic-outlook></strategic-outlook>"
       : "<tactical-dashboard></tactical-dashboard>";
     this._applyModeToView();
+    // The tactical card head carries the route's Update now — the
+    // same affordance conditions-here has in its card head; disabled
+    // offline like the here button (the server refuses the refresh)
+    const tactical = this._view.querySelector("tactical-dashboard");
+    tactical?.setOnline(this._status?.online === true);
+    if (tactical) {
+      tactical.onRefresh = () => this.refreshBriefing();
+    }
     if (this._exceptions) {
       this.renderData();
     }

package/public/components/sk-api.js

@@ -287,38 +287,33 @@ export async function fetchNavigationState() {
 }
 
 /**
- * The plugin's critical-hazard notifications
- * (`notifications.navigation.briefing.hazards.*`), best effort — the
- * path is absent when nothing is active.
+ * The plugin's active critical-hazard notifications (work doc #30),
+ * from the plugin's own `api/hazards/active` endpoint — the same list
+ * the escalation publishes over the Signal K stream. Polling the REST
+ * notifications subtree instead 404'd whenever nothing was active.
  *
  * @returns {Promise<Array<{id: string, state: string, message: string}>|
- *   null>} Active notifications (state !== normal), null when the
- *   path or server is unavailable
+ *   null>} Active notifications, null when the server is unreachable
  */
 export async function fetchHazardNotifications() {
-  const unwrap = (node) =>
-    node && typeof node === "object" && "value" in node ? node.value : node;
   try {
-    const subtree = await fetchJson(
-      `${BASE}/api/vessels/self/notifications/navigation/briefing/hazards`,
+    const body = await fetchJson(
+      "/plugins/signalk-passage-briefing/api/hazards/active",
     );
-    const node = unwrap(subtree);
-    if (!node || typeof node !== "object") {
+    if (
+      !body ||
+      typeof body !== "object" ||
+      !Array.isArray(body.notifications)
+    ) {
       return null;
     }
-    const notifications = [];
-    for (const [id, raw] of Object.entries(node)) {
-      const value = unwrap(raw);
-      if (!value || typeof value !== "object" || value.state === "normal") {
-        continue;
-      }
-      notifications.push({
-        id,
-        state: String(value.state ?? "warn"),
-        message: String(value.message ?? ""),
-      });
-    }
-    return notifications;
+    return body.notifications
+      .filter((n) => n && typeof n === "object" && n.state !== "normal")
+      .map((n) => ({
+        id: String(n.id),
+        state: String(n.state ?? "warn"),
+        message: String(n.message ?? ""),
+      }));
   } catch {
     return null;
   }

package/public/components/tactical-dashboard.js

@@ -99,9 +99,21 @@ strong.sev {
           text-overflow: ellipsis;
         }
         .sky span { margin-right: 10px; }
+        .card-head {
+          display: flex; align-items: center; justify-content: space-between;
+          gap: 8px;
+        }
+        .card-head h2 { margin: 0; }
+        .refresh {
+          min-height: 36px; padding: 6px 12px; flex: none;
+        }
+        .refresh:disabled { opacity: 0.5; }
       </style>
       <section class="sk-card theme-teal">
-        <h2>Next 24 Hours</h2>
+        <div class="card-head">
+          <h2>Next 24 Hours</h2>
+          <button id="refresh" class="refresh">Update now</button>
+        </div>
         <div class="now">
           <span class="label">AWS</span>
           <span class="value" id="aws">—</span>
@@ -128,6 +140,9 @@ strong.sev {
     this._awsEl = this.shadowRoot.getElementById("aws");
     this._tierEl = this.shadowRoot.getElementById("tier");
     this._cinfo = this.shadowRoot.getElementById("cinfo");
+    this._refreshEl = this.shadowRoot.getElementById("refresh");
+    this._refreshEl.disabled = !this._online;
+    this._refreshEl.addEventListener("click", () => this.onRefresh?.());
     this._spark = this.shadowRoot.getElementById("spark");
     this._departureControl =
       this.shadowRoot.getElementById("departure-control");
@@ -230,6 +245,27 @@ strong.sev {
    */
   onDepartureChange = null;
 
+  /**
+   * Online state: the refresh button only fires while the link is up
+   * (the server refuses offline refreshes).
+   *
+   * @param {boolean} online
+   */
+  setOnline(online) {
+    this._online = online === true;
+    if (this._refreshEl) {
+      this._refreshEl.disabled = !this._online;
+    }
+  }
+
+  /**
+   * Refresh callback (set by the root component): posts the route
+   * refresh and reloads — the tactical view otherwise has no way to
+   * recompile between scheduled windows, and a cached payload
+   * predating a new payload field would render stale forever.
+   */
+  onRefresh = null;
+
   /**
    * Briefing payload (work docs #3, #17): carries the space events
    * and zone transitions the timeline merges in alongside the

package/tests/fetch-engine.test.js

@@ -18,6 +18,7 @@ const {
   kIndex,
   normalizeLocations,
   fetchWeatherAlongTrack,
+  throttleWaypointForecasts,
   savePayload,
   loadPayload,
   listCachedRoutes,
@@ -133,6 +134,101 @@ const WAYPOINTS = sampleRoutePoints([
   [0, 1.5],
 ]);
 
+describe("throttleWaypointForecasts", () => {
+  const HOUR = 3600000;
+  const FETCH = "2026-10-16T00:00:00.000Z";
+
+  /** Builds one hourly step. */
+  const step = (h) => ({
+    timestamp: new Date(Date.parse(FETCH) + h * HOUR).toISOString(),
+    surface: { tws: h },
+  });
+
+  test("windows bracket the arrival across the speed range", () => {
+    const waypoints = [
+      {
+        distanceFromStartNm: 0,
+        forecasts: Array.from({ length: 168 }, (_, h) => step(h)),
+      },
+      {
+        distanceFromStartNm: 210,
+        forecasts: Array.from({ length: 168 }, (_, h) => step(h)),
+      },
+    ];
+    throttleWaypointForecasts(waypoints, FETCH);
+    const second = waypoints[1].forecasts.map((f) =>
+      Math.round((Date.parse(f.timestamp) - Date.parse(FETCH)) / HOUR),
+    );
+    // Fast boat: 210 nm at 10 kn arrives at 21 h, window opens 12 h
+    // before — the early hours the boat cannot be there yet are gone
+    assert.equal(second[0], 9);
+    // Slow boat: 210 nm at 2.5 kn arrives at 84 h, window closes 48 h
+    // after — beyond that the boat is reading the next waypoint's data
+    assert.equal(second[second.length - 1], 132);
+  });
+
+  test("hourly steps collapse to 3-hourly past the first day of the window", () => {
+    const waypoints = [
+      {
+        distanceFromStartNm: 0,
+        forecasts: Array.from({ length: 168 }, (_, h) => step(h)),
+      },
+    ];
+    throttleWaypointForecasts(waypoints, FETCH);
+    const stamps = waypoints[0].forecasts.map((f) =>
+      Math.round((Date.parse(f.timestamp) - Date.parse(FETCH)) / HOUR),
+    );
+    // The departure waypoint's window closes 48 h after its
+    // (immediate) arrival: 24 hourly steps, then every third hour
+    assert.equal(stamps.length, 24 + (48 - 24) / 3 + 1);
+    assert.equal(stamps[stamps.length - 1], 48);
+    for (let i = 24; i < stamps.length - 1; i++) {
+      assert.equal(stamps[i] % 3, 0);
+    }
+  });
+
+  test("a guaranteed minimum span survives a wildly slow boat", () => {
+    // 420 nm: the slow-bracket arrival (2.5 kn) sits past the 168 h
+    // horizon, so the window rides the whole horizon's tail — plenty
+    // of coverage either way, and the last step must survive decimation
+    const waypoints = [
+      {
+        distanceFromStartNm: 420,
+        forecasts: Array.from({ length: 168 }, (_, h) => step(h)),
+      },
+    ];
+    throttleWaypointForecasts(waypoints, FETCH);
+    const stamps = waypoints[0].forecasts.map((f) =>
+      Math.round((Date.parse(f.timestamp) - Date.parse(FETCH)) / HOUR),
+    );
+    assert.ok(stamps.length >= 16, "at least two days' 3-hourly coverage");
+    assert.equal(stamps[stamps.length - 1], 167);
+  });
+
+  test("short fixtures pass through unchanged", () => {
+    const forecasts = [step(0), step(1)];
+    const waypoints = [{ distanceFromStartNm: 0, forecasts }];
+    throttleWaypointForecasts(waypoints, FETCH);
+    assert.equal(waypoints[0].forecasts.length, 2);
+  });
+
+  test("roughly a quarter of the original payload remains on a week-long route", () => {
+    // 15 waypoints, 30 nm apart, 7-day horizon: the shape behind the
+    // 1.3 MB briefing
+    const waypoints = Array.from({ length: 15 }, (_, i) => ({
+      distanceFromStartNm: i * 30,
+      forecasts: Array.from({ length: 168 }, (_, h) => step(h)),
+    }));
+    const before = waypoints.reduce((sum, wp) => sum + wp.forecasts.length, 0);
+    throttleWaypointForecasts(waypoints, FETCH);
+    const after = waypoints.reduce((sum, wp) => sum + wp.forecasts.length, 0);
+    assert.ok(after <= before * 0.35, `${after} of ${before} steps remain`);
+    for (const wp of waypoints) {
+      assert.ok(wp.forecasts.length > 0, "no waypoint stripped bare");
+    }
+  });
+});
+
 describe("fetchWeatherAlongTrack", () => {
   test("builds the SPEC §3.1 payload with unit conversions", async () => {
     const payload = await fetchWeatherAlongTrack({

package/tests/plugin.test.js

@@ -2687,3 +2687,31 @@ test("routes listing: cached with stale-while-revalidate, distances active-only"
   assert.equal(listCalls, 1);
   plugin.stop();
 });
+
+test("active hazard notifications serve from the plugin's own endpoint", async () => {
+  // Work doc #30 webapp transport: the escalation's active list rides
+  // GET /api/hazards/active (200 with an empty list when nothing is
+  // active) — polling the Signal K REST notifications subtree instead
+  // 404'd whenever no notification had ever been raised
+  const app = createMockApp();
+  const plugin = pluginFactory(app);
+  plugin.start({});
+  plugin.registerWithRouter(app.router);
+  const route = app.getRoutes().find((r) => r.path === "/api/hazards/active");
+  assert.ok(route, "hazards/active route registered");
+  const res = {
+    code: null,
+    payload: null,
+    status(code) {
+      this.code = code;
+      return this;
+    },
+    json(payload) {
+      this.payload = payload;
+    },
+  };
+  await route.handler({}, res);
+  assert.equal(res.code, null);
+  assert.deepEqual(res.payload, { notifications: [] });
+  plugin.stop();
+});