signalk-polar-performance-plugin 2.0.0 → 2.2.0

package/plugin/index.js

@@ -1,8 +1,6 @@
 'use strict'
 
-const { Polar } = require('polar-math')
 const {
-  MessageHandler,
   createSmoothedPolar,
   createSmoothedHandler,
   SmoothedAngle,
@@ -14,8 +12,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,
@@ -43,15 +39,16 @@ module.exports = (app) => {
   let hasPendingChanges = false
   let isRunning = false
 
-  // Active polar — sourced from the `polars.activePolar` / `polars.performanceFactor`
-  // SK paths (published by a 'polars' resource-provider plugin, e.g. signalk-polar-management).
-  // This plugin no longer stores or manages polar files itself.
-  let polar = null                 // polar-math Polar instance, or null when unavailable
-  let activePolarId = null
-  let activePolarDoc = null        // raw canonical resource, for descriptive metadata
-  let performanceFactor = 1
-  let activePolarHandler = null
-  let performanceFactorHandler = null
+  // Active polar — provided entirely by signalk-polar-management's in-process
+  // service, discovered through the `polarManagement` PropertyValue. The active
+  // handle mirrors the shared active polar, sailplan, performance factor and
+  // wave-correction toggle on every calculation, so this plugin applies none of
+  // them itself. Descriptive metadata and the plotter's TWS axis come from the
+  // handle's describe() snapshot — no resource lookups or `polars.*` paths.
+  let polarHandle = null           // live activePolar() calculation handle, or null
+  let polarDescription = null      // latest handle.describe() result, or null
+  let unsubscribeDiscovery = null  // PropertyValues discovery subscription
+  let unsubscribeChanges = null    // polarHandle.onChange subscription
 
   let windSmoother = null
   let bspSmoother = null
@@ -85,7 +82,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 +102,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 +116,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
@@ -167,9 +185,8 @@ module.exports = (app) => {
     }
 
     if (s.settingsVersion < 2) {
-      // v1 → v2: polar selection and performance adjustment moved to the
-      // `polars.activePolar` / `polars.performanceFactor` SK paths, published
-      // by a 'polars' resource-provider plugin (e.g. signalk-polar-management).
+      // v1 → v2: polar selection and performance adjustment moved to
+      // signalk-polar-management, which owns the shared selection and factor.
       delete s.activePolar
       delete s.perfAdjust
       s.settingsVersion = 2
@@ -192,59 +209,59 @@ module.exports = (app) => {
   }
 
   // ---------------------------------------------------------------------------
-  // Active polar — sourced from SK paths published by a 'polars' resource provider
+  // Active polar — calculations and descriptive metadata via the polar
+  // management in-process service
   // ---------------------------------------------------------------------------
 
-  // Extracts the resource id from an `href` of the shape `/resources/polars/<id>`.
-  function hrefToId(href) {
-    if (typeof href !== 'string') return null
-    const match = href.match(/\/resources\/polars\/([^/]+)$/)
-    return match ? match[1] : null
-  }
-
-  async function checkPolarProvider() {
-    if (!app.resourcesApi || typeof app.resourcesApi.listResources !== 'function') return false
-    try {
-      await app.resourcesApi.listResources('polars', {})
-      return true
-    } catch (_e) {
-      return false
+  // Refreshes the cached describe() snapshot that feeds /meta and the plotter's
+  // TWS axis, clears outputs when the polar becomes unavailable, and keeps the
+  // plugin status in sync with the current selection.
+  function refreshDescription() {
+    if (!polarHandle) return
+    const hadPolar = polarDescription?.available === true
+    polarDescription = polarHandle.describe()
+    if (polarDescription.available) {
+      app.setPluginStatus(`Polar '${polarDescription.name || polarDescription.id}' active`)
+    } else {
+      if (hadPolar) nullifyOutputs()
+      app.setPluginStatus(polarDescription.reason === 'no_active_polar'
+        ? 'No active polar selected — select one in the polar management webapp'
+        : `Polar calculations unavailable (${String(polarDescription.reason).replace(/_/g, ' ')})`)
     }
   }
 
-  function handleActivePolarDelta() {
-    const value = activePolarHandler.value
-    const href = value?.href
-    if (!href) {
-      polar = null
-      activePolarId = null
-      activePolarDoc = null
-      nullifyOutputs()
-      app.setPluginStatus('No active polar selected — select one in the polar management webapp')
+  // Discovery of the polar calculation service announced by
+  // signalk-polar-management through the `polarManagement` PropertyValue.
+  // Only the latest record counts: an `available: false` record means the
+  // provider stopped and old handles are permanently unusable.
+  function handleServiceDiscovery(history) {
+    const record = history.findLast(entry => entry?.setter === 'signalk-polar-management')
+    const service = record?.value
+    unsubscribeChanges?.()
+    unsubscribeChanges = null
+    const hadPolar = polarDescription?.available === true
+    polarHandle = null
+    polarDescription = null
+    if (service?.apiVersion !== 1 || service.available !== true ||
+        typeof service.activePolar !== 'function' || typeof service.polar !== 'function') {
+      if (hadPolar) nullifyOutputs()
+      app.setPluginStatus('Polar calculation service not available — install or enable signalk-polar-management')
       return
     }
-
-    const id = hrefToId(href)
-    if (!id) {
-      app.setPluginError(`Cannot parse active polar href: ${href}`)
+    const handle = service.activePolar()
+    if (typeof handle.describe !== 'function') {
+      if (hadPolar) nullifyOutputs()
+      app.setPluginError('signalk-polar-management is too old — update it to a version whose polar handles provide describe()')
       return
     }
-
-    app.resourcesApi.getResource('polars', id).then((doc) => {
-      try {
-        polar = Polar.fromTable(doc)
-        activePolarId = id
-        activePolarDoc = doc
-        app.setPluginStatus(`Polar '${doc.name || id}' loaded`)
-      } catch (e) {
-        // Keep the last valid polar (if any) rather than dropping outputs on a bad update.
-        app.setPluginError(`Invalid active polar '${id}': ${e.message}`)
-        if (!polar) nullifyOutputs()
-      }
-    }).catch((e) => {
-      app.setPluginError(`Cannot load active polar '${id}': ${e.message}`)
-      if (!polar) nullifyOutputs()
+    polarHandle = handle
+    // Every change kind can affect the description (selection, edits, factor).
+    // Callbacks must stay short, so the snapshot refresh is deferred.
+    unsubscribeChanges = polarHandle.onChange((change) => {
+      app.debug('Polar configuration changed: %o', change)
+      setImmediate(() => { if (polarHandle === handle) refreshDescription() })
     })
+    refreshDescription()
   }
 
   // ---------------------------------------------------------------------------
@@ -290,9 +307,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 +325,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 +334,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())
   }
 
   // ---------------------------------------------------------------------------
@@ -334,169 +343,132 @@ module.exports = (app) => {
 
   function computeAndSend() {
     if (hasPendingChanges) applyOptionChanges()
-    if (!polar) return
+    if (!polarHandle) return
 
     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.')
-      }
-    }
-
-    // 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
-    const targetAngle = isUpwind ? beatAngle : runAngle
-    const targetVMG   = isUpwind ? beatVMG   : runVMG
-
-    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.')
-      }
-    }
-
-    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.')
-          }
-        }
-
-        if (Number.isFinite(BSP)) {
-          add('performance.polarSpeedRatio', BSP / polarSpeed, 'ratio',
-            'Actual boat speed divided by polar speed.')
-        }
-      }
-
-      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.')
-          }
+    // 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 {
-      // 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.')
+      } else if (lastOutputs[skPath] !== null) {
+        values.push({ path: skPath, value: null })
       }
     }
 
