Draw aids to navigation as buoys

A buoy, beacon, RACON, light or IALA mark in the vessel feed was drawn
as a ship. A vessel record whose type names one, or whose MMSI is an
aid-to-navigation station's (99MIDxxxx), is now isAidToNavigation and
vesselModelSpec draws it as the fleet set's buoy of its mark (cardinal
N/E/S/W, port or starboard hand, safe water, isolated danger, special
mark; a red can when the type names no mark), at its built size and
flagged fixed so its model does not turn to a heading. Its icon is a
disc instead of a chevron.

AISStream now subscribes to AidsToNavigationReport by default, and the
server names each report's aid type code (0 to 31) as its kind instead
of reading it as a ship type.

src/data/aisStreamSentinels.test.mjs

@@ -316,3 +316,29 @@ test('a Class B report carries its dimensions in part B', () => {
   assert.equal(row.length, 12);
   assert.equal(row.beam, 4);
 });
+
+test('an aid-to-navigation report is a row named by its kind of aid, not a ship type', () => {
+  assert.equal(
+    ingestAisStreamEnvelope({
+      MessageType: 'AidsToNavigationReport',
+      Message: {
+        AidsToNavigationReport: {
+          UserID: 993672001,
+          Type: 20,
+          Name: 'SF APPROACH N',
+        },
+      },
+      MetaData: {
+        MMSI: '993672001',
+        latitude: 37.79,
+        longitude: -122.52,
+        time_utc: '2026-09-17 20:00:00.000000000 +0000 UTC',
+      },
+    }),
+    true,
+  );
+  const row = rowFor('993672001');
+  assert.equal(row.type, 'Cardinal Mark N');
+  assert.equal(row.name, 'SF APPROACH N');
+  assert.equal(row.speed, null);
+});

src/data/fleetModels.js

@@ -11,6 +11,9 @@
  * vehicle's road or rail top), and is drawn life size: a type's published
  * length over the model's built length is its scale.
  *
+ * An aid to navigation (a buoy, beacon, mark, RACON or light) is drawn as
+ * the set's buoy of its IALA mark, by the mark its type names.
+ *
  * The resolvers are plain functions over the parsed JSON; `loadFleetModelSet`
  * fetches the JSON and every GLB once, up front, so no model is fetched
  * mid-session.
@@ -18,6 +21,7 @@
 
 import { classifyAircraft } from './aircraftClass.js';
 import { FLEET_TRAIL_ANCHORS } from './fleetTrailAnchors.js';
+import { isAidToNavigation } from './vesselTypes.js';
 
 /** Where the model set is served, relative to the application base. */
 export const FLEET_MODEL_BASE = '/models/fleet/';
@@ -84,6 +88,44 @@ const TEXT_SHIP_TYPES = [
   [/pleasure|yacht/i, 37],
 ];
 
+/**
+ * The buoy an aid to navigation is drawn as, by the mark its type names
+ * ("Cardinal Mark N", "Beacon, Port hand", "Safe Water"): the first pattern
+ * that matches. Beacons, lights, RACONs and reference points with no mark of
+ * their own are the special mark.
+ */
+const AID_MODELS = [
+  [/cardinal\b.*\bn(orth)?$/i, 'buoy_cardinal_north'],
+  [/cardinal\b.*\be(ast)?$/i, 'buoy_cardinal_east'],
+  [/cardinal\b.*\bs(outh)?$/i, 'buoy_cardinal_south'],
+  [/cardinal\b.*\bw(est)?$/i, 'buoy_cardinal_west'],
+  [/isolated danger/i, 'buoy_isolated_danger'],
+  [/safe water/i, 'buoy_safe_water'],
+  [/port hand/i, 'buoy_lateral_port'],
+  [/starboard hand/i, 'buoy_lateral_starboard'],
+  [/special mark|light vessel|lanby/i, 'buoy_special'],
+  [
+    /^(beacon|light\b|leading light|racon|reference point|navigation aid)/i,
+    'buoy_special',
+  ],
+];
+
+/** The buoy an aid to navigation whose type names no mark is drawn as. */
+export const DEFAULT_AID_MODEL = 'can_red';
+
+/**
+ * The buoy model of an aid to navigation's type, else undefined when the
+ * type names no mark.
+ * @param {string|null} [type]
+ * @returns {string|undefined}
+ */
+export function aidToNavigationModel(type) {
+  const text = String(type ?? '').trim();
+  for (const [pattern, model] of AID_MODELS)
+    if (pattern.test(text)) return model;
+  return undefined;
+}
+
 /**
  * The model for an aircraft of ICAO type `type` (A320, B738, R44), ADS-B
  * emitter category `category` and callsign `callsign`: the first of the
@@ -397,13 +439,26 @@ export function aircraftModelSpec(
 
 /**
  * The model a vessel is drawn with, from its AIS ship type (a code or a text
- * family), reported length and beam (metres) and name.
+ * family), reported length and beam (metres) and name. An aid to navigation
+ * ({@link isAidToNavigation}: its type names a buoy, beacon, mark, RACON or
+ * light, or its MMSI is an aid's) is the buoy of its mark
+ * ({@link aidToNavigationModel}), else {@link DEFAULT_AID_MODEL}, drawn as
+ * built and flagged `fixed`: it has no heading to turn to.
  * @param {{catalog: object, types: object}} set
- * @param {{type?: string|number|null, length?: number|null,
- *   beam?: number|null, name?: string|null}} vessel
- * @returns {object} {@link fleetModelSpec}
+ * @param {{type?: string|number|null, mmsi?: string|number|null,
+ *   length?: number|null, beam?: number|null, name?: string|null}} vessel
+ * @returns {object} {@link fleetModelSpec}, with `fixed` for an aid
  */
