@meri-imperiumi/signalk-dead-reckoning 0.11.2 → 0.12.0

package/CHANGELOG.md

@@ -7,6 +7,116 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-09-21
+
+### Added
+- **Chartplotter UX (work doc #30, north-up phase):** the DR webapp
+  navigates like a plotter, not a map viewer:
+  - **Own-ship boat glyphs** replace the GPS dot and the bare DR X —
+    a pointed-hull vessel shape rotated to COG (GPS) and to the DR
+    course (DR), the navigator's X kept as a small detail inside the
+    DR hull. Dot/X fallbacks when course is unknown.
+  - **10-minute predictor vectors** (layers control, "Vectors"): a
+    dashed COG×SOG line from the GPS position and a DR-course×DR-speed
+    line from the DR position, with tick marks at 2-minute intervals;
+    the AIS velocity leader extends from the 6-minute to the same
+    10-minute convention so every predictor on the chart reads as one
+    family.
+  - **Nautical scale bar** (bottom-left): a custom control snapped to
+    a 0.1–1000 NM ladder (80–200 px band), metric fallback at deep
+    zooms; no `1:x` numeric readout.
+  - **Range rings** (layers control, "Range rings"): three
+    concentric rings centered on the GPS position, spacing derived
+    from the zoom ladder, re-spaced on zoom.
+  - **Wind laylines** (layers control, "Laylines"): two rays from the
+    DR vessel at TWD ± beat/gybe angle (the polar performance plugin's
+    angles — the established feed), port tack red / starboard green
+    per the navigation-light convention, fixed screen-relative length.
+    Gated honestly: renders only while `navigation.state` is
+    `sailing`, and only when true wind and the angle this point of
+    sail needs are actually published.
+  - **Pick menu is now the target surface:** every pick shows bearing
+    & distance from BOTH own-ship references (DR and GPS — the
+    most-wanted helm readout, absent-source rows hidden); AIS picks
+    add the target details panel (type, flag, dimensions, destination
+    & ETA — Freeboard-SK's field set, new static paths in the AIS
+    subscription folded into the store) plus **CPA/TCPA for both
+    references** (DR-based = conservative, GPS-based = conventional);
+    a target closing inside the CPA watch limits (0.5 nm / 20 min)
+    turns its glyph red and carries the CPA figure in its tooltip.
+  - **Measure tool** ("Measure from here…" in the pick menu): tap
+    points, get true bearing + distance leg by leg with a running
+    total in a floating readout; double-click / right-click / Esc ends.
+  - **Signal K notes on the chart**: positioned notes from the v2
+    resources API render as orange pin markers on a toggleable
+    "Notes" layer; clicking/right-clicking opens the detail surface
+    (title, body rendered per mimeType with a minimal safe markdown
+    renderer, timestamp, DR/GPS bearings, all pick actions). The pick
+    menu gains "New note at…" — a one-handed hazard-marking form
+    (Hazard preset, position pre-seeded) that POSTs to the v2
+    resources API, with edit/delete from the note's menu and refetch
+    on stream reconnect. Failed writes surface in the form, never
+    silently.
+
+- **Fixes over a day old carry their date on the chart** —
+  "Fix 18.9. 02:36Z" instead of the ambiguous "Fix 02:36Z". With the
+  new 7-day history window most fixes on the chart aren't from
+  today, so the time alone no longer identifies the fix. Under 24 h
+  the label is unchanged.
+- **History-aware chart window: tracks, overlays and trip
+  boundaries.** The webapp now shows the last
+  `max(7 days, since trip start)` on the chart instead of nothing:
+  both the GPS track and the DR ghost track backfill from the Signal K
+  History API over the window (10-minute resolution — ~1000 points per
+  track on a full week), and the persisted chartwork overlays (fixes,
+  LOPs, CPLs, snap vectors) are window-filtered via a new `since`
+  query parameter on the REST endpoints (`/fixes`, `/observations`,
+  `/corrections`; ISO-8601 or epoch ms, invalid values ignored).
+  Two bugs fixed on the way: the DR track backfill silently never
+  worked — the history provider emits plugin-published positions as
+  `{latitude, longitude}` objects where the parser only accepted
+  GeoJSON `[lon, lat]` pairs — and the 6-hour fetch window was
+  replaced by the proper window.
+- **Trip log now actually resets at trip boundaries (SPEC §9.2).**
+  `engine.resetTrip()` existed but nothing ever called it, so
+  `navigation.deadReckoning.trip.log` accumulated since install (the
+  production log read 703 nm — more than the last two trips
+  combined). A sustained `navigation.state` transition from
+  `anchored`/`moored` to underway (5-minute debounce, configurable
+  via `tripBoundary.sustainS`/`clearS`) now zeroes the trip log and
+  records the trip start, which is persisted across restarts
+  (mid-trip server restarts keep the boundary) and exposed via
+  GET /status as `tripStartMs` — the webapp uses it to anchor its
+  history window. A flapping autostate source can't zero the log:
+  blips shorter than the debounce are ignored.
+- **The headline log figure is now the trip log.** The bottom-right
+  readout shows `navigation.deadReckoning.trip.log` ("Trip log")
+  instead of the cumulative water-track log — the watchkeeper's
+  glance figure is distance-since-departure; the cumulative total
+  rides along as the figure's hover tooltip. Falls back to the
+  cumulative log until a first trip boundary is ever observed.
+
+### Fixed
+- **Hosted plotter widgets showed as empty black squares with no
+  data** (sea trial 2026-09-21). Two independent bugs, both in the
+  widget host, both reproducible with a locally served webapp against
+  a stub Signal K server:
+  - The bus port captured the widget iframe's `contentWindow` at
+    context creation — but a browser replaces that Window object when
+    the frame navigates from `about:blank` to its `src` (and the
+    frame is still detached, window `null`, when the context is
+    created). Every message from the loaded widget was silently
+    dropped: the handshake never completed and the tile sat on its
+    placeholder grid. The port now resolves the live window per
+    message (`liveWindowPort`).
+  - A placement restored from layout storage (page reload) rendered
+    an empty dark cell forever: the area element renders its cells
+    before discovery has created the widget contexts, and the iframe
+    was only adopted at cell creation. Adoption is now idempotent —
+    every render adopts a context's iframe into its cell unless it's
+    already home (never re-parenting a live iframe, which would
+    reload it).
+
 ## [0.11.2] - 2026-09-21
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meri-imperiumi/signalk-dead-reckoning",
-  "version": "0.11.2",
+  "version": "0.12.0",
   "description": "Offline-first dead reckoning and sensor fusion engine for Signal K",
   "main": "plugin/index.js",
   "scripts": {

package/plugin/db.js

@@ -654,10 +654,14 @@ function dequeueLogbookPending(db, pendingId) {
 
 /**
  * Lists recent confirmed fixes for the UI (SPEC §14.1 fix points).
+ * The webapp's history window filters via `sinceMs` (epoch ms): rows
+ * older than the boundary are left out so the chart shows current
+ * chartwork, not everything since install.
  *
  * @param {import("node:sqlite").DatabaseSync} db
  * @param {object} [q]
  * @param {number} [q.limit=100]
+ * @param {number|null} [q.sinceMs] - include rows at/after this epoch ms
  * @returns {Array<object>} newest-first
  */
 function listFixes(db, q = {}) {
@@ -666,9 +670,35 @@ function listFixes(db, q = {}) {
       `SELECT fix_id, timestamp, source_type, latitude, longitude,
               estimated_error_radius, confirmed_by, resets_dr_origin,
               derived_from_fix_id
-       FROM fixes ORDER BY fix_id DESC LIMIT ?`,
+       FROM fixes ${sinceClause(q)} ORDER BY fix_id DESC LIMIT ?`,
     )
-    .all(q.limit ?? 100);
+    .all(...sinceArgs(q), q.limit ?? 100);
+}
+
+/**
+ * WHERE fragment for the optional `sinceMs` window filter, shared by
+ * the overlay list queries — fixes, LOPs, CPLs and corrections all
+ * carry the same ISO-8601 `timestamp` column. Compares via julianday()
+ * rather than string comparison: stored timestamps vary in shape
+ * (`…00Z` vs `…00.001Z` vs `…00.000Z`), and lexicographic order is
+ * wrong across those shapes (a bare `Z` sorts AFTER a fraction).
+ *
+ * @param {object} q - the query options carrying `sinceMs`
+ * @returns {string} "" or the WHERE clause (args from sinceArgs)
+ */
+function sinceClause(q) {
+  return q.sinceMs != null ? "WHERE julianday(timestamp) >= julianday(?)" : "";
+}
+
+/**
+ * Positional args matching {@link sinceClause}; callers pass them to
+ * .all() BEFORE the limit.
+ *
+ * @param {object} q
+ * @returns {Array<unknown>}
+ */
+function sinceArgs(q) {
+  return q.sinceMs != null ? [new Date(q.sinceMs).toISOString()] : [];
 }
 
 /**
@@ -709,10 +739,12 @@ function getCircularPositionLine(db, id) {
 
 /**
  * Lists persisted lines of position for the UI (SPEC §14.1 LOP overlay).
+ * `sinceMs` window-filters as in listFixes.
  *
  * @param {import("node:sqlite").DatabaseSync} db
  * @param {object} [q]
  * @param {number} [q.limit=100]
+ * @param {number|null} [q.sinceMs]
  * @returns {Array<object>} newest-first
  */
 function listLinesOfPosition(db, q = {}) {
@@ -720,9 +752,9 @@ function listLinesOfPosition(db, q = {}) {
     .prepare(
       `SELECT lop_id, timestamp, lop_type, assumed_lat, assumed_lon,
               azimuth_true, intercept_nm, body_or_object, used_in_fix_id
-       FROM lines_of_position ORDER BY lop_id DESC LIMIT ?`,
+       FROM lines_of_position ${sinceClause(q)} ORDER BY lop_id DESC LIMIT ?`,
     )
-    .all(q.limit ?? 100);
+    .all(...sinceArgs(q), q.limit ?? 100);
 }
 
 /**
@@ -732,6 +764,7 @@ function listLinesOfPosition(db, q = {}) {
  * @param {import("node:sqlite").DatabaseSync} db
  * @param {object} [q]
  * @param {number} [q.limit=100]
+ * @param {number|null} [q.sinceMs]
  * @returns {Array<object>} newest-first
  */
 function listCircularPositionLines(db, q = {}) {
@@ -739,18 +772,20 @@ function listCircularPositionLines(db, q = {}) {
     .prepare(
       `SELECT cpl_id, timestamp, center_lat, center_lon, radius_nm,
               source_object, used_in_fix_id
-       FROM circular_position_lines ORDER BY cpl_id DESC LIMIT ?`,
+       FROM circular_position_lines ${sinceClause(q)} ORDER BY cpl_id DESC LIMIT ?`,
     )
-    .all(q.limit ?? 100);
+    .all(...sinceArgs(q), q.limit ?? 100);
 }
 
 /**
  * Lists recent snap-to-fix corrections for the UI (SPEC §9.3/§14.1 —
  * dashed vector from pre-snap ghost position to confirmed fix).
+ * `sinceMs` window-filters as in listFixes.
  *
  * @param {import("node:sqlite").DatabaseSync} db
  * @param {object} [q]
  * @param {number} [q.limit=20]
+ * @param {number|null} [q.sinceMs]
  * @returns {Array<object>} newest-first
  */
 function listCorrections(db, q = {}) {
@@ -759,9 +794,9 @@ function listCorrections(db, q = {}) {
       `SELECT correction_id, timestamp, dr_lat, dr_lon, fix_lat, fix_lon,
               deviation_nm, deviation_bearing, dr_elapsed_seconds,
               sail_state, sea_state
-       FROM dr_corrections ORDER BY correction_id DESC LIMIT ?`,
+       FROM dr_corrections ${sinceClause(q)} ORDER BY correction_id DESC LIMIT ?`,
     )
-    .all(q.limit ?? 20);
+    .all(...sinceArgs(q), q.limit ?? 20);
 }
 
 // -------------------------------------------------------------------------

package/plugin/index.js

@@ -323,6 +323,18 @@ const DEFAULT_CONFIG = {
     sustainS: 10,
     clearS: 10,
   },
+  /**
+   * Trip-boundary hysteresis (SPEC §9.2): how long navigation.state
+   * must STAY underway (leaving moored/anchored) before the transition
+   * counts as a trip start and resets the trip log. Longer than the
+   * sensor-health windows on purpose — untying, anchor aweigh and
+   * lunch stops all bounce the state for a few minutes — long enough
+   * that only real departure zeroes the trip log.
+   */
+  tripBoundary: {
+    sustainS: 300,
+    clearS: 300,
+  },
   /**
    * §3.1 inertial-polar fallback (work doc #18): running-average window
    * and staleness cutoff for the polar speed — both the
@@ -610,6 +622,27 @@ module.exports = (app) => {
   /** @type {number|null} monotonic seconds counter for the training loop */
   let clockS = 0;
 
+  /**
+   * Trip boundary tracking (SPEC §9.2): the debounced moored/anchored
+   * → underway transition resets the trip log and records the trip
+   * start. Debounced symmetric hysteresis (createFlagState/flagTick)
+   * so a flapping autostate source can't zero the trip log spuriously.
+   * `raw` is this tick's underway verdict; the flag RAISES on the
+   * sustained underway edge and never drops mid-trip — the boundary
+   * event is the transition INTO a trip, not the trip's end.
+   * @type {ReturnType<typeof createFlagState>|null}
+   */
+  let tripFlag = null;
+
+  /**
+   * Trip start timestamp (ms) of the current/last trip — persisted in
+   * dr_state_store so a mid-trip restart keeps the boundary (and the
+   * webapp's history window: max(7 days, since trip start)). Null when
+   * no boundary has ever been observed.
+   * @type {number|null}
+   */
+  let tripStartMs = null;
+
   /** @type {ReturnType<typeof createDivergenceState>|null} §7.3 divergence monitor */
   let divergence = null;
 
@@ -859,6 +892,10 @@ module.exports = (app) => {
         ...DEFAULT_CONFIG.sensorHealth,
         ...(opts.sensorHealth ?? {}),
       };
+      config.tripBoundary = {
+        ...DEFAULT_CONFIG.tripBoundary,
+        ...(opts.tripBoundary ?? {}),
+      };
       config.logbook = {
         ...DEFAULT_CONFIG.logbook,
         ...(opts.logbook ?? {}),
@@ -955,6 +992,14 @@ module.exports = (app) => {
       shadowGate = deps.createPublishGate({
         everyTicks: config.publish.everyTicks,
       });
+      // Trip boundary tracking (SPEC §9.2): fresh debounce state per
+      // start; the trip start itself survives restarts via dr_state_store
+      // so the webapp's history window keeps the trip boundary across a
+      // mid-trip restart.
+      tripFlag = deps.createFlagState();
+      const savedTripStartMs = Number(deps.getState(db, "dr_trip_start_ms"));
+      tripStartMs = Number.isFinite(savedTripStartMs) ? savedTripStartMs : null;
+
       polarState = deps.createPolarSpeedState();
       polarModel = null;
       polarLoadedId = null;
@@ -1461,6 +1506,30 @@ module.exports = (app) => {
     const navState = deltaState.get("navigation.state");
     const underway = navState !== "anchored" && navState !== "moored";
 
+    // Trip boundary (SPEC §9.2): a sustained moored/anchored → underway
+    // transition starts a trip — resets the trip log and records the
+    // start. The flag raises once on the sustained edge and never drops
+    // (a trip ends at the NEXT raise, not on the underway→moored edge),
+    // so an afternoon of anchoring for lunch doesn't zero the log. Only
+    // a reset that actually moves the count is recorded — restarting
+    // underway (no prior observed boundary) must not fabricate one.
+    const tripEdge = deps.flagTick(
+      tripFlag,
+      underway,
+      config.tickIntervalMs / 1000,
+      config.tripBoundary,
+    );
+    if (tripEdge.transition === "raise") {
+      if (engine.tripLogNm > 0) {
+        engine.resetTrip();
+        tripStartMs = Date.now();
+        deps.setState(db, "dr_trip_start_ms", String(tripStartMs));
+        app.debug(
+          `Trip boundary: navigation.state sustained underway — trip log reset, trip started ${new Date(tripStartMs).toISOString()}`,
+        );
+      }
+    }
+
     // GPS-derived motion (independent of the water-track sensors):
     // updated every tick, used to detect "idle but making way" below.
     updateGpsMotion(gps);
@@ -2725,6 +2794,11 @@ module.exports = (app) => {
     }
     deps.setState(db, "dr_log_nm", String(engine.logNm));
     deps.setState(db, "dr_trip_log_nm", String(engine.tripLogNm));
+    // Trip boundary (SPEC §9.2) survives restarts: persisted at the
+    // boundary tick AND on every flush (the boundary itself can't be
+    // re-derived — a restart mid-trip sees only "underway").
+    if (tripStartMs != null)
+      deps.setState(db, "dr_trip_start_ms", String(tripStartMs));
     deps.setState(db, "dr_log_since_origin", String(engine.logNmSinceOrigin));
     // Sea trial 2026-09-06: elapsed time drives the current-knowledge
     // term of the uncertainty cone — a restart must not zero it, or the
@@ -2746,6 +2820,25 @@ module.exports = (app) => {
 
   // --- REST API ----------------------------------------------------------
 
+  /**
+   * Parses the optional `since` query parameter (ISO-8601 string or
+   * epoch ms) of the overlay endpoints into the db layer's `sinceMs`
+   * option. Invalid values are ignored (unfiltered) — the window is a
+   * display concern, never a reason to 4xx the chart.
+   *
+   * @param {object} req - Express request
+   * @returns {{sinceMs?: number}}
+   */
+  function sinceOpt(req) {
+    const raw = req.query?.since;
+    if (raw == null || raw === "") return {};
+    const n = Number(raw);
+    if (Number.isFinite(n) && n > 0) return { sinceMs: n };
+    const t = Date.parse(String(raw));
+    if (Number.isFinite(t)) return { sinceMs: t };
+    return {};
+  }
+
   /**
    * Registers REST routes on the plugin router.
    *
@@ -2766,6 +2859,9 @@ module.exports = (app) => {
         origin: engine.origin,
         logNm: engine.logNm,
         tripLogNm: engine.tripLogNm,
+        // SPEC §9.2 trip boundary (null when none observed yet): the
+        // webapp's history window is max(7 days, since trip start).
+        tripStartMs,
         elapsedSinceOriginS: engine.elapsedSinceOriginS,
         underwaySinceOriginS: engine.underwaySinceOriginS,
         binCount: matrix.count(),
@@ -2794,8 +2890,9 @@ module.exports = (app) => {
     });
 
     /**
-     * GET /fixes — recent confirmed fixes for the map overlay (SPEC
-     * §14.1 fix points). `limit` caps the result (default 100).
+     * GET /fixes — confirmed fixes for the map overlay (SPEC §14.1 fix
+     * points). `limit` caps the result (default 100); `since` (ISO-8601
+     * or epoch ms) window-filters to the webapp's history window.
      */
     router.get("/fixes", (req, res) => {
       if (!engine || !db) {
@@ -2806,13 +2903,14 @@ module.exports = (app) => {
         1,
         Math.min(1000, Number(req.query?.limit) || 100),
       );
-      res.json({ fixes: deps.listFixes(db, { limit }) });
+      res.json({ fixes: deps.listFixes(db, { limit, ...sinceOpt(req) }) });
     });
 
     /**
      * GET /observations — persisted LOPs and CPLs for the map overlay
      * (SPEC §14.1 geometric primitives). Unused/unresolved observations
      * (used_in_fix_id IS NULL) are marked so the UI can emphasize them.
+     * `since` window-filters to the webapp's history window.
      */
     router.get("/observations", (req, res) => {
       if (!engine || !db) {
@@ -2823,15 +2921,17 @@ module.exports = (app) => {
         1,
         Math.min(1000, Number(req.query?.limit) || 100),
       );
+      const since = sinceOpt(req);
       res.json({
-        lops: deps.listLinesOfPosition(db, { limit }),
-        cpls: deps.listCircularPositionLines(db, { limit }),
+        lops: deps.listLinesOfPosition(db, { limit, ...since }),
+        cpls: deps.listCircularPositionLines(db, { limit, ...since }),
       });
     });
 
     /**
      * GET /corrections — recent snap-to-fix corrections for the dashed
-     * vector overlay (SPEC §9.3, §14.1).
+     * vector overlay (SPEC §9.3, §14.1). `since` window-filters to the
+     * webapp's history window.
      */
     router.get("/corrections", (req, res) => {
       if (!engine || !db) {
@@ -2839,7 +2939,9 @@ module.exports = (app) => {
         return;
       }
       const limit = Math.max(1, Math.min(200, Number(req.query?.limit) || 20));
-      res.json({ corrections: deps.listCorrections(db, { limit }) });
+      res.json({
+        corrections: deps.listCorrections(db, { limit, ...sinceOpt(req) }),
+      });
     });
 
     /**