signalk-race-control 0.10.0 → 0.11.0

package/README.md

@@ -113,6 +113,9 @@ and a live projected finishing order — during and after the race.
   navigation aid within 30m of wherever was clicked, it asks whether to snap to that
   aid's exact position and name instead of the raw click), and switches to **Use my
   position** once it has one, to re-centre it on wherever you are right now instead.
+  Once a navigation aid's been picked (or snapped to) anywhere in the course, it's
+  offered instantly in every other start/finish/mark row too — no repeat OpenSeaMap
+  lookup for the same one, e.g. reusing a rounding mark as the finish pin.
   Setting a position this way (map click or self
   position — not while still typing lat/lon by hand) also suggests a name for it from
   OpenStreetMap, when there's a real charted place right there and the name field is
@@ -123,7 +126,18 @@ and a live projected finishing order — during and after the race.
   available regardless). Every other known waypoint (not part of this race's own
   course) shows on the chart too, as a small dim pin with its name, so it's there to
   reference — or type into a mark's name field — even before it's used.
-  The chart itself is a real background map, like freeboard-sk's: it uses whatever
+  The chart itself runs almost the full page width. Scrolling over it doesn't zoom it
+  by default — the page scrolls past normally, same as anywhere else on the page —
+  click it once to turn scroll-to-zoom on for as long as the mouse stays over it; move
+  off and scrolling past it again goes back to just scrolling the page. It auto-fits to
+  the course, waypoints, and boat tracks once when a race is first opened — panning or
+  zooming around after that doesn't get undone on its own; the ⊙ button under the zoom
+  controls re-centers on demand, scoped to just this race's own start/finish/marks (not
+  other waypoints or wherever the boats have since sailed to) — a stable "back to the
+  course" reset rather than one that shifts as the race goes on. With no course entered
+  yet, it centers on this vessel's own current position instead of doing nothing. It's a
+  real background map, like
+  freeboard-sk's: it uses whatever
   tile-based chart resource(s) this SignalK server has registered, or falls back to
   public OpenStreetMap tiles when none is configured (same fallback freeboard-sk itself
   uses). Registering more than one chart offers them as alternative base layers via the
@@ -254,30 +268,40 @@ Then restart the SignalK server, enable "Race Control" under
    boat if you want its AIS position tracked for the chart/estimate.
 3. Optionally expand **Course & chart** and enter the start line, marks (in rounding
    order — reorder with ↑/↓), and finish line, then **Save Course**.
-4. Either click **Start Race** now, or set a date/time and click **Schedule Start** —
+4. For a staggered/pursuit start, optionally expand **Classes (staggered starts)** and
+   add a class per start group (e.g. "Cruisers", "Spinnaker"). Assign each boat to a
+   class from the dropdown in its row (or when adding it), then give each class its own
+   start time (Now, once the race has started, or type one directly). A boat with no
+   class assigned — or a class with no start time set yet — falls back to the race's own
+   start time, same as before classes existed. A boat's own **Start time** override (for
+   an individual correction) still wins over either.
+5. Either click **Start Race** now, or set a date/time and click **Schedule Start** —
    the race starts itself automatically at that moment (even across a server restart).
+   A real date's always needed here regardless of a single- vs. multi-day race, since a
+   start is often scheduled well ahead of race day itself.
    Clicked it a little late? Fix the recorded moment directly in the **Race start**
    field next to the clock (Now/Clear) — unlike Reset, it never touches any boat's
    finish time, DNF, or individual start override. If a particular boat actually
    started at a different moment (a staggered/pursuit start, or a correction), set
    its own time in the **Start time** column instead of leaving it to follow the
    race's start.
-5. As boats finish, click **Now** to stamp the current time, or type the exact time
+6. As boats finish, click **Now** to stamp the current time, or type the exact time
    (plus date, for a multi-day race) into the finish-time field. **Clear** undoes a
    finish.
