signalk-polar-performance-plugin 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -6,6 +6,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+### Changed
+- Requires signalk-server >=2.35.0 for the upstream metadata-first subscription fix ([SignalK/signalk-server#3216](https://github.com/SignalK/signalk-server/pull/3216)).
+- Requires signalkutilities >=3.2.0 (subscriptions without cached-value replay, smoothers cleared by `null`) and polar-math >=1.1.1 (in-irons cutoff relative to the 25° curve endpoint).
+- Read-only Signal K users can now access live values, status, active-polar display metadata, and polar curve queries used by the plotter. Curve resolution is bounded to at most 181 samples per request; settings remain administrator-only.
+- Clearer `meta` descriptions for `performance.optimumWindAngle` (where the optimal angle comes from, what zero means) and `performance.polarVelocityMadeGood` (the polar's prediction, not the actual VMG).
+
+### Fixed
+- Removed idle-triggered input resubscriptions to avoid replaying cached values during sensor outages. Idle/stale warnings remain, and existing subscriptions receive data when the source resumes. Source changes and heading toggles still update subscriptions normally.
+- Heading inputs enabled at runtime now use the same lifecycle-warning callbacks as heading inputs enabled at startup.
+- When sailing in irons, all values taken from the polar (polar speed, target speed, target and polar VMG, beat/gybe angles and VMGs, max speed) and the percentages based on them are now cleared consistently. Previously some were cleared, some kept showing and VMG % froze on its last value. This also prevents spikes in the performance percentages while tacking. Steering advice (target angle, optimum wind angle, opposite tack heading) stays available so you can see how far to bear away. Everything returns as soon as you leave irons ([#38](https://github.com/htool/signalk-polar-performance-plugin/issues/38)).
+- When pinching (between the in-irons cutoff and the beat angle), all outputs keep being published.
+- Actual VMG keeps updating in irons instead of freezing on its last value.
+- Performance outputs whose inputs become unavailable (for example missing boat speed, heading or polar targets) are now cleared instead of showing a stale value.
+
 ## [2.0.0] - 2026-09-09
 
 ### Added

package/README.md

@@ -16,6 +16,8 @@ When a polar lookup cannot be completed or required instrument data is missing/s
 
 ## Installation
 
+Requires signalk-server >=2.35.0 for reliable metadata-first input subscriptions. Idle/stale warnings do not trigger resubscriptions; existing subscriptions receive data when the source resumes.
+
 Install both plugins from the Signal K App Store, or via npm:
 
 ```sh
@@ -27,6 +29,12 @@ Then restart Signal K and enable both plugins in **Server → Plugin Config**. W
 
 ---
 
+## HTTP endpoint access
+
+Signal K read-only users can view live values, status, active-polar display metadata, and polar curves used by the plotter. Plugin settings, including settings reads, require administrator access. Anonymous access remains controlled by the server's security configuration and is not enabled by this plugin. See the [developer reference](./docs/developer-reference.md#rest-api) for the endpoint list and access policies.
+
+---
+
 ## Quick start
 
 1. Open the **Polar Management** webapp and import or select an active polar (and optionally set a performance factor).
@@ -156,6 +164,23 @@ Requires `navigation.headingTrue` to be available.
 
 Useful when you want downstream instruments to use the same smoothed values that drive the performance calculation.
 
+### Output handling when pinching and in irons
+
+The polar defines two zones above the beat angle:
+
+- **Pinching** — TWA is between the in-irons cutoff and the beat angle. The boat is still sailing, and the polar curve is extended smoothly towards zero speed. **All outputs are published.**
+- **In irons** — TWA is below the cutoff, which lies 80 % of the way from 25° to the beat angle (for example ~38.6° for a 42° beat angle). The polar has no sailing state here, so the outputs are handled per kind:
+
+| Kind | Outputs | In irons |
+|------|---------|----------|
+| Measured | `velocityMadeGood`, `angleTrueWaterDamped`, `boatSpeedDamped` | Published |
+| Steering advice | `targetAngle`, `optimumWindAngle`, `tackTrue` | Published, so you can see how far to bear away |
+| Polar values and ratios based on them | `polarSpeed`, `polarSpeedRatio`, `targetSpeed`, `targetVelocityMadeGood`, `polarVelocityMadeGood`, `polarVelocityMadeGoodRatio`, `beatAngle`, `gybeAngle`, `beatAngleVelocityMadeGood`, `gybeAngleVelocityMadeGood`, `maxSpeed`, `maxSpeedAngle` | Set to `null` |
+
+Clearing the polar values in irons also prevents spikes in the performance ratios while tacking. Through a tack the boat carries its speed head-to-wind while the polar speed falls towards zero, which would briefly drive the ratios to meaningless values. As soon as you bear away out of irons, all values return on the next wind update.
+
+A value is set to `null` once when it becomes unavailable and is not repeated until it returns.
+
 ---
 
 ## Managing polars
@@ -222,8 +247,8 @@ The webapp shows warnings whenever something prevents accurate calculation:
 | *True wind angle — no data* | `environment.wind.angleTrueWater` is not arriving.  |
 | *Boat speed — no data* | `navigation.speedThroughWater` (or SOG) is not arriving.  |
 | *No active polar* | No `polars.activePolar` is published. Select an active polar in the polar management webapp. |
-| *Sailing in irons* | TWA is below the minimum angle in the polar. No output is produced. |
-| *Pinching* | TWA is between the minimum polar angle and the beat angle. Values come from the extrapolated beat zone. |
+| *Sailing in irons* | TWA is below the in-irons cutoff. Polar values and the ratios based on them are set to `null`; measured values and steering advice keep updating. See [Output handling when pinching and in irons](#output-handling-when-pinching-and-in-irons). |
+| *Pinching* | TWA is between the in-irons cutoff and the beat angle. All outputs are published; values come from the extrapolated beat zone. |
 | *Extrapolated beyond run angle* | TWA is deeper than the run angle. Values come from the cosine-VMG extrapolation model. |
 | *Wind speed below/above polar range* | TWS is outside the range covered by the polar. Values are extrapolated from the nearest TWS entry. |
 

package/docs/developer-reference.md

@@ -25,16 +25,21 @@ unavailable, the last successfully loaded polar is kept until a valid update arr
 
 The plugin exposes a REST API under `/plugins/signalk-polar-performance-plugin/`. Authentication
 follows Signal K server rules; the same session cookie used by the webapp works for direct API calls.
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/live` | Current smoothed TWS, TWA, BSP, polar speed, and polar state. |
-| `GET` | `/status` | Full snapshot: raw inputs, smoothed inputs, and all enabled output values. |
-| `GET` | `/meta` | Display unit metadata for all fields, plus a read-only summary of the active polar (name, boatType, sailnumber, year, source) and performance factor. |
-| `GET` | `/settings` | Current plugin settings (smoother, output toggles, speed source — no polar selection). |
-| `PUT` | `/settings` | Update settings. Body: JSON object with changed keys only. |
-| `GET` | `/polar/axes/tws` | TWS axis of the currently active polar. 404 if none is active. |
-| `GET` | `/polar/queries/curve?tws=&step=` | Interpolated curve for the active polar at the given TWS, with beat/run markers, performance factor already applied. |
+The endpoints marked **Read-only** are available to users with Signal K read-only permission.
+Anonymous access is controlled only by the server's `allow_readonly` setting and is not enabled by
+the plugin. Curve queries are capped at 181 sample angles per request (minimum step 1°).
+`/meta` includes the active polar's boat type, sail number, source, and free-text notes, so those
+fields are also available to read-only users.
+
+| Method | Path | Description | Access |
+|--------|------|-------------|--------|
+| `GET` | `/live` | Current smoothed TWS, TWA, BSP, polar speed, and polar state. | Read-only |
+| `GET` | `/status` | Full snapshot: raw inputs, smoothed inputs, and all enabled output values. | Read-only |
+| `GET` | `/meta` | Display unit metadata for all fields, plus a read-only summary of the active polar (name, boatType, sailnumber, year, source) and performance factor. | Read-only |
+| `GET` | `/settings` | Current plugin settings (smoother, output toggles, speed source — no polar selection). | Administrator |
+| `PUT` | `/settings` | Update settings. Body: JSON object with changed keys only. | Administrator |
+| `GET` | `/polar/axes/tws` | TWS axis of the currently active polar. 404 if none is active. | Read-only |
+| `GET` | `/polar/queries/curve?tws=&step=` | Interpolated curve for the active polar at the given TWS, with beat/run markers, performance factor already applied. `step` must be at least 1° and at most π/2 radians. | Read-only |
 
 The authoritative machine-readable schema for the two `/polar/*` endpoints is in
 [../openApi.json](../openApi.json).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-polar-performance-plugin",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Calculates live sailing performance from the active polar selected in a polar management plugin (e.g. signalk-polar-management).",
   "main": "plugin/index.js",
   "exports": {
@@ -19,15 +19,15 @@
   ],
   "engines": {
     "node": ">=20",
-    "signalk-server": ">=2.28.0"
+    "signalk-server": ">=2.35.0"
   },
   "scripts": {
     "test": "node --test test/**/*.test.js",
     "prepublishOnly": "npm test"
   },
   "dependencies": {
-    "polar-math": "^1.0.0",
-    "signalkutilities": "^3.1.3"
+    "polar-math": "^1.1.1",
+    "signalkutilities": "^3.2.0"
   },
   "peerDependencies": {
     "signalk-polar-management": ">=1.0.0"

package/plugin/index.js

@@ -14,8 +14,6 @@ const {
 
 const CURRENT_SETTINGS_VERSION = 2
 
-const STALE_RESUBSCRIBE_PERIOD = 60000 // ms — idle period before live input subscriptions are re-established
-
 const DEFAULT_SETTINGS = {
   settingsVersion: CURRENT_SETTINGS_VERSION,
   showAllTwsLines: true,
@@ -85,7 +83,7 @@ module.exports = (app) => {
   function _setLifecycleWarning(id, status, path) {
     const safePath = path || 'unknown path'
     const message = status === 'idle'
-      ? `Input ${id} is idle on ${safePath}; resubscribing`
+      ? `Input ${id} is idle on ${safePath}`
       : `Input ${id} is stale on ${safePath}`
     lifecycleWarningMap.set(id, {
       id,
@@ -105,9 +103,8 @@ module.exports = (app) => {
       .sort((a, b) => b.updatedAt - a.updatedAt)
   }
 
-  function _wireHandlerWatchdog({ id, getPath, unsubscribe, subscribe }) {
+  function _wireHandlerWatchdog({ id, getPath }) {
     return {
-      idlePeriod: STALE_RESUBSCRIBE_PERIOD,
       onDelta: () => {
         _clearLifecycleWarning(id)
       },
@@ -120,14 +117,36 @@ module.exports = (app) => {
       onIdle: () => {
         if (!isRunning) return
         const path = getPath()
-        app.debug(`[${plugin.id}] idle input ${id} on ${path}; resubscribing`)
+        app.debug(`[${plugin.id}] idle input ${id} on ${path}`)
         _setLifecycleWarning(id, 'idle', path)
-        unsubscribe()
-        subscribe()
       }
     }
   }
 
+  // Ratios below this denominator (m/s) are numerically meaningless (near-zero wind).
+  const MIN_RATIO_DENOMINATOR = 0.01
+
+  function finiteOrNull(value) {
+    return Number.isFinite(value) ? value : null
+  }
+
+  function signed(angle, port) {
+    return angle === null ? null : angle * port
+  }
+
+  function ratio(numerator, denominator) {
+    if (!Number.isFinite(numerator) || !Number.isFinite(denominator)) return null
+    return denominator > MIN_RATIO_DENOMINATOR ? numerator / denominator : null
+  }
+
+  function publishNulls(paths) {
+    if (paths.length === 0) return
+    paths.forEach(path => { lastOutputs[path] = null })
+    app.handleMessage(plugin.id, {
+      updates: [{ values: paths.map(path => ({ path, value: null })) }]
+    })
+  }
+
   function getSmootherClass(type) {
     switch (type) {
       case 'None':          return BaseSmoother
@@ -290,9 +309,8 @@ module.exports = (app) => {
           SmootherClass: SC,
           smootherOptions: so,
           ..._wireHandlerWatchdog({
-            get path() { return hdgSmoother?.handler?.path ?? 'navigation.headingTrue' },
-            unsubscribe: () => hdgSmoother?.unsubscribe(),
-            subscribe: () => hdgSmoother?.subscribe(false, true),
+            id: 'hdg.smoothed',
+            getPath: () => hdgSmoother?.handler?.path ?? 'navigation.headingTrue',
           })
         })
       } else if (!settings.tackTrue && hdgSmoother) {
@@ -309,11 +327,7 @@ module.exports = (app) => {
     const disabledPaths = keys
       .filter(k => OUTPUT_PATHS[k] && !settings[k])
       .flatMap(k => OUTPUT_PATHS[k])
-    if (disabledPaths.length) {
-      app.handleMessage(plugin.id, {
-        updates: [{ values: disabledPaths.map(path => ({ path, value: null })) }]
-      })
-    }
+    publishNulls(disabledPaths)
   }
 
   // ---------------------------------------------------------------------------
@@ -322,10 +336,7 @@ module.exports = (app) => {
   // ---------------------------------------------------------------------------
 
   function nullifyOutputs() {
-    const allPaths = Object.values(OUTPUT_PATHS).flat()
-    app.handleMessage(plugin.id, {
-      updates: [{ values: allPaths.map(path => ({ path, value: null })) }]
-    })
+    publishNulls(Object.values(OUTPUT_PATHS).flat())
   }
 
   // ---------------------------------------------------------------------------
@@ -339,164 +350,127 @@ module.exports = (app) => {
     const wind = windSmoother.polarValue
     const TWS = wind.magnitude
     const TWAsigned = wind.angle
-    if (!Number.isFinite(TWS) || !Number.isFinite(TWAsigned)) return
+    const windValid = Number.isFinite(TWS) && Number.isFinite(TWAsigned)
 
     // TWA is always positive for polar lookups; sign is tracked via `port`
-    const TWA = Math.abs(TWAsigned)
+    const TWA = windValid ? Math.abs(TWAsigned) : null
     const port = TWAsigned < 0 ? -1 : 1
-    const BSP = bspSmoother ? bspSmoother.value : null
-    const HDG = hdgSmoother ? hdgSmoother.value : null
+    const BSP = finiteOrNull(bspSmoother ? bspSmoother.value : null)
+    const HDG = finiteOrNull(hdgSmoother ? hdgSmoother.value : null)
 
     const values = []
     const metas = []
 
-    function add(skPath, value, unit, description) {
-      if (!Number.isFinite(value)) return
-      values.push({ path: skPath, value })
-      if (!metaSentPaths.has(skPath)) {
-        metas.push({ path: skPath, value: { units: unit, description } })
-        metaSentPaths.add(skPath)
-      }
-    }
-
-    // Always emit smoothed inputs
-    if (settings.smoothedInputs) {
-      add('environment.wind.angleTrueWaterDamped', TWAsigned, 'rad',
-        'True Wind Angle after smoothing, negative to port.')
-      if (Number.isFinite(BSP)) {
-        add('performance.boatSpeedDamped', BSP, 'm/s', 'Boat speed after smoothing.')
+    // Each enabled output is either published or explicitly cleared, so
+    // consumers never keep seeing a frozen value once its inputs disappear.
+    // Nulls are only sent on the transition to unavailable to limit bus traffic.
+    function output(settingKey, skPath, value, unit, description) {
+      if (!settings[settingKey]) return
+      if (Number.isFinite(value)) {
+        values.push({ path: skPath, value })
+        if (!metaSentPaths.has(skPath)) {
+          metas.push({ path: skPath, value: { units: unit, description } })
+          metaSentPaths.add(skPath)
+        }
+      } else if (lastOutputs[skPath] !== null) {
+        values.push({ path: skPath, value: null })
       }
     }
 
-    // Polar lookups
-    const isUpwind = TWA < Math.PI / 2
-    const { value: targets } = polar.targetsAt({ tws: TWS, performanceFactor })
-    const beatAngle = targets?.beat?.twa ?? null
-    const runAngle  = targets?.run?.twa ?? null
-    const beatVMG   = targets?.beat?.vmg ?? null
-    const runVMG    = targets?.run?.vmg ?? null
+    // Output classes:
+    // - measured values (actual VMG, damped inputs) are published whenever their inputs are valid;
+    // - steering advice (target angle, optimum wind angle, tack heading) is always published,
+    //   including in irons, where it says how far to bear away;
+    // - all other polar values and polar ratios are cleared in irons, where the polar says nothing
+    //   about the boat's current state.
+    const isUpwind = windValid && TWA < Math.PI / 2
+    const speedResult = windValid ? polar.speedAt({ tws: TWS, twa: TWA, performanceFactor }) : null
+    const inIrons = speedResult?.state?.twa === 'in_irons'
+    const fromPolar = value => (inIrons ? null : finiteOrNull(value))
+
+    const targets = windValid ? polar.targetsAt({ tws: TWS, performanceFactor }).value : null
+    const adviceBeatAngle = finiteOrNull(targets?.beat?.twa)
+    const adviceRunAngle  = finiteOrNull(targets?.run?.twa)
+    const adviceAngle     = isUpwind ? adviceBeatAngle : adviceRunAngle
+
+    const beatAngle = fromPolar(adviceBeatAngle)
+    const runAngle  = fromPolar(adviceRunAngle)
+    const beatVMG   = fromPolar(targets?.beat?.vmg)
+    const runVMG    = fromPolar(targets?.run?.vmg)
     const targetAngle = isUpwind ? beatAngle : runAngle
     const targetVMG   = isUpwind ? beatVMG   : runVMG
+    const maxSpeed = fromPolar(targets?.maxSpeed?.speed)
+    const maxSpeedAngle = maxSpeed === null ? null : finiteOrNull(targets?.maxSpeed?.twa)
 
-    if (Number.isFinite(beatAngle)) {
-      if (settings.beatAngle) {
-        add('performance.beatAngle', beatAngle * port, 'rad',
-          'Optimal beat angle for current TWS, negative to port.')
-      }
-      if (settings.targetTWA && isUpwind) {
-        add('performance.targetAngle', beatAngle * port, 'rad',
-          'Target TWA — auto-switches between beat and run, negative to port.')
-      }
-    }
+    // Polar speed at the current TWA is also unavailable outside the polar's angle range
+    const speedAtTwa = speedResult?.value
+    const polarSpeed = Number.isFinite(speedAtTwa) && speedAtTwa > 0 ? speedAtTwa : null
 
-    if (Number.isFinite(runAngle)) {
-      if (settings.beatAngle) {
-        add('performance.gybeAngle', runAngle * port, 'rad',
-          'Optimal run/gybe angle for current TWS, negative to port.')
-      }
-      if (settings.targetTWA && !isUpwind) {
-        add('performance.targetAngle', runAngle * port, 'rad',
-          'Target TWA — auto-switches between beat and run, negative to port.')
-      }
-    }
-
-    if (Number.isFinite(beatVMG)) {
-      if (settings.beatVMG) {
-        add('performance.beatAngleVelocityMadeGood', beatVMG, 'm/s',
-          'Optimal beat VMG for current TWS.')
-      }
-      if (settings.targetTWA && isUpwind) {
-        add('performance.targetVelocityMadeGood', beatVMG, 'm/s',
-          'Target VMG — auto-switches between beat and run.')
-      }
-    }
-
-    if (Number.isFinite(runVMG)) {
-      if (settings.beatVMG) {
-        add('performance.gybeAngleVelocityMadeGood', runVMG, 'm/s',
-          'Optimal run VMG for current TWS.')
-      }
-      if (settings.targetTWA && !isUpwind) {
-        add('performance.targetVelocityMadeGood', runVMG, 'm/s',
-          'Target VMG — auto-switches between beat and run.')
-      }
-    }
-
-    // Optimum wind angle: angular difference between current TWA and optimal angle
-    if (settings.optimumWindAngle) {
-      if (isUpwind && Number.isFinite(beatAngle)) {
-        add('performance.optimumWindAngle', (TWA - beatAngle) * port, 'rad',
-          'Difference between TWA and beat angle, negative to port.')
-      } else if (!isUpwind && Number.isFinite(runAngle)) {
-        add('performance.optimumWindAngle', (runAngle - TWA) * port * -1, 'rad',
-          'Difference between TWA and run angle, negative to port.')
-      }
-    }
-
-    // Polar speed and performance ratios
-    const { value: polarSpeed } = polar.speedAt({ tws: TWS, twa: TWA, performanceFactor })
-    if (Number.isFinite(polarSpeed) && polarSpeed > 0) {
-      if (settings.polarSpeed) {
-        add('performance.polarSpeed', polarSpeed, 'm/s',
-          'Polar chart boat speed for current TWS and TWA.')
-
-        // Target speed: only meaningful when sailing within the polar range
-        if (Number.isFinite(targetAngle) && Number.isFinite(targetVMG)) {
-          const cosTarget = Math.abs(Math.cos(targetAngle))
-          if (cosTarget > 0.01) {
-            add('performance.targetSpeed', targetVMG / cosTarget, 'm/s',
-              'Boat speed needed to achieve target VMG at the optimal angle.')
-          }
-        }
+    const targetCos = targetAngle === null ? 0 : Math.abs(Math.cos(targetAngle))
+    const targetSpeed = targetVMG !== null && targetVMG >= 0 && targetCos > 0.01
+      ? targetVMG / targetCos
+      : null
 
-        if (Number.isFinite(BSP)) {
-          add('performance.polarSpeedRatio', BSP / polarSpeed, 'ratio',
-            'Actual boat speed divided by polar speed.')
-        }
-      }
+    const vmg = windValid && BSP !== null ? BSP * Math.cos(TWA) : null
+    const vmgRatio = ratio(vmg === null ? null : Math.abs(vmg), targetVMG)
 
-      if (Number.isFinite(BSP)) {
-        if (settings.VMG && Number.isFinite(targetVMG) && targetVMG > 0) {
-          const vmg = BSP * Math.cos(TWA)
-          add('performance.velocityMadeGood', vmg, 'm/s',
-            'Actual VMG based on current boat speed and TWA.')
-          add('performance.polarVelocityMadeGood', targetVMG, 'm/s',
-            'Polar VMG for current TWS.')
-          if (Number.isFinite(vmg)) {
-            add('performance.polarVelocityMadeGoodRatio', Math.abs(vmg) / targetVMG, 'ratio',
-              'Actual VMG divided by polar VMG.')
-          }
-        }
-      }
-    } else {
-      // Clear these paths so no stale non-zero value remains on the SK bus
-      if (settings.polarSpeed) {
-        values.push({ path: 'performance.polarSpeed', value: null })
-        values.push({ path: 'performance.polarSpeedRatio', value: null })
-        values.push({ path: 'performance.targetSpeed', value: null })
-      }
-    }
-
-    // Max speed for current TWS
-    if (settings.maxSpeed) {
-      const maxSpeed = targets?.maxSpeed?.speed ?? null
-      const maxSpeedAngle = targets?.maxSpeed?.twa ?? null
-      if (Number.isFinite(maxSpeed)) {
-        add('performance.maxSpeed', maxSpeed, 'm/s',
-          'Maximum polar boat speed for current TWS.')
-        add('performance.maxSpeedAngle', maxSpeedAngle * port, 'rad',
-          'TWA at which maximum speed is achieved, negative to port.')
-      }
-    }
+    let optimumWindAngle = null
+    if (isUpwind && adviceBeatAngle !== null) optimumWindAngle = (TWA - adviceBeatAngle) * port
+    else if (windValid && !isUpwind && adviceRunAngle !== null) optimumWindAngle = (adviceRunAngle - TWA) * port * -1
 
-    // Opposite tack heading
-    if (settings.tackTrue && Number.isFinite(HDG) && Number.isFinite(targetAngle)) {
-      let tack = port < 0 ? HDG - targetAngle : HDG + targetAngle
+    let tack = null
+    if (HDG !== null && adviceAngle !== null) {
+      tack = port < 0 ? HDG - adviceAngle : HDG + adviceAngle
       tack = ((tack % (2 * Math.PI)) + 2 * Math.PI) % (2 * Math.PI)
-      add('performance.tackTrue', tack, 'rad',
-        'Opposite tack heading relative to true north.')
     }
 
+    output('smoothedInputs', 'environment.wind.angleTrueWaterDamped', windValid ? TWAsigned : null, 'rad',
+      'True Wind Angle after smoothing, negative to port.')
+    output('smoothedInputs', 'performance.boatSpeedDamped', BSP, 'm/s',
+      'Boat speed after smoothing.')
+
+    output('beatAngle', 'performance.beatAngle', signed(beatAngle, port), 'rad',
+      'Optimal beat angle for current TWS, negative to port.')
+    output('beatAngle', 'performance.gybeAngle', signed(runAngle, port), 'rad',
+      'Optimal run/gybe angle for current TWS, negative to port.')
+
+    output('beatVMG', 'performance.beatAngleVelocityMadeGood', beatVMG, 'm/s',
+      'Optimal beat VMG for current TWS.')
+    output('beatVMG', 'performance.gybeAngleVelocityMadeGood', runVMG, 'm/s',
+      'Optimal run VMG for current TWS.')
+
+    output('targetTWA', 'performance.targetAngle', signed(adviceAngle, port), 'rad',
+      'Target TWA — auto-switches between beat and run, negative to port.')
+    output('targetTWA', 'performance.targetVelocityMadeGood', targetVMG, 'm/s',
+      'Target VMG — auto-switches between beat and run.')
+
+    output('optimumWindAngle', 'performance.optimumWindAngle', optimumWindAngle, 'rad',
+      isUpwind
+        ? 'Difference between TWA and beat angle, negative to port. The optimal angle comes from the polar for the current true wind speed; zero means sailing at the optimal angle.'
+        : 'Difference between TWA and run angle, negative to port. The optimal angle comes from the polar for the current true wind speed; zero means sailing at the optimal angle.')
+
+    output('polarSpeed', 'performance.polarSpeed', polarSpeed, 'm/s',
+      'Polar chart boat speed for current TWS and TWA.')
+    output('polarSpeed', 'performance.targetSpeed', targetSpeed, 'm/s',
+      'Boat speed needed to achieve target VMG at the optimal angle.')
+    output('polarSpeed', 'performance.polarSpeedRatio', ratio(BSP, polarSpeed), 'ratio',
+      'Actual boat speed divided by polar speed.')
+
+    output('VMG', 'performance.velocityMadeGood', vmg, 'm/s',
+      'Actual VMG based on current boat speed and TWA.')
+    output('VMG', 'performance.polarVelocityMadeGood', targetVMG, 'm/s',
+      "Polar VMG for current TWS. The VMG predicted by the polar, not the vessel's actual VMG.")
+    output('VMG', 'performance.polarVelocityMadeGoodRatio', vmgRatio, 'ratio',
+      'Actual VMG divided by polar VMG.')
+
+    output('maxSpeed', 'performance.maxSpeed', maxSpeed, 'm/s',
+      'Maximum polar boat speed for current TWS.')
+    output('maxSpeed', 'performance.maxSpeedAngle', signed(maxSpeedAngle, port), 'rad',
+      'TWA at which maximum speed is achieved, negative to port.')
+
+    output('tackTrue', 'performance.tackTrue', tack, 'rad',
+      'Opposite tack heading relative to true north.')
+
     if (values.length === 0) return
 
     if (metas.length > 0) {
@@ -505,11 +479,8 @@ module.exports = (app) => {
 
     app.handleMessage(plugin.id, { updates: [{ values }] })
 
-    // Snapshot enabled outputs for /status endpoint
-    // Each output key maps to an array of { path, value } computed this cycle
-    const outputSnapshot = {}
-    values.forEach(({ path, value }) => { outputSnapshot[path] = value })
-    Object.assign(lastOutputs, outputSnapshot)
+    // Snapshot outputs for the /status endpoint and null-transition tracking
+    values.forEach(({ path, value }) => { lastOutputs[path] = value })
   }
 
   // ---------------------------------------------------------------------------
@@ -585,12 +556,12 @@ module.exports = (app) => {
 
       // ---- Active polar curve queries (read-only — for the webapp's polar canvas) --
 
-      router.get('/polar/axes/tws', (req, res) => {
+      router.access('readonly').get('/polar/axes/tws', (req, res) => {
         if (!polar) return res.status(404).json({ error: 'No active polar selected' })
         res.json(getPolarTwsValues())
       })
 
-      router.get('/polar/queries/curve', (req, res) => {
+      router.access('readonly').get('/polar/queries/curve', (req, res) => {
         if (!polar) return res.status(404).json({ error: 'No active polar selected' })
         try {
           const tws = parseFloat(req.query.tws)
@@ -598,8 +569,8 @@ module.exports = (app) => {
             return res.status(400).json({ error: "'tws' query parameter required (m/s)" })
           }
           const stepRad = parseFloat(req.query.step) || (2 * Math.PI / 180)
-          if (!Number.isFinite(stepRad) || stepRad <= 0 || stepRad > Math.PI / 2) {
-            return res.status(400).json({ error: "'step' must be between 0 and π/2 radians" })
+          if (!Number.isFinite(stepRad) || stepRad < Math.PI / 180 || stepRad > Math.PI / 2) {
+            return res.status(400).json({ error: "'step' must be between 1° and π/2 radians" })
           }
           res.json(buildCurveResult(tws, stepRad))
         } catch (e) {
@@ -611,7 +582,7 @@ module.exports = (app) => {
       // tws/bsp/polarSpeed in m/s; twa in rad (positive = starboard, negative = port).
       // Returns null for any field not yet available (plugin not running,
       // no BSP source, polar not loaded, or boat in irons).
-      router.get('/live', (req, res) => {
+      router.access('readonly').get('/live', (req, res) => {
         const wind = windSmoother?.ready ? windSmoother.polarValue : null
         const TWS       = wind ? wind.magnitude : null
         const TWAsigned = wind ? wind.angle : null
@@ -646,7 +617,7 @@ module.exports = (app) => {
       // inputs.smoothed.* — value the plugin actually used for computation
       // outputs.*     — only present for enabled settings; null if polar not ready
       // polarState    — same as /live
-      router.get('/status', (req, res) => {
+      router.access('readonly').get('/status', (req, res) => {
         const si = v => (Number.isFinite(v) ? parseFloat(v.toFixed(5)) : null)
 
         // Raw inputs: read directly from the smoother handlers
@@ -709,7 +680,7 @@ module.exports = (app) => {
       // returned by /live and the canonical curve query endpoints, plus a
       // read-only summary of the active polar and performance factor
       // (both sourced from the `polars.*` SK paths — not editable here).
-      router.get('/meta', (req, res) => {
+      router.access('readonly').get('/meta', (req, res) => {
         const speed = { formula: 'value * 1.943844', symbol: 'kn', displayFormat: '0.0' }
         const angle = { formula: 'value * 57.29577951308231', symbol: '\u00b0', displayFormat: '0.0' }
         const ratio = { formula: 'value * 100', symbol: '%', displayFormat: '0.1' }
@@ -779,10 +750,8 @@ module.exports = (app) => {
       })
 
       // Active polar / performance factor — read-only, published by a 'polars' resource provider.
-      // These are event-driven (change only on user action), so the idle-watchdog
-      // unsubscribe/resubscribe used for sensor handlers below does not apply here: absence
-      // of deltas is the normal state, not a sign of a broken subscription, and periodically
-      // forcing a resubscribe would just be churn (and possible side effects) for no reason.
+      // These are event-driven (change only on user action), so sensor idle warnings
+      // do not apply here: absence of deltas is the normal state.
       activePolarHandler = new MessageHandler(app, plugin.id, 'activePolar')
       activePolarHandler.path = 'polars.activePolar'
       activePolarHandler.onDelta = () => handleActivePolarDelta()
@@ -813,8 +782,6 @@ module.exports = (app) => {
         ..._wireHandlerWatchdog({
           id: 'wind.smoothed',
           getPath: () => `${windSmoother?.polar?.pathMagnitude ?? 'environment.wind.speedTrue'}, ${windSmoother?.polar?.pathAngle ?? 'environment.wind.angleTrueWater'}`,
-          unsubscribe: () => windSmoother?.unsubscribe(),
-          subscribe: () => windSmoother?.subscribe(true, true),
         }),
         onDelta: () => {
           _clearLifecycleWarning('wind.smoothed')
@@ -836,8 +803,6 @@ module.exports = (app) => {
         ..._wireHandlerWatchdog({
           id: 'bsp.smoothed',
           getPath: () => bspSmoother?.handler?.path ?? (settings.useSOG ? 'navigation.speedOverGround' : 'navigation.speedThroughWater'),
-          unsubscribe: () => bspSmoother?.unsubscribe(),
-          subscribe: () => bspSmoother?.subscribe(),
         })
       })
 
@@ -852,8 +817,6 @@ module.exports = (app) => {
           ..._wireHandlerWatchdog({
             id: 'hdg.smoothed',
             getPath: () => hdgSmoother?.handler?.path ?? 'navigation.headingTrue',
-            unsubscribe: () => hdgSmoother?.unsubscribe(),
-            subscribe: () => hdgSmoother?.subscribe(false, true),
           })
         })
       }

package/test/lifecycle.test.js

@@ -5,6 +5,7 @@ const assert = require('node:assert/strict')
 const fs = require('fs')
 const path = require('path')
 const os = require('os')
+const { withRoutePolicies, wrapPluginRoutes } = require('./routePolicyShim')
 
 // ---------------------------------------------------------------------------
 // Minimal app shim
@@ -39,7 +40,7 @@ function makeApp(dataDir) {
 
 function freshPlugin(app) {
   delete require.cache[require.resolve('../plugin/index.js')]
-  return require('../plugin/index.js')(app)
+  return wrapPluginRoutes(require('../plugin/index.js')(app))
 }
 
 // ---------------------------------------------------------------------------
@@ -106,6 +107,25 @@ describe('Plugin lifecycle — start() → stop() → start()', () => {
     assert.ok(routes.some(r => r.startsWith('GET')), 'no GET routes registered')
   })
 
+  it('applies readonly access only to safe live and polar metadata routes', () => {
+    const router = {
+      use: () => {},
+      get: () => {},
+      put: () => {},
+    }
+    plugin.registerWithRouter(withRoutePolicies(router))
+
+    assert.deepEqual(Object.fromEntries(router.routePolicies), {
+      'GET /polar/axes/tws': 'readonly',
+      'GET /polar/queries/curve': 'readonly',
+      'GET /live': 'readonly',
+      'GET /status': 'readonly',
+      'GET /meta': 'readonly',
+      'GET /settings': 'admin',
+      'PUT /settings': 'admin',
+    })
+  })
+
   it('registerWithRouter + start() + stop() + start() does not throw', () => {
     const router = {
       use: () => {},
@@ -116,4 +136,73 @@ describe('Plugin lifecycle — start() → stop() → start()', () => {
     plugin.stop()
     assert.doesNotThrow(() => plugin.start({}))
   })
+
+  it('keeps subscriptions through silence and receives resumed wind without replay', t => {
+    t.mock.timers.enable({ apis: ['setTimeout', 'Date'] })
+    const subscribers = new Map()
+    let subscriptions = 0
+    let unsubscriptions = 0
+    let messages = 0
+    app.handleMessage = () => { messages++ }
+    app.subscriptionmanager.subscribe = (msg, unsubscribes, _err, callback) => {
+      subscriptions++
+      for (const { path } of msg.subscribe) {
+        if (!subscribers.has(path)) subscribers.set(path, new Set())
+        subscribers.get(path).add(callback)
+      }
+      unsubscribes.push(() => {
+        unsubscriptions++
+        for (const { path } of msg.subscribe) subscribers.get(path).delete(callback)
+      })
+    }
+    const routes = {}
+    plugin.registerWithRouter({
+      use: () => {}, get: (p, cb) => { routes[p] = cb },
+      put: (p, cb) => { routes[`PUT ${p}`] = cb }, post: () => {}, delete: () => {}
+    })
+    plugin.start({ tackTrue: true })
+    const deliver = (path, value) => {
+      for (const callback of subscribers.get(path)) {
+        callback({ updates: [{ values: [{ path, value }] }] })
+      }
+    }
+    deliver('environment.wind.speedTrue', 5)
+    deliver('environment.wind.angleTrueWater', 0.4)
+    const initialSubscriptions = subscriptions
+    const initialMessages = messages
+    t.mock.timers.tick(120000)
+    assert.equal(subscriptions, initialSubscriptions)
+    assert.equal(unsubscriptions, 0)
+    assert.equal(messages, initialMessages, 'silence must not publish cached inputs')
+    let status
+    routes['/status']({}, { json: value => { status = value } })
+    for (const id of ['wind.smoothed', 'bsp.smoothed', 'hdg.smoothed']) {
+      const warning = status.lifecycleWarnings.find(w => w.id === id)
+      assert.equal(warning?.status, 'idle', id)
+      assert.doesNotMatch(warning.message, /resubscrib/i)
+    }
+    assert.equal(status.inputs.smoothed.tws, null)
+    deliver('environment.wind.speedTrue', 6)
+    deliver('environment.wind.angleTrueWater', 0.5)
+    routes['/status']({}, { json: value => { status = value } })
+    assert.equal(status.lifecycleWarnings.some(w => w.id === 'wind.smoothed'), false)
+    assert.equal(status.inputs.smoothed.tws, 6)
+    assert.equal(subscriptions, initialSubscriptions)
+
+    routes['PUT /settings']({ body: { useSOG: true } }, { json: () => {} })
+    assert.equal(subscriptions, initialSubscriptions + 1, 'a source change must still resubscribe')
+    assert.equal(unsubscriptions, 1)
+    assert.equal(subscribers.get('navigation.speedThroughWater').size, 0)
+    assert.equal(subscribers.get('navigation.speedOverGround').size, 1)
+
+    routes['PUT /settings']({ body: { tackTrue: false } }, { json: () => {} })
+    routes['PUT /settings']({ body: { tackTrue: true } }, { json: () => {} })
+    const configuredSubscriptions = subscriptions
+    const configuredUnsubscriptions = unsubscriptions
+    t.mock.timers.tick(120000)
+    routes['/status']({}, { json: value => { status = value } })
+    assert.equal(status.lifecycleWarnings.find(w => w.id === 'hdg.smoothed')?.status, 'idle')
+    assert.equal(subscriptions, configuredSubscriptions)
+    assert.equal(unsubscriptions, configuredUnsubscriptions)
+  })
 })

package/test/outputs.test.js

@@ -0,0 +1,304 @@
+'use strict'
+
+const { describe, it, beforeEach, afterEach } = require('node:test')
+const assert = require('node:assert/strict')
+const { Polar } = require('polar-math')
+const { wrapPluginRoutes } = require('./routePolicyShim')
+
+const KNOTS = 1 / 1.94384
+const rad = degrees => degrees * Math.PI / 180
+const target = (degrees, knots) => {
+  const twa = rad(degrees)
+  const tbs = knots * KNOTS
+  return { twa, tbs, vmg: tbs * Math.abs(Math.cos(twa)) }
+}
+
+const TABLE = {
+  kind: 'polarTable', schemaVersion: '1.0.0', name: 'Reference Polar',
+  units: { tws: 'm/s', twa: 'rad', boatSpeed: 'm/s' },
+  symmetry: { portStarboardSymmetric: true },
+  axes: { tws: [4, 12, 24].map(k => k * KNOTS), twa: [52, 60, 75, 90, 110, 120, 135, 150].map(rad) },
+  values: { boatSpeedMatrix: [
+    [3.66, 3.88, 4, 3.9, 3.7, 3.54, 3.12, 2.56],
+    [6.42, 6.58, 6.72, 6.82, 6.89, 6.83, 6.62, 6.25],
+    [6.69, 6.91, 7.27, 7.61, 8.04, 8.44, 8.54, 8.18]
+  ].map(row => row.map(k => k * KNOTS)) },
+  derived: { rows: [
+    { tws: 4 * KNOTS, beat: target(43.2, 3.24), run: target(147.5, 2.63) },
+    { tws: 12 * KNOTS, beat: target(39.6, 5.84), run: target(162.4, 5.83) },
+    { tws: 24 * KNOTS, beat: target(40.6, 6.11), run: target(178.6, 7.63) }
+  ] }
+}
+
+// Downwind-only polar: no beat targets exist, so upwind targets are unavailable.
+const DOWNWIND_ONLY = {
+  kind: 'polarTable', schemaVersion: '1.0.0', name: 'Downwind Only',
+  units: { tws: 'm/s', twa: 'rad', boatSpeed: 'm/s' },
+  symmetry: { portStarboardSymmetric: true },
+  axes: { tws: [12 * KNOTS], twa: [90, 120, 150].map(rad) },
+  values: { boatSpeedMatrix: [[6.8, 6.8, 6.2].map(k => k * KNOTS)] }
+}
+
+// settingsVersion skips migration, which would otherwise force Exponential smoothing
+const ALL_OUTPUTS = {
+  settingsVersion: 2, smootherType: 'None',
+  beatAngle: true, beatVMG: true, targetTWA: true, optimumWindAngle: true,
+  VMG: true, maxSpeed: true, polarSpeed: true, tackTrue: true, smoothedInputs: true
+}
+
+const TWS = 12 * KNOTS
+const reference = Polar.fromTable(TABLE)
+const targets = reference.targetsAt({ tws: TWS }).value
+const close = (actual, expected, msg) =>
+  assert.ok(Number.isFinite(actual) && Math.abs(actual - expected) < 1e-9, `${msg}: ${actual} != ${expected}`)
+
+function harness(table = TABLE) {
+  const subscribers = new Map()
+  const bus = new Map()      // latest value per path written by the plugin
+  const writes = []          // every { path, value } written, in order
+  const app = {
+    debug: () => {}, error: () => {},
+    setPluginStatus: () => {}, setPluginError: () => {},
+    savePluginOptions: (_o, cb) => cb(null),
+    getDataDirPath: () => '.',
+    handleMessage: (_id, delta) => {
+      for (const update of delta.updates) {
+        for (const { path, value } of update.values || []) {
+          bus.set(path, value)
+          writes.push({ path, value })
+        }
+      }
+    },
+    resourcesApi: {
+      listResources: async () => ({}),
+      getResource: async () => table
+    },
+    subscriptionmanager: {
+      subscribe: (msg, unsubscribes, _err, callback) => {
+        for (const { path } of msg.subscribe) {
+          if (!subscribers.has(path)) subscribers.set(path, new Set())
+          subscribers.get(path).add(callback)
+        }
+        unsubscribes.push(() => {
+          for (const { path } of msg.subscribe) subscribers.get(path).delete(callback)
+        })
+      }
+    }
+  }
+  delete require.cache[require.resolve('../plugin/index.js')]
+  const plugin = wrapPluginRoutes(require('../plugin/index.js')(app))
+  const routes = {}
+  plugin.registerWithRouter({
+    use: () => {}, get: (p, cb) => { routes[p] = cb },
+    put: (p, cb) => { routes[`PUT ${p}`] = cb }, post: () => {}, delete: () => {}
+  })
+
+  const deliver = (path, value) => {
+    for (const callback of subscribers.get(path) || []) {
+      callback({ updates: [{ $source: 'test', values: [{ path, value }] }] })
+    }
+  }
+  return {
+    app, plugin, bus, writes, routes, deliver,
+    async start(options = ALL_OUTPUTS) {
+      plugin.start(options)
+      deliver('polars.activePolar', { href: '/resources/polars/ref' })
+      await new Promise(resolve => setImmediate(resolve))
+    },
+    sail({ tws = TWS, twa, bsp, hdg }) {
+      if (bsp !== undefined) deliver('navigation.speedThroughWater', bsp)
+      if (hdg !== undefined) deliver('navigation.headingTrue', hdg)
+      deliver('environment.wind.speedTrue', tws)
+      deliver('environment.wind.angleTrueWater', twa)
+    },
+    status() {
+      let result
+      routes['/status']({}, { json: value => { result = value } })
+      return result
+    }
+  }
+}
+
+describe('computeAndSend output validity', () => {
+  let h
+
+  beforeEach(() => { h = harness() })
+  afterEach(() => {
+    try { h.plugin.stop() } catch (_) {}
+    delete require.cache[require.resolve('../plugin/index.js')]
+  })
+
+  it('publishes every output while sailing normally upwind on starboard', async () => {
+    await h.start()
+    const twa = rad(50)
+    const bsp = 6 * KNOTS
+    h.sail({ twa, bsp, hdg: 1 })
+    const polarSpeed = reference.speedAt({ tws: TWS, twa }).value
+    const vmg = bsp * Math.cos(twa)
+    close(h.bus.get('performance.polarSpeed'), polarSpeed, 'polarSpeed')
+    close(h.bus.get('performance.polarSpeedRatio'), bsp / polarSpeed, 'polarSpeedRatio')
+    close(h.bus.get('performance.targetSpeed'), targets.beat.vmg / Math.cos(targets.beat.twa), 'targetSpeed')
+    close(h.bus.get('performance.targetAngle'), targets.beat.twa, 'targetAngle')
+    close(h.bus.get('performance.targetVelocityMadeGood'), targets.beat.vmg, 'targetVMG')
+    close(h.bus.get('performance.velocityMadeGood'), vmg, 'VMG')
+    close(h.bus.get('performance.polarVelocityMadeGood'), targets.beat.vmg, 'polarVMG')
+    close(h.bus.get('performance.polarVelocityMadeGoodRatio'), vmg / targets.beat.vmg, 'VMG ratio')
+    close(h.bus.get('performance.beatAngle'), targets.beat.twa, 'beatAngle')
+    close(h.bus.get('performance.gybeAngle'), targets.run.twa, 'gybeAngle')
+    close(h.bus.get('performance.optimumWindAngle'), twa - targets.beat.twa, 'optimumWindAngle')
+    close(h.bus.get('performance.tackTrue'), 1 + targets.beat.twa, 'tackTrue')
+    close(h.bus.get('environment.wind.angleTrueWaterDamped'), twa, 'damped TWA')
+    close(h.bus.get('performance.boatSpeedDamped'), bsp, 'damped BSP')
+  })
+
+  it('in irons clears polar values, keeps steering advice and VMG live, and restores them on leaving', async () => {
+    await h.start()
+    const bsp = 4 * KNOTS
+    h.sail({ twa: rad(50), bsp, hdg: 1 })
+    assert.ok(h.bus.get('performance.polarSpeed') > 0)
+
+    const ironsTwa = rad(20)
+    assert.equal(reference.speedAt({ tws: TWS, twa: ironsTwa }).state.twa, 'in_irons')
+    h.sail({ twa: ironsTwa, bsp, hdg: 1 })
+    for (const path of ['performance.polarSpeed', 'performance.polarSpeedRatio', 'performance.targetSpeed',
+      'performance.targetVelocityMadeGood', 'performance.polarVelocityMadeGood',
+      'performance.polarVelocityMadeGoodRatio', 'performance.beatAngle', 'performance.gybeAngle',
+      'performance.beatAngleVelocityMadeGood', 'performance.gybeAngleVelocityMadeGood',
+      'performance.maxSpeed', 'performance.maxSpeedAngle']) {
+      assert.equal(h.bus.get(path), null, path)
+    }
+    close(h.bus.get('performance.targetAngle'), targets.beat.twa, 'targetAngle in irons')
+    close(h.bus.get('performance.optimumWindAngle'), ironsTwa - targets.beat.twa, 'optimumWindAngle in irons')
+    close(h.bus.get('performance.tackTrue'), 1 + targets.beat.twa, 'tackTrue in irons')
+    close(h.bus.get('performance.velocityMadeGood'), bsp * Math.cos(ironsTwa), 'VMG in irons')
+
+    // VMG must keep updating while in irons, not freeze
+    h.sail({ twa: ironsTwa, bsp: 2 * KNOTS })
+    close(h.bus.get('performance.velocityMadeGood'), 2 * KNOTS * Math.cos(ironsTwa), 'VMG updates in irons')
+
+    const status = h.status()
+    assert.equal(status.outputs['performance.polarSpeed'], null)
+    assert.equal(status.outputs['performance.targetSpeed'], null)
+
+    // Pinching is not in irons, so nothing is cleared
+    const pinchTwa = rad(38)
+    assert.equal(reference.speedAt({ tws: TWS, twa: pinchTwa }).state.twa, 'pinching')
+    h.sail({ twa: pinchTwa, bsp })
+    close(h.bus.get('performance.targetSpeed'), targets.beat.vmg / Math.cos(targets.beat.twa), 'targetSpeed pinching')
+    close(h.bus.get('performance.targetVelocityMadeGood'), targets.beat.vmg, 'targetVMG pinching')
+    close(h.bus.get('performance.polarVelocityMadeGood'), targets.beat.vmg, 'polarVMG pinching')
+    close(h.bus.get('performance.polarVelocityMadeGoodRatio'), bsp * Math.cos(pinchTwa) / targets.beat.vmg, 'ratio pinching')
+    close(h.bus.get('performance.beatAngle'), targets.beat.twa, 'beatAngle pinching')
+    assert.ok(h.bus.get('performance.maxSpeed') > 0)
+
+    h.sail({ twa: rad(50), bsp })
+    const polarSpeed = reference.speedAt({ tws: TWS, twa: rad(50) }).value
+    close(h.bus.get('performance.polarSpeed'), polarSpeed, 'polarSpeed after irons')
+    close(h.bus.get('performance.polarSpeedRatio'), bsp / polarSpeed, 'ratio after irons')
+    close(h.bus.get('performance.targetSpeed'), targets.beat.vmg / Math.cos(targets.beat.twa), 'targetSpeed after irons')
+  })
+
+  it('clears unavailable outputs only once per transition', async () => {
+    await h.start()
+    h.sail({ twa: rad(50), bsp: 4 * KNOTS })
+    h.sail({ twa: rad(20), bsp: 4 * KNOTS })
+    h.sail({ twa: rad(21), bsp: 4 * KNOTS })
+    const polarSpeedNulls = h.writes.filter(w => w.path === 'performance.polarSpeed' && w.value === null)
+    assert.equal(polarSpeedNulls.length, 1)
+  })
+
+  it('mirrors signed angles and keeps magnitudes on port tack', async () => {
+    await h.start()
+    const twa = rad(-50)
+    const bsp = 6 * KNOTS
+    h.sail({ twa, bsp, hdg: 1 })
+    close(h.bus.get('performance.targetAngle'), -targets.beat.twa, 'targetAngle port')
+    close(h.bus.get('performance.beatAngle'), -targets.beat.twa, 'beatAngle port')
+    close(h.bus.get('performance.optimumWindAngle'), -(rad(50) - targets.beat.twa), 'optimumWindAngle port')
+    close(h.bus.get('performance.tackTrue'), 1 - targets.beat.twa, 'tackTrue port')
+    close(h.bus.get('performance.targetSpeed'), targets.beat.vmg / Math.cos(targets.beat.twa), 'targetSpeed port')
+    close(h.bus.get('performance.velocityMadeGood'), bsp * Math.cos(rad(50)), 'VMG port')
+
+    h.sail({ twa: rad(-20), bsp })
+    assert.equal(h.bus.get('performance.polarSpeed'), null)
+    assert.equal(h.bus.get('performance.targetSpeed'), null)
+    assert.equal(h.bus.get('performance.targetVelocityMadeGood'), null)
+    assert.equal(h.bus.get('performance.beatAngle'), null)
+    close(h.bus.get('performance.targetAngle'), -targets.beat.twa, 'targetAngle port irons')
+    close(h.bus.get('performance.optimumWindAngle'), -(rad(20) - targets.beat.twa), 'optimumWindAngle port irons')
+    close(h.bus.get('performance.tackTrue'), 1 - targets.beat.twa, 'tackTrue port irons')
+  })
+
+  it('selects run targets when sailing downwind', async () => {
+    await h.start()
+    const twa = rad(150)
+    const bsp = 6 * KNOTS
+    h.sail({ twa, bsp, hdg: 1 })
+    const vmg = bsp * Math.cos(twa)
+    close(h.bus.get('performance.targetAngle'), targets.run.twa, 'run targetAngle')
+    close(h.bus.get('performance.targetVelocityMadeGood'), targets.run.vmg, 'run targetVMG')
+    close(h.bus.get('performance.targetSpeed'), targets.run.vmg / Math.abs(Math.cos(targets.run.twa)), 'run targetSpeed')
+    close(h.bus.get('performance.velocityMadeGood'), vmg, 'downwind VMG is negative')
+    assert.ok(vmg < 0)
+    close(h.bus.get('performance.polarVelocityMadeGoodRatio'), Math.abs(vmg) / targets.run.vmg, 'downwind ratio')
+    close(h.bus.get('performance.optimumWindAngle'), twa - targets.run.twa, 'downwind optimumWindAngle')
+    close(h.bus.get('performance.tackTrue'), 1 + targets.run.twa, 'downwind tackTrue')
+  })
+
+  it('clears BSP-dependent outputs when boat speed is missing', async () => {
+    await h.start()
+    h.sail({ twa: rad(50), bsp: 6 * KNOTS })
+    assert.ok(h.bus.get('performance.velocityMadeGood') > 0)
+    h.sail({ twa: rad(50), bsp: null })
+    for (const path of ['performance.velocityMadeGood', 'performance.polarVelocityMadeGoodRatio',
+      'performance.polarSpeedRatio', 'performance.boatSpeedDamped']) {
+      assert.equal(h.bus.get(path), null, path)
+    }
+    assert.ok(h.bus.get('performance.polarSpeed') > 0)
+    assert.ok(h.bus.get('performance.targetSpeed') > 0)
+    close(h.bus.get('performance.polarVelocityMadeGood'), targets.beat.vmg, 'polarVMG without BSP')
+  })
+
+  it('clears target-dependent outputs when polar targets are unavailable', async () => {
+    h = harness(DOWNWIND_ONLY)
+    await h.start()
+    const noBeat = Polar.fromTable(DOWNWIND_ONLY).targetsAt({ tws: TWS }).value
+    assert.equal(noBeat.beat, null)
+
+    h.sail({ twa: rad(150), bsp: 6 * KNOTS, hdg: 1 })
+    assert.ok(h.bus.get('performance.targetSpeed') > 0)
+    assert.ok(h.bus.get('performance.polarVelocityMadeGood') > 0)
+
+    h.sail({ twa: rad(60), bsp: 6 * KNOTS, hdg: 1 })
+    for (const path of ['performance.targetSpeed', 'performance.targetAngle',
+      'performance.targetVelocityMadeGood', 'performance.polarVelocityMadeGood',
+      'performance.polarVelocityMadeGoodRatio', 'performance.beatAngle',
+      'performance.beatAngleVelocityMadeGood', 'performance.optimumWindAngle', 'performance.tackTrue']) {
+      assert.equal(h.bus.get(path), null, path)
+    }
+    close(h.bus.get('performance.velocityMadeGood'), 6 * KNOTS * Math.cos(rad(60)), 'actual VMG without targets')
+  })
+
+  it('does not publish disabled outputs and clears outputs toggled off or on stop', async () => {
+    await h.start({ settingsVersion: 2, smootherType: 'None', polarSpeed: true })
+    h.sail({ twa: rad(50), bsp: 4 * KNOTS })
+    const published = new Set(h.writes.map(w => w.path))
+    assert.deepEqual([...published].sort(),
+      ['performance.polarSpeed', 'performance.polarSpeedRatio', 'performance.targetSpeed'])
+    assert.ok(h.bus.get('performance.targetSpeed') > 0)
+
+    h.routes['PUT /settings']({ body: { polarSpeed: false } }, { json: () => {} })
+    assert.equal(h.bus.get('performance.targetSpeed'), null)
+    const before = h.writes.length
+    h.sail({ twa: rad(50), bsp: 4 * KNOTS })
+    assert.equal(h.writes.length, before, 'disabled outputs must not be written')
+
+    h.routes['PUT /settings']({ body: { polarSpeed: true } }, { json: () => {} })
+    h.sail({ twa: rad(50), bsp: 4 * KNOTS })
+    assert.ok(h.bus.get('performance.polarSpeed') > 0)
+    h.plugin.stop()
+    for (const path of ['performance.polarSpeed', 'performance.targetSpeed', 'performance.polarSpeedRatio']) {
+      assert.equal(h.bus.get(path), null, path)
+    }
+  })
+})

package/test/routePolicyShim.js

@@ -0,0 +1,42 @@
+'use strict'
+
+function withRoutePolicies(router) {
+  if (router.routePolicies instanceof Map) return router
+
+  const policies = new Map()
+  const methods = ['get', 'post', 'put', 'patch', 'delete']
+  const originalMethods = new Map()
+  for (const method of methods) {
+    if (typeof router[method] !== 'function') continue
+    const original = router[method]
+    originalMethods.set(method, original)
+    router[method] = (route, ...handlers) => {
+      policies.set(`${method.toUpperCase()} ${route}`, 'admin')
+      return original.call(router, route, ...handlers)
+    }
+  }
+
+  router.access = (level) => {
+    if (level !== 'readonly' && level !== 'readwrite') {
+      throw new Error(`Unsupported route access level: ${level}`)
+    }
+    const scopedRouter = {}
+    for (const [method, original] of originalMethods) {
+      scopedRouter[method] = (route, ...handlers) => {
+        policies.set(`${method.toUpperCase()} ${route}`, level)
+        return original.call(router, route, ...handlers)
+      }
+    }
+    return scopedRouter
+  }
+  router.routePolicies = policies
+  return router
+}
+
+function wrapPluginRoutes(plugin) {
+  const registerWithRouter = plugin.registerWithRouter
+  plugin.registerWithRouter = (router) => registerWithRouter(withRoutePolicies(router))
+  return plugin
+}
+
+module.exports = { withRoutePolicies, wrapPluginRoutes }