signalk-performance-processor 0.0.0-stage → 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.0.1 — 2026-10-29
+
+First release, a proof of concept. Run it in Shadow mode alongside your instruments before relying on it.
+
+- Corrections, each with an on/off switch: boat speed (linearity by speed plus heel correction), leeway (K × heel ÷ STW²), and H5000-style TWA and TWS tables with upwind, reach and downwind rows by TWS.
+- True wind from apparent wind minus boat velocity including leeway; TWD from heading and variation; current from SOG/COG.
+- Shadow mode publishes `…Corrected` paths; Replace mode publishes the standard paths under the plugin's own source for Source Priorities.
+- Webapp with Live, Calibration and Settings pages. Configuration is saved as the plugin's options and validated before it is applied.
+- Ships with this boat's defaults: the owner's STW table and leeway K, and TWA/TWS tables fitted to the 2025 race logs.
+- Loop guard, input plausibility checks, a choice of source per input, and a test suite.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ghotihook
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+<img src="public/icon.svg" width="72" align="right" alt="">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# signalk-performance-processor
+
+> **Proof of concept (0.0.1).** Run it in Shadow mode alongside your instruments and compare before relying on it.
+
+Signal K plugin and webapp that does the calibration job of an instrument processor such as a B&G H5000: it corrects boat speed and leeway, works out true wind from apparent wind, applies H5000-style TWA and TWS correction tables, and publishes true wind and current.
+
+Each correction can be switched on or off and edited in the webapp. A fresh install starts with values fitted to this boat's 2025 race logs.
+
+See the [changelog](CHANGELOG.md) for what changed in each release.
+
+## What it does
+
+The corrections run in this order, each on the output of the one before:
+
+| Step | What | Default |
+|---|---|---|
+| Boat speed (STW) | Knots added to the paddlewheel: a **linearity** row by speed plus a **heel correction** row by heel, the same split as the H5000 | On |
+| Leeway | Leeway = K × heel ÷ STW², turning the boat's velocity to leeward | On, K = 7.9446 |
+| True wind | Apparent wind minus the boat's velocity through the water | Always |
+| TWA table | Degrees added to \|TWA\| by TWS, with upwind, reach and downwind rows blended by TWA (70° / 100° / 130°) | On |
+| TWS table | Percent applied to TWS by TWS, same rows and blending | Off |
+| TWD, current | TWD from heading and corrected TWA; current from SOG/COG minus water velocity | Always, when heading and GPS are available |
+
+### Inputs
+
+| Input | Signal K path |
+|---|---|
+| Apparent wind | `environment.wind.angleApparent`, `environment.wind.speedApparent` |
+| Speed through water | `navigation.speedThroughWater` |
+| Heading | `navigation.headingTrue`, or `navigation.headingMagnetic` + the variation in Settings |
+| Heel | `navigation.attitude` (roll) |
+| SOG and COG | `navigation.speedOverGround`, `navigation.courseOverGroundTrue` |
+
+True wind is worked out on every apparent wind update. Inputs older than 3 seconds are not used. Without STW there is no true wind. Without heel, the heel correction and leeway are skipped. Without heading, there is no TWD or current.
+
+Feed it **measured** apparent wind and **raw** paddlewheel speed. If another plugin already corrects STW (for example `signalk-stw-heel-correction`), choose the instrument as the STW source in Settings, or the correction is applied twice.
+
+### Outputs
+
+| Output | Replace mode | Shadow mode |
+|---|---|---|
+| True wind angle | `environment.wind.angleTrueWater` | `environment.wind.angleTrueWaterCorrected` |
+| True wind speed | `environment.wind.speedTrue` | `environment.wind.speedTrueCorrected` |
+| True wind direction | `environment.wind.directionTrue` | `environment.wind.directionTrueCorrected` |
+| Speed through water (when on) | `navigation.speedThroughWater` | `navigation.speedThroughWaterCorrected` |
+| Leeway (when on) | `navigation.leewayAngle` | `navigation.leewayAngleCorrected` |
+| Current | `environment.current` (`drift`, `setTrue`) | `environment.currentCorrected` |
+
+Everything is published under this plugin's own `$source`. Corrected STW goes out each time the paddlewheel reports, while the STW correction is on; the rest goes out with each apparent wind update. Shadow paths carry `meta` with units, since they are not in the Signal K schema.
+
+## Modes
+
+- **Shadow** (default) publishes to separate `…Corrected` paths. Your instruments and displays carry on unchanged, and you can log both side by side.
+- **Replace** publishes on the standard paths. Then:
+  1. In **Server → Source Priorities**, rank `signalk-performance-processor` above the instrument for each output path.
+  2. Zero the instrument's own TWA/TWS correction tables and leeway, so nothing is corrected twice. Keep the masthead unit alignment and the boat speed calibration factor in the instrument.
+
+## The webapp
+
+Open **Webapps → Performance Processor**.
+
+- **Live**: the outputs next to their uncorrected values, what each step is doing right now, and which source and how fresh each input is.
+- **Calibration**: every correction in pipeline order with an on/off switch. Select one to edit its values, then **Save**. **Reset to defaults** puts back this boat's fitted values for that correction.
+- **Settings**: Shadow or Replace, magnetic variation, and which source to read for each input.
+
+Saving needs write access when Signal K security is on. The settings are stored as the plugin's normal configuration, so they are also visible (and editable as a fallback) under **Server → Plugin Config**.
+
+## Defaults for this boat
+
+Fitted to the 2025 race logs and checked on Jan–Mar 2026 races not used in fitting, by how little true wind direction and current jump through tacks, gybes and roundings.
+
+- **STW:** linearity +0.58 kn at 0.5 kn falling to 0 at 8.5 kn (tapering to 0 below 0.5 kn); heel 0 to −0.29 kn at 30°. This is the owner's measured heel × STW table, reduced to two rows within 0.03 kn of every cell.
+- **Leeway:** K = 7.9446, one value for every sail.
+- **TWA table (°):**
+
+  | TWS (kn) | 5 | 10 | 15 | 20 | 25 | 30 |
+  |---|---|---|---|---|---|---|
+  | Upwind | −12.0 | −13.4 | −5.7 | −4.3 | −4.3 | −4.3 |
+  | Reach | −10.7 | −10.7 | −10.7 | −10.7 | −10.7 | −10.7 |
+  | Downwind | −4.2 | −3.5 | −1.6 | −1.3 | −1.3 | −1.3 |
+
+  The reach row is provisional: it rests on roundings only.
+- **TWS table (%):** off. Downwind −11.1% at 15 kn and −14.4% from 20 kn; light air and upwind left at 0.
+- **Variation:** 12.8° E.
+
+## Adding a correction
+
+Corrections live in `lib/processor.js` as entries in `CORRECTIONS`, each with a stage (`input` before true wind, `trueWind` after) and an `apply` function. Their defaults go in `lib/defaults.js`. The pipeline, the Live view and the enable switch pick a new entry up from there; the Calibration page needs an editor for its values in `public/app.js`.
+
+## API
+
+Under `/plugins/signalk-performance-processor`:
+
+- `GET /config` returns the configuration in use and the defaults.
+- `PUT /config` validates, saves and restarts with a new configuration. It returns 400 with the reasons if the configuration is invalid.
+- `GET /live` returns the latest result, each step, input ages and the sources seen.
+
+## Development
+
+```bash
+npm test          # node --test
+```
+
+To run it from a working copy on a Signal K server:
+
+```bash
+cd ~/.signalk && npm install /path/to/signalk-performance-processor
+sudo systemctl restart signalk
+```
+
+## Licence
+
+MIT