-6. **Stop** calls the race off now (freezes the clock, DNFs whoever hasn't finished);
+7. **Stop** calls the race off now (freezes the clock, DNFs whoever hasn't finished);
    **Schedule Call-off** does the same at a future time instead. **Resume** discards
    a stop and un-DNFs whoever it DNF'd. **Reset** (click once to arm, again to
-   confirm) clears this race's start/finish/DNF state and recorded tracks entirely so
-   it can be re-run — boats and TCF values are kept.
-7. Click a boat's ☆ to mark it **self** and see the **vs Self** column fill in for
+   confirm) clears this race's start/finish/DNF state, every class's start time, and
+   recorded tracks entirely so it can be re-run — boats, their class assignments, and
+   TCF values are kept.
+8. Click a boat's ☆ to mark it **self** and see the **vs Self** column fill in for
    every other boat.
-8. **Export to Excel** downloads the current standings as a `.xlsx` file at any time
+9. **Export to Excel** downloads the current standings as a `.xlsx` file at any time
    — before, during, or after the race. **Download Offline Timer** grabs a standalone
    backup copy of the race instead — worth doing before the start if you want a safety
    net in case the server drops out mid-race.
-9. Switch races anytime via the dropdown at the top to review an earlier race's
-   results, or plan the next one. **Delete Race** (arm-then-confirm) removes one.
+10. Switch races anytime via the dropdown at the top to review an earlier race's
+    results, or plan the next one. **Delete Race** (arm-then-confirm) removes one.
 
 Corrected time is shown live throughout the race (using elapsed-so-far), and freezes
 once a boat's finish time is recorded. The **Est. finish** column shows a projected

package/index.js

@@ -275,6 +275,10 @@ function makeBoatId() {
   return 'b' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
 }
 