-    // Opposite tack heading
-    if (settings.tackTrue && Number.isFinite(HDG) && Number.isFinite(targetAngle)) {
-      let tack = port < 0 ? HDG - targetAngle : HDG + targetAngle
+    // 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 ? polarHandle.speedAt({ tws: TWS, twa: TWA }) : null
+    const inIrons = speedResult?.state?.twa === 'in_irons'
+    const fromPolar = value => (inIrons ? null : finiteOrNull(value))
+
+    const targets = windValid ? polarHandle.targetsAt({ tws: TWS }).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 targetVMG = finiteOrNull(isUpwind ? targets?.beat?.vmg : targets?.run?.vmg)
+    const polarTargetVMG = fromPolar(targetVMG)
+    const maxSpeed = fromPolar(targets?.maxSpeed?.speed)
+    const maxSpeedAngle = maxSpeed === null ? null : finiteOrNull(targets?.maxSpeed?.twa)
+
+    // 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
+
+    const targetCos = adviceAngle === null ? 0 : Math.abs(Math.cos(adviceAngle))
+    const targetSpeed = targetVMG !== null && targetVMG >= 0 && targetCos > 0.01
+      ? targetVMG / targetCos
+      : null
+
+    const vmg = windValid && BSP !== null ? BSP * Math.cos(TWA) : null
+    const vmgRatio = ratio(vmg === null ? null : Math.abs(vmg), polarTargetVMG)
+
+    let optimumWindAngle = null
+    if (isUpwind && adviceBeatAngle !== null) optimumWindAngle = (TWA - adviceBeatAngle) * port
+    else if (windValid && !isUpwind && adviceRunAngle !== null) optimumWindAngle = (adviceRunAngle - TWA) * port * -1
+
+    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', polarTargetVMG, '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 +477,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 })
   }
 
   // ---------------------------------------------------------------------------
