@meri-imperiumi/signalk-passage-briefing 0.5.2 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-10-04
+
+### Added
+- CAP (Common Alerting Protocol) source (work doc #24): official structured warnings as a second ingestion channel alongside the free-text bulletin pipeline. Feeds: direct CAP documents (the NWS Pacific tsunami center's PHEBCAP.xml is the default) and Filtered Alert Hub aggregations whose RSS items link to per-alert CAP documents (newest followed, bounded). The parser maps CAP's own geometry — polygons with the latitude-first order flipped (the classic CAP integration trap, regression-tested), circles approximated, zero-radius circles as placeable points — onto the bulletin-engine's geometry types and reuses its track-intersection tests. Severity gate (default Severe and above), deterministic `<expires>` expiry, identifier-based dedup with repolls updating in place. Surviving alerts ride the payload as `capAlerts`, render as an "Official Alerts" card in the tactical, strategic and conditions-here views — visually separate from the METAREA text (severity-coloured, expires stamp, instruction text attached), with an explicit "No official alerts in effect for these waters" empty state so silence is distinguishable from a dead feed — and publish as chart notes with the native polygon carried schema-safely in the note properties (the SK Note schema has no feature field) with centroid placement and scoped expiry. Each configured feed is a row in the #23 data source checklist, success and failure alike. Verified against the live PHEBCAP document and the live Filtered Alert Hub unfiltered feed.
+- Critical hazard notifications (work doc #30): an escalation layer over the warning stream — GDACS events, CAP alerts, bulletin blocks — publishes Signal K notifications for the small subset that qualifies, so the right warnings interrupt dinner instead of waiting for the next glance at the plotter. The matrix requires both a hazard condition and an exposure condition: a GDACS TC at Red/Orange or a CAP hurricane/typhoon event escalates to `emergency` (impact near vessel or route, established by the compile-time filters); a CAP tsunami warning escalates to `emergency` while anchored or moored (a roadstead is shallow by definition) and to `error` when a live depth sounding exists (a transducer reading means shallow) — a tsunami observed in deep open water with no sounding stays a passive event; a bulletin gale/storm block escalates to `error` when its native geometry contains the vessel position *now*. Notifications publish at `notifications.navigation.briefing.hazards.<eventId>` via the standard delta path so every Signal K client sees them; two-cycle hysteresis prevents borderline flapping; acknowledged events are not re-raised until they leave the matrix and return; expiry clears deterministically. The webapp renders an interrupting full-width banner with an acknowledge button on both screens and polls the notifications subtree — an ack returns the notification to nominal for every connected client. Depth presence rides the watched-path subscription. The severity tiers are ordered so escalations stay rare enough to always be taken seriously.
+
+## [0.6.0] - 2026-10-04
+
+### Added
+
+- Timezone change events along the route (work doc #19): the briefing now says when the clock itself changes — the moment a crew sets watches and re-plans arrival in local time. Offshore, the simulated track detects crossings of the 15° zone meridians (short-arc direction from the step's longitude delta, so the antimeridian reads "180°" either way) and the unified timeline renders them as `time` events (◷ glyph): "Crossing 165°E — solar time 1 h ahead/behind — clock change due", advising but never asserting what the crew does with the clock. Crossings inside territorial waters stay quiet — the local zone governs there — using distance stints folded from the plugin's enter/leave transitions. Territorial transitions (work doc #17) are now timezone-annotated: the IANA zone at the crossing point comes from vendored tz-lookup (CC0, ~72 KB single ES module under `public/vendor/tz-lookup/` — resolved by position, which sidesteps the multi-zone-country problem entirely, and consistent with signalk-ships-time's answer) and its UTC offset at the crossing instant from the platform's `Intl` database (DST handled, no dependency); `mergeTimeline` adds the "time zone UTC+13" line when the crossing's offset differs from the vessel's current zone, or when none is published. Stamps themselves stay in the current ship's zone.
+- No-sails semantics: slatting and survival regimes (work doc #26). On a cruising boat a logged `NO_SAILS` means one of three things the old pipeline could not tell apart — the slatting regime (apparent wind too low to keep flow attached: canvas down so it stops banging, the engine drives), the survival regime (wind very high: nothing set, nobody motors into it) — or a propulsion/non-passage state (motor-sailing nights, anchorage entries). The learning pipeline now enforces that reading. The regimes are defined in the physics module: `SAILS_FILL_MIN_AWS_KNOTS` (7 kt apparent, mirroring the upwind slatting gate in apparent rather than true wind — motoring into light air is exactly when canvas slats) and `SAILS_MAX_AWS_KNOTS` (45 kt apparent — Beaufort 9 territory, deliberately decoupled from the comfort bands whose 33 kt line marks seasickness, not the rig decision; the vessel carries working canvas standing well into the forties), with `noSailsRegime()` answering slatting / survival / null. The learning gate folds a `NO_SAILS` observation into a rig bin only when its wind window justifies it — the window's average TWS below the point-of-sail slatting gates (7 kt upwind, 12 kt downwind, from the comfort model) or its peak gust at the survival floor; a mid-scale bare-poles observation still caches its wind window (idempotency intact) and stays in the logbook record, but never wins the bin, and the backfill counts it in a new `skippedNoSails` the UI reports ("7 bare-poles entries kept out of the matrix"). The simulation only accepts a `NO_SAILS` suggestion when the step's real apparent wind (boat speed and heading included) sits in a regime, so already-poisoned learned cells cannot depower a passage. The drive under an accepted canvas-down follows one shared rule for rows and events: survival — no drive, the water moves the boat, and the timeline names the decision "Storm tactics" rather than claiming a tactic (heave to, drogue, run off — proper storm tactics are their own work document, #27); becalmed with drift mode enabled — drift on the current alone; otherwise the engine pushes at motor speed with honest motor hours and fuel. A plan holding `NO_SAILS` no longer makes phantom polar speed with zero motor hours. The one-time migration on plugin start clears the learned matrix, its wind-history cache and the recorded events (guarded by `PRAGMA user_version`, logbook files untouched) so the next backfill rebuilds every bin under the new rules — the recency rule had let single bare-poles entries erase a bin's real rig, and that loss is unrecoverable from the matrix alone; empty bins degrade safely to "keep the current rig". **Upgrading crews must run the Logbook Backfill once after starting this version** (the webapp card, or `POST /plugins/.../api/backfill`) — until then the learned plan is empty and the simulation keeps whatever rig the plan already had.
+
+### Changed
+
+- Slatting has a name wherever the comfort tier shows: timeline details at sail changes and sparkline titles read "slatting" instead of the escalated "rough" — a 10 kn afternoon in a residual swell was rendering as weather it isn't, sending someone looking for wind that isn't there. The comfort explainer (ℹ️) carries a SLATTING entry with its thresholds ("wind < 7–12 kn by point of sail · swell ≥ 0.6 m").
+
+### Fixed
+
+- Phone timeline layout: the when-gutter (relative hours + date stamp + moon glyph) squeezed the event text to the side on narrow screens. On phone (below the app's 700 px layout breakpoint) each entry now renders on two lines — the date/time gutter on top at full width, glyph and event data beneath with the whole row's width available. Desktop layout unchanged.
+- No more tacks and gybes with canvas down: the maneuver detector's sailing-step test now requires the plan's rig up — a course change under power or carried by the current is not a tack or gybe. This closes a real leak: drift rows carry `motoring: false` and can hold current-driven SOG above the sailing threshold, previously qualifying as sailing steps.
+
 ## [0.5.2] - 2026-10-04
 
 ### Fixed
@@ -26,7 +48,8 @@
 ## [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.
+- The plan anchors to actual route progress (work doc #28, compile-time trim): the briefing is forward-looking — when the course provider reports the vessel navigating the briefed route (`navigation.course.activeRoute` with `pointIndex`, verified against `@signalk/course-provider`'s published shape, `reverse` honored), the plan starts where the boat is and sails to the point it is heading for, then the remaining points. Sailed legs drop out; ETA, comfort, sail work, lines of interest, landfall and territorial waters all describe the remaining passage, and events in already-sailed water disappear naturally. The payload stamps the trim point (`trimmedFromNm`, the boat's distance along the original plan); no progress (or a briefing for a non-active route) serves the full plan exactly as before.
+- 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. While underway the plan keeps advancing: navigation.state rides the live stream, so a moored → underway flip re-anchors to now immediately and the 10-minute check keeps the schedule fresh. 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.

package/README.md

@@ -2,6 +2,16 @@
 
 Offshore passage daily briefing webapp for Signal K: a plugin that plans and reviews passages for a cruising sailing vessel.
 
+## What it does
+
+- Simulates the passage hourly from the boat's actual position: speed from the vessel's polar, current added, ETA percentiles for the remaining route
+- Recommends sail changes hour by hour from what the crew actually did, learned from the electronic logbook
+- Rates every hour on the Sereno comfort scale and flags when light air in a residual swell will be worse than a gale
+- Renders one unified timeline: sail work, tacks and gybes, clock changes, territorial waters, official alerts, sky events and hazards in order
+- Fetches bulletins, official structured alerts, global disaster events and synoptic charts for the waters the route actually crosses
+- Keeps working offline: everything fetches in the online window and survives the other 23 hours from the cache
+- Shows a mini summary on the chart plotter and learns from every logbook entry the crew writes
+
 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).

package/SPEC.md

@@ -253,6 +253,31 @@ interface UnifiedWeatherPayload {
     time: string;               // ISO — the schedule's anchor instant
     reason: string;             // 'underway' | 'next_dawn' | 'daylight_prep' | 'no_dawn' | 'manual'
   };
+  trimmedFromNm?: number;       // when the plan trimmed to route progress (work doc #28):
+                                // the boat's distance along the original plan; the
+                                // payload's distances count from the boat
+  capAlerts?: {
+    id: string;                 // identifier + sent dedup key
+    identifier: string;         // CAP identifier
+    sent: string | null;        // ISO issue instant
+    msgType: string | null;     // 'Alert' | 'Update' | 'Cancel' | ...
+    senderName: string | null;
+    event: string | null;       // e.g. 'Tsunami Warning'
+    severity: string | null;    // 'extreme' | 'severe' | 'moderate' | 'minor'
+    urgency: string | null;
+    certainty: string | null;
+    effective: string | null;
+    expires: string | null;     // hard expiry — deterministic drop
+    headline: string | null;
+    description: string | null;
+    instruction: string | null;
+    web: string | null;
+    areaDesc: string | null;
+    geometry: {                 // native CAP geometry, mapped to the
+      type: 'polygon' | 'bbox'; // bulletin-engine types (circle → polygon)
+      coordinates: any;
+    };
+  }[];                          // CAP alerts near the vessel or route (work doc #24)
 }
 
 interface TimeStepForecast {

package/package.json

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

package/plugin/bulletin-engine.js

@@ -877,6 +877,236 @@ function extractIssuer(text) {
  *   source, blocks: [{text, subject, geometryType, source}]}` — null
  *   when the whole message is discarded by the subject filter
  */
+/**
+ * Builds a quadrant-arc ring around a storm center (work doc #21):
+ * walking bearings 0..360°, each 90° quadrant carries its own radius
+ * (NE/SE/SW/NW), the four arcs join into one closed ring. A zero or
+ * missing radius collapses that quadrant's arc onto the center — the
+ * NHC "0SW" case — without breaking the ring. Points are [lon, lat].
+ *
+ * @param {object} params
+ * @param {number} params.lat - Center latitude
+ * @param {number} params.lon - Center longitude
+ * @param {{ne: number, se: number, sw: number, nw: number}} params.radiiNm
+ * @returns {number[][]|null} Closed ring, null when every radius is
+ *   zero (no area to draw)
+ */
+function quadrantRing({ lat, lon, radiiNm }) {
+  const radii = [
+    radiiNm?.ne ?? 0,
+    radiiNm?.se ?? 0,
+    radiiNm?.sw ?? 0,
+    radiiNm?.nw ?? 0,
+  ];
+  if (radii.every((r) => !(r > 0))) {
+    return null;
+  }
+  const toRad = Math.PI / 180;
+  const ring = [];
+  for (let bearing = 0; bearing < 360; bearing += 5) {
+    const quadrant = Math.floor(bearing / 90) % 4;
+    const radiusNm = radii[quadrant];
+    if (!(radiusNm > 0)) {
+      ring.push([lon, lat]); // Collapsed quadrant: touch the center
+      continue;
+    }
+    const distanceRad = radiusNm / 3440.065;
+    const bearingRad = bearing * toRad;
+    const latRad = lat * toRad;
+    const lat2 = Math.asin(
+      Math.sin(latRad) * Math.cos(distanceRad) +
+        Math.cos(latRad) * Math.sin(distanceRad) * Math.cos(bearingRad),
+    );
+    const lon2 =
+      lon * toRad +
+      Math.atan2(
+        Math.sin(bearingRad) * Math.sin(distanceRad) * Math.cos(latRad),
+        Math.cos(distanceRad) - Math.sin(latRad) * Math.sin(lat2),
+      );
+    ring.push([
+      Math.round((((lon2 / toRad + 540) % 360) - 180) * 100) / 100,
+      Math.round((lat2 / toRad) * 100) / 100,
+    ]);
+  }
+  ring.push([...ring[0]]);
+  return { type: "polygon", coordinates: ring };
+}
+
+/**
+ * Severity label for the advisory family, from the max wind threshold
+ * present (work doc #21): 64 KT and above is hurricane force, 48–63
+ * storm force, 34–47 gale.
+ *
+ * @param {number} maxWindKt
+ * @returns {string|null}
+ */
+function advisorySeverityLabel(maxWindKt) {
+  if (!(maxWindKt > 0)) {
+    return null;
+  }
+  if (maxWindKt >= 64) {
+    return "HURRICANE FORCE";
+  }
+  if (maxWindKt >= 48) {
+    return "STORM FORCE";
+  }
+  if (maxWindKt >= 34) {
+    return "GALE";
+  }
+  return null;
+}
+
+/**
+ * Parses an NHC tropical-cyclone FORECAST/ADVISORY (the WTPZ/TCM
+ * family, work doc #21) into structured storm data with native
+ * geometry: present wind radii per threshold as quadrant-arc
+ * polygons, sea-height radii as a single ring, and the forecast and
+ * outlook positions with their own radii — the plan's forward storm
+ * coverage.
+ *
+ * Radii lines carry the largest expected radius per quadrant:
+ * `64 KT....... 40NE  35SE  25SW  40NW.` — zero radii (the "0SW"
+ * case) collapse onto the center in the ring. Forecast positions:
+ * `FORECAST VALID 03/1200Z 19.5N 112.1W` followed by their own wind
+ * and radii lines.
+ *
+ * @param {string} text - Cleaned bulletin text
+ * @returns {object|null} Structured storm, null when the text is not
+ *   the advisory family
+ */
+function parseAdvisory(text) {
+  if (
+    typeof text !== "string" ||
+    !/FORECAST\/ADVISORY/i.test(text) ||
+    !/MAX SUSTAINED WINDS/i.test(text)
+  ) {
+    return null;
+  }
+  const nameMatch = text.match(
+    /\b([A-Z][A-Z .'-]+?)\s+FORECAST\/ADVISORY\s+NUMBER\s+(\d+)/i,
+  );
+  const centerMatch = text.match(
+    /CENTER LOCATED NEAR\s+(\d+(?:\.\d+)?)([NS])\s+(\d+(?:\.\d+)?)([EW])/i,
+  );
+  if (!centerMatch) {
+    return null;
+  }
+  const center = {
+    lat:
+      Number.parseFloat(centerMatch[1]) *
+      (centerMatch[2].toUpperCase() === "S" ? -1 : 1),
+    lon:
+      Number.parseFloat(centerMatch[3]) *
+      (centerMatch[4].toUpperCase() === "W" ? -1 : 1),
+  };
+  const movement = text.match(
+    /PRESENT MOVEMENT TOWARD THE ([^.]+?) OR (\d{1,3}) DEGREES AT\s+(\d+) KT/i,
+  );
+  const pressure = text.match(/MINIMUM CENTRAL PRESSURE\s+(\d+) MB/i);
+  const winds = text.match(
+    /MAX SUSTAINED WINDS\s+(\d+) KT(?:\s+WITH GUSTS TO (\d+) KT)?/i,
+  );
+  const maxWindKt = winds ? Number.parseInt(winds[1], 10) : null;
+  const gustKt = winds?.[2] ? Number.parseInt(winds[2], 10) : null;
+
+  // Radius sets: the present fields live before the first VALID line;
+  // each FORECAST/OUTLOOK VALID line starts a position block with its
+  // own fields, centered on that block's position
+  const parseRadii = (segment, centerLat, centerLon) => {
+    const fields = [];
+    const radiiRe =
+      /\b(\d{1,3})\s*(M|FT)?\s*(SEAS|KT)\s*\.{2,}\s*(\d+)\s*NE\s+(\d+)\s*SE\s+(\d+)\s*SW\s+(\d+)\s*NW/gi;
+    for (const radiiMatch of segment.matchAll(radiiRe)) {
+      const threshold = Number.parseInt(radiiMatch[1], 10);
+      const kind = radiiMatch[3].toLowerCase() === "seas" ? "seas" : "wind";
+      const source = radiiMatch[2] ? `${radiiMatch[2].toUpperCase()} ` : "";
+      const label = `${threshold} ${source}${radiiMatch[3].toUpperCase()}`;
+      const radiiNm = {
+        ne: Number.parseInt(radiiMatch[4], 10),
+        se: Number.parseInt(radiiMatch[5], 10),
+        sw: Number.parseInt(radiiMatch[6], 10),
+        nw: Number.parseInt(radiiMatch[7], 10),
+      };
+      fields.push({
+        label,
+        threshold,
+        kind,
+        radiiNm,
+        geometry: quadrantRing({
+          lat: centerLat,
+          lon: centerLon,
+          radiiNm,
+        }),
+      });
+    }
+    return fields;
+  };
+  const parsePositionBlock = (segment) => {
+    const position = segment.match(
+      /\b(\d{1,2})\/(\d{4})Z\s+(\d+(?:\.\d+)?)([NS])\s+(\d+(?:\.\d+)?)([EW])/,
+    );
+    const wind = segment.match(
+      /MAX WIND\s+(\d+) KT(?:\.{2,}|\s+)GUSTS\s+(\d+) KT/i,
+    );
+    const lat =
+      position && Number.isFinite(Number.parseFloat(position[3]))
+        ? Number.parseFloat(position[3]) *
+          (position[4].toUpperCase() === "S" ? -1 : 1)
+        : null;
+    const lon =
+      position && Number.isFinite(Number.parseFloat(position[5]))
+        ? Number.parseFloat(position[5]) *
+          (position[6].toUpperCase() === "W" ? -1 : 1)
+        : null;
+    return {
+      validText: headerMatch(segment),
+      lat,
+      lon,
+      maxWindKt: wind ? Number.parseInt(wind[1], 10) : null,
+      gustKt: wind ? Number.parseInt(wind[2], 10) : null,
+      fields: parseRadii(segment, lat ?? center.lat, lon ?? center.lon),
+    };
+  };
+  const headerMatch = (segment) =>
+    segment.match(/\b((?:FORECAST|OUTLOOK) VALID [^\n]*)/)?.[1]?.trim() ?? null;
+
+  const parts = text.split(/(?=\b(?:FORECAST|OUTLOOK) VALID )/);
+  const fields = parseRadii(parts[0] ?? "", center.lat, center.lon);
+  const forecastPoints = [];
+  const outlookPoints = [];
+  for (let i = 1; i < parts.length; i++) {
+    const block = parsePositionBlock(parts[i]);
+    if (block.lat == null) {
+      continue; // A VALID line without a position is not a storm point
+    }
+    const target = /OUTLOOK VALID/i.test(parts[i])
+      ? outlookPoints
+      : forecastPoints;
+    target.push(block);
+  }
+  const primary =
+    fields.find((field) => field.threshold === 34 && field.kind === "wind") ??
+    fields.find((field) => field.kind === "wind") ??
+    fields[0] ??
+    null;
+  return {
+    stormName: nameMatch ? nameMatch[1].trim() : null,
+    advisoryNumber: nameMatch ? Number.parseInt(nameMatch[2], 10) : null,
+    center,
+    movementText: movement ? movement[1].trim() : null,
+    movementDegrees: movement ? Number.parseInt(movement[2], 10) : null,
+    movementSpeedKt: movement ? Number.parseInt(movement[3], 10) : null,
+    pressureMb: pressure ? Number.parseInt(pressure[1], 10) : null,
+    maxWindKt,
+    gustKt,
+    severityLabel: advisorySeverityLabel(maxWindKt),
+    fields,
+    forecastPoints,
+    outlookPoints,
+    primaryGeometry: primary?.geometry ?? null,
+  };
+}
+
 function filterBulletin({
   rawText,
   source,
@@ -889,6 +1119,49 @@ function filterBulletin({
     return null;
   }
   const cleaned = stripBoilerplate(rawText);
+  const advisory = parseAdvisory(cleaned);
+  if (advisory) {
+    // Advisory family (work doc #21): one semantic unit — the whole
+    // text is the block. The track filter runs over every field
+    // (present + forecast wind/seas areas): the storm's forward
+    // coverage counts, not just its present position. Severity from
+    // the max wind threshold rides the block for the console.
+    const fieldGeometries = [
+      ...advisory.fields,
+      ...advisory.forecastPoints.flatMap((point) => point.fields),
+    ]
+      .map((field) => field.geometry)
+      .filter(Boolean);
+    const onTrack =
+      fieldGeometries.length === 0 ||
+      fieldGeometries.some((geometry) => intersectsTrack(geometry, track));
+    if (!onTrack) {
+      return null; // Storm coverage misses our waters entirely
+    }
+    const spoolWatcher = require("./spool-watcher.js");
+    return {
+      header: cleaned.split(/\r?\n/, 1)[0]?.trim() ?? "",
+      issuedAt:
+        issuedAt ??
+        spoolWatcher.extractIssuedAt(cleaned) ??
+        new Date(0).toISOString(),
+      issuer: extractIssuer(cleaned),
+      bulletinText: rawText,
+      source,
+      blocks: [
+        {
+          text: cleaned,
+          subject: subject ?? null,
+          geometryType: advisory.primaryGeometry
+            ? advisory.primaryGeometry.type
+            : null,
+          geometry: advisory.primaryGeometry,
+          storm: advisory,
+          source,
+        },
+      ],
+    };
+  }
   const features = collectFeatures(cleaned);
   const header = cleaned.split(/\r?\n/, 1)[0]?.trim() ?? "";
   const blocks = segmentBlocks(cleaned)
@@ -1105,6 +1378,9 @@ function ukhoGeometry(warning) {
 }
 
 module.exports = {
+  parseAdvisory,
+  advisorySeverityLabel,
+  quadrantRing,
   RETAINED_SUBJECTS,
   SEVERE_KEYWORDS,
   SECTION_ANCHORS,