+function makeClassId() {
+  return 'c' + Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+}
+
 function raceSummary(race) {
   const boats = Object.values(race.boats);
   return {
@@ -301,6 +305,10 @@ function ensureRaceShape(race) {
   if (race.stopTime === undefined) race.stopTime = null;
   if (race.scheduledCallOff === undefined) race.scheduledCallOff = null;
   if (race.multiDay === undefined) race.multiDay = false;
+  if (!race.classes) race.classes = [];
+  race.classes.forEach((c) => {
+    if (c.startTime === undefined) c.startTime = null;
+  });
   Object.values(race.boats).forEach((b) => {
     if (!b.track) b.track = [];
     if (b.dnf === undefined) b.dnf = false;
@@ -308,16 +316,32 @@ function ensureRaceShape(race) {
     if (b.dnfPosition === undefined) b.dnfPosition = null;
     if (b.startTime === undefined) b.startTime = null;
     if (b.sailNumber === undefined) b.sailNumber = null;
+    if (b.classId === undefined) b.classId = null;
     if (!b.markTimes) b.markTimes = {};
   });
+  // A boat's classId can go stale (its class got deleted) — rather than
+  // check for that everywhere a class is looked up, just clear it here so
+  // every other boat.classId in memory is always either null or a real
+  // class.
+  const classIds = new Set(race.classes.map((c) => c.id));
+  Object.values(race.boats).forEach((b) => {
+    if (b.classId && !classIds.has(b.classId)) b.classId = null;
+  });
+}
+
+function findClass(race, classId) {
+  return (race.classes || []).find((c) => c.id === classId) || null;
 }
 
-// A boat with its own start time (a staggered/pursuit start, or a
-// correction for a boat that didn't actually start with the fleet) uses
-// that instead of the race's single start time — everyone else still just
-// uses race.startTime, unchanged from before this existed.
+// A boat's own start time (a per-boat correction) wins if set; otherwise
+// its class's start time (a staggered/pursuit start by class) if it's in
+// one and that class has its own start time set; otherwise the race's
+// single start time, same as before either of those existed.
 function effectiveStartTime(race, boat) {
-  return boat.startTime != null ? boat.startTime : race.startTime;
+  if (boat.startTime != null) return boat.startTime;
+  const cls = boat.classId ? findClass(race, boat.classId) : null;
+  if (cls && cls.startTime != null) return cls.startTime;
+  return race.startTime;
 }
 
 const EARTH_RADIUS_NM = 3440.065;
@@ -1576,6 +1600,28 @@ module.exports = function (app) {
   let dataFile = null;
   const scheduleTimers = new Map(); // raceId -> Timeout, for scheduledStart
   const callOffTimers = new Map(); // raceId -> Timeout, for scheduledCallOff
+
+  // setTimeout's delay is a 32-bit signed int internally — anything past
+  // ~24.8 days silently wraps and fires almost immediately instead of
+  // waiting (this bit a race scheduled weeks out: it — and, since its
+  // call-off got armed right after, that too — fired within moments of
+  // being scheduled, leaving the race already stopped/DNF'd). This chains
+  // multiple max-length timeouts instead of one long one, re-checking the
+  // actual remaining delay each time it fires so it also self-corrects
+  // for clock changes over a long wait; `timers` is keyed by raceId so
+  // disarming always clears whichever leg of the chain is currently
+  // pending, the same way a single setTimeout's handle would.
+  const MAX_TIMEOUT_MS = 2147483647;
+  function scheduleAt(timers, raceId, atTime, fn) {
+    const delay = Math.min(Math.max(atTime - Date.now(), 0), MAX_TIMEOUT_MS);
+    timers.set(
+      raceId,
+      setTimeout(() => {
+        if (Date.now() >= atTime) fn();
+        else scheduleAt(timers, raceId, atTime, fn);
+      }, delay)
+    );
+  }
   let handicapCache = { fetchedAt: 0, boats: [], sourceUrl: null, csvUrl: null };
   let ktkCache = { fetchedAt: 0, boats: [], sourceUrl: null };
 
@@ -1978,14 +2024,10 @@ module.exports = function (app) {
   function armSchedule(race) {
     disarmSchedule(race.id);
     if (race.scheduledStart && !race.startTime) {
-      const delay = race.scheduledStart - Date.now();
-      if (delay <= 0) {
+      if (race.scheduledStart - Date.now() <= 0) {
         doStart(race, race.scheduledStart);
       } else {
-        scheduleTimers.set(
-          race.id,
-          setTimeout(() => doStart(race, race.scheduledStart), delay)
-        );
+        scheduleAt(scheduleTimers, race.id, race.scheduledStart, () => doStart(race, race.scheduledStart));
       }
     }
   }
@@ -2038,14 +2080,10 @@ module.exports = function (app) {
   function armCallOffSchedule(race) {
     disarmCallOffSchedule(race.id);
     if (race.scheduledCallOff && race.startTime && !race.stopTime) {
-      const delay = race.scheduledCallOff - Date.now();
-      if (delay <= 0) {
+      if (race.scheduledCallOff - Date.now() <= 0) {
         doStop(race, race.scheduledCallOff);
       } else {
-        callOffTimers.set(
-          race.id,
-          setTimeout(() => doStop(race, race.scheduledCallOff), delay)
-        );
+        scheduleAt(callOffTimers, race.id, race.scheduledCallOff, () => doStop(race, race.scheduledCallOff));
       }
     }
   }
@@ -2415,6 +2453,9 @@ module.exports = function (app) {
       race.scheduledStart = null;
       race.stopTime = null;
       race.scheduledCallOff = null;
+      (race.classes || []).forEach((c) => {
+        c.startTime = null;
+      });
       Object.values(race.boats).forEach((b) => {
         b.finishTime = null;
         b.startTime = null;
@@ -2565,6 +2606,8 @@ module.exports = function (app) {
       if (!isHandicapRegisterMatch(name) && registryEntry && registryEntry.tcf != null) {
         tcf = registryEntry.tcf;
       }
+      const givenClassId = ((req.body && req.body.classId) || '').toString().trim();
+      const classId = givenClassId && findClass(race, givenClassId) ? givenClassId : null;
       const boat = {
         id: makeBoatId(),
         name,
@@ -2573,6 +2616,7 @@ module.exports = function (app) {
         tcf,
         finishTime: null,
         startTime: null,
+        classId,
         track: [],
         dnf: false,
         dns: false,
@@ -2595,6 +2639,88 @@ module.exports = function (app) {
       res.json({ ok: true });
     });
 
+    // Classes group boats for a staggered start by class (e.g. "Cruisers
+    // start at 12:00, Racers at 12:15") — an alternative to setting every
+    // boat's own start time by hand. A boat's own start time (if it has
+    // one) still wins over its class's, same as it already won over the
+    // race's single start time — see effectiveStartTime.
+    router.post('/races/:id/classes', (req, res) => {
+      const race = getRace(req.params.id);
+      if (!race) return res.status(404).json({ error: 'No such race' });
+      const name = ((req.body && req.body.name) || '').trim();
+      if (!name) return res.status(400).json({ error: 'name is required' });
+      ensureRaceShape(race);
+      const cls = { id: makeClassId(), name, startTime: null };
+      race.classes.push(cls);
+      saveState();
+      res.json(raceWithEstimates(race));
+    });
+
+    router.put('/races/:id/classes/:classId', (req, res) => {
+      const race = getRace(req.params.id);
+      if (!race) return res.status(404).json({ error: 'No such race' });
+      ensureRaceShape(race);
+      const cls = findClass(race, req.params.classId);
+      if (!cls) return res.status(404).json({ error: 'No such class' });
+      if ('name' in (req.body || {})) {
+        const name = (req.body.name || '').trim();
+        if (!name) return res.status(400).json({ error: 'name cannot be empty' });
+        cls.name = name;
+      }
+      saveState();
+      res.json(raceWithEstimates(race));
+    });
+
+    // Sets (or, with startTime: null, clears) this class's own start time —
+    // same pattern as a boat's own start time.
+    router.put('/races/:id/classes/:classId/startTime', (req, res) => {
+      const race = getRace(req.params.id);
+      if (!race) return res.status(404).json({ error: 'No such race' });
+      ensureRaceShape(race);
+      const cls = findClass(race, req.params.classId);
+      if (!cls) return res.status(404).json({ error: 'No such class' });
+      const raw = req.body ? req.body.startTime : undefined;
+      if (raw === null) {
+        cls.startTime = null;
+      } else {
+        const t = Number(raw);
+        if (!isFinite(t) || t <= 0) {
+          return res.status(400).json({ error: 'startTime must be an epoch-millisecond timestamp or null' });
+        }
+        cls.startTime = t;
+      }
+      saveState();
+      res.json(raceWithEstimates(race));
+    });
+
+    router.delete('/races/:id/classes/:classId', (req, res) => {
+      const race = getRace(req.params.id);
+      if (!race) return res.status(404).json({ error: 'No such race' });
+      ensureRaceShape(race);
+      if (!findClass(race, req.params.classId)) return res.status(404).json({ error: 'No such class' });
+      race.classes = race.classes.filter((c) => c.id !== req.params.classId);
+      Object.values(race.boats).forEach((b) => {
+        if (b.classId === req.params.classId) b.classId = null;
+      });
+      saveState();
+      res.json(raceWithEstimates(race));
+    });
+
+    // Sets (or, with classId: null, clears) a boat's class.
+    router.put('/races/:id/boats/:boatId/class', (req, res) => {
+      const race = getRace(req.params.id);
+      if (!race) return res.status(404).json({ error: 'No such race' });
+      const boat = getBoat(race, req.params.boatId);
+      if (!boat) return res.status(404).json({ error: 'No such boat' });
+      const classId = (req.body || {}).classId;
+      if (classId != null && !findClass(race, classId)) {
+        return res.status(400).json({ error: 'No such class' });
+      }
+      boat.classId = classId || null;
+      saveState();
+      res.json(boat);
+    });
+
     // Sets (or, with finishTime: null, clears) a boat's finish time to an
     // arbitrary timestamp, so race committee can correct a mistimed click.
     router.put('/races/:id/boats/:boatId/finishTime', (req, res) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-race-control",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "SignalK plugin and webapp for tracking elapsed and handicap-corrected (Time-on-Time) race time, with a per-boat editable TCF and boat names pulled from AIS when available.",
   "main": "index.js",
   "author": "Joachim Bakke <github@heiamoss.com>",