-export function vesselModelSpec(set, { type, length, beam, name } = {}) {
+export function vesselModelSpec(set, { type, mmsi, length, beam, name } = {}) {
+  if (isAidToNavigation({ type, mmsi })) {
+    const model = aidToNavigationModel(type);
+    const known = model && set.catalog[model] ? model : DEFAULT_AID_MODEL;
+    if (set.catalog[known])
+      return Object.freeze({
+        ...fleetModelSpec(set, known, null),
+        fixed: true,
+      });
+  }
   // A beam counts only beside a reported length: a vessel drawn at its type's
   // typical length keeps the model's proportions.
   const reported = hullLength(length ?? undefined);
@@ -460,6 +515,8 @@ export function namedFleetModels(types) {
     transit.default[0],
     ...Object.keys(transit.elevation),
     ...Object.values(CLASS_MODELS),
+    ...AID_MODELS.map(([, model]) => model),
+    DEFAULT_AID_MODEL,
   ]);
 }
 

src/data/fleetModels.test.mjs

@@ -4,7 +4,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
+  DEFAULT_AID_MODEL,
   FLEET_MODEL_BASE,
+  aidToNavigationModel,
   aircraftModelSpec,
   aisShipTypeCode,
   emitterCategory,
@@ -381,6 +383,58 @@ test('vessel specs read AIS codes and text families, stretched to the reported b
   assert.equal(unknown.scale, 1);
 });
 