@@ -543,16 +512,18 @@ module.exports = (app) => {
         return Number.isFinite(value) ? parseFloat(value.toFixed(digits)) : null
       }
 
+      // TWS axis for the webapp plotter — from the handle's description, which
+      // already reflects the active selection (v1 table, or v2 best/sailplan).
       function getPolarTwsValues() {
-        return polar.entries
-          .filter(entry => entry.tws > 0.001)
-          .map(entry => parseFloat(entry.tws.toFixed(4)))
+        return polarDescription.twsAxis
+          .filter(tws => Number.isFinite(tws) && tws > 0.001)
+          .map(tws => parseFloat(tws.toFixed(4)))
       }
 
       function buildCurveResult(tws, stepRad) {
         const points = []
         for (let twa = 0; twa <= Math.PI + 1e-9; twa += stepRad) {
-          const { value: tbs } = polar.speedAt({ tws, twa, performanceFactor })
+          const { value: tbs } = polarHandle.speedAt({ tws, twa })
           if (Number.isFinite(tbs) && tbs > 0) {
             points.push({
               twa: toFixedNumber(twa, 5),
@@ -561,7 +532,7 @@ module.exports = (app) => {
           }
         }
 
-        const { value: targets } = polar.targetsAt({ tws, performanceFactor })
+        const { value: targets } = polarHandle.targetsAt({ tws })
         return {
           tws,
           points,
@@ -585,21 +556,21 @@ module.exports = (app) => {
 
       // ---- Active polar curve queries (read-only — for the webapp's polar canvas) --
 
-      router.get('/polar/axes/tws', (req, res) => {
-        if (!polar) return res.status(404).json({ error: 'No active polar selected' })
+      router.access('readonly').get('/polar/axes/tws', (req, res) => {
+        if (!polarDescription?.available) return res.status(404).json({ error: 'No active polar selected' })
         res.json(getPolarTwsValues())
       })
 
-      router.get('/polar/queries/curve', (req, res) => {
-        if (!polar) return res.status(404).json({ error: 'No active polar selected' })
+      router.access('readonly').get('/polar/queries/curve', (req, res) => {
+        if (!polarHandle || !polarDescription?.available) return res.status(404).json({ error: 'No active polar selected' })
         try {
           const tws = parseFloat(req.query.tws)
           if (!Number.isFinite(tws) || tws < 0) {
             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,15 +582,15 @@ 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
         const TWA       = Number.isFinite(TWAsigned) ? Math.abs(TWAsigned) : null
         const BSP       = bspSmoother ? bspSmoother.value : null
 
-        const polarResult = (polar && Number.isFinite(TWS) && Number.isFinite(TWA))
-          ? polar.speedAt({ tws: TWS, twa: TWA, performanceFactor })
+        const polarResult = (polarHandle && Number.isFinite(TWS) && Number.isFinite(TWA))
+          ? polarHandle.speedAt({ tws: TWS, twa: TWA })
           : null
         const polarSpeed = polarResult ? polarResult.value : 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
@@ -663,8 +634,8 @@ module.exports = (app) => {
 
         const bspPath = settings.useSOG ? 'navigation.speedOverGround' : 'navigation.speedThroughWater'
 
-        const polarState = (polar && Number.isFinite(TWS) && Number.isFinite(TWAsigned))
-          ? polar.speedAt({ tws: TWS, twa: Math.abs(TWAsigned), performanceFactor }).state
+        const polarState = (polarHandle && Number.isFinite(TWS) && Number.isFinite(TWAsigned))
+          ? polarHandle.speedAt({ tws: TWS, twa: Math.abs(TWAsigned) }).state
           : null
 
         // Build outputs object: only include paths that are enabled and were
@@ -707,9 +678,11 @@ module.exports = (app) => {
 
       // Metadata describing the units and display preferences for each field
       // 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) => {
+      // read-only summary of the active polar and performance factor, taken
+      // from the management handle's describe() snapshot. The factor is
+      // informational: the handle applies it in every calculation, so this
+      // plugin never multiplies by it.
+      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' }
@@ -723,16 +696,17 @@ module.exports = (app) => {
           'curve.tbs': { units: 'm/s', displayUnits: speed },
           'curve.vmg': { units: 'm/s', displayUnits: speed },
           'curve.twa': { units: 'rad', displayUnits: angle },
-          activePolar: activePolarDoc ? {
-            id: activePolarId,
-            name: activePolarDoc.name || activePolarId,
-            boatType: activePolarDoc.boatType ?? null,
-            sailnumber: activePolarDoc.sailnumber ?? null,
-            year: activePolarDoc.year ?? null,
-            source: activePolarDoc.source ?? null,
-            notes: activePolarDoc.notes ?? null
+          activePolar: polarDescription?.available ? {
+            id: polarDescription.id,
+            name: polarDescription.name || polarDescription.id,
+            boatType: polarDescription.boatType,
+            sailnumber: polarDescription.sailnumber,
+            year: polarDescription.year,
+            source: polarDescription.source,
+            notes: polarDescription.notes,
+            sailplanId: polarDescription.sailplanId
           } : null,
-          performanceFactor
+          performanceFactor: polarDescription?.available ? polarDescription.performanceFactor : null
         })
       })
 
@@ -764,37 +738,21 @@ module.exports = (app) => {
       metaSentPaths = new Set()  // reset so metadata is re-emitted after restart
       lifecycleWarningMap = new Map()
       lifecycleWarnings = []
-      polar = null
-      activePolarId = null
-      activePolarDoc = null
-      performanceFactor = 1
+      polarHandle = null
+      polarDescription = null
 
       settings = migrateSettings({ ...DEFAULT_SETTINGS, ...options, settingsVersion: options.settingsVersion ?? 0 })
 
-      checkPolarProvider().then((available) => {
-        app.debug(`checkPolarProvider: ${available ? 'polars resource provider found' : 'no polars resource provider'}`)
-        if (!available) {
-          app.setPluginStatus("No 'polars' resource provider registered — install signalk-polar-management (or another plugin providing the 'polars' resource type) to select an active polar.")
-        }
-      })
-
-      // 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.
-      activePolarHandler = new MessageHandler(app, plugin.id, 'activePolar')
-      activePolarHandler.path = 'polars.activePolar'
-      activePolarHandler.onDelta = () => handleActivePolarDelta()
-      activePolarHandler.subscribe()
-
-      performanceFactorHandler = new MessageHandler(app, plugin.id, 'performanceFactor')
-      performanceFactorHandler.path = 'polars.performanceFactor'
-      performanceFactorHandler.onDelta = () => {
-        const value = performanceFactorHandler.value
-        performanceFactor = Number.isFinite(value) ? value : 1
+      // Discover the in-process polar calculation service. The callback fires
+      // immediately with the retained PropertyValues history, so startup order
+      // relative to signalk-polar-management does not matter. The handle also
+      // provides the active selection's metadata through describe(), so no
+      // `polars.*` subscriptions or resource lookups are needed.
+      if (typeof app.onPropertyValues === 'function') {
+        unsubscribeDiscovery = app.onPropertyValues('polarManagement', handleServiceDiscovery)
+      } else {
+        app.setPluginError('Signal K server does not support PropertyValues — polar calculations unavailable')
       }
-      performanceFactorHandler.subscribe()
 
       const SmootherClass = getSmootherClass(settings.smootherType)
       const smootherOptions = getSmootherOptions(settings.smootherType, settings)
@@ -813,8 +771,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 +792,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 +806,6 @@ module.exports = (app) => {
           ..._wireHandlerWatchdog({
             id: 'hdg.smoothed',
             getPath: () => hdgSmoother?.handler?.path ?? 'navigation.headingTrue',
-            unsubscribe: () => hdgSmoother?.unsubscribe(),
-            subscribe: () => hdgSmoother?.subscribe(false, true),
           })
         })
       }
@@ -869,11 +821,10 @@ module.exports = (app) => {
       if (windSmoother) { windSmoother.terminate(); windSmoother = null }
       if (bspSmoother)  { bspSmoother.terminate();  bspSmoother = null  }
       if (hdgSmoother)  { hdgSmoother.terminate();  hdgSmoother = null  }
-      if (activePolarHandler) { activePolarHandler.unsubscribe(); activePolarHandler = null }
-      if (performanceFactorHandler) { performanceFactorHandler.unsubscribe(); performanceFactorHandler = null }
-      polar = null
-      activePolarId = null
-      activePolarDoc = null
+      if (unsubscribeDiscovery) { unsubscribeDiscovery(); unsubscribeDiscovery = null }
+      if (unsubscribeChanges) { unsubscribeChanges(); unsubscribeChanges = null }
+      polarHandle = null
+      polarDescription = null
       lifecycleWarningMap = new Map()
       lifecycleWarnings = []
       app.debug('Plugin stopped')