signalk-pypilot-newui 2.11.0 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,358 @@
 # Changelog
 
+## 3.0.0 — 2026-10-10 — AIS collision overlay + Freeboard-SK embedded
+
+Rolls up Rev431 through Rev438 (8 revs). The headline feature of 3.0.0
+is an AIS collision overlay on the compass rose and a Freeboard-SK
+chart embedded in the rose box on double-tap. Pypilot-newui is a pure
+CONSUMER of the external
+[`signalk-collision-alerts`](https://github.com/dirkwa/signalk-collision-alerts)
+plugin (by @dirkwa, the maintainer of @signalk/app-dock and
+server-admin-ui) and of the Signal K v2 Notifications API — no
+CPA/TCPA engine lives here. The decision rationale is captured in the
+new memory `feedback_signalk_ecosystem_first.md`: Signal K is a
+cooperative ecosystem; reinventing a well-maintained plugin is
+anti-pattern. See `docs/_feature_ais_overlay.md` for the full
+operator guide + install.
+
+Carlos classified this bump as **major (3.0.0)** at the start of the
+sprint: it adds a new optional external-plugin dependency, changes
+double-tap-on-rose behaviour (was no-op; now opens Freeboard) and
+introduces a user-facing concept — AIS alarms with ACK — that was
+not present in the 2.x line.
+
+### Added
+
+- **AIS collision overlay (Rev431 → Rev438)**. Subscribes to
+  `notifications.navigation.closestApproach.<mmsi>` emitted by
+  `signalk-collision-alerts`. For each active `warn` / `alarm`:
+  - **Red / orange triangle** painted on the compass circle at the
+    bearing from the self vessel to the target *as of now* (not the
+    CPA future projection — Rev436 fetches the target's current
+    position + SOG via `/signalk/v1/api/vessels/<ctx>/...` on each
+    delta with a 30 s cache).
+  - **Infobox** on top of the self boat with level badge
+    (`ALARM` / `WARN`), target name (or "objetivo" when the target
+    has no name yet — MMSI never shown or spoken), CPA · TCPA,
+    closing speed, ACK button, and when > 1 target is active a
+    `N/M` navigator with `‹` / `›`.
+  - **Voice**: short Spanish sentence built from the raw data, not
+    the plugin's English string (which TTS garbled into "ce-pe-a cero
+    coma cero cuatro ene eme"). Example: *"Alarma A I S, PIRATA DE
+    ONS, a 47 metros, ya"*.
+  - **ACK** button sends `POST /signalk/v2/api/notifications/<id>/acknowledge`
+    (so Freeboard + every SK consumer sees it) AND silences the MMSI
+    locally for 10 min — survives the plugin re-publishing the same
+    threat with a fresh UUID.
+  - **"Silenciadas…" modal** (Rev438) lists every locally-silenced
+    MMSI with remaining minutes + per-row *Reactivar* + bulk *Reactivar
+    todas*.
+  - **Stationary filter** (Rev436): targets whose cached SOG < 0.15 kn
+    are dropped from the UI even if the plugin keeps emitting the
+    alarm. Mandatory in a Ría with dozens of moored vessels.
+  - **Overlay-card in Setup → ROSE OVERLAYS**: master on/off, voice
+    sub-toggle, link to the plugin's config page, access to the
+    silenced modal.
+- **Freeboard-SK embedded in the rose box** (Rev432 → Rev433). Double-
+  tap `#wind-rose` opens `/@signalk/freeboard-sk/` as an iframe
+  positioned inside the compass square so the side panels (mode,
+  nudges, AP) stay visible. Chrome row has ⤢ Maximize (full
+  viewport) / ⤡ Restore / × Close. Iframe `src` cleared on close so
+  Freeboard releases its websocket.
+
+### Changed
+
+- No breaking API changes to the pypilot-newui plugin itself —
+  everything existing in 2.12.0 still works identically. The 3.0.0
+  bump reflects the new user-facing concepts (AIS alarms, Freeboard
+  entry point) and the optional external-plugin dependency.
+
+### Fixed
+
+Bugs found and fixed during the AIS sprint, each informed by Carlos's
+QA notes and the real SK bus on Tunatunes:
+- **ACK button did not close the infobox** (Rev436). Was keyed by
+  notification UUID (Rev434); plugin cycles the id while the threat
+  persists → infobox resurrected on the next delta. Now keyed by
+  MMSI with a 10-minute TTL.
+- **Triangle 180° off** (Rev436). Rev431 pointed at
+  `data.cpaPositions.target` which is the *projected* position at the
+  CPA future instant — hence "me avisa babor cuando el target me
+  viene por aleta estribor". Now uses the current self + target
+  positions fetched from the SK REST API.
+- **Multiple alarms, including moored vessels** (Rev436). Added the
+  stationary SOG < 0.15 kn drop filter so a Ría with 30 moored boats
+  doesn't fire false alarms through the plugin's own thresholds.
+- **TTS garble on Freeboard open** (Rev436). Removed the
+  `_alSpeak("abriendo carta")` that the English TTS read as "ICE
+  open chat".
+- **Overlay-card nested checkbox hidden under the master** (Rev437).
+  CSS `.overlay-card input[type=checkbox]` matched every checkbox and
+  stacked them at top-right. Scoped to direct child so the AIS
+  card's "Voice alert" sub-toggle renders in-flow.
+
+### Known limitations / upstream work
+
+- **Upstream `signalk-collision-alerts` issue #17** —
+  https://github.com/dirkwa/signalk-collision-alerts/issues/17 — the
+  admin UI does not render the `Alert sensitivity` / `Level`
+  dropdowns because the plugin's typebox schema emits `anyOf+const`
+  instead of `enum`. We filed the issue with a fix proposal; the
+  workaround is to hand-edit the plugin JSON config or patch the
+  built `config.js` locally. See `docs/_feature_ais_overlay.md`.
+- **Needs sea-trial QA** on real moving traffic with mixed `warn` /
+  `alarm` targets. Default sensible config documented
+  (preset: `harbour`, `maxRange`: 3 NM) for a Ría-style navigation
+  env; switch to `coastal` / `offshore` as needed.
+
+---
+
+## 2.12.0 — 2026-10-08 — Virtual-tack audit cycle + Profile UX overhaul + safety aproado/empopado
+
+Rolls up Rev410 through Rev430 (21 revs). Driven by two sea trials
+(2026-10-03 and 2026-10-04) that exposed critical virtual-tack bugs
+and a batch of UX problems around profiles and the mode selector.
+Six audit MDs accompany the fixes (`docs/_audit_commit[2-6]_pre_rev*.md`
++ `docs/_sea_trial_2026-10-04.md`) following the "audit before fix"
+rule that paid for itself after three failed attempts at the drag/drop
+bug.
+
+### Added
+
+- **Virtual-tack audit cycle (Commits 2–6 of the Rev407 plan)**.
+  - *Commit 2 (Rev410)* — Mando trace enrichment (`ap.tack.state` and
+    `ap.tack.direction` deltas now log heading + AWA + mode + vtPhase),
+    VT `remainingDeg` on the mirror HUD (shows "N°" while turning,
+    "settling" during the handover phase), explicit "VT fallida: X"
+    toast when the backend publishes a terminal `failed` snapshot.
+  - *Commit 3 (Rev411)* — Writes propagate pypilot refusal through
+    `PUT /raw`, the SignalK v2 PUT handler and the `/ap/*` fallbacks
+    (503 instead of a false 200), and `dodge()` throws so KIP sees
+    the failure.
+  - *Commit 5 (Rev412)* — Empopado hot-gains that **actually apply**
+    (silent no-op since Rev320: the code read `catalog[path].value`
+    which never existed). Reads from `state.pypilotValues[path]`
+    now. New `data-hot={on|off|failed}` badge inside the active HUD
+    makes the PID state visible.
+  - *Commit 6 (Rev413)* — Yellow (warn) toast when settling times out
+    but the compass rotation finished: "Virada completada, viento sin
+    converger". Target is still applied; sailor sees it did not fully
+    confirm.
+  - *Commit 4 (Rev414)* — AWA settling EMA with τ ≈ 2 s applied to the
+    noisy raw apparent-wind sample. Fixes the "settling-timeout" seen
+    on light-wind sea trials. 4 unit tests cover seed / convergence /
+    ±π wrap-around / α = 0 identity.
+- **Virtual-tack final-angle override** (Rev416, fix #12). Backend
+  accepts optional `finalAngleRad` on `/virtual-tack/start`; the visor
+  forwards whatever is set in `localStorage.pypilotnewui.tackFinalAngleDeg`.
+  Sailor can trim the destination AWA ±170° without having to nudge
+  after the tack. Backend validates (`|rad| ≤ π`) and falls back to
+  the AWA mirror on any invalid value.
+- **EMA staleness guard** (Rev415). The settling loop now reads
+  `p.timestamp` from the SK path; samples older than
+  `STALE_SAMPLE_MS = 3000` are ignored, the dwell counter resets, and
+  the EMA state is cleared so a frozen value (e.g. after a WiFi
+  dropout) cannot sneak into the "ok" window.
+- **Nudge target trace** (Rev415, fix #1 instrumentation).
+  `apSetTargetRad` logs the current target / heading / AWA / TWA /
+  mode / engaged BEFORE each PUT and the status / ok AFTER, so a
+  stale-UI vs. real-refusal diagnosis is trivial on the next sea trial.
+- **Mode selector custom modal** (Rev425 → Rev430, fix #13 iterated).
+  Replaces the native `<select>` with a centered modal built lazily
+  under `<body>` (`.mode-select-modal-backdrop`). Contents:
+  - "MODO" label + list; the active mode highlighted in accent blue.
+  - "PERFIL" label + autowrapping button (1–2 lines so long names
+    like "Ceñida fondo medio viento" fit).
+  - Nested list opens **upward** (position: absolute; bottom: 100%)
+    so expanding profiles does not force the modal to scroll.
+  - Idempotent repaint — SK deltas never flash the open modal.
+- **Doctor suggestions sorted + numbered** (Rev417, fix #8). Visor
+  pre-sorts by the same priority map the backend `applyAll` uses
+  (`bias < authority < oscillation < noise`), stamps a 1-based
+  ordinal prefix ("1.", "2.", "3.") on each card and gives the first
+  pending suggestion a `.top-priority` accent border so the sailor
+  can see which card the "Apply top priority" button will target.
+- **Unlock prompt** (Rev421, fix #7). Flipping a group's unlock
+  checkbox opens a 3-choice modal ("Editar en perfil actual" /
+  "Cambiar a 'basic' primero" / "Cancelar") so the sailor explicitly
+  chooses the edit scope before touching sliders. Modal body answers
+  the second half of Carlos's question: "Los cambios se aplican en el
+  acto, no hace falta cerrar la pantalla."
+
+### Changed
+
+- **Safety: aproado/empopado restoreAll default = false** (Rev415,
+  fix #11). Carlos: "hay que anular el restituir rumbo cuando salimos
+  de aproado o empopado porque es peligroso". Pre-Rev415 the finish
+  path unconditionally restored mode + target + disengage; now it
+  leaves the pilot where it is unless the caller opts in. The
+  "lost stern" auto-cancel in empopado passes `restoreAll:false` too.
+- **Fork modal wording** (Rev418, fix #6). The "Keep in '{pilot}'"
+  button was filling `{pilot}` with `state.pilot` (always "basic"),
+  misleading when the active profile was called something else. Now
+  reads "Guardar en el perfil activo" + an info line showing the
+  actual profile + pilot pair. Cancel label clarified to
+  "Cancelar (deshacer último cambio)".
+- **VT mirror watchdog raised 60 s → 120 s** (Rev410, fix U.2) so it
+  does not race the backend's own `PYPILOT_STUCK_MS = 60 s`.
+- **Pypilot-silent watchdog gated on VT state** (Rev410, fix U.1).
+  During a VT the backend owns the authoritative stuck detection;
+  the legacy 40 s time-since-delta heuristic only fires on native
+  tack paths (no VT active) to avoid false "virada cancelada" toasts.
+- **Fork modal strings fully translated** (Rev419, fix #6 follow-up).
+  Modal title, body and name label were English fallbacks because
+  `data-i18n` is not walked on dynamic `innerHTML`; now set
+  explicitly from `t()` after creation.
+
+### Fixed
+
+- **Profile Manager drag/drop ping-pong flicker** (Rev420 after Rev418
+  and Rev419 attempts). The live-reorder approach was intrinsically
+  unstable — after each `insertBefore` the next `pointermove`
+  re-triggered a swap. Rewritten with the deferred-commit pattern:
+  only `translateY` the dragged item during the gesture, mark the
+  nearest drop-target with a visual line, commit one `insertBefore`
+  at the end. Also moved listeners to `window` + pointerId filter
+  (was on the handle, failed silently on tablet browsers) and gave
+  `.pm-item.dragging { touch-action: none }` so the gesture is not
+  interpreted as a scroll. Flash animation `.just-moved` on commit
+  confirms the move landed.
+- **Tack stats HUD "dejaron de salir" + z-index + X not clickable**
+  (Rev416, fix #10). The HUD was only wired to the native pypilot
+  tack path (`_tackCountdownTick` arrived); VT (wind mode) never
+  triggered it. Terminal `virtualTack` snapshots now call
+  `_tackStatsOnTackCompleted` (completed) or
+  `_tackStatsOnTackCancelled` (cancelled/failed). Corner tiles had
+  `z-index:3` and the SVG wind-rose had no stacking context, so the
+  HUD painted behind corners; added a `stats-hud-up` class on
+  `.dash-rose` that raises `.rose-wrap` to `z-index:5` while the HUD
+  is open and drops corners to `z-index:1` with
+  `pointer-events:none`. Close × hit area widened to 34 × 34 so
+  off-centre taps still land.
+- **Mode modal "se carga dos veces"** (Rev428). `refreshPypilotValues`
+  called `_rebuildModeSelect()` twice back-to-back (once when
+  `profiles` landed, once when `profile` landed) and each call
+  wiped-and-repopulated the modal's sub-select, producing a visible
+  double flash. Consolidated into a single `needsModeRebuild` flag
+  + made `_rebuildModePopupProfiles` idempotent (diffs the current
+  option list and skips the repaint when it matches).
+- **Mode popup viewport cropping** (Rev426 before the Rev427 full
+  redesign). Pre-Rev427 the anchored popup overflowed the viewport
+  bottom on 80 %-zoom laptops and phone portrait; added
+  viewport-aware placement + internal scroll before deciding to
+  switch to a centered modal anyway.
+- **Doctor "Apply top priority" button targets the right card**
+  (Rev417 side-effect of #8). The visor now mirrors the backend's
+  priority sort so the highlighted card is always the one the button
+  will apply.
+
+### Known limitations / pending real-water verification
+
+- Rev410 U.2 / U.3 — 120 s watchdog + "VT fallida" toast on backend
+  `outcomeReason` need a real pypilot-dead moment to confirm.
+- Rev411 J.1 / J.2 / J-1.5 — 503 propagation on `PUT /raw`, SK v2 PUT
+  handler and `dodge()` need pypilot genuinely offline to exercise.
+- Rev412 — "aggressive PID" on empopado now ACTUALLY writes gains to
+  pypilot (dormant since Rev320). Validate in water that the new
+  P × 1.5 / D × 1.7 / servo-slew × 1.3 does not cause oscillation.
+- Rev414 — AWA EMA τ = 2 s needs confirmation in light wind that the
+  dampened sample reaches the ±10° / 2 s dwell to produce
+  `completed:ok` instead of `settling-timeout`.
+- Rev416 — final-angle override is exposed via `localStorage` only; a
+  slider UI will come in a later rev.
+- Observation #2 from the 2026-10-04 sea trial (pilot behaves as if
+  tracking true wind in `wind` mode) is still open and awaits the
+  next sea trial's nav-session data with the Rev415 instrumentation
+  to confirm it as a real bug vs. a PID-tuning symptom.
+- Observation #9 — AIS collision overlay on the rose — is planned for
+  the next **major (3.0.0)** bump; the design is drafted in
+  `docs/_audit_feature9_ais_overlay.md` but not implemented yet.
+
+---
+
+## 2.11.0 — 2026-09-30 — Sea-trial Sprint K fixes + severity override + portrait layout
+
+Rolls up Rev324 through Rev376. Between 2.10.0 (Rev323) and 2.11.0 the
+plugin went through a second sea trial (2026-09-28, 27 min on Tunatunes)
+that surfaced 13 bugs. The ones not requiring open water are fixed in
+this release; the remainder (aproado/empopado true-wind, mando-físico
+HUD mirror) are implemented and awaiting sea-trial QA.
+
+### Added
+
+- **Per-rule alarm severity override** (Rev342 backend + Rev374 frontend).
+  Each rule in Setup > Alarms now has an inline `🔴 Alarma / 🟡 Aviso /
+  🔵 Info` dropdown. Changes are persisted via `props.alarmSeverityOverrides`
+  so they survive restarts. The shipped default is marked with `★` so the
+  sailor can see which option is the factory setting before changing it.
+  Endpoint: `POST /alarms/severity/:id {severity}`.
+- **Mute countdown mm:ss** (Rev375). The muted-rule status pill now shows
+  real-time `MM:SS` (updated every second) instead of coarse `N minutes`.
+- **Maneuver HUD mirror for external tacks** (Rev348 → Rev355). When a
+  tack is triggered from the pypilot native UI or physical remote, the
+  visor opens the overlay, animates the orange buttons, and emits the
+  post-tack stats panel — the same experience as a visor-initiated tack.
+- **Tack cancellation stats** (Rev355). Cancelling mid-tack shows the HUD
+  immediately with `pre` + "CANCELADO" and no post window.
+- **Pypilot-silence watchdog** (Rev367). If pypilot stops sending `ap.tack.state`
+  deltas for more than 60 s during a maneuver, the visor closes the mirror
+  overlay itself so the UI doesn't hang indefinitely on a lost connection.
+- **Observability instrumentation** (Rev346). `maneuver-trace` now logs
+  stage events (`wallTs + monoTs`) for frontier debugging, plus `mtLog`
+  calls in `pluginRaw` and the `ap.tack.state/direction` handleDelta
+  branch tag the event source as `external` vs visor-local.
+- **Heap diagnostics** sidecar (preserved from Rev885-equivalent work):
+  internal structure sizes under `/api/diagnostic.heapAudit` for
+  long-term RSS tracking.
+
+### Changed
+
+- **Tack stats post window shortened** 60 s → 15 s (Rev371). Was 30 s
+  wait + 30 s measurement; now 5 s wait + 10 s measurement. 10 samples at
+  1 Hz still yield a stable TWS/AWA/SOG average.
+- **Rate-of-turn fallback more conservative** (Rev345). Minimum completion
+  threshold raised to `max(20°, total × 0.4)` so brief rotations don't
+  trigger a premature "tack completed" verdict.
+- **Portrait tablet layout** (Rev370). `font-size` media queries at
+  900 / 1200 / 1600 / 2000 px heights cascade through `em` units to
+  scale both the rose and the surrounding buttons on tall tablets.
+  Confirmed working on Opera Mobile (where `zoom` had no effect).
+- **Button labels in wind mode** (Rev343). `±100°` becomes `VIRAR ← / →`
+  when the pilot is in `wind` or `truewind`, matching the actual
+  semantics.
+- **Cancel labels during active maneuver** (Rev343). The orange buttons
+  show `CANCELAR VIRADA` or `CANCELAR TRASLUCHADA` instead of their
+  normal text so the sailor knows what tapping them will do.
+
+### Fixed
+
+- **Diamond target stuck on external tacks** (Rev347). The
+  `_countdownPlannedTargetRad` variable now only masks `state.target`
+  when the countdown overlay is actually visible; stale values from
+  previously aborted visor tacks are cleared belt-and-suspenders.
+- **Severity dropdown reverted to default on every poll** (Rev375,
+  `alarms.ts` `describe()`). Was returning `rule.severity` (the factory
+  default) instead of `s.severity` (the runtime value with override
+  applied). Fixed to return `s.severity`.
+- **Visor countdown mask over authoritative state** (Rev347 lesson,
+  documented pattern). Any JS variable that fronts an authoritative
+  bus value must be gated by a visible UI signal, not by a cleanup
+  that may not fire on every abort path.
+
+### Known limitations
+
+- Aproado / empopado true-wind flow (`apSetMode("wind")` with
+  `await state.mode = "wind"` before `apSetTargetRad`) is implemented
+  but awaits sea-trial QA.
+- Physical-remote tack → HUD mirror hook (bug #7 from the 2026-09-28
+  trial) is implemented via `observeTackTransition` + `external` flag
+  but awaits sea-trial validation.
+- The pypilot-core direction rewrite for short-arc wind tacks is
+  upstream (not our plugin) and remains open; a GitHub issue is drafted
+  but not yet posted to Sean D'Epagnier.
+
+---
+
 ## 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

package/README.md

@@ -235,6 +235,37 @@ pypilot version, restart pypilot_web).
 
 **Webapp URL**: `http://<sk-host>:3000/signalk-pypilot-newui/`
 
+## Works well with
+
+Pypilot-newui is built as a well-behaved citizen of the Signal K
+ecosystem — it consumes other mature plugins and standard APIs instead
+of reinventing them. The sections below describe the plugins we
+integrate with; none are hard dependencies (the autopilot visor works
+on its own), but installing them unlocks the features listed.
+
+- **[`@signalk/freeboard-sk`](https://www.npmjs.com/package/@signalk/freeboard-sk)**
+  — Double-tap the compass rose to open Freeboard-SK embedded inside
+  the rose box (side panels stay visible and usable). Lets you drop
+  from the autopilot view to the full chart with every AIS target in
+  one tap, without leaving the pypilot-newui session.
+  See `docs/_feature_ais_overlay.md`.
+
+- **[`signalk-collision-alerts`](https://www.npmjs.com/package/signalk-collision-alerts)**
+  by @dirkwa — Provides the CPA/TCPA engine behind our AIS collision
+  overlay. Pypilot-newui subscribes to
+  `notifications.navigation.closestApproach.*` and renders a red /
+  orange triangle on the rose + an infobox with ACK that routes
+  through the Signal K v2 Notifications API, so an ACK from
+  pypilot-newui is also seen by Freeboard-SK and every other SK
+  client.
+  See `docs/_feature_ais_overlay.md`.
+
+- **[`pypilot-autopilot-provider`](https://www.npmjs.com/package/pypilot-autopilot-provider)**
+  by Panaaj — Shares the single pypilot socket cleanly with our
+  autopilot provider (see next section) so KIP, Freeboard's Autopilot
+  Console and any other SK v2 Autopilot API client all drive the same
+  pilot without duplicate connections.
+
 ## Working alongside `pypilot-autopilot-provider`
 
 We build on top of the excellent
@@ -316,6 +347,7 @@ that isolated TinyPilot.
 | `POST` | `/plugins/signalk-pypilot-newui/alarms/ack/:id`     | Acknowledge one active alarm (silences the sound, banner stays visible). |
 | `POST` | `/plugins/signalk-pypilot-newui/alarms/mute/:id`    | Mute the RULE for N minutes (query `?min=15`). |
 | `POST` | `/plugins/signalk-pypilot-newui/alarms/enable/:id`  | Enable / disable a rule (query `?on=1\|0`). |
+| `POST` | `/plugins/signalk-pypilot-newui/alarms/severity/:id` | Override the severity of one rule. Body: `{ "severity": "info\|warn\|alarm" }`. Persists via `props.alarmSeverityOverrides` so it survives restart. |
 | `GET`  | `/plugins/signalk-pypilot-newui/prechecks`     | Pre-departure autopilot check verdict: `ready` / `ready-with-caveats` / `do-not-engage` + per-item detail. |
 | `POST` | `/plugins/signalk-pypilot-newui/doctor/start`  | Start a diagnostic session (query `?duration=180`). Requires AP engaged. |
 | `POST` | `/plugins/signalk-pypilot-newui/doctor/cancel` | Cancel the current session. |