package/index.js

@@ -0,0 +1,368 @@
+'use strict'
+
+const { DEFAULTS } = require('./lib/defaults')
+const { process, correctInputs, normalizeConfig, CORRECTIONS } = require('./lib/processor')
+
+const MS_TO_KN = 1.94384
+const RAD_TO_DEG = 180 / Math.PI
+const STALE_MS = 3000 // an input older than this is not used
+const STATUS_INTERVAL_MS = 1000
+// Bounds for sanity-checking sensor input. Anything outside these is a fault, not a reading.
+const MAX_PLAUSIBLE_STW_KN = 60
+const MAX_PLAUSIBLE_AWS_KN = 120
+const MAX_PLAUSIBLE_HEEL_DEG = 90
+// See signalk-stw-heel-correction: below this a correction is float noise, and recording
+// it as an output would make the next identical raw sample look like an echo.
+const ECHO_MIN_DELTA_MS = 1e-6
+
+// Inputs, grouped the way they are chosen in Settings.
+const INPUTS = {
+  apparentWind: ['environment.wind.angleApparent', 'environment.wind.speedApparent'],
+  stw: ['navigation.speedThroughWater'],
+  heading: ['navigation.headingMagnetic', 'navigation.headingTrue'],
+  attitude: ['navigation.attitude'],
+  gps: ['navigation.speedOverGround', 'navigation.courseOverGroundTrue']
+}
+const INPUT_OF = Object.fromEntries(Object.entries(INPUTS).flatMap(([k, ps]) => ps.map(p => [p, k])))
+
+// Outputs on their standard paths. Shadow mode appends SHADOW_SUFFIX so nothing
+// already on the boat is displaced while the numbers are being checked.
+const OUTPUTS = {
+  twa: { path: 'environment.wind.angleTrueWater', units: 'rad', description: 'True wind angle, corrected' },
+  tws: { path: 'environment.wind.speedTrue', units: 'm/s', description: 'True wind speed, corrected' },
+  twd: { path: 'environment.wind.directionTrue', units: 'rad', description: 'True wind direction, corrected' },
+  stw: { path: 'navigation.speedThroughWater', units: 'm/s', description: 'Speed through water, corrected' },
+  leeway: { path: 'navigation.leewayAngle', units: 'rad', description: 'Leeway angle, + to starboard' },
+  current: { path: 'environment.current', description: 'Current: drift (m/s) and setTrue (rad)' }
+}
+const SHADOW_SUFFIX = 'Corrected'
+
+module.exports = function (app) {
+  const plugin = {
+    id: 'signalk-performance-processor',
+    name: 'gh - Performance Processor',
+    description: 'H5000-style calibration: corrects STW and leeway, then true wind angle and speed, and publishes true wind and current'
+  }
+
+  let config = null
+  let unsubscribes = []
+  let retryTimer = null
+  let running = false
+
+  // Latest value per input path, and every source seen on each input group.
+  let latest = {}
+  let sourcesSeen = {}
+  let lastResult = null
+  let lastResultAt = 0
+  let lastStatus = ''
+
+  plugin.schema = schemaFor(DEFAULTS)
+
+  function outPath (key) {
+    return config.mode === 'shadow' ? OUTPUTS[key].path + SHADOW_SUFFIX : OUTPUTS[key].path
+  }
+
+  // Loop guard. The server stamps our deltas with $source = plugin.id; tolerate a
+  // suffix, as signalk-stw-heel-correction learned to.
+  function isOwnSource (src) {
+    if (!src) return false
+    const s = String(src)
+    return s === plugin.id || s.startsWith(plugin.id + '.')
+  }
+
+  // Backstop echo detector for the one path that is both input and output (STW in
+  // replace mode): remember published values that differ from their input.
+  const recentStw = []
+  let loopWarned = false
+  function noteStw (ms) {
+    recentStw.push(ms)
+    if (recentStw.length > 32) recentStw.shift()
+  }
+  const isStwEcho = ms => recentStw.some(o => Math.abs(o - ms) < 1e-12)
+
+  function fresh (path, now) {
+    const l = latest[path]
+    return l && now - l.at < STALE_MS ? l.value : undefined
+  }
+
+  // Refresh on a change of state, and at most once a second within a state so the
+  // live numbers in the status keep moving without flooding the admin UI.
+  let statusAt = 0
+  let statusKind = null
+  function status (kind, text) {
+    const now = Date.now()
+    if (kind === statusKind && now - statusAt < STATUS_INTERVAL_MS) return
+    statusKind = kind
+    lastStatus = text
+    statusAt = now
+    app.setPluginStatus(text)
+  }
+
+  function heelDeg (now) {
+    const att = fresh('navigation.attitude', now)
+    const roll = att && typeof att === 'object' ? att.roll : null
+    if (roll == null || !Number.isFinite(roll)) return null
+    const h = roll * RAD_TO_DEG
+    return Math.abs(h) > MAX_PLAUSIBLE_HEEL_DEG ? null : h
+  }
+
+  function publish (values, timestamp) {
+    if (!values.length) return
+    // No source object: the server stamps $source with plugin.id, which is what the
+    // loop guard and the user's Source Priorities entry match on.
+    app.handleMessage(plugin.id, { updates: [{ timestamp, values }] })
+  }
+
+  // Corrected STW goes out as soon as the paddlewheel reports, at its own rate.
+  function onStw (rawMs, timestamp, now) {
+    const stw = config.corrections.stw
+    if (!stw.enabled) return
+    const stwKn = rawMs * MS_TO_KN
+    // A sensor fault is not a reading; republishing it under this plugin's source
+    // would put the source the user ranked first behind a bad number.
+    if (stwKn < 0 || stwKn > MAX_PLAUSIBLE_STW_KN) return
+    const { c } = correctInputs({ stw: stwKn, heel: heelDeg(now) }, config)
+    const ms = c.stw / MS_TO_KN
+    if (config.mode === 'replace' && Math.abs(ms - rawMs) > ECHO_MIN_DELTA_MS) noteStw(ms)
+    publish([{ path: outPath('stw'), value: ms }], timestamp)
+  }
+
+  // True wind, current and leeway go out on every apparent wind update.
+  function onWind (timestamp, now) {
+    const awa = fresh('environment.wind.angleApparent', now)
+    const aws = fresh('environment.wind.speedApparent', now)
+    const stw = fresh('navigation.speedThroughWater', now)
+    if (awa == null || aws == null) return status('nowind', 'Waiting for apparent wind')
+    if (stw == null) return status('nostw', 'Waiting for speed through water — no true wind without it')
+
+    const awsKn = aws * MS_TO_KN
+    const stwKn = stw * MS_TO_KN
+    if (awsKn < 0 || awsKn > MAX_PLAUSIBLE_AWS_KN) return status('badaws', `Not publishing — AWS of ${awsKn.toFixed(1)} kn is not plausible`)
+    if (stwKn < 0 || stwKn > MAX_PLAUSIBLE_STW_KN) return status('badstw', `Not publishing — STW of ${stwKn.toFixed(1)} kn is not plausible`)
+
+    const deg = v => v == null ? undefined : v * RAD_TO_DEG
+    const input = {
+      awa: deg(Math.atan2(Math.sin(awa), Math.cos(awa))),
+      aws: awsKn,
+      stw: stwKn,
+      heel: heelDeg(now),
+      headingMagnetic: deg(fresh('navigation.headingMagnetic', now)),
+      headingTrue: deg(fresh('navigation.headingTrue', now)),
+      sog: (v => v == null ? undefined : v * MS_TO_KN)(fresh('navigation.speedOverGround', now)),
+      cog: deg(fresh('navigation.courseOverGroundTrue', now))
+    }
+    const result = process(input, config)
+    lastResult = { input, ...result }
+    lastResultAt = now
+
+    const o = result.out
+    const values = [
+      { path: outPath('twa'), value: o.twa / RAD_TO_DEG },
+      { path: outPath('tws'), value: o.tws / MS_TO_KN }
+    ]
+    if (o.twd != null) values.push({ path: outPath('twd'), value: o.twd / RAD_TO_DEG })
+    if (config.corrections.leeway.enabled) values.push({ path: outPath('leeway'), value: o.leeway / RAD_TO_DEG })
+    if (o.current) values.push({ path: outPath('current'), value: { drift: o.current.drift / MS_TO_KN, setTrue: o.current.set / RAD_TO_DEG } })
+    publish(values, timestamp)
+
+    const missing = []
+    if (input.heel == null) missing.push('heel')
+    if (o.twd == null) missing.push('heading')
+    status('running', `${config.mode === 'shadow' ? 'Shadow' : 'Live'} — TWA ${Math.abs(o.twa).toFixed(1)}°, TWS ${o.tws.toFixed(1)} kn, STW ${o.stw.toFixed(2)} kn` +
+      (missing.length ? ` · no ${missing.join(' or ')}` : ''))
+  }
+
+  function onDelta (delta) {
+    const now = Date.now()
+    let windChanged = false
+    let windTimestamp = null
+    for (const update of (delta.updates || [])) {
+      if (isOwnSource(update.$source)) continue
+      for (const v of (update.values || [])) {
+        const group = INPUT_OF[v.path]
+        if (!group || v.value == null) continue
+        if (v.path !== 'navigation.attitude' && !Number.isFinite(v.value)) continue
+
+        const src = String(update.$source || '')
+        ;(sourcesSeen[group] = sourcesSeen[group] || new Set()).add(src)
+        const wanted = config.sources[group]
+        if (wanted && src !== wanted) continue
+
+        if (v.path === 'navigation.speedThroughWater' && config.mode === 'replace' && isStwEcho(v.value)) {
+          if (!loopWarned) {
+            loopWarned = true
+            app.error(`Loop guard mismatch: received STW this plugin published, but its $source was "${src}" rather than "${plugin.id}". Skipping it — set the STW source in Settings.`)
+          }
+          continue
+        }
+
+        latest[v.path] = { value: v.value, source: src, at: now }
+        if (group === 'apparentWind') { windChanged = true; windTimestamp = update.timestamp }
+        if (group === 'stw') onStw(v.value, update.timestamp, now)
+      }
+    }
+    if (windChanged) onWind(windTimestamp, now)
+  }
+
+  function startWith (cfg) {
+    stopEverything()
+    config = cfg
+    latest = {}
+    sourcesSeen = {}
+    lastResult = null
+    running = true
+
+    if (config.mode === 'shadow') {
+      // The shadow paths are not in the Signal K schema; give consumers their units.
+      app.handleMessage(plugin.id, {
+        updates: [{
+          meta: Object.keys(OUTPUTS).map(k => ({
+            path: OUTPUTS[k].path + SHADOW_SUFFIX,
+            value: { description: OUTPUTS[k].description, ...(OUTPUTS[k].units ? { units: OUTPUTS[k].units } : {}) }
+          }))
+        }]
+      })
+    }
+
+    // sourcePolicy 'all': every source at full rate, chosen here rather than by
+    // priorities, which this plugin's own output may outrank in replace mode.
+    const subscription = {
+      context: 'vessels.self',
+      sourcePolicy: 'all',
+      subscribe: Object.keys(INPUT_OF).map(path => ({ path }))
+    }
+
+    function trySubscribe (attempt) {
+      retryTimer = null
+      if (!running) return
+      const sm = app.subscriptionmanager
+      if (sm && typeof sm.subscribe === 'function') {
+        try {
+          sm.subscribe(subscription, unsubscribes, err => app.setPluginError(String(err)), onDelta)
+          status('waiting', 'Waiting for apparent wind')
+          return
+        } catch (e) {
+          app.error(`subscribe failed: ${e.message}`)
+        }
+      }
+      if (attempt >= 20) {
+        app.setPluginError('Could not subscribe — subscriptionmanager unavailable')
+        return
+      }
+      retryTimer = setTimeout(() => trySubscribe(attempt + 1), 500)
+    }
+
+    const on = CORRECTIONS.filter(c => config.corrections[c.id] && config.corrections[c.id].enabled).map(c => c.id)
+    app.debug(`started in ${config.mode} mode; corrections on: ${on.join(', ') || 'none'}`)
+    status('starting', `Starting — ${config.mode} mode`)
+    trySubscribe(0)
+  }
+
+  function stopEverything () {
+    running = false
+    if (retryTimer) { clearTimeout(retryTimer); retryTimer = null }
+    unsubscribes.forEach(f => f())
+    unsubscribes = []
+  }
+
+  plugin.start = function (options) {
+    const { config: cfg, errors } = normalizeConfig(options || {})
+    if (errors.length) {
+      app.setPluginError(`Configuration: ${errors.join('; ')}`)
+      return
+    }
+    startWith(cfg)
+  }
+
+  plugin.stop = function () {
+    stopEverything()
+    app.setPluginStatus('Stopped')
+  }
+
+  // ---- API for the webapp -------------------------------------------------
+
+  function liveSnapshot () {
+    const now = Date.now()
+    const inputs = {}
+    for (const [path, l] of Object.entries(latest)) inputs[path] = { source: l.source, ageMs: now - l.at }
+    return {
+      running,
+      status: lastStatus,
+      mode: config ? config.mode : null,
+      ageMs: lastResult ? now - lastResultAt : null,
+      result: lastResult,
+      inputs,
+      sourcesSeen: Object.fromEntries(Object.entries(sourcesSeen).map(([k, s]) => [k, Array.from(s).sort()])),
+      outputPaths: config ? Object.fromEntries(Object.keys(OUTPUTS).map(k => [k, outPath(k)])) : {}
+    }
+  }
+
+  function readBody (req) {
+    if (req.body && typeof req.body === 'object') return Promise.resolve(req.body)
+    return new Promise((resolve, reject) => {
+      let s = ''
+      req.on('data', d => { s += d })
+      req.on('end', () => { try { resolve(s ? JSON.parse(s) : {}) } catch (e) { reject(e) } })
+      req.on('error', reject)
+    })
+  }
+
+  plugin.registerWithRouter = function (router) {
+    router.get('/config', (req, res) => {
+      res.set('Cache-Control', 'no-store')
+      let stored = {}
+      try { stored = app.readPluginOptions().configuration || {} } catch (e) {}
+      res.json({ config: config || normalizeConfig(stored).config, defaults: DEFAULTS })
+    })
+
+    router.put('/config', async (req, res) => {
+      let body
+      try { body = await readBody(req) } catch (e) { return res.status(400).json({ errors: ['body is not valid JSON'] }) }
+      const { config: cfg, errors } = normalizeConfig(body)
+      if (errors.length) return res.status(400).json({ errors })
+      app.savePluginOptions(cfg, err => {
+        if (err) return res.status(500).json({ errors: [`could not save: ${err.message || err}`] })
+        startWith(cfg)
+        res.json({ config: cfg })
+      })
+    })
+
+    router.get('/live', (req, res) => {
+      res.set('Cache-Control', 'no-store')
+      res.json(liveSnapshot())
+    })
+  }
+
+  return plugin
+}
+
+// JSON schema for the admin "Plugin Config" form, built from the defaults so the form
+// is a working fallback editor and a fresh install starts from this boat's values.
+function schemaFor (defaults) {
+  const titles = {
+    mode: 'Output: shadow publishes …Corrected paths alongside the instruments; replace publishes the standard paths (rank this plugin first in Source Priorities)',
+    variation: 'Magnetic variation (degrees, east positive)',
+    sources: 'Input sources ($source to read; blank = any source except this plugin)',
+    corrections: 'Corrections (easier to edit in the Performance Processor webapp)'
+  }
+  function node (value, title) {
+    if (Array.isArray(value)) return { type: 'array', title, items: { type: 'number' }, default: value }
+    if (value && typeof value === 'object') {
+      return {
+        type: 'object',
+        title,
+        properties: Object.fromEntries(Object.entries(value).map(([k, v]) => [k, node(v, k)]))
+      }
+    }
+    if (typeof value === 'boolean') return { type: 'boolean', title, default: value }
+    if (typeof value === 'number') return { type: 'number', title, default: value }
+    return { type: 'string', title, default: value }
+  }
+  const schema = node(defaults)
+  for (const [k, t] of Object.entries(titles)) schema.properties[k].title = t
+  schema.properties.mode.enum = ['shadow', 'replace']
+  return schema
+}
+
+// Exposed for the test suite only; not part of the Signal K plugin API.
+module.exports._internals = { schemaFor, OUTPUTS, INPUTS, SHADOW_SUFFIX }

