signalk-pypilot-newui 2.9.0 → 2.10.0

package/CHANGELOG.md

@@ -1,5 +1,103 @@
 # Changelog
 
+## 2.10.0 — 2026-09-27 — Sea-trial wind-mode fixes + maneuver forensics
+
+Rolls up Rev309 through Rev323. Between 2.9.0 (Rev280) and 2.10.0 the
+plugin absorbed a sea trial (2026-09-25) that surfaced several critical
+gaps in the wind-mode workflow, plus a new forensics module so future
+sea trials can be audited offline.
+
+### Added
+
+- **Maneuver Trace Log** (Rev322, opt-in). Every user-driven action from
+  the visor — aproado / empopado pick, tack tap, mode change, target PUT,
+  engage / disengage — is recorded together with pypilot state right
+  before the command AND 300 ms after. Pair pre/post makes it trivial
+  to answer "did the pilot actually obey?". Files land as JSONL under
+  `<plugin data dir>/maneuver-trace/`. New endpoints:
+  `GET|POST /maneuver-trace/{status,start,stop,event}` +
+  `GET /maneuver-trace/tail?n=N`. Setup card "Maneuver trace
+  (sea-trial forensics)" toggles it on the fly, off by default.
+- **Empopado pseudo-mode** (Rev313 → Rev320) — mirror of Aproado for the
+  other extreme: bring the boat to TWA ≈ 180° so the mainsail flogs the
+  least while striking sail. Full HUD (choosing → transit → active),
+  hot gains at latch (P × 1.5, D × 1.7, servo slew × 1.3), audible
+  warning when `|TWA| < 160°` sustained 1 s ("empopado inestable"),
+  auto-cancel when `|TWA| < 140°` sustained 2.5 s. Restore in order
+  hot gains → profile → mode → target → engaged on SALIR / cancel.
+- **Attitude safety alarms** (Rev299 / I1) — `attitude-heel-extreme` and
+  `attitude-pitch-extreme` rules with configurable thresholds
+  (`alarmAttitudeHeelDeg`, `alarmAttitudePitchDeg`), off by default so
+  a fresh install never disarms on the dock.
+- **Roll feed-forward** (Rev282+) and **Post-tack catch-up** (Rev299)
+  publish diagnostic paths under
+  `steering.autopilot.pypilot.tuning.rollFf.*` and `.tackCatchup.*`.
+  Both are currently `appliedToAp: false` — computed and observable
+  but not yet fed to the pilot; a later release flips the switch after
+  sea trial validation.
+- **Leeway estimator** (Rev298 / H4) publishing
+  `steering.autopilot.pypilot.derived.leewayRad` from the classical
+  `drift_deg = adj * heel_deg / bsp_kn²` formula. Opt-in via
+  `leewayAdjustment > 0`, kept off the canonical `performance.leeway`
+  path so it never overwrites `signalk-derived-data`.
+- **Failsafe boat speed** (Rev299 / H2) — when both BSP and SOG go
+  missing, the plugin injects a configurable knots value so downstream
+  wind / leeway calculations keep producing plausible numbers.
+- **Profile default persistence fix** (Rev310) — opening the visor from
+  a second device no longer silently overwrites the pypilot profile with
+  `default`; the select is now primed from the HTTP snapshot before the
+  WebSocket delta arrives.
+
+### Fixed (critical — from the 2026-09-25 sea trial)
+
+- **Tack in wind mode** (Rev309) — pressing VIRAR to a specific side now
+  reliably rotates the bow to that side, even when the "short arc" would
+  go the other way. Root cause: `planned = -refRad` in the countdown
+  path was ignoring the sign; now `_tackCountdownToExecuting` delegates
+  to `ap.tack.direction` + `ap.tack.state=begin` so pypilot honours the
+  band the sailor chose.
+- **Aproado without countdown** (Rev311) — pressing POR PROA / POR POPA
+  starts the maneuver on the same tap (previously 5 s delay). Sustain
+  3 s for the "achieved" latch avoids false positives on brief AWA
+  oscillations.
+- **Alarm silence during maneuvers** (Rev311 → Rev312 → Rev323) — the
+  `heading-deviation`, `cruise-drift` and `unable-to-steer` rules now
+  respect both pypilot's own `ap.tack.state != "none"` AND a visor-side
+  pseudo-mode flag posted to `POST /maneuver-state` when Aproado /
+  Empopado are running. Independent flag needed because pypilot does
+  not always update `ap.tack.state` when the sailor uses one of the
+  pseudo-modes.
+- **Heading-deviation false positives in wind mode** (Rev323) —
+  threshold raised to 35° and sustain to 30 s when the pilot mode is
+  `wind` / `true wind`. In waves and gusts the AWA target legitimately
+  oscillates ±20-30° while the AP is still correcting; the 20°/15 s
+  default of compass mode was disarming the alarm several times per
+  hour on Tunatunes.
+- **Tack countdown stability close-out** (Rev312) — if the tack overshoots
+  the plan but the boat is clearly settled (rate-of-turn < 3°/s for 2 s),
+  the overlay closes on its own instead of counting up to the 120 s
+  timeout.
+
+### Changed
+
+- **Alarms OFF by default** (Rev317) — a fresh install no longer arms
+  every rule; the sailor opts in via Setup → Alarms. Pre-Rev299 installs
+  keep legacy behaviour (undefined = all-on) so nothing changes silently
+  under an existing boat.
+- **Terminology cleanup** (Rev321) — all references to third-party
+  autopilot brands / dashboards in code, comments, docs, UI hints and
+  package metadata have been rewritten as neutral descriptions of the
+  mechanism ("downstream Signal K clients", "wind-response damping
+  bands", "classical heel-over-speed² formula"). No behavioural change.
+- **Tablet vertical crop hardening** (Rev314) — `100vh` → `100dvh` in
+  every fullscreen modal, `-webkit-overflow-scrolling: touch`, safe-area
+  padding. Fixes bottom-of-card clipping on Android tablets in portrait.
+
+### Removed
+
+- `docs/PROMPT_FOR_LLM_maneuver_catalog.md` — obsolete Rev209 audit
+  prompt, superseded by the current tack design.
+
 ## 2.9.0 — 2026-09-23 — Relicensed to AGPL-3.0-or-later
 
 ### License change (see NOTICE for details)

package/README.md

@@ -3,12 +3,12 @@
 **This plugin enhances and extends the magic of [pypilot](https://github.com/pypilot/pypilot)**,
 Sean D'Epagnier's open-source autopilot, with more functions, a modern
 touch-first user experience on tablets and phones, first-class
-**Signal K integration** so tools like [KIP](https://kip.signalk.org),
-WilhelmSK and freeboard can drive and monitor the autopilot out of the
-box, and a strong focus on **reliability, ease of use and ease of
-tuning**: the plugin itself watches how your autopilot is behaving and
-quietly suggests how to sharpen its settings, so you spend more time
-sailing and less time guessing which slider to move.
+**Signal K integration** so any downstream Signal K client can drive
+and monitor the autopilot out of the box, and a strong focus on
+**reliability, ease of use and ease of tuning**: the plugin itself
+watches how your autopilot is behaving and quietly suggests how to
+sharpen its settings, so you spend more time sailing and less time
+guessing which slider to move.
 
 Runs alongside [`pypilot-autopilot-provider`](https://www.npmjs.com/package/pypilot-autopilot-provider)
 by Panaaj — see [Working alongside pypilot-autopilot-provider](#working-alongside-pypilot-autopilot-provider).
@@ -78,8 +78,8 @@ by Panaaj — see [Working alongside pypilot-autopilot-provider](#working-alongs
 18. **Alarm engine — 9 rules** — heading deviation, cruise drift,
     unable-to-steer, servo overcurrent, servo temp, motor temp, high
     AP load, low voltage, sensor lost, pypilot disconnected — all
-    published as canonical `notifications.autopilot.*` for KIP /
-    WilhelmSK.
+    published as canonical `notifications.autopilot.*` for any
+    downstream Signal K client.
 19. **Head-to-wind pseudo-mode** — a "raise the sails" mode not
     present in pypilot, with countdown and bow / stern swing
     selection.
@@ -112,16 +112,16 @@ by Panaaj — see [Working alongside pypilot-autopilot-provider](#working-alongs
     stored as JSONL with tags (wind, sea state, propulsion, point of
     sail, crew), shareable for advice.
 28. **Full Signal K path catalog viewer** in the visor with
-    copy-to-clipboard for KIP.
+    copy-to-clipboard for downstream widgets.
 
 ### Signal K integration — 8 new added functions
 
 29. **~110 Signal K paths** under `steering.autopilot.pypilot.*`,
     opt-in per path so you never flood the bus.
-30. **Autopilot API v2 provider** (absorbable) — WilhelmSK,
-    freeboard and KIP talk to this plugin as the canonical
+30. **Autopilot API v2 provider** (absorbable) — any downstream
+    Signal K autopilot client talks to this plugin as the canonical
     autopilot.
-31. **KIP action paths** — Simple Switch for engage, nudge, tack,
+31. **Simple Switch action paths** — engage, nudge, tack,
     mode selector, profile selector.
 32. **9 momentary switches** — nudge ±10 / ±1, tack port / starboard
     / cancel — as KIP boolean paths.
@@ -152,8 +152,8 @@ history.
 2.0.0 is a **breaking release** addressing feedback from Sean D'Epagnier
 (pypilot author). Every pypilot key now maps 1:1 to
 `steering.autopilot.pypilot.<key>` verbatim - no more hand-picked renames
-or C -> K / deg -> rad conversions. If you have KIP widgets or WilhelmSK
-dashboards wired to 1.0.0 paths, see the full migration table in
+or C -> K / deg -> rad conversions. If you have Signal K dashboards
+wired to 1.0.0 paths, see the full migration table in
 [`CHANGELOG.md`](./CHANGELOG.md) - most notable examples:
 
 - `.servo.controllerTemperature` (K) -> `.servo.controller_temp` (C)
@@ -241,7 +241,7 @@ We build on top of the excellent
 [`pypilot-autopilot-provider`](https://www.npmjs.com/package/pypilot-autopilot-provider)
 by Panaaj — the plugin that gives Signal K the standard
 **Autopilot API v2** surface (`/signalk/v2/api/vessels/self/autopilots/*`) so
-WilhelmSK, freeboard and other clients can drive pypilot through the canonical
+any downstream Signal K autopilot client can drive pypilot through the canonical
 interface. Panaaj focuses tightly on that API and opens its own socket.io
 connection to `pypilot_web`.
 
@@ -260,7 +260,7 @@ register the same ID and behaviour is undefined). Valid setups:
 | Enabled | Off (default) | Both run happily side by side. Panaaj owns the AP v2 API; this plugin adds the extra paths + UI. **2 sockets** to `pypilot_web`. |
 | Disabled | **On** | Only this plugin. Same AP v2 API + all the extras. **1 socket**. Handy on Pi Zero W. |
 | Enabled | On | Both try to register the same AP ID — leave one off. |
-| Disabled | Off | WilhelmSK / freeboard / KIP won't see the AP. Only useful if you exclusively use this plugin's own webapp. |
+| Disabled | Off | No downstream Signal K client will see the AP. Only useful if you exclusively use this plugin's own webapp. |
 
 Absorb mode lives in **Setup → Autopilot Provider (one-socket mode)**.
 

package/dist/alarms.js

@@ -12,10 +12,10 @@
 //   - Rules never share state - a rule that says "true" this tick can
 //     later say "false" without any cleanup dance.
 //   - Every fire increments a per-rule counter used to add jitter to
-//     the emitted notification timestamp, so KIP/WilhelmSK never
-//     collapse two consecutive alerts into one.
+//     the emitted notification timestamp, so downstream SK clients
+//     never collapse two consecutive alerts into one.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AlarmEngine = exports.DEFAULT_RULES = exports.RULE_PYPILOT_DISC_SEC = exports.RULE_RUDDER_TRIM_RAD = exports.RULE_SERVO_TRIM_FRAC = exports.RULE_LOW_VOLTAGE_V = exports.RULE_SERVO_TEMP_C = exports.RULE_SERVO_OVERCURR_A = exports.RULE_UNABLE_DUTY_MIN = exports.RULE_UNABLE_ERR_RAD = exports.RULE_HEADING_ERR_RAD = exports.DEFAULT_MOTOR_TEMP_C = void 0;
+exports.AlarmEngine = exports.RULE_ATTITUDE_PITCH_DEG = exports.RULE_ATTITUDE_HEEL_DEG = exports.DEFAULT_RULES = exports.RULE_PYPILOT_DISC_SEC = exports.RULE_RUDDER_TRIM_RAD = exports.RULE_SERVO_TRIM_FRAC = exports.RULE_LOW_VOLTAGE_V = exports.RULE_SERVO_TEMP_C = exports.RULE_SERVO_OVERCURR_A = exports.RULE_UNABLE_DUTY_MIN = exports.RULE_UNABLE_ERR_RAD = exports.RULE_HEADING_ERR_RAD = exports.DEFAULT_MOTOR_TEMP_C = void 0;
 const SEV_TO_SK = {
     info: "nominal",
     warn: "warn",
@@ -53,13 +53,35 @@ exports.DEFAULT_RULES = [
         label: "Heading deviation",
         severity: "warn",
         defaultEnabled: true,
-        sustainSec: 15,
-        description: `RMS heading error exceeds ${(exports.RULE_HEADING_ERR_RAD * 180 / Math.PI) | 0}° with the AP engaged.`,
+        // Rev323 (Carlos, 2026-09-27): sustain subido de 15 s a 30 s. Con
+        // 15 s cualquier ola grande / racha corta metía la RMS 20 s por
+        // encima del umbral y disparaba la alarma; 30 s filtra el ruido
+        // legítimo de un mar entrecortado sin perder la señal de un AP
+        // realmente descolgado.
+        sustainSec: 30,
+        description: `RMS heading error exceeds ${(exports.RULE_HEADING_ERR_RAD * 180 / Math.PI) | 0}° (compass) / 35° (wind) with the AP engaged.`,
         evaluate: (c) => {
             if (!c.kpis || !c.sample || !c.sample.engaged)
                 return false;
+            // Rev311: durante una maniobra nativa del pypilot silenciamos.
+            if (c.maneuverInProgress)
+                return false;
+            // Rev323 (Carlos, 2026-09-27): pseudo-modo visor-side (Aproado /
+            // Empopado) también silencia — el visor está pilotando la
+            // maniobra por su cuenta y el "error" que reporta pypilot es
+            // el gap intencionado durante el swing.
+            if (c.maneuverPseudoActive)
+                return false;
+            // Rev323 mode-aware threshold. En wind / true-wind el heading
+            // command es un AWA/TWA target, que oscila naturalmente ±20-30°
+            // en olas y ráfagas mientras el AP sí está corrigiendo. Subir
+            // el umbral en esos modos elimina el disparo por doquier que
+            // Carlos reportó 2026-09-27.
+            const mode = (c.sample.mode || "").toLowerCase();
+            const isWind = mode.includes("wind");
+            const threshold = isWind ? (35 * Math.PI / 180) : exports.RULE_HEADING_ERR_RAD;
             const r = c.kpis.window1m.rmsErrorRad;
-            return typeof r === "number" && r > exports.RULE_HEADING_ERR_RAD;
+            return typeof r === "number" && r > threshold;
         },
         message: (c) => {
             const r = c.kpis?.window1m.rmsErrorRad ?? 0;
@@ -81,6 +103,10 @@ exports.DEFAULT_RULES = [
         evaluate: (c) => {
             if (!c.kpis || !c.sample || !c.sample.engaged)
                 return false;
+            if (c.maneuverInProgress)
+                return false; // Rev311: silencio en maniobra
+            if (c.maneuverPseudoActive)
+                return false; // Rev323: idem pseudo-modo
             const mean = c.kpis.window1m.meanErrorRad;
             return typeof mean === "number" && Math.abs(mean) > (5 * Math.PI / 180);
         },
@@ -100,6 +126,10 @@ exports.DEFAULT_RULES = [
         evaluate: (c) => {
             if (!c.kpis || !c.sample || !c.sample.engaged)
                 return false;
+            if (c.maneuverInProgress)
+                return false; // Rev311: silencio en maniobra
+            if (c.maneuverPseudoActive)
+                return false; // Rev323: idem pseudo-modo
             const r = c.kpis.window1m.rmsErrorRad;
             const d = c.kpis.window1m.servoDutyPct;
             return typeof r === "number" && r > exports.RULE_UNABLE_ERR_RAD
@@ -213,9 +243,10 @@ exports.DEFAULT_RULES = [
     {
         // Rev156 (Carlos): ServoHealth already grades the drive as
         // learning/good/elevated/high on the deviation ratio (recent avg
-        // vs learned baseline). Surface "high" as a notification so KIP /
-        // WilhelmSK show the same red banner the visor card does. Only
-        // fires once the baseline is actually learned (deviation != null).
+        // vs learned baseline). Surface "high" as a notification so
+        // downstream SK clients show the same red banner the visor card
+        // does. Only fires once the baseline is actually learned
+        // (deviation != null).
         id: "servo-load-high",
         label: "Autopilot load high",
         severity: "warn",
@@ -318,7 +349,55 @@ exports.DEFAULT_RULES = [
             return `Pypilot desconectado desde hace ${tail}`;
         },
     },
+    // Rev299 (I1): attitude safety envelope. These rules watch what the
+    // sailor cares about — is the boat pinned on its side, is the bow
+    // buried — not just what the servo is doing. Both are opt-in
+    // (defaultEnabled=false) because a heavy-weather passage will trip
+    // them and we do not want a fresh install screaming across a
+    // deliberate rail-in-the-water broach. Thresholds live in
+    // AlarmThresholds so the sailor can tune per-boat.
+    {
+        id: "attitude-heel-extreme",
+        label: "Escora extrema",
+        severity: "warn",
+        defaultEnabled: false,
+        sustainSec: 5,
+        description: "Heel angle sostenido por encima del umbral configurado (por defecto 45°). Sirve como envoltura de seguridad: no reemplaza el criterio del navegante ni desengancha el piloto.",
+        evaluate: (c) => {
+            if (!c.sample || typeof c.sample.heel !== "number")
+                return false;
+            const thrDeg = c.thresholds?.attitudeHeelDeg ?? exports.RULE_ATTITUDE_HEEL_DEG;
+            return Math.abs(c.sample.heel) * 180 / Math.PI > thrDeg;
+        },
+        message: (c) => {
+            const heelDeg = Math.abs((c.sample?.heel ?? 0) * 180 / Math.PI);
+            const thrDeg = c.thresholds?.attitudeHeelDeg ?? exports.RULE_ATTITUDE_HEEL_DEG;
+            return `Escora ${heelDeg.toFixed(0)}° (umbral ${thrDeg}°)`;
+        },
+    },
+    {
+        id: "attitude-pitch-extreme",
+        label: "Cabeceo extremo",
+        severity: "warn",
+        defaultEnabled: false,
+        sustainSec: 3,
+        description: "Pitch (cabeceo) sostenido por encima del umbral configurado. Suele indicar embarque de proa o clavado en ola.",
+        evaluate: (c) => {
+            if (!c.sample || typeof c.sample.pitch !== "number")
+                return false;
+            const thrDeg = c.thresholds?.attitudePitchDeg ?? exports.RULE_ATTITUDE_PITCH_DEG;
+            return Math.abs(c.sample.pitch) * 180 / Math.PI > thrDeg;
+        },
+        message: (c) => {
+            const pitchDeg = Math.abs((c.sample?.pitch ?? 0) * 180 / Math.PI);
+            const thrDeg = c.thresholds?.attitudePitchDeg ?? exports.RULE_ATTITUDE_PITCH_DEG;
+            return `Cabeceo ${pitchDeg.toFixed(0)}° (umbral ${thrDeg}°)`;
+        },
+    },
 ];
+// Rev299 (I1): defaults for the attitude envelope.
+exports.RULE_ATTITUDE_HEEL_DEG = 45;
+exports.RULE_ATTITUDE_PITCH_DEG = 25;
 class AlarmEngine {
     constructor(rules = exports.DEFAULT_RULES, opts = {}) {
         this.rules = new Map();

package/dist/failsafe-bsp.js

@@ -0,0 +1,64 @@
+"use strict";
+// Fail-safe boat speed resolver.
+//
+// When both `navigation.speedThroughWater` (BSP) and
+// `navigation.speedOverGround` (SOG) disappear at the same time —
+// speedo cable snagged, GPS antenna covered by a sail, both plugin
+// providers dropped — several downstream calculations collapse:
+//
+//   - `environment.wind.speedTrue` needs BSP to subtract vessel motion
+//     from the masthead reading. Without BSP, `signalk-derived-data`
+//     stops emitting TWS and everything that depends on it (Doctor
+//     rules, wind KPIs, leeway estimator) goes null.
+//   - Our `performance.leeway` estimator (leeway.ts) divides by
+//     BSP squared and refuses to publish when BSP is null.
+//
+// The classical racing racks answer this with a configured "failsafe
+// boat speed" — a plausible value (typically 5–7 kn for a cruising
+// keelboat) that keeps the wind stack producing plausible numbers
+// while the sailor investigates. We adopt the same pattern.
+//
+// Ranking (highest priority first):
+//   1. Direct BSP.
+//   2. SOG as proxy (acceptable in calm current; a source of error
+//      when there is significant tide, but the alternative is a hole
+//      in the wind chain).
+//   3. Configured `failSafeBspKn` converted to m/s.
+//   4. null.
+//
+// The caller receives both the resolved value and a `source` label so
+// KPIs, Doctor, and the visor can tag any measurement that leans on
+// the failsafe. This is important: a TWS computed off a failsafe BSP
+// is a plausibility, not a measurement, and should not be graded like
+// a real one.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FailsafeBspResolver = void 0;
+const KN_PER_MS = 1.9438444924406046;
+const DEFAULTS = {
+    failSafeBspKn: 0,
+};
+class FailsafeBspResolver {
+    constructor(opts = {}) {
+        this.opts = { ...DEFAULTS, ...opts };
+    }
+    update(patch) {
+        this.opts = { ...this.opts, ...patch };
+    }
+    getOptions() { return this.opts; }
+    /** Pick a boat-speed value in m/s using the priority ladder.
+     *  Callers pass whatever they read from SK; null and NaN are both
+     *  treated as "missing". */
+    resolve(bspMs, sogMs) {
+        if (typeof bspMs === "number" && Number.isFinite(bspMs) && bspMs >= 0) {
+            return { valueMs: bspMs, source: "bsp" };
+        }
+        if (typeof sogMs === "number" && Number.isFinite(sogMs) && sogMs >= 0) {
+            return { valueMs: sogMs, source: "sog" };
+        }
+        if (this.opts.failSafeBspKn > 0) {
+            return { valueMs: this.opts.failSafeBspKn / KN_PER_MS, source: "failsafe" };
+        }
+        return { valueMs: null, source: "none" };
+    }
+}
+exports.FailsafeBspResolver = FailsafeBspResolver;