+test('aids to navigation are the buoy of the mark their type names', () => {
+  const cases = [
+    ['Cardinal Mark N', 'buoy_cardinal_north'],
+    ['Beacon, Cardinal E', 'buoy_cardinal_east'],
+    ['Cardinal Mark S', 'buoy_cardinal_south'],
+    ['Beacon, Cardinal W', 'buoy_cardinal_west'],
+    ['Port Hand Mark', 'buoy_lateral_port'],
+    ['Beacon, Port hand', 'buoy_lateral_port'],
+    ['Starboard Hand Mark', 'buoy_lateral_starboard'],
+    ['Preferred Channel Starboard hand', 'buoy_lateral_starboard'],
+    ['Safe Water', 'buoy_safe_water'],
+    ['Isolated danger', 'buoy_isolated_danger'],
+    ['Beacon, Special Mark', 'buoy_special'],
+    ['Special Mark', 'buoy_special'],
+    ['Light Vessel / LANBY / Rigs', 'buoy_special'],
+    ['RACON', 'buoy_special'],
+    ['Light, with Sectors', 'buoy_special'],
+    ['Reference point', 'buoy_special'],
+    ['Navigation aid', 'buoy_special'],
+  ];
+  for (const [type, model] of cases) {
+    assert.equal(aidToNavigationModel(type), model, type);
+    assert.ok(catalog[model], model);
+    const spec = vesselModelSpec(set, { type, mmsi: '993672001' });
+    assert.equal(spec.model, model, type);
+    assert.equal(spec.category, 'buoys', type);
+    assert.equal(spec.fixed, true, type);
+    // A buoy is drawn as built, whatever length the report gives.
+    assert.equal(spec.scale, 1, type);
+  }
+  assert.equal(
+    vesselModelSpec(set, { type: 'Safe Water', length: 120, beam: 30 }).scale,
+    1,
+  );
+  // An aid of no stated kind, known only by its MMSI, is the default can.
+  assert.ok(catalog[DEFAULT_AID_MODEL]);
+  const unnamed = vesselModelSpec(set, { type: '', mmsi: '993660123' });
+  assert.equal(unnamed.model, DEFAULT_AID_MODEL);
+  assert.equal(unnamed.fixed, true);
+  assert.equal(aidToNavigationModel('Fixed structure off shore'), undefined);
+  // Vessels, including those that work on buoys, keep their hulls.
+  for (const vessel of [
+    { type: 'Buoy Tender', mmsi: '366999001', length: 60 },
+    { type: '70', mmsi: '366999002' },
+    { type: 'Tug', mmsi: '' },
+  ]) {
+    const spec = vesselModelSpec(set, vessel);
+    assert.notEqual(spec.category, 'buoys', vessel.type);
+    assert.equal(spec.fixed, undefined, vessel.type);
+  }
+});
+
 test('transit specs: rail category and mode, then route type, then mode, then the default', () => {
   assert.deepEqual(resolveTransit(types, { railCategory: 'national' }), {
     model: 'intercity',

src/data/vesselTypes.js

@@ -45,3 +45,82 @@ export function normalizeVesselType(type) {
   if (NUMERIC_TYPE_SPECIALS[code]) return NUMERIC_TYPE_SPECIALS[code];
   return NUMERIC_TYPE_FAMILIES[Math.floor(code / 10)] || 'OTHER';
 }
+
+/**
+ * The kind of aid to navigation an AIS aid-to-navigation report (message 21)
+ * names by its type code, 0 to 31 (ITU-R M.1371, IALA marks): beacons and
+ * floating marks by their cardinal quadrant, lateral side, safe water,
+ * isolated danger or special mark, and the lights, RACONs and reference
+ * points around them. Code 0 names no kind.
+ */
+const AID_TYPE_NAMES = Object.freeze([
+  'Navigation aid',
+  'Reference point',
+  'RACON',
+  'Fixed structure off shore',
+  'Emergency wreck marking buoy',
+  'Light, without sectors',
+  'Light, with sectors',
+  'Leading light front',
+  'Leading light rear',
+  'Beacon, Cardinal N',
+  'Beacon, Cardinal E',
+  'Beacon, Cardinal S',
+  'Beacon, Cardinal W',
+  'Beacon, Port hand',
+  'Beacon, Starboard hand',
+  'Beacon, Preferred channel port hand',
+  'Beacon, Preferred channel starboard hand',
+  'Beacon, Isolated danger',
+  'Beacon, Safe water',
+  'Beacon, Special mark',
+  'Cardinal Mark N',
+  'Cardinal Mark E',
+  'Cardinal Mark S',
+  'Cardinal Mark W',
+  'Port hand Mark',
+  'Starboard hand Mark',
+  'Preferred Channel Port hand',
+  'Preferred Channel Starboard hand',
+  'Isolated danger',
+  'Safe Water',
+  'Special Mark',
+  'Light Vessel / LANBY / Rigs',
+]);
+
+/**
+ * The kind an AIS aid-to-navigation type code names ("19" → "Beacon, Special
+ * mark"); "Navigation aid" for code 0 and for a code outside 0 to 31.
+ * @param {string|number|null|undefined} code
+ * @returns {string}
+ */
+export function aidToNavigationTypeName(code) {
+  const text = String(code ?? '').trim();
+  const index = /^\d+$/.test(text) ? Number(text) : -1;
+  return AID_TYPE_NAMES[index] ?? AID_TYPE_NAMES[0];
+}
+
+/**
+ * Words a vessel type uses for an aid to navigation. A vessel that works on
+ * one ("Buoy Tender", "Buoy-Laying Vessel") is a ship underway, not a mark on
+ * the water.
+ */
+const AID_TYPE_TEXT =
+  /navaid|\baton\b|aids? to nav|nav(igation)? aid|racon|lighthouse|lightship|light vessel|reference point|hand mark|cardinal|safe water|preferred channel|isolated danger|special mark|beacon|buoy/i;
+const AID_WORKER_TEXT = /tender|laying/i;
+
+/** ITU MID 99: the MMSI of an AIS aid-to-navigation station (99MIDxxxx). */
+const AID_MMSI = /^99\d{7}$/;
+
+/**
+ * Whether a vessel record is an aid to navigation (a buoy, beacon, mark,
+ * RACON or light) rather than a vessel: its type names one, or its MMSI is
+ * an aid-to-navigation station's. A numeric AIS ship type never names one.
+ * @param {{type?: string|number|null, mmsi?: string|number|null}} vessel
+ * @returns {boolean}
+ */
+export function isAidToNavigation({ type, mmsi } = {}) {
+  const text = String(type ?? '').trim();
+  if (AID_TYPE_TEXT.test(text) && !AID_WORKER_TEXT.test(text)) return true;
+  return AID_MMSI.test(String(mmsi ?? '').trim());
+}

src/data/vesselTypes.test.mjs

@@ -0,0 +1,47 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { aidToNavigationTypeName, isAidToNavigation } from './vesselTypes.js';
+
+test('an aid-to-navigation type code names its kind of aid', () => {
+  assert.equal(aidToNavigationTypeName(20), 'Cardinal Mark N');
+  assert.equal(aidToNavigationTypeName('13'), 'Beacon, Port hand');
+  assert.equal(aidToNavigationTypeName(2), 'RACON');
+  assert.equal(aidToNavigationTypeName(29), 'Safe Water');
+  assert.equal(aidToNavigationTypeName(31), 'Light Vessel / LANBY / Rigs');
+  // Code 0, a code past 31 and no code name no kind.
+  for (const code of [0, 32, -1, '', null, undefined, 'x'])
+    assert.equal(aidToNavigationTypeName(code), 'Navigation aid', code);
+});
+
+test('aids to navigation are known by their type, else their MMSI', () => {
+  for (const type of [
+    'Beacon, Special Mark',
+    'Cardinal Mark N',
+    'Port Hand Mark',
+    'Starboard Hand Mark',
+    'Safe Water',
+    'Isolated danger',
+    'Preferred Channel Port hand',
+    'RACON',
+    'Light Vessel / LANBY / Rigs',
+    'Reference point',
+    'Navigation aid',
+    'AtoN',
+    'Lighthouse',
+    'Buoy',
+  ])
+    assert.equal(isAidToNavigation({ type, mmsi: '' }), true, type);
+  // AIS aid-to-navigation stations are numbered 99MIDxxxx.
+  assert.equal(isAidToNavigation({ type: '', mmsi: '993672001' }), true);
+  assert.equal(isAidToNavigation({ type: '0', mmsi: ' 992351234 ' }), true);
+  for (const vessel of [
+    { type: 'Buoy Tender', mmsi: '366999001' },
+    { type: 'Buoy-Laying Vessel', mmsi: '' },
+    { type: '70', mmsi: '366999002' },
+    { type: '0', mmsi: '' },
+    { type: 'Cargo', mmsi: '99' },
+    { type: 'Passenger', mmsi: '9936720011' },
+    {},
+  ])
+    assert.equal(isAidToNavigation(vessel), false, JSON.stringify(vessel));
+});

src/layers/vessels/ownership.test.mjs

@@ -515,3 +515,27 @@ test('AIS feed rows stay keyed by their MMSI', async () => {
     ['235000001', '235000001'],
   );
 });
+
+test('an aid to navigation is drawn as a disc, a vessel as its chevron', async () => {
+  const aid = {
+    ...observation('993672001'),
+    mmsi: '993672001',
+    type: 'Port Hand Mark',
+    speedMps: 0,
+  };
+  const ship = { ...observation('366999002'), type: 'Cargo' };
+  const { layer, primitives } = setup({
+    async getSnapshot() {
+      return snapshot([aid, ship]);
+    },
+  });
+  await layer.update();
+  const svgOf = (id) => {
+    const primitive = [...primitives].find((p) => p.id?.id === id);
+    assert.ok(primitive, id);
+    return atob(primitive.image.split(',')[1]);
+  };
+  assert.match(svgOf('993672001'), /<circle/);
+  assert.doesNotMatch(svgOf('993672001'), /<path/);
+  assert.match(svgOf('366999002'), /<path/);
+});

src/layers/vessels/rendering.js

@@ -28,6 +28,10 @@ import {
   vesselModelSpec,
 } from '../../data/fleetModels.js';
 import { createFleetModelLayer } from '../../data/fleetModelInstances.js';
+import { isAidToNavigation } from '../../data/vesselTypes.js';
+
+/** An aid to navigation's disc: a bone white apart from every ship type's colour. */
+const AID_ICON_CSS = '#d9d2c0';
 
 /** How often vessels move on as the world clock plays (wall ms). */
 const FOLLOW_POSITION_MS = 250;
@@ -182,12 +186,14 @@ export function createRendering({
    * Best available real-world direction of travel for a vessel, degrees
    * clockwise from north (true heading preferred, course-over-ground fallback).
    * Screen rotation is computed from this by the shared projected-rotation
-   * pass in updateVisibility — never directly from the compass value.
+   * pass in updateVisibility — never directly from the compass value. An aid
+   * to navigation is fixed, so it has none.
    * @param {Object} record - Vessel record.
    * @returns {number} Course in degrees (0 when unknown).
    */
 
   function vesselCourseDeg(record) {
+    if (isAidToNavigation(record)) return 0;
     const direction = record.heading ?? record.course;
     return Number.isFinite(direction) ? direction : 0;
   }
@@ -195,6 +201,7 @@ export function createRendering({
   /**
    * Build (and cache) a chevron/delta-wing SVG data URL tinted for the vessel.
    * The shape points north (up) so billboard rotation maps directly to heading.
+   * An aid to navigation, which has no heading, is a ringed disc instead.
    * One icon is generated per color+variant and reused across all billboards.
    * @param {Object} record - Vessel record (drives per-type tint).
    * @param {boolean} selected - True for the white/brighter selected variant.
@@ -202,16 +209,25 @@ export function createRendering({
    */
 
   function shipIcon(record, selected) {
-    const cssColor = selected ? '#ffffff' : vesselTypeCss(record.type);
-    const key = `${cssColor}:${selected ? 'selected' : 'normal'}`;
+    const aid = isAidToNavigation(record);
+    const cssColor = selected
+      ? '#ffffff'
+      : aid
+        ? AID_ICON_CSS
+        : vesselTypeCss(record.type);
+    const key = `${cssColor}:${selected ? 'selected' : 'normal'}:${aid ? 'aid' : 'ship'}`;
     if (vesselState.shipIconCache.has(key))
       return vesselState.shipIconCache.get(key);
 
     const stroke = selected ? 'rgba(6,26,32,0.95)' : 'rgba(4,18,24,0.9)';
     const strokeWidth = selected ? 1.1 : 0.7;
+    const shape = aid
+      ? `<circle r="8" fill="${cssColor}" stroke="${stroke}" stroke-width="${strokeWidth * 2}"/>
+      <circle r="3" fill="${stroke}"/>`
+      : `<path d="M0,-14 L11,10 L4,7 L0,14 L-4,7 L-11,10 Z" fill="${cssColor}" stroke="${stroke}" stroke-width="${strokeWidth}" stroke-linejoin="round"/>`;
     const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 32 32">
     <g transform="translate(16,16)">
-      <path d="M0,-14 L11,10 L4,7 L0,14 L-4,7 L-11,10 Z" fill="${cssColor}" stroke="${stroke}" stroke-width="${strokeWidth}" stroke-linejoin="round"/>
+      ${shape}
     </g>
   </svg>`;
     const icon = 'data:image/svg+xml;base64,' + btoa(svg);
@@ -265,13 +281,14 @@ export function createRendering({
     let item = modelItems.get(record.id);
     if (!item || item.record !== record)
       item = { record, pickId: record, tint: null, modelOwnsVisual: false };
-    const specKey = `${record.type}|${record.length}|${record.beam}|${record.name}`;
+    const specKey = `${record.type}|${record.mmsi}|${record.length}|${record.beam}|${record.name}`;
     if (item.specKey !== specKey) {
       item.specKey = specKey;
       item.spec = vesselModelSpec(set, record);
     }
     item.position = getVisual(record).waterline;
-    item.headingDeg = vesselCourseDeg(record);
+    // An aid to navigation is a fixed mark: it does not turn to a heading.
+    item.headingDeg = item.spec?.fixed ? 0 : vesselCourseDeg(record);
     item.show = record.id !== state.cockpitSubjectId;
     return item;
   }