AIS: live online traffic overlay with ownship recognition

[DocGerd]

User request (2026-07-16), future scope: integrate live online AIS data to show surrounding vessel traffic, including recognizing ownship.

Scope

• Traffic overlay on the map (primarily in the Live tab, optionally while planning): vessel positions with COG vectors, heading, name/MMSI/type/speed on tap; targets age out when stale (AIS updates are irregular); declutter at low zoom.
• Ownship recognition: user enters their MMSI in settings → own vessel is filtered out of the traffic layer (no ghost duplicate next to the GPS boat marker) and can optionally cross-check the AIS-reported position/SOG/COG against device GPS in the Live view.
• Explicitly a live-online feature: AIS is inherently network-dependent. It must degrade exactly like planning does (feature disabled + honest banner when offline) and must never break the offline core (repo rule: everything except planning — and now AIS — keeps working offline).

Constraints to resolve during design

• No-backend rule: candidate sources that work browser-direct: aisstream.io (WebSocket, free but requires a per-user API key — store the key in settings, entered by the user, never shipped in the repo), AISHub (requires being a feed contributor), regional open feeds (Danish/German coverage needs evaluation for the Flensburg Förde / Danish South Sea area). WebSocket avoids CORS issues. If NO keyless/user-key browser-direct source covers the area acceptably, this feature forces a design discussion (proxy = backend = currently forbidden) — surface that trade-off to the owner rather than deciding silently.
• Not a navigation device: traffic display must carry the existing disclaimer framing prominently. NO collision-avoidance features (CPA/TCPA alarms) in this issue's scope — that would cross into navigation-device territory; if ever wanted, it needs its own spec discussion.
• Battery/data budget: WebSocket stream filtering to the visible bbox; pause when the tab/app is hidden.
• Privacy note: entering an MMSI identifies the user's vessel — keep it local (IndexedDB settings), never transmitted anywhere except the AIS provider's subscription filter.

Interactions

• Pairs with Chart features: buoys, beacons and other seamarks on the map (and optionally in routing) #7 (seamarks) as map-overlay infrastructure; independent of routing (Routing: account for currents/tides and sea state (waves) in the isochrone cost #18/Multi-day trip planning: chained legs with overnight stops, feasibility and arrival-window checks #19).
• Live view (E6) already owns the 1 Hz-adjacent rendering discipline — AIS targets must follow the same pattern (no app-wide re-renders per target update).

Future scope — after 0.1.0; needs a short spec addendum + owner approval before implementation (data-source choice is the key decision).

🤖 Generated with Claude Code

[DocGerd]

Status: ownship half SHIPPED — this issue now tracks the deferred AIS overlay

Shipped (PR #104, merged to develop @ 99725eb): the ownship marker, decoupled from Live View — a "show my position" Settings toggle (default off, opt-in) renders the existing GPS BoatMarker + accuracy circle in any map context (planning, no plan, or Live View), fully offline, no key, single render site (no duplicate marker). Spec: "Addendum 2026-07-22: Ownship marker (standalone) + AIS overlay (deferred) (#25)" in the design doc.

Deferred (remaining scope of this issue): the AIS traffic overlay. The 2026-07-22 feasibility spike found the ONLY browser-direct, no-backend-compliant live source for this region is aisstream.io via bring-your-own-key (WS handshake is CORS-exempt; a single shipped app key would be an uncappable public secret and is forbidden; BYOK keeps the key user data). Recorded in the same spec addendum, including: bbox-filtered subscription, target store with age-out, MMSI self-filtering (the AIS-side "ownship recognition"), honest offline degradation (disabled + banner, never a stale snapshot as live).

Implementation is gated on:

1. Explicit owner go-ahead accepting aisstream's BETA/no-SLA feed + per-user signup friction (each user registers their own free key).
2. A live coverage spot-check over the Flensburg bbox before committing effort.

Also noted for a future pass (from PR #104 review, minor): when the ownship toggle AND Live View tracking are both active, two watchPosition subscriptions run concurrently — harmless, but a shared GPS provider would be a nice consolidation when the AIS work touches this area anyway.