signalk-racer 1.1.2 → 1.3.1

package/.claude/RESUME.md

@@ -0,0 +1,23 @@
+# Claude Code — resume checkpoint
+
+Session: fe0c247c-615f-438d-9888-bb2d81cfa8b7
+Written: 2026-08-19T08:14:05.997Z
+Trigger: near-limit
+Ref with your in-progress files: refs/claude/checkpoint-fe0c247c
+
+## To resume
+
+    claude --resume fe0c247c-615f-438d-9888-bb2d81cfa8b7
+
+(or open Claude Code in this directory and run /resume)
+
+## Plan (from TodoWrite state)
+
+No task list was active; see transcript via the resume command above.
+
+---
+
+Don't want these changes? Resume this session (above), then run
+`/rewind` to roll back the turn's tool edits (bash-made changes
+excluded). refs/claude/checkpoint-fe0c247c holds a full snapshot until this session's
+next checkpoint, or for up to ~2 weeks.

package/.claude/settings.local.json

@@ -5,7 +5,21 @@
       "Bash(git -C /home/gregw/src/signalk-racer tag -l)",
       "Bash(git -C /home/gregw/src/signalk-racer log --oneline -5)",
       "Bash(git -C /home/gregw/src/signalk-racer status -sb)",
-      "Bash(git -C /home/gregw/src/signalk-racer remote -v)"
+      "Bash(git -C /home/gregw/src/signalk-racer remote -v)",
+      "Bash(npx jest *)",
+      "Bash(node --check index.js)",
+      "Bash(node --check racer.js)",
+      "Bash(node *)",
+      "Bash(npm root *)",
+      "Read(//home/gregw/.signalk/**)",
+      "Read(//home/gregw/.signalk/plugin-config-data/**)",
+      "Bash(npm view *)",
+      "Bash(systemctl list-units *)",
+      "Bash(systemctl --user list-units --type=service --all)",
+      "Bash(sed *)",
+      "Bash(python3 -)",
+      "Bash(awk '/^## 1.2.0/,/^## 1.1.2/' ReleaseNotes.md)",
+      "Bash(tee /dev/stderr)"
     ]
   }
 }

package/README.md

@@ -14,26 +14,34 @@ GitHub repository: [https://github.com/gregw/signalk-racer](https://github.com/g
 
 This plugin calculates and publishes the following Signal K paths:
 
-| Path                                            | Description                                            | Units                  | Std |
-|-------------------------------------------------|--------------------------------------------------------|------------------------|-----|
-| `navigation.racing.`<br/>`distanceStartline`    | Signed minimum distance from the bow to the start line | `m`                    | Y   |
-| `navigation.racing.`<br/>`startLineLength`      | Total length of the start line                         | `m`                    |     |
-| `navigation.racing.`<br/>`stbLineBias`          | Bias of the start line toward the starboard end        | `m`                    |     |
-| `navigation.racing.`<br/>`startLinePort`        | Location of the port (pin) end of the start line       | `{latitude,longitude}` | Y   |
-| `navigation.racing.`<br/>`startLineStb`         | Location of the starboard (boat) end of the start line | `{latitude,longitude}` | Y   |
-| `navigation.racing.`<br/>`nextLegHeading`       | True heading for the next leg of the course            | `rad`                  |     |
-| `navigation.racing.`<br/>`nextLegTrueWindAngle` | True Wind Angle for the next leg of the course         | `rad`                  |     |
-| `navigation.racing.`<br/>`timeToStart`          | Period of time until the race start                    | `s`                    | Y   |
-| `navigation.racing.`<br/>`timeToLine`           | Period of time to sail to the line at best VMG         | `s`                    |     |
-| `navigation.racing.`<br/>`timeToBurn`           | Period of time delay before sailing to the at best VMG | `s`                    |     |
-| `navigation.racing.`<br/>`startTime`            | The start time as an ISO timestamp                     | `rfc3339`              |     |
+| Path                                       | Description                                                            | Units                                              | Std |
+|--------------------------------------------|------------------------------------------------------------------------|----------------------------------------------------|-----|
+| `navigation.racing.distanceStartline`      | Signed minimum distance from the bow to the start line                 | `m`                                                | Y   |
+| `navigation.racing.startLineLength`        | Total length of the start line                                         | `m`                                                |     |
+| `navigation.racing.startLineBearing`       | Bearing of the start line, from the stb end to the port end            | `rad`                                              |     |
+| `navigation.racing.stbLineBias`            | Bias of the start line toward the starboard end                        | `m`                                                |     |
+| `navigation.racing.bestVmg.toCourseSide`   | Best VMG across the line towards the course side                       | `m/s`                                              |     |
+| `navigation.racing.bestVmg.fromCourseSide` | Best VMG back across the line from the course side (used when OCS)     | `m/s`                                              |     |
+| `navigation.racing.bestVmg.toPortEnd`      | Best VMG along the line towards the port end (pin)                     | `m/s`                                              |     |
+| `navigation.racing.bestVmg.toStbEnd`       | Best VMG along the line towards the stb end (boat)                     | `m/s`                                              |     |
+| `navigation.racing.bestVmg.*.override`     | The manual adjustment behind each best VMG, `null` when not adjusted   | `m/s`                                              |     |
+| `navigation.racing.effectiveVmg.toLine`    | VMG the perpendicular leg of the time to line is divided by            | `m/s`                                              |     |
+| `navigation.racing.effectiveVmg.alongLine` | VMG the along-line leg is divided by, 0 when inside the start zone     | `m/s`                                              |     |
+| `navigation.racing.startLinePort`          | Location of the port (pin) end of the start line                       | `{latitude,longitude}`                             | Y   |
+| `navigation.racing.startLineStb`           | Location of the starboard (boat) end of the start line                 | `{latitude,longitude}`                             | Y   |
+| `navigation.racing.nextLegHeading`         | True heading for the next leg of the course                            | `rad`                                              |     |
+| `navigation.racing.nextLegTrueWindAngle`   | True Wind Angle for the next leg of the course                         | `rad`                                              |     |
+| `navigation.racing.timeToStart`            | Period of time until the race start                                    | `s`                                                | Y   |
+| `navigation.racing.timeToLine`             | Period of time to sail to the line at best VMG                         | `s`                                                |     |
+| `navigation.racing.timeToBurn`             | Period of time delay before sailing to the at best VMG                 | `s`                                                |     |
+| `navigation.racing.startTime`              | The start time as an ISO timestamp                                     | `rfc3339`                                          |     |
 
 These values can be displayed in KIP widgets, Freeboard-SK, or other Signal K clients.  
 There are dedicated widgets for the start timer and line adjustment since 3.5.0 of KIP 
 
 ![KIP and Freeboard Screenshot](racer-kip.png)
 
-There is also a webapp to adjust the line and timer.
+There is also a webapp to: adjust the line, visualize the approach to the line, adjust VMGs and configure the timer.
 
 ![Signalk Racer Webapp](racer-webapp.png)
 
@@ -53,6 +61,7 @@ You can configure the plugin via the Signal K web interface or by editing `setti
 | `period`                  | How often to update values (in milliseconds)                            | `1000`        |
 | `updateStartLineWaypoint` | Should the waypoints be updated if the line is set/adjusted             | `true`        |
 | `createStartLineWaypoint` | Should the waypoints be created if the line is set                      | `true`        |
+| `minEffectiveVmg`         | Floor under each effective VMG used for time to line (in knots)         | `0.5`         |
 | `lines`                   | Array of named lines                                                    | null          |
 
 ---
@@ -90,9 +99,18 @@ If `navigation.headingTrue` is not available, then `navigation.courseOverGroundT
 
  - Uses the effective VMG as the maximum VMG of either the current COG/SOG or the 90th percentile of the VMG recently achieved (approx in the last 10 minutes).
    This allows a boat to luff / delay without changing the time to line.
+ - Each effective VMG is floored at `minEffectiveVmg` (default 0.5 knots), so a direction
+   with nothing collected yet - or a drifting boat - still yields a time rather than none.
+   The floor is not applied to the along-line leg when the boat is inside the start zone,
+   there being no such leg to sail.
  - A boat within the start zone has the time calculated by the perpendicular distance to the line divided by their effective VMG to the line.
  - A boat outside the start zone also has the perpendicular time plus the time calculated by the parallel distance to the zone divided by their effective VMG in that direction.
  - If the line is changed, then the samples used to calculate the effective VMGs are cleared.
+ - The four collected VMGs are published under `navigation.racing.bestVmg.*` and may be manually
+   adjusted. An adjustment stands in for the 90th percentile of the samples, but the VMG the boat
+   is actually sailing still wins if it is better, so an adjustment can never make the estimate
+   ignore real progress. Adjustments are cleared when the start timer reaches zero, when the line
+   changes, and by the `reset` command.
  - If the boat is navigating a route and the next waypoint is beyond the second in the route, then the time to line is not calculated.
 
 
@@ -114,6 +132,35 @@ If `navigation.headingTrue` is not available, then `navigation.courseOverGroundT
 
 ---
 
+## 📉 Webapp Start Line Visualization
+
+The webapp draws the line "line up": always horizontal, with the **port (pin) end to the left**
+and the **starboard (committee boat) end to the right**. The course side of the line is therefore
+always the **upper** half of the drawing and the pre-start side the lower half, so the arrow beside
+the line length and start heading always points straight up. The drawing is auto-scaled to fit the
+line and the boat, so it zooms as the boat closes. The line length and the heading to sail to cross
+the line are marked on the line itself, and the boat is drawn as a triangle pointing along its
+heading, amber when OCS.
+
+A projection runs from the boat, drawn to the same scale as the rest of the drawing, so its **tip
+can be read directly against the line**. Hovering the boat reports its SOG and COG and names the
+line running from it.
+
+#### Course projection — "Current cog/sog to start"
+
+Runs along the boat's present `navigation.courseOverGroundTrue`. While the start timer is counting
+down, its length is `SOG × timeToStart`: the distance the boat will cover before the gun if nothing
+changes. Its tip is therefore **where the boat will be when the start fires**:
+
+- tip short of the line — the boat is late and will cross after the gun
+- tip on the line — a perfect start
+- tip beyond the line — the boat is early and will be OCS
+
+With no timer running there is nothing to project against, so it degrades to a short fixed-length
+stub showing course only.
+
+---
+
 ## 🌐 API Access
 
 This plugin uses the following WebSocket-based PUT requests to Signal K model paths.
@@ -139,6 +186,39 @@ Used to **set** or **adjust** either end of the start line.
 
 ---
 
+### `navigation.racing.swapStartLine`
+
+Used to **swap** the port (pin) and starboard (boat) ends of the line, reversing its bearing.
+Takes no parameters. Collected VMG samples and any manual adjustments are exchanged along
+with the ends rather than discarded, since reversing the bearing flips the sign of both VMG
+components and so leaves every sample valid, just relabelled.
+
+---
+
+### `navigation.racing.setBestVmg`
+
+Used to **adjust** or **reset** the best VMGs used to estimate the time to line.
+
+#### Payload:
+```
+{
+  "vmg": "toCourseSide" | "fromCourseSide" | "toPortEnd" | "toStbEnd",
+  "value": 5.0,
+  "delta": 0.0514,
+  "command": "reset" | "clear"
+}
+```
+
+- `vmg`: which best VMG to adjust. Optional for `reset`, which otherwise clears all four.
+- `value`: absolute best VMG in `m/s`.
+- `delta`: adjustment in `m/s` applied to the current best VMG.
+- `command`: `"reset"` to clear the override and revert to the collected samples, or
+  `"clear"` to throw away the collected samples themselves and start again.
+
+An absolute value may also be put directly to `navigation.racing.bestVmg.<name>`.
+
+---
+
 ### `navigation.racing.setStartTime`
 
 Used to **start**, **sync**, **reset**, or **set a fixed start time**.
@@ -184,6 +264,9 @@ Bug reports and suggestions are welcome at
 
 ---
 ## Development
+
+### Linking the plugin into a local server
+
 ```text
 npm install
 npm link
@@ -191,6 +274,63 @@ cd ~/.signalk
 npm link signalk-racer
 ```
 
+This replaces `~/.signalk/node_modules/signalk-racer` with a symlink to your checkout, so
+edits take effect on the next server restart with no reinstall. Verify the link with:
+
+```text
+readlink -f ~/.signalk/node_modules/signalk-racer
+```
+
+> ⚠️ **The link is fragile.** `~/.signalk/package.json` still lists `signalk-racer` as a
+> normal dependency, so running `npm install` (or installing/updating *any* plugin from the
+> server's Appstore) will overwrite the symlink with the published release from npm, silently
+> reverting you to the registry version. Re-run `npm link signalk-racer` in `~/.signalk`
+> whenever that happens.
+
+### Checking which build is actually running
+
+The plugin stamps its version in three places, so a stale link is easy to spot:
+
+- the **Plugin Config** page in the admin UI, as the plugin status `signalk-racer <version> started`
+- the bottom of the **racer webapp**
+- the server log, via `app.debug`, including the directory it was loaded from
+
+During development the version carries a `-dev.N` suffix (e.g. `1.2.0-dev.0`), so it is
+immediately distinguishable from a released version installed from npm.
+
+A restart is required for any change to plugin code — the server does not hot-reload plugins.
+Changes to files under `public/` are served statically, so those only need a browser reload
+(with cache bypass: `Ctrl+Shift+R`).
+
+### Running the server on this machine
+
+The server is installed **globally** (`npm root -g` → `/usr/lib/node_modules`) and runs as a
+system service, using `~/.signalk` as its config directory:
+
+```text
+sudo systemctl status signalk       # is it running?
+sudo systemctl restart signalk      # pick up plugin changes
+journalctl -u signalk -f            # follow the log
+```
+
+### Updating signalk-server
+
+Because it is installed into a system directory, updating needs `sudo`, and the service must be
+restarted afterwards:
+
+```text
+npm view signalk-server version                 # latest published
+npm ls -g --depth=0 signalk-server              # currently installed
+sudo npm install -g signalk-server              # update to latest
+sudo systemctl restart signalk
+```
+
+To pin a specific version instead, use `sudo npm install -g signalk-server@2.31.1`.
+
+Note that `~/.signalk/package.json` also lists `signalk-server` as a dependency; that entry is
+only bookkeeping for the Appstore and is **not** what the service runs — the globally installed
+copy in `/usr/lib/node_modules/signalk-server` is. Updating the global copy is what counts.
+
 ---
 ## 🚀 Releasing
 

package/ReleaseNotes.md

@@ -1,3 +1,51 @@
+## 1.3.1 Start line approach
+ + Fixed the distance to the start zone being measured against a 54.7 degree wedge while
+   the zone itself was tested at 45 degrees, so `distanceStartline` and `timeToLine`
+   jumped by 0.29 times the offset as a boat crossed the boundary. They are now continuous
+   and the along-line leg reaches zero exactly at the wedge
+ + The start zone geometry moved from `index.js` into `racer.js` as `startZoneDistances`,
+   where it is unit tested - it had no coverage at all, which is how the above survived
+ + `navigation.racing.timeToBurn` is now published when OCS as well. The time to line is
+   then the time to get back over the line from the course side, so the spare time before
+   you have to turn and do it is just as real, and goes negative once it is too late
+ + Removed `navigation.racing.bestApproach` and the `cog`/`sog` each VMG sample carried
+   to produce it. It described one course the boat had genuinely sailed, which was useful
+   but not the path the time to line is computed over, so it read as a second answer to a
+   question that already had one. Best VMG angles will be revisited once the polar plugin
+   offers an API for them, by which point the shape is likely to be quite different
+ + Each effective VMG is now floored at a configurable minimum, `minEffectiveVmg`,
+   defaulting to 0.5 knots. A direction with nothing collected reported no VMG at all, which
+   left the time to line falling back to the time to start rather than estimating anything
+ + `navigation.racing.setBestVmg` accepts `command: "clear"`, which discards the collected
+   samples themselves rather than just the manual adjustments
+ + Published the two VMGs the time to line is actually divided by as
+   `navigation.racing.effectiveVmg.{toLine,alongLine}`: the collected best for each
+   direction, or the VMG being sailed right now when that is better. `bestVmg.*` reports
+   only the collected half, so a client drawing the approach from it disagreed with the
+   published time whenever the boat was going well
+
+## 1.3.0 Visualize line and best VMGs
+ + Added `navigation.racing.swapStartLine` to swap the port and starboard ends of the line,
+   carrying the collected VMG samples across with the ends
+ + Published the four best VMGs behind the time to line as `navigation.racing.bestVmg.`
+   `{toCourseSide,fromCourseSide,toPortEnd,toStbEnd}`, each with an `.override` beside it
+   reporting the manual adjustment, if any
+ + Added `navigation.racing.setBestVmg` to adjust or reset them, plus direct puts to each path.
+   An adjustment holds until the gun, but the VMG actually being sailed wins if it is better
+ + Samples now keep the `cog` and `sog` that produced them, published as
+   `navigation.racing.bestApproach`: the course actually sailed that best closes the line
+ + Published the start line bearing as `navigation.racing.startLineBearing`
+ + Webapp: swap-ends button, race countdown, and a start line visualisation with the best VMGs
+   as a cross below it and projections showing where the boat reaches at the gun
+ + Webapp and admin UI now show the running plugin version
+ + Fixed VMG samples being rejected below an absolute 1 m/s in each direction, so a boat closing
+   the line at an angle only fed the direction it was mostly travelling (now `minVmg`, 0.01 m/s)
+ + Fixed the collected VMG samples being discarded whenever any waypoint changed
+ + Fixed the start line bias not being cleared when the line is lost
+ + Fixed the webapp race countdown never being displayed
+
+## 1.2.0 Never released
+
 ## 1.1.2 TTL fixes
  + use a FIFO queue for VMGs towards the line.
  + avoid undefined values in deltas