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

package/CHANGELOG.md

@@ -2,6 +2,118 @@
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-03
+
+### Added
+- Daylight-anchored departure time (work doc #15): while the boat is moored, the whole forecast schedule anchors to a realistic departure instead of "now" — nobody casts off at 02:40 because the forecast said so. Auto mode: underway sails from now; night at the start position waits for next first light (civil dawn, −6° sun altitude at the route's first waypoint); day adds the prep delay (1.5 h, configurable 0.5–3) unless the sun would set within it, in which case the anchor is the next dawn — never an immediate departure right before dark (the recorded decision). The pure helper (`assumedDepartureTime` in sereno-physics) detects a rising sun crossing with 5-minute steps bounded at 18 h and states what it assumed (`reason`), including a polar `no_dawn` fallback. The tactical and strategic views share a departure control (Auto / Now / First light / +1 h / +2 h / custom) whose manual choice overrides auto until it is put back; the root owns the state, re-checks the anchor every 10 minutes, and re-simulates only when the anchor moved more than 10 minutes so the view doesn't flap around dawn. The tactical chip states the anchor ("First light 10-05 06:00 +13"), the strategic ETA header says "Assumed departure first light …" ("Underway — from now" when sailing), sparkline titles read wall-clock stamps while shifted, and a delayed departure appears in the timeline as a ⚓ event ("Departure at first light" / "Departure after prep"). The served payload carries the same `departure` metadata so external consumers see numbers consistent with the auto assumption. SPEC §2.1/§3.1 updated.
+- Energy forecast consumption (work doc #10): the briefing finally powers its energy views — in the predictor's own terms. signalk-energy-predictor's hourly forecast (`electrical.energy.prediction.forecast.hourly`, the whole 48 h series as one delta value) and its outlook paths (`status`, `net`, `surplus` + window, `timeToEmpty`) are subscribed like any other Signal K path; the hourly series adapts into the frozen `energyHourly` consumer contract at compile time (the contract's `solarWh` carries total ideal generation: solar + wind + hydro + alternator) and rides the briefing payload so the offline hours re-derive from the cache. The 24 h solar-yield strip and the deficit banner work for the first time; the conditions-here view gains an "Energy 24h" line (the passage strip's here-mode sibling at SOG 0). New in the timeline: the predictor's own energy events — **surplus** is forecast curtailment (battery full while yield continues; the event carries the curtailed Wh and its window, "run opportunistic loads"), **deficit** and **critical** come from the outlook status (the event carries the 24 h net and, when the trajectory names one, the depletion time) — no independent re-derivation with invented thresholds.
+- Territorial waters transitions along the route (work doc #17): the briefing now says where the route crosses the boundaries that change the practical picture on board — entering or leaving a country's internal, archipelagic or 12 NM waters (the metered-ocean data boundary, customs and discharge rules). Built on `@openwaters/maritime-zones` (MIT) over the Marine Regions Maritime Boundaries Geodatabase (VLIZ, CC-BY 4.0 — the "not for navigation, no legal value" disclaimer rides the payload and renders wherever zones do). Corridor tiles (about 8 MB for a 900 nm crossing) download during the online window into the plugin data directory and answer offline afterwards; the boundary walk resamples the route at 1 nm so short territorial hops are not missed. The route simulation timestamps each crossing against the passage schedule, the unified timeline renders enter/leave events (leave events carry the "ocean data rules beyond this point" connectivity note), and here mode reports the waters the vessel sits in right now in the conditions view. Missing tiles, older Node (the package needs ≥ 24, the plugin allows 22.5) or a failed download degrade to no zone data — never a failed briefing. — entering or leaving a country's internal, archipelagic or 12 NM waters (the metered-ocean data boundary, customs and discharge rules). Built on `@openwaters/maritime-zones` (MIT) over the Marine Regions Maritime Boundaries Geodatabase (VLIZ, CC-BY 4.0 — the "not for navigation, no legal value" disclaimer rides the payload and renders wherever zones do). Corridor tiles (about 8 MB for a 900 nm crossing) download during the online window into the plugin data directory and answer offline afterwards; the boundary walk resamples the route at 1 nm so short territorial hops are not missed. The route simulation timestamps each crossing against the passage schedule, the unified timeline renders enter/leave events (leave events carry the "ocean data rules beyond this point" connectivity note), and here mode reports the waters the vessel sits in right now in the conditions view. Missing tiles, older Node (the package needs ≥ 24, the plugin allows 22.5) or a failed download degrade to no zone data — never a failed briefing.
+- GDACS hazard events also surface in the conditions-here view: earthquakes, cyclones and floods near the vessel are critical while stationary, so the here view lists them (Red events highlighted) alongside the passage timeline.
+- GDACS hazard event feed (work doc #22): earthquakes, tropical cyclones, floods and volcanic activity from the EU JRC's `gdacs.org/xml/rss.xml`, fetched during the online window and cached in `weather/hazards.json` with id-based dedup (repolls update in place). Events filter route-relative — alert level at or above the configured minimum (default Orange), within 500 nm of the route corridor or 1000 nm of the vessel, and no older than 72 h — and ride the briefing payload as `hazardEvents`, render in the unified timeline as `hazard` events with the alert level setting the severity, and publish as georeferenced `resources/notes` chart notes (category `hazard-event`, provenance `GDACS`) with scoped expiry that leaves the METAREA notes and other clients' notes untouched. Zero XML dependencies: a targeted extractor reads the stable RSS shape; malformed items skip without costing the feed.
+- Slatting & roll-dampening penalty in the Sereno comfort index (work doc #14): a residual swell (combined Hs ≥ 0.6 m) with too little wind to keep the sails loaded — below 7 kn upwind, below 12 kn downwind — now scores as the wash machine it is: the vertical acceleration carries a 2.5× discomfort multiplier before banding and the hour is forced to at least Rough. The hourly rows tag `slatting: true`, and the tactical dashboard's sparkline renders those Rough blocks with a diagonal hatch (alternating `--comfort-rough` over the card background) so the skipper sees the discomfort is light-air slatting, not heavy weather. SPEC §5.2 amended.
+- Real-world bulletin fixtures (work doc #4 follow-up): ten received-as-is High Seas texts — NHC Atlantic T1/T2, OPC East Pacific EP1, NHC EP2, Honolulu North and South Pacific (NP/SP), Fiji NAVAREA XIV, MetService NZ Subtropic, Australian BoM Western X and an NHC hurricane advisory — live under `tests/fixtures/bulletins/` with a per-family regression suite asserting issue metadata, issuer and geography extraction.
+- The bulletin engine now parses the NHC/OPC/PHFO High Seas families: compact coordinate pairs (`13N67W`, no separator) normalize into the spaced form; a hemisphere-less second number that is not the dateline shorthand is rejected as prose ("07N TO 31N" is two latitudes, not 7N 31E); issue lines from NHC (`0430 UTC SAT OCT 3 2026`), PHFO (`1130 UTC TUE FEB 17 2026`), Fiji (`OCT 022000 UTC`, mixed case `Oct` from the WMO bulletin sets), MetService New Zealand (`Wellington issued at 021856UTC`) and the Australian BoM (`commencing 2300 UTC 2 October 2026`) all parse to real timestamps; `.FORECASTER <NAME>.` lines identify the issuer when no `ISSUED BY` exists, and a leading article is trimmed ("Issued by the Australian Government Bureau of Meteorology").
+- NWS's renamed Gulf is normalized back to the crew's name: "GULF OF AMERICA" reads "GULF OF MEXICO" everywhere the cleaned bulletin text is shown or matched.
+- Lines of interest (work doc #1): the briefing detects where the planned passage crosses the traditional ceremonial lines — the equator (Shellback ceremony), the tropics, the polar circles (Blue Nose / Red Nose), the prime meridian and the antimeridian (Domain of the Golden Dragon, with the calendar skip/repeat note) — reading the simulated track, so each crossing's position, distance from start and ETA come from the boat's own schedule rather than the forecast window. The crossings ride the unified passage timeline as `line` events (⌀ glyph, the general form the timeline was built for) instead of a separate strategic block; `passageSummary.linesOfInterest` carries the data, `lines_of_interest_enabled` (default on) turns the feature off.
+- Celestial ephemeris engine (work doc #3 Phase 2): the sky is computed, not fetched. A new `plugin/celestial-ephemeris.js` module built on `astronomy-engine` (MIT, zero transitive dependencies — the dependency decision is made) derives planetary conjunctions and oppositions during nautical night, and meteor shower peaks (static annual calendar) gated to dark, clear, visible nights: moon set or a crescent, radiant able to clear 20° from the vessel's latitude, forecast cloud cover under 30 %. Bright station passes (ISS, Tiangong) are propagated locally from CelesTrak two-line elements with `satellite.js` (MIT — the SGP4 propagator call resolved) in `plugin/satellite-source.js`, reported when the pass peaks over 15° in nautical night under a clear enough sky. Every event passes the full tactical visibility gate the work document specifies — nautical night, altitude over 15° to clear the marine boundary-layer haze, cloud cover, moonlight — and the Phase-1 aurora alert is upgraded onto the same gate (nautical night replaces the sunset-based check; moonlit or overcast nights no longer raise aurora banners). Briefing payloads gain `celestialNights` — per-night twilight times (civil, nautical, astronomical) and moon phase/illumination — and `TimeStepForecast` gains `surface.cloudCover` (Open-Meteo `cloud_cover`; the Weather API provider publishes none and maps null, which leaves the cloud gate open).
+- The timeline's night stamps show the actual moon phase instead of a fixed crescent: `mergeTimeline` picks one of the eight moon glyphs (🌑🌒🌓🌔🌕🌖🌗🌘) for each night-flagged event from the payload's `celestialNights`, falling back to ☾ for payloads that predate the field. The strategic ETA table's night-arrival markers (P10/P50/P90) get the same treatment.
+- **METAREA notes now carry provenance: who published, when.** Every note the bulletin pipeline serves in `resources/notes` is stamped in its `properties` with `publishedBy` — the issuing authority parsed from the bulletin header ("ISSUED BY FIJI METEOROLOGICAL SERVICE …" → `FIJI METEOROLOGICAL SERVICE`), falling back to `signalk-passage-briefing` when the bulletin names no service (structured UKHO warnings, some NWS products) — and `publishedAt`, the bulletin's issue time. Chart plotters can show the line "Published on 10-03 12:00Z by FIJI METEOROLOGICAL SERVICE" straight from the resource; the DR webapp's note detail surface does.
+
+## [0.4.0] - 2026-10-03
+
+### Added
+
+- Sail changes are scheduled when the crew can act on them:
+  recommendation-driven canvas changes anchor to the *previous watch
+  handover* when a watch schedule is running (signalk-watch-schedule;
+  boundaries are extrapolated across the forecast horizon from the
+  rotation cycle, and the watch boundary wins over sunlight),
+  otherwise to the next sunrise/sunset. Several detections between
+  boundaries collapse into one change carrying the last suggested
+  state, no-op re-rigs are dropped, and the timeline says which
+  anchor applied ("watch change" / "at dusk" / "at dawn"). Tacks and
+  gybes stay at their tactical times.
+- Unified passage timeline: a new `<passage-timeline>` component and
+  `mergeTimeline()` view model render every event source — sail
+  changes, planned tacks and gybes, convective risk, macro sea state,
+  territorial waters transitions, sky events and hazard notes — as
+  one chronological list with a time gutter, kind glyph and severity
+  colour. The tactical dashboard renders the 24 h slice, the
+  strategic outlook the whole passage; the per-type blocks (Sail
+  Work, Convective Risk, Macro Sea State, Sky Notes) and the tactical
+  hazard banners are replaced by it. The exception view now carries
+  the whole-route hazard list in `passageSummary.hazards` (the 24 h
+  `next24h.sailChanges` and `next24h.hazards` slices are gone — the
+  timeline slices itself).
+- Sail-change events in the timeline carry the forecast conditions
+  at the change point (nearest simulated hour): true wind, sea state
+  and Sereno comfort tier — "Main 1 reef — 14.2 kn TWS · Hs 1.5 m ·
+  coffee" — so the crew knows what they are rigging into. The
+  simulation's hourly rows now include wave height and period.
+- Ship's time display: the webapp reads the vessel's published
+  timezone (`environment.time.timezoneOffset` / `.timezoneRegion`, as
+  served by signalk-ships-time) over the REST API and the delta
+  stream, and renders briefing stamps in ship's time (`MM-DD HH:MM
+  +13`) instead of UTC, falling back to UTC `Z` when no offset is
+  published. The offset rides on every stamp so a zone crossing
+  mid-passage reads honestly; a header pill names the zone (IANA
+  region when known, else the offset).
+- Weather source selection (`weather_source`: `auto` / `weather-api` /
+  `open-meteo`, default `auto`): when the server has the Weather API
+  and a provider answers — signalk-weather-router-plus serving its
+  decoded ECMWF run — waypoint forecasts for the here and route
+  briefing windows are read from it in-process (`app.weatherApi`)
+  instead of Open-Meteo, so the briefing reasons from the same
+  forecast the router planned with and offshore fetches stay local.
+  Provider responses (Signal K units) map onto the payload
+  conventions (knots, degrees true, hPa); combined sea only — swell
+  and wind-sea partitions and the upper-air fields behind the
+  convective warnings degrade to absent. A failed Weather API fetch
+  falls back to Open-Meteo for that window; the forced choices never
+  fall back.
+
+### Changed
+
+- Convective warnings read as episodes, not hourly spam: consecutive
+  anomalies (and steep-sea anomalies alike) merge into one timeline
+  event with a time range and peak values — "CAPE 713 J/kg · K 28.6 ·
+  until 10-05 05:38Z". Severity follows the peak: CAPE ≥ 400 J/kg (the
+  bar where weather services start coloring the index) or K-index ≥ 30
+  is a red alert, while the unstable-air band below it (K ≥ 28 with
+  low CAPE) still shows as an orange warning with units and sane
+  precision instead of being dropped or inflated.
+
+### Fixed
+
+- The webapp flags stale cached briefings: when a served payload was
+  compiled more than a day ago, a banner above the briefing shows the
+  compile stamp and age with a Fetch now affordance, instead of
+  presenting a multi-day-old timeline's `+Xh` labels as upcoming.
+- The plugin re-fetches stale briefings without waiting for an edge
+  trigger: the oneshot fires only when the internet state changes and
+  cron windows only run while moored and charged, so a server that
+  stays up for days while the machine sits in STANDBY_OFFSHORE kept
+  serving a briefing sliding into the past. The one-minute ticker now
+  re-fetches (trigger `stale`) when online and the cached briefing
+  (active route, else last briefed, else here) is older than the
+  route TTL — at most once per six hours, and only when something is
+  actually cached.
+
+- Bulletin geography now resolves named synoptic features in area
+  bounds: `SOUTH OF 09S AND WEST OF CF` and `SOUTH OF 10S, BETWEEN
+  150W AND CF` compose a polygon from the cold front's defining
+  chain (clipped to the stated latitude bounds, closed across the
+  antimeridian with a margin so western-Pacific vessels stay in
+  west-of-front areas) instead of falling back to a hemisphere-wide
+  box that matched every vessel south of the bound.
+
+- Coordinate chains accept the Fiji/NFFN bulletin conventions the
+  strict parser dropped: the dateline written as bare `180` (`TROUGH
+  T3 12S 175E 14S 180 15S 177W`) and the equator written as `EQT`
+  (`EQT 177E`). Prose numbers (`280600 UTC`, `20 TO 30 KNOTS`) are
+  still rejected, and a rejected span no longer swallows a following
+  coordinate pair.
+
 ## [0.3.0] - 2026-09-28
 
 ### Added

package/README.md

@@ -1,85 +1,58 @@
 # signalk-passage-briefing
 
-Offshore passage daily briefing webapp for Signal K: a plugin that plans
-and reviews passages for a cruising sailing vessel.
+Offshore passage daily briefing webapp for Signal K: a plugin that plans and reviews passages for a cruising sailing vessel.
 
-The plugin fetches multi-model weather along the planned route (online,
-or via a GRIB/text spool when offline offshore), runs a step-forward
-isochrone simulation with a monohull comfort model, learns the crew's
-sail preferences from the electronic logbook, and serves a two-screen
-webapp: a 24-hour tactical dashboard and a strategic passage summary.
-See [SPEC.md](SPEC.md) for the full design.
+The plugin fetches weather along the planned route — from the server's Weather API when a provider answers, Open-Meteo otherwise; fetched online, or via a GRIB/text spool when offline offshore. It runs a step-forward isochrone simulation with a monohull comfort model, learns the crew's sail preferences from the electronic logbook, and serves a two-screen webapp: a 24-hour tactical dashboard and a strategic passage summary. See [SPEC.md](SPEC.md) for the full design.
 
-Part of the Lille Ø offshore suite, alongside
-[@meri-imperiumi/signalk-energy-predictor](https://github.com/meri-imperiumi/signalk-energy-predictator)
-and [@meri-imperiumi/signalk-logbook](https://github.com/meri-imperiumi/signalk-logbook).
+Part of the Lille Ø offshore suite, alongside [@meri-imperiumi/signalk-energy-predictor](https://github.com/meri-imperiumi/signalk-energy-predictator) and [@meri-imperiumi/signalk-logbook](https://github.com/meri-imperiumi/signalk-logbook).
 
 ## Data sources
 
 ### Signal K
 
-- `navigation.course.activeRoute` — the route being sailed; wins over
-  the last briefed route when the cron/oneshot fetch window opens
-- `navigation.position` — vessel position for the conditions-here
-  empty state and position-only bulletin filtering
-- `network.internet.state` — connectivity gating (weather, bulletins
-  and backfill only fetch while `online` or `metered`)
-- `navigation.state`, `electrical.batteries.house.capacity.stateOfCharge`
-  — state machine inputs (moored/anchored/sailing, publication windows)
-- `polars.activePolar`, `polars.performanceFactor` — the canonical
-  polar resource consumed for boat speed (falls back to a bundled
-  default table)
+- `navigation.course.activeRoute` — the route being sailed; wins over the last briefed route when the cron/oneshot fetch window opens
+- `navigation.position` — vessel position for the conditions-here empty state and position-only bulletin filtering
+- `network.internet.state` — connectivity gating (weather, bulletins and backfill only fetch while `online` or `metered`)
+- `navigation.state`, `electrical.batteries.house.capacity.stateOfCharge` — state machine inputs (moored/anchored/sailing, publication windows)
+- `polars.activePolar`, `polars.performanceFactor` — the canonical polar resource consumed for boat speed (falls back to a bundled default table)
 - Resources API — route geometries and polar tables
-- History API (on board) — wind/attempt snapshots for the sail-event
-  backfill
-- Published tile paths — `navigation.briefing.generatedAt` / `.route` /
-  `.hasNew` / `.comfort` drive the plotter-extension tile
-  (`.acknowledgedAt` is writable to clear the NEW badge)
-- [signalk-logbook](https://github.com/meri-imperiumi/signalk-logbook)
-  store — crewed sail events (reefs, sail changes) that train the
-  preference matrix
-- [@signalk/sailsconfiguration](https://www.npmjs.com/package/@signalk/sailsconfiguration)
-  — sail inventory used to filter free-text noise out of log entries
+- History API (on board) — wind/attempt snapshots for the sail-event backfill
+- Published tile paths — `navigation.briefing.generatedAt` / `.route` / `.hasNew` / `.comfort` drive the plotter-extension tile (`.acknowledgedAt` is writable to clear the NEW badge)
+- [signalk-logbook](https://github.com/meri-imperiumi/signalk-logbook) store — crewed sail events (reefs, sail changes) that train the preference matrix
+- [signalk-ships-time](https://github.com/meri-imperiumi/signalk-ships-time) — `environment.time.timezoneOffset` / `.timezoneRegion`, the vessel's published timezone: briefing stamps render in ship's time when available (the offset rides on every stamp), falling back to UTC `Z` when nothing is published
+- [signalk-watch-schedule](https://github.com/hoeken/signalk-watch-schedule) — `watch.state.onWatch`, `watch.state.startedAt`, `watch.system` and `watch.schedule`: the running watch rotation. While a watch is running, planned sail changes anchor to the previous watch handover (both teams awake) instead of sunrise/sunset; boundaries are extrapolated across the forecast horizon from the rotation cycle
+- [@signalk/sailsconfiguration](https://www.npmjs.com/package/@signalk/sailsconfiguration) — sail inventory used to filter free-text noise out of log entries
+- Weather API (`app.weatherApi`) — waypoint forecasts from the registered provider, the preferred source (`weather_source: auto`) whenever one answers; [signalk-weather-router-plus](https://github.com/motamman/signalk-weather-router-plus) serves it from its decoded ECMWF run, so briefing numbers match what the router planned with. That source carries combined sea only: swell/wind-sea partitions and the upper-air fields behind the convective warnings degrade to absent rather than being invented
 
 ### External
 
-- [Open-Meteo Forecast API](https://open-meteo.com/en/docs) — surface
-  wind, gusts, MSL pressure, CAPE and the pressure-layer fields behind
-  the K-index (best-match model)
-- [NOAA SWPC planetary K-index forecast](https://services.swpc.noaa.gov/products/noaa-planetary-k-index-forecast.json)
-  — geomagnetic activity behind the aurora advisories
-- [JPL SBDB query API](https://ssd-api.jpl.nasa.gov/doc/sbdb_query.html)
-  — comet brightness parameters (M1/K1) behind the Sky Notes comets
-- [NOAA TGFTP radiofax tree](https://tgftp.nws.noaa.gov/fax/) and the
-  [BoM difacs charts](http://www.bom.gov.au/difacs/) — synoptic
-  surface-analysis charts per METAREA zone (work doc #11), per the
-  schedule in
-  [otherfax.txt](https://tgftp.nws.noaa.gov/fax/otherfax.txt)
-- [Open-Meteo Marine API](https://open-meteo.com/en/docs) —
-  NOAA GFS-Wave 0.25° combined sea/wind sea/swell partitions, and
-  Météo-France SMOC surface currents
-- NOAA TGFTP (`tgftp.nws.noaa.gov`) — raw METAREA bulletin text for
-  the resolved GMDSS zone's station (e.g. `FQPS01 NFFN` for XIV)
-- WMO GMDSS portal (`weather.gmdss.org`) — per-zone bulletin pages,
-  fallback when the TGFTP station is not configured
-- api.weather.gov product API — US High Seas Forecast texts (default
-  `bulletin_urls`: HSF NP/EP1/EP2); extra sources can be added via the
-  `bulletin_urls` configuration (plain text or api.weather.gov
-  product URLs; UKHO MSI JSON works too)
-
-All external fetches are online-gated and cached to the plugin data
-directory, so the last payloads survive the offline hours.
+The Open-Meteo entries below are the fallback weather source: used when no Weather API provider answers (or `weather_source` is `open-meteo`), and the only source of the partition and upper-air fields the Weather API providers don't publish.
+
+- [Open-Meteo Forecast API](https://open-meteo.com/en/docs) — surface wind, gusts, MSL pressure, CAPE and the pressure-layer fields behind the K-index (best-match model)
+- [NOAA SWPC planetary K-index forecast](https://services.swpc.noaa.gov/products/noaa-planetary-k-index-forecast.json) — geomagnetic activity behind the aurora advisories
+- [JPL SBDB query API](https://ssd-api.jpl.nasa.gov/doc/sbdb_query.html) — comet brightness parameters (M1/K1) behind the Sky Notes comets
+- [CelesTrak](https://celestrak.org/NORAD/elements/gp.php?GROUP=stations&FORMAT=tle) — two-line elements for the crewed stations (ISS, Tiangong); bright satellite passes are propagated locally from the fetched TLEs with SGP4, gated to nautical night, clear sky and a 15° haze line
+- [NOAA TGFTP radiofax tree](https://tgftp.nws.noaa.gov/fax/) and the [BoM difacs charts](http://www.bom.gov.au/difacs/) — synoptic surface-analysis charts per METAREA zone (work doc #11), per the schedule in [otherfax.txt](https://tgftp.nws.noaa.gov/fax/otherfax.txt)
+- [UKHO Admiralty MSI API](https://msi.admiralty.co.uk/) — structured NAVAREA navigational warnings for the resolved zone; the third rung of the GMDSS bulletin fetch ladder (TGFTP raw text, WMO GMDSS portal, then UKHO MSI JSON) and also accepted verbatim as a `bulletin_urls` source
+- [GDACS RSS](https://www.gdacs.org/xml/rss.xml) — EU JRC global disaster alerts (earthquakes, tropical cyclones, floods, volcanic activity), filtered route-relative by alert level and corridor distance: they ride the unified passage timeline and publish as georeferenced chart notes (work doc #22)
+- [Open-Meteo Marine API](https://open-meteo.com/en/docs) — NOAA GFS-Wave 0.25° combined sea/wind sea/swell partitions, and Météo-France SMOC surface currents
+- NOAA TGFTP (`tgftp.nws.noaa.gov`) — raw METAREA bulletin text for the resolved GMDSS zone's station (e.g. `FQPS01 NFFN` for XIV)
+- WMO GMDSS portal (`weather.gmdss.org`) — per-zone bulletin pages, fallback when the TGFTP station is not configured
+- api.weather.gov product API — US High Seas Forecast texts (default `bulletin_urls`: HSF NP/EP1/EP2); extra sources can be added via the `bulletin_urls` configuration (plain text or api.weather.gov product URLs; UKHO MSI JSON works too)
+
+All external fetches are online-gated and cached to the plugin data directory, so the last payloads survive the offline hours.
+
+## Pairing with Weather Router Plus
+
+[signalk-weather-router-plus](https://github.com/motamman/signalk-weather-router-plus) plans the passage: isochrone routing against the vessel's polar on the ECMWF open-data run it keeps decoded on disk, with map overlays, tides and currents. Activate the route it publishes to the Resources API, and this plugin briefs it — `navigation.course.activeRoute` wins over the last briefed route at the next fetch window, and with `weather_source: auto` (the default) the briefing reads its forecasts from the router's Weather API provider. One forecast on board, planner and briefing in agreement: the router for planning and visualization, the briefing for the underway daily routine (comfort, sail changes, bulletins, energy).
+
+## Pairing with Watch Schedule
+
+[signalk-watch-schedule](https://github.com/hoeken/signalk-watch-schedule) runs the crew's watch rotation and publishes it under `watch.*`. When a watch is running, this plugin reads the schedule at app load and moves planned sail changes (reefs, canvas work) to the *previous* watch handover — the moment both teams are awake on deck — rather than sunrise/sunset; tacks and gybes stay at their tactical times, since course work can't wait for a handover. The watch boundary wins over sunlight. Without a running watch, canvas work anchors to the next sunrise/sunset. Webapp-side only: no configuration, and the briefing works unchanged when the plugin is absent.
 
 ## Acknowledgments
 
-The comfort model and the whole idea of "what will each departure
-actually feel like" come from SV Sabado's
-[passage-weather](https://github.com/sailing12388/passage-weather)
-ensemble departure planner by Ray Hendricks. The Sereno comfort scale
-(Champagne, Easy, Coffee, Rough, Sick), the encounter-period motion
-math, and the ISO 2631-1 comfort bands are adapted from it for a
-monohull (heel and waterline-pitch resonance instead of catamaran
-beam-roll and bridgedeck slam).
+The comfort model and the whole idea of "what will each departure actually feel like" come from SV Sabado's [passage-weather](https://github.com/sailing12388/passage-weather) ensemble departure planner by Ray Hendricks. The Sereno comfort scale (Champagne, Easy, Coffee, Rough, Sick), the encounter-period motion math, and the ISO 2631-1 comfort bands are adapted from it for a monohull (heel and waterline-pitch resonance instead of catamaran beam-roll and bridgedeck slam).
 
 ## License
 

package/SPEC.md

@@ -77,6 +77,52 @@ signalk-passage-outlook/
       "type": "number",
       "title": "Pitching Acceleration Multiplier Constant",
       "default": 0.40
+    },
+    "lines_of_interest_enabled": {
+      "type": "boolean",
+      "title": "Lines of Interest (ceremonial crossings)",
+      "default": true
+    },
+    "hazard_events_enabled": {
+      "type": "boolean",
+      "title": "GDACS Hazard Events",
+      "default": true
+    },
+    "hazard_min_alert_level": {
+      "type": "string",
+      "enum": ["green", "orange", "red"],
+      "title": "Minimum GDACS Alert Level",
+      "default": "orange"
+    },
+    "hazard_radius_offroute_nm": {
+      "type": "number",
+      "title": "Hazard Off-route Radius (nm)",
+      "default": 500
+    },
+    "hazard_radius_ahead_nm": {
+      "type": "number",
+      "title": "Hazard Vessel Radius (nm)",
+      "default": 1000
+    },
+    "hazard_max_age_hours": {
+      "type": "number",
+      "title": "Hazard Event Aging (hours)",
+      "default": 72
+    },
+    "departure_daylight_auto": {
+      "type": "boolean",
+      "title": "Anchor Departure to Daylight (auto)",
+      "default": true
+    },
+    "departure_prep_hours": {
+      "type": "number",
+      "title": "Departure Prep Delay (hours)",
+      "default": 1.5
+    },
+    "departure_dawn_altitude_deg": {
+      "type": "number",
+      "title": "First Light Sun Altitude (degrees)",
+      "default": -6
     }
   }
 }
@@ -144,6 +190,63 @@ interface UnifiedWeatherPayload {
     issuedAt: string;
     bulletinText: string;
   };
+  spaceEvents?: {
+    kind: string;               // 'aurora' | 'comet' | 'conjunction' | 'opposition' | 'meteor'
+    timestamp: string;          // ISO timestamp
+    tactical: boolean;          // 24h dashboard banner vs strategic sky note
+    description: string;
+  }[];
+  celestialNights?: {
+    timestamp: string;          // ISO timestamp (night anchor)
+    moonPhaseDeg: number;       // 0 = new, 90 = first quarter, 180 = full, 270 = third quarter
+    moonIllumination: number;   // fraction 0-1
+    civilDusk: string | null;   // ISO timestamps, null beyond polar day/night
+    nauticalDusk: string | null;
+    astronomicalDusk: string | null;
+    astronomicalDawn: string | null;
+    nauticalDawn: string | null;
+    civilDawn: string | null;
+  }[];
+  hazardEvents?: {
+    id: string;                 // GDACS event id
+    type: string;               // 'EQ' | 'TC' | 'FL' | 'VO' | 'DR' | 'WF'
+    alertLevel: string;         // 'green' | 'orange' | 'red'
+    title: string;
+    description: string;
+    timestamp: string;          // ISO, newer of pubDate/datemodified
+    lat: number;
+    lon: number;
+    distanceNm: number;         // from the admitting reference (vessel or route)
+    bearingDeg: number;         // degrees true from the same reference
+    link: string | null;        // GDACS event page
+  }[];
+  zoneTransitions?: {
+    kind: 'enter' | 'leave';    // boundary crossing direction
+    territory: { name: string; iso_ter: string };
+    lat: number;                // crossing position
+    lon: number;
+    distanceFromStartNm: number;
+    connectivity?: 'ocean';     // leave events: metered-ocean rules beyond
+  }[];
+  zonesHere?: {                 // here mode: waters the vessel sits in
+    layer: string;              // 'internal' | 'archipelagic' | '12nm'
+    name: string;
+    iso_ter: string;
+    territory: string;
+  }[];
+  zoneDisclaimer?: string;      // Marine Regions attribution + no-navigation notice
+  energyHourly?: {
+    timestamp: string;          // ISO hour stamp
+    solarWh: number;            // total ideal generation (solar+wind+hydro+alternator)
+    loadWh: number;             // house consumption
+    netWh: number;              // solarWh - loadWh
+    soc: number | null;         // ideal SoC 0-1 at hour end
+  }[];                          // signalk-energy-predictor forecast, 48 h
+  departure?: {
+    assumed: boolean;           // auto daylight anchor vs crew override
+    time: string;               // ISO — the schedule's anchor instant
+    reason: string;             // 'underway' | 'next_dawn' | 'daylight_prep' | 'no_dawn' | 'manual'
+  };
 }
 
 interface TimeStepForecast {
@@ -152,6 +255,7 @@ interface TimeStepForecast {
     tws: number;                // knots
     twd: number;                // degrees true
     mslp: number;               // hPa
+    cloudCover: number | null;  // percent (0-100); null when the source carries none
   };
   marine: {
     hsCombined: number;         // meters
@@ -351,6 +455,19 @@ $$a_z = a_{z,\text{base}} \cdot \mu_{\text{heel}} \cdot \mu_{\text{pitch}}$$
 * $0.630 \le a_z < 1.250\text{ m/s}^2 \implies \mathbf{Rough}$
 * $a_z \ge 1.250\text{ m/s}^2 \implies \mathbf{Sick}$
 
+#### Slatting & Roll-Dampening Penalty (work doc #14)
+
+On a monohull, aerodynamic pressure in the sails dampens roll. When
+that pressure is lost but a residual swell remains, the snap-roll and
+boom shock-loading can be worse than a gale — yet raw $a_z$ scores it
+calm, because the sea state itself is modest. After the base rating:
+
+1. **Glassy-calm gate:** if $H_{s,\text{combined}} < 0.6\text{ m}$ there is not enough wave energy to roll the hull — the penalty is skipped entirely.
+2. **Dampening-loss thresholds:** otherwise the sails have lost their dampening pressure when
+   * upwind / reaching ($|TWA| < 90°$): $TWS < 7.0\text{ kt}$
+   * downwind / running ($|TWA| \ge 90°$): $TWS < 12.0\text{ kt}$ — the boat sails away from its wind, dropping apparent wind below flow-attachment.
+3. **Washing-machine penalty:** when the regime is detected, the vertical acceleration is multiplied by $\mu_{\text{slat}} = 2.5$ before ISO banding, and the hour's tier is forced to at least **Rough**. The hourly row carries a `slatting` tag; the tactical dashboard renders slatting-triggered Rough blocks with a diagonal hatch (alternating `--comfort-rough` over the card background) so the skipper sees the discomfort is light-air slatting, not heavy weather — alter course for a better wave angle, drop the main and motor, or lock the boom down.
+
 
 
 ### 5.3 Hazard Proximity Ray-Casting Algorithm

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meri-imperiumi/signalk-passage-briefing",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Offshore passage daily briefing webapp for Signal K",
   "main": "plugin/index.js",
   "scripts": {
@@ -34,12 +34,19 @@
       "@meri-imperiumi/signalk-energy-predictor",
       "@meri-imperiumi/signalk-internet",
       "signalk-polar-management"
+    ],
+    "recommends": [
+      "signalk-watch-schedule",
+      "signalk-ships-time"
     ]
   },
   "engines": {
     "node": ">=22.5.0"
   },
   "dependencies": {
+    "@openwaters/maritime-zones": "^0.2.1",
+    "astronomy-engine": "^2.1.19",
+    "satellite.js": "^7.1.0",
     "yaml": "^2.9.0"
   },
   "devDependencies": {