package/lib/defaults.js

@@ -0,0 +1,47 @@
+'use strict'
+
+// Defaults for this boat, fitted to the 2025 races and checked against Jan–Mar 2026
+// (see the README). Every value can be changed in the webapp; these are what a fresh
+// install starts from.
+
+const TWS_BINS = [5, 10, 15, 20, 25, 30]
+
+const DEFAULTS = {
+  mode: 'shadow', // 'shadow' publishes …Corrected paths; 'replace' publishes the standard paths
+  variation: 12.8, // degrees, east positive; Sydney
+  sources: { apparentWind: '', stw: '', heading: '', attitude: '', gps: '' }, // '' = any but this plugin
+  corrections: {
+    // Knots added to STW: linearity by speed, plus heel correction by |heel|.
+    // The 185-cell heel x STW table reduced to two rows (every cell within 0.03 kn).
+    stw: {
+      enabled: true,
+      linearity: { stw: [0.5, 1, 2, 3, 4, 6, 8.5], add: [0.58, 0.61, 0.38, 0.19, 0.09, 0.02, 0.00] },
+      heel: { heel: [0, 10, 20, 30, 35], add: [0.00, -0.03, -0.13, -0.29, -0.29] }
+    },
+    // Leeway (degrees) = K x heel / STW^2, one K for every sail: downwind heel is
+    // small, so leeway there is near zero whatever K is.
+    leeway: { enabled: true, k: 7.9446 },
+    // Degrees added to |TWA| by TWS; negative = TWA was reading too wide.
+    // Rows are blended by TWA: upwind in full to angles.upwind, reach at angles.reach,
+    // downwind from angles.downwind. The TWS table shares these angles.
+    twa: {
+      enabled: true,
+      tws: TWS_BINS.slice(),
+      upwind: [-12.0, -13.4, -5.7, -4.3, -4.3, -4.3],
+      reach: [-10.7, -10.7, -10.7, -10.7, -10.7, -10.7],
+      downwind: [-4.2, -3.5, -1.6, -1.3, -1.3, -1.3],
+      angles: { upwind: 70, reach: 100, downwind: 130 }
+    },
+    // Percent applied to TWS by TWS, same rows and blending as the TWA table.
+    // Off by default: light air fitted to implausible values, so it is zeroed here.
+    tws: {
+      enabled: false,
+      tws: TWS_BINS.slice(),
+      upwind: [0, 0, 0, 0, 0, 0],
+      reach: [0, 0, 0, 0, 0, 0],
+      downwind: [0, 0, -11.1, -14.4, -14.4, -14.4]
+    }
+  }
+}
+
+module.exports = { DEFAULTS }