sailkick-boat 0.18.5 → 0.20.0

package/README.md

@@ -237,6 +237,23 @@ so the boat's own app opens with no password, fully offline. Everything else in
 config passes through untouched. (Hand-edit `proxy.openAccess: false` to keep the cloud
 login gate — there is no toggle, since the gate cannot complete over the mirror anyway.)
 
+## Routes, polars and settings — stored on the boat
+The app reads and writes these through `/api/profile/*`. On the cloud that router is
+session-gated, and the mirror can never satisfy it: the caching GET path forwards no
+headers at all, and the browser is on the boat's LAN origin so it holds no cloud cookie
+to forward either. Every call returned **401** — the route panel showed nothing, saving a
+route failed, and the mobile route-weather deck silently fell back to "Dead reckoning".
+Offline it was a 504.
+
+So the plugin serves `/api/profile/*` itself, from `profile.json` in the plugin's data
+directory (atomic writes, saves serialized so a burst from the route panel can't clobber
+itself). Same envelopes as the cloud, so the app can't tell the difference — and route
+planning now works with no uplink at all, which is when you actually want it.
+
+**This copy is boat-local and does not sync.** A route saved on board stays on board; a
+route saved in the web app stays in the cloud. Merging the two needs conflict resolution
+worth designing properly rather than guessing at, so for now they are simply separate.
+
 ## Local history (offline Trends + track)
 **One source: a live ring**, sampled from the same BoatState that feeds `/ws/telemetry`
 — no database, works on a Victron GX with nothing else installed. `historyAvailable` is
@@ -465,8 +482,21 @@ Point your chart app / browser at:
 ```bash
 cd ~/.signalk && npm install sailkick-boat   # or a packed tarball
 ```
-Enable + configure under **Server → Plugin Config → "Sailkick boat companion"**.
-Set **Data directory** to a path on the SSD (or leave blank for the plugin data dir).
+The plugin **enables itself on install** and appears in Signal K's **Webapps** menu as
+**Sailkick** — a launcher with two entries, "Open Sailkick" (full app) and "Open on
+phone" (mobile view). Both point at the mirror on this boat, so nothing has to be typed
+by hand. One npm package can only produce one menu item — Signal K dedupes webapps by
+package name — hence one launcher rather than two entries.
+
+Nothing is uploaded by enabling it. Telemetry sync needs an account write token and
+refuses to start without one; AIS upload and the backfill are off by default; and the
+worldwide base-map seed is skipped entirely on an unpaired boat, so a fresh install
+downloads only what you actually look at. **The whole app works with no account** —
+charts, instruments, trends, AIS, routes and polars are all served from the boat. An
+account adds cloud sync, off-boat access and long-term history.
+
+Set **Data directory** to a path on the SSD (or leave blank for the plugin data dir) —
+that is the one setting worth changing straight away.
 
 ### Victron GX / Venus OS (Cerbo, Ekrano)
 Works on Venus OS Large (Signal K enabled). Point **Data directory** at USB/SD storage
@@ -517,6 +547,10 @@ Things this deliberately does not do yet, so they don't come as a surprise:
 - **Backfilled history is not browsable in the app.** `/api/history/*` accepts only a
   relative window clamped to 24 h, so once 2024 is in the cloud there is still no way to
   display it. That needs `from`/`to` support server-side.
+- **Routes saved on the boat don't reach the cloud, and vice versa.** `/api/profile/*` is
+  served from a file on board because the cloud's copy is session-gated and unreachable
+  from the mirror. The two copies never merge, so a route drawn at anchor won't show up
+  in the web app on shore.
 - **Per-path sync rate is approximate.** The subscription sets `period` without a
   `policy`, so Signal K's default governs and a few chatty paths exceed the configured
   interval.

package/index.js

@@ -9,6 +9,7 @@ const { createHistory } = require('./lib/history')
 const { createBackfill } = require('./lib/backfill')
 const { createAis } = require('./lib/ais')
 const { createAisTargets } = require('./lib/ais/targets')
+const { createProfile } = require('./lib/profile')
 const { resolveAccountConfig } = require('./lib/account')
 
 // sailkick-boat: one Signal K plugin, two independently-toggleable modules —
@@ -96,6 +97,9 @@ module.exports = function (app) {
   let backfill = null
   let ais = null
   let aisTargets = null
+  let profile = null
+  let proxyPort = null // what the launcher page needs to build its links
+  let pairedSlug = null
   let statusTimer = null
   let accountStatus = null
   let syncWarning = null
@@ -262,7 +266,7 @@ module.exports = function (app) {
       const pOpts = {
         sailkickUrl: upstream.url,
         storeDir: store,
-        proxyPort: p.proxyPort == null ? 8080 : p.proxyPort,
+        proxyPort: (proxyPort = p.proxyPort == null ? 8080 : p.proxyPort),
         localSignalkUrl: p.localSignalkUrl || 'http://127.0.0.1:3000',
         localPaths: (p.localPaths && p.localPaths.length) ? p.localPaths : PROXY_TUNING.localPaths,
         telemetryPath: p.telemetryPath || PROXY_TUNING.telemetryPath,
@@ -307,6 +311,18 @@ module.exports = function (app) {
         }
       }
 
+      // Routes / polars / settings, from a file on the boat. The cloud's /api/profile is
+      // session-gated and the mirror can never hold that session, so proxying it always
+      // returned 401 — no saved routes, and route-weather fell back to dead reckoning.
+      try {
+        profile = createProfile(app, {})
+        profile.start()
+        pOpts.profile = profile
+      } catch (e) {
+        (app.error || console.error)('[sailkick-boat] profile start failed: ' + e.message)
+        profile = null
+      }
+
       if (p.serveTelemetry !== false) {
         try {
           telemetry = createTelemetry(app, {})
@@ -419,6 +435,7 @@ module.exports = function (app) {
     if (telemetry) parts.push(telemetry.status())
     if (history) parts.push(history.status())
     if (aisTargets) parts.push(aisTargets.status())
+    if (profile) parts.push(profile.status())
     if (ais) parts.push(ais.status())
     if (backfill) parts.push(backfill.status())
     try { app.setPluginStatus(parts.join('   |   ') || 'idle (both features off)') } catch {}
@@ -431,6 +448,7 @@ module.exports = function (app) {
     try { if (telemetry) telemetry.stop() } catch {}
     try { if (history) history.stop() } catch {}
     try { if (aisTargets) aisTargets.stop() } catch {}
+    try { if (profile) profile.stop() } catch {}
     try { if (ais) ais.stop() } catch {}
     try { if (backfill) backfill.stop() } catch {}
     try { if (proxy) proxy.stop() } catch {}
@@ -440,6 +458,9 @@ module.exports = function (app) {
     backfill = null
     ais = null
     aisTargets = null
+    profile = null
+    proxyPort = null
+    pairedSlug = null
     proxy = null
     accountStatus = null
     syncWarning = null
@@ -448,6 +469,19 @@ module.exports = function (app) {
   // Mounted by Signal K at /plugins/sailkick-boat. Handlers dispatch to the live
   // proxy module (created in start), so enable/disable works at request time.
   plugin.registerWithRouter = function (router) {
+    // Read by the launcher page (public/index.html), which Signal K serves at
+    // /sailkick-boat/. That page lives outside this process and cannot know which port
+    // the mirror was configured on, so it asks. `paired` drives the hint about cloud
+    // sync; `running` distinguishes "plugin off" from "mirror port disabled".
+    router.get('/info', (req, res) => {
+      res.json({
+        ok: true,
+        running: !!proxy,
+        port: proxyPort,
+        paired: !!pairedSlug,
+        version: (() => { try { return require('./package.json').version } catch { return null } })()
+      })
+    })
     router.get('/p/*', (req, res) => {
       if (proxy) proxy.handleGet(req, res)
       else res.status(503).send('proxy not enabled')

package/lib/profile/index.js

@@ -0,0 +1,193 @@
+'use strict'
+
+// Per-boat profile (routes, polars, settings), served from the boat itself.
+//
+// The app reads and writes routes through /api/profile/routes. On the cloud that
+// router is requireBoat-gated, and the mirror can never satisfy it: the GET cache path
+// forwards no headers at all, and even if it did, the browser is on the boat's LAN
+// origin and holds no cloud cookie to forward. So every /api/profile call through the
+// mirror returned 401 — the route panel showed nothing, mobile route-weather silently
+// fell back to dead reckoning, and saving a route failed. Offline it was a 504.
+//
+// Same answer as history and AIS: serve it locally. The boat is single-tenant, so
+// there is nothing to authenticate; and route planning offshore is exactly when the
+// cloud is unreachable, which makes local the more useful copy rather than a
+// compromise.
+//
+// Contract: byte-for-byte the envelopes of the cloud's server/routes/profile.js, over
+// the same storage shape as server/profile/store.js (one JSON file, atomic writes,
+// serialized so concurrent saves can't clobber). public/ui/route-panel.js and
+// public/mobile/route-weather.js cannot tell the difference.
+//
+// Boat-local is AUTHORITATIVE here and does not sync: a route saved on board stays on
+// board, a route saved in the webapp stays in the cloud. That divergence is deliberate
+// for now — merging the two needs conflict resolution that is worth designing on its
+// own rather than guessing at.
+
+const fs = require('fs')
+const fsp = fs.promises
+const path = require('path')
+const { randomBytes } = require('crypto')
+
+const SECTIONS = ['polars', 'routes'] // item sections, as the cloud router defines them
+const MAX_BODY_BYTES = 4 * 1024 * 1024 // a polar table is the big one; well under this
+const emptyProfile = () => ({ polars: [], activePolar: null, routes: [], settings: {} })
+const newId = () => randomBytes(8).toString('hex')
+const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v)
+
+function createProfile (app, options = {}) {
+  const log = (m) => (app.debug ? app.debug('[profile] ' + m) : console.log('[sailkick-boat:profile]', m))
+  const warn = (m) => (app.error ? app.error('[sailkick-boat:profile] ' + m) : console.error('[sailkick-boat:profile]', m))
+
+  const dataDir = options.dataDir || (app.getDataDirPath && app.getDataDirPath()) || '.'
+  const file = options.file || path.join(dataDir, 'profile.json')
+  let queue = Promise.resolve() // serializes read-modify-write, as the cloud store does
+  let lastError = null
+  let writes = 0
+
+  async function load () {
+    try {
+      return { ...emptyProfile(), ...JSON.parse(await fsp.readFile(file, 'utf8')) }
+    } catch (e) {
+      if (e.code === 'ENOENT') return emptyProfile() // first use
+      throw e // corrupt or unreadable — surface it rather than silently resetting
+    }
+  }
+
+  async function save (profile) {
+    await fsp.mkdir(path.dirname(file), { recursive: true })
+    const tmp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`
+    await fsp.writeFile(tmp, JSON.stringify(profile, null, 2), { mode: 0o600 })
+    await fsp.rename(tmp, file) // atomic on POSIX — a yanked power cable can't truncate it
+    writes++
+    return profile
+  }
+
+  // mutator(profile) may mutate in place and/or return the next profile.
+  function update (mutator) {
+    const run = async () => {
+      const p = await load()
+      return save((await mutator(p)) || p)
+    }
+    const next = queue.then(run, run) // run regardless of how the previous one ended
+    queue = next.then(() => {}, () => {}) // the tail must never reject
+    return next
+  }
+
+  // ---- HTTP ------------------------------------------------------------------
+  const send = (res, status, body) => {
+    res.statusCode = status
+    res.setHeader('Content-Type', 'application/json')
+    res.end(JSON.stringify(body))
+  }
+  const notFound = (res, what) => send(res, 404, { ok: false, code: 'not-found', message: `${what} not found` })
+  const badBody = (res, what) => send(res, 400, { ok: false, code: 'bad-body', message: `${what} must be a JSON object` })
+  const failed = (res, e) => { lastError = e.message; warn(e.message); send(res, 500, { ok: false, code: 'profile-error', message: e.message }) }
+
+  function readJson (req) {
+    return new Promise((resolve, reject) => {
+      let size = 0
+      const chunks = []
+      req.on('data', (c) => {
+        size += c.length
+        if (size > MAX_BODY_BYTES) { reject(new Error('body too large')); req.destroy(); return }
+        chunks.push(c)
+      })
+      req.on('error', reject)
+      req.on('end', () => {
+        const raw = Buffer.concat(chunks).toString('utf8')
+        if (!raw.trim()) return resolve(null)
+        try { resolve(JSON.parse(raw)) } catch { resolve(undefined) } // undefined = malformed
+      })
+    })
+  }
+
+  // True for anything this module owns, so the mirror can hand it over before the
+  // cache/proxy path sees it.
+  function handles (reqPath) {
+    const p = String(reqPath).split('?')[0]
+    return p === '/api/profile' || p.startsWith('/api/profile/')
+  }
+
+  async function handle (req, res) {
+    try {
+      const [rawPath, query] = String(req.url).split('?')
+      const rest = rawPath.slice('/api/profile'.length).replace(/^\//, '') // '' | 'settings' | 'routes' | 'routes/<id>'
+      const [head, rawId] = rest.split('/')
+      const id = rawId ? decodeURIComponent(rawId) : null
+      const method = req.method === 'HEAD' ? 'GET' : req.method
+
+      // GET /api/profile[?section=…] — whole profile or one section
+      if (head === '' && method === 'GET') {
+        const section = new URLSearchParams(query || '').get('section')
+        const p = await load()
+        return send(res, 200, { ok: true, profile: section ? p[section] : p })
+      }
+
+      if (head === 'settings') {
+        if (method === 'GET') return send(res, 200, { ok: true, settings: (await load()).settings || {} })
+        if (method === 'PUT') {
+          const body = await readJson(req)
+          if (!isObj(body)) return badBody(res, 'settings')
+          await update((p) => { p.settings = body; return p })
+          return send(res, 200, { ok: true })
+        }
+      }
+
+      if (head === 'active-polar' && method === 'PUT') {
+        const body = await readJson(req)
+        await update((p) => { p.activePolar = (body && body.id != null) ? body.id : null; return p })
+        return send(res, 200, { ok: true })
+      }
+
+      if (SECTIONS.includes(head)) {
+        if (method === 'GET' && !id) {
+          const arr = (await load())[head]
+          return send(res, 200, { ok: true, [head]: Array.isArray(arr) ? arr : [] })
+        }
+        if (method === 'GET') {
+          const item = ((await load())[head] || []).find((x) => x && x.id === id)
+          return item ? send(res, 200, { ok: true, item }) : notFound(res, `${head}/${id}`)
+        }
+        if (method === 'POST' && !id) {
+          const body = await readJson(req)
+          if (!isObj(body)) return badBody(res, `${head} item`)
+          const item = { ...body, id: newId(), updatedAt: Date.now() }
+          await update((p) => { (Array.isArray(p[head]) ? p[head] : (p[head] = [])).push(item); return p })
+          return send(res, 201, { ok: true, item })
+        }
+        if (method === 'PUT' && id) {
+          const body = await readJson(req)
+          if (!isObj(body)) return badBody(res, `${head} item`)
+          let missing = false
+          const item = { ...body, id, updatedAt: Date.now() }
+          await update((p) => {
+            const arr = Array.isArray(p[head]) ? p[head] : (p[head] = [])
+            const i = arr.findIndex((x) => x && x.id === id)
+            if (i < 0) { missing = true; return p } // 404, and nothing is written
+            arr[i] = { ...arr[i], ...item }
+            return p
+          })
+          return missing ? notFound(res, `${head}/${id}`) : send(res, 200, { ok: true, item })
+        }
+        if (method === 'DELETE' && id) {
+          await update((p) => { p[head] = (p[head] || []).filter((x) => x && x.id !== id); return p })
+          return send(res, 200, { ok: true })
+        }
+      }
+
+      send(res, 404, { ok: false, code: 'not-found', message: `${req.method} ${rawPath} not found` })
+    } catch (e) { failed(res, e) }
+  }
+
+  function start () { log(`serving /api/profile from ${file} (boat-local; not synced with the cloud copy)`) }
+  function stop () {}
+  function available () { return true } // a local file — no reason it would not be
+  function status () {
+    return `profile: local${writes ? `, ${writes} save(s)` : ''}${lastError ? ` (last error: ${lastError})` : ''}`
+  }
+
+  return { start, stop, status, available, handles, handle, _load: load, _file: () => file }
+}
+
+module.exports = { createProfile, SECTIONS }

package/lib/proxy/index.js

@@ -5,6 +5,7 @@ const http = require('http')
 const net = require('net')
 const { getResource, clearStore } = require('./cache')
 const { createManifest } = require('./manifest')
+const { createContractCheck } = require('../telemetry/contract')
 const { createSeeder } = require('./seed')
 const { countBboxTiles, bboxTiles, boxAround } = require('./tiles')
 
@@ -70,6 +71,7 @@ function createProxy (app, options) {
   let server = null
   let manifest = null
   let seeder = null
+  let contract = null
   let area = null // "download around the boat" progress
   let stopping = false
   // Shared upstream circuit breaker: once a fetch fails offline, uncached requests
@@ -90,6 +92,7 @@ function createProxy (app, options) {
       telemetryPath: options.telemetryPath || '/ws/telemetry',
       history: options.history || null,
       aisTargets: options.aisTargets || null,
+      profile: options.profile || null,
       openAccess: options.openAccess !== false
     }
     log(`mirroring ${cfg.upstream}; local SignalK ${cfg.localSignalk}; store ${cfg.storeDir}`)
@@ -98,9 +101,11 @@ function createProxy (app, options) {
     // announces a new bake. Tiles are otherwise pinned (no time-based expiry).
     if (!options.manifest || options.manifest.enabled !== false) {
       try {
+        contract = createContractCheck(app, { timeoutMs: cfg.timeoutMs })
         manifest = createManifest(app, {
           upstream: cfg.upstream,
           storeDir: cfg.storeDir,
+          contract,
           manifestPath: options.manifest && options.manifest.path,
           pollIntervalSec: options.manifest && options.manifest.pollIntervalSec,
           timeoutMs: cfg.timeoutMs
@@ -147,6 +152,7 @@ function createProxy (app, options) {
     seeder = null
     try { if (manifest) manifest.stop() } catch {}
     manifest = null
+    contract = null
     if (server) {
       try { if (server.closeAllConnections) server.closeAllConnections() } catch {}
       try { server.close() } catch {}
@@ -158,7 +164,8 @@ function createProxy (app, options) {
     if (!cfg) return 'proxy: off'
     const m = manifest ? '; ' + manifest.status() : ''
     const s = seeder ? '; ' + seeder.status() : ''
-    return `proxy: mirror ${cfg.upstream}${cfg.port ? ' :' + cfg.port : ''}; live -> ${cfg.localSignalk}${m}${s}${areaStatus()}`
+    const c = (contract && contract.status()) ? '; ' + contract.status() : ''
+    return `proxy: mirror ${cfg.upstream}${cfg.port ? ' :' + cfg.port : ''}; live -> ${cfg.localSignalk}${m}${s}${areaStatus()}${c}`
   }
 
   // Per-layer max zoom from the upstream asset manifest, cached. Never throws: on any
@@ -232,6 +239,14 @@ function createProxy (app, options) {
         req.url.split('?')[0] === '/api/ais') {
       return cfg.aisTargets.handleAis(req, res)
     }
+    // Routes / polars / settings, from a file on the boat. The cloud's /api/profile is
+    // requireBoat-gated and the mirror can hold no such session — the GET cache path
+    // forwards no headers, and the browser has no cloud cookie for this LAN origin
+    // anyway — so proxying it returned 401 on every call and 504 offline. All methods,
+    // since the app saves and deletes routes here too.
+    if (cfg.profile && cfg.profile.available() && cfg.profile.handles(req.url)) {
+      return cfg.profile.handle(req, res)
+    }
     // /api/config drives the app's login gate + Trends toggle. On the single-tenant
     // boat we serve it with auth turned off (no cloud login over the offline HTTP
     // mirror) and history forced on when we serve it locally. All other config passes
@@ -483,12 +498,19 @@ function createProxy (app, options) {
     if (clamped.length) log(`area prefetch: ${clamped.map(([l, v]) => `${l} capped at z${v.top}`).join(', ')} (upstream limit — those tiles do not exist)`)
     if (total > CAP) { area = { capped: true, total, radius, maxZoom }; log(`area prefetch: ~${total} tiles too large — reduce radius/detail`); return null }
     const paths = [...enumerateTiles(bbox, minZoom, perLayer)]
-    area = { done: 0, total: paths.length, running: true, radius, maxZoom, perLayer }
+    // Hold our OWN reference and mutate that, never the `area` slot. A prefetch of tens
+    // of thousands of tiles outlives a plugin disable by minutes, and stop() sets
+    // area = null — so settling handlers that touched `area` threw
+    // "Cannot set properties of null (setting 'running')" on every disable/enable. The
+    // same reference also protects against a restart having installed a NEWER prefetch:
+    // the old run must not report its progress into the new one's counters.
+    const run = { done: 0, total: paths.length, running: true, radius, maxZoom, perLayer }
+    area = run
     log(`area prefetch: ${radius}nm around ${pos.latitude.toFixed(2)},${pos.longitude.toFixed(2)} to z${maxZoom} — ${paths.length} tiles`)
-    area.promise = warmMany(paths, { concurrency: pf.concurrency || 4, onProgress: () => { area.done++ } })
-      .then((r) => { area.running = false; area.result = r; log(`area prefetch done: ${r.cached} cached, ${r.empty} empty, ${r.failed} failed`); return r })
-      .catch((e) => { area.running = false; log('area prefetch error: ' + e.message) })
-    return area.promise
+    run.promise = warmMany(paths, { concurrency: pf.concurrency || 4, onProgress: () => { run.done++ } })
+      .then((r) => { run.running = false; run.result = r; log(`area prefetch done: ${r.cached} cached, ${r.empty} empty, ${r.failed} failed`); return r })
+      .catch((e) => { run.running = false; log('area prefetch error: ' + e.message) })
+    return run.promise
   }
 
   function areaStatus () {

package/lib/proxy/manifest.js

@@ -67,6 +67,11 @@ function createManifest (app, options) {
     } catch { return } // offline / bad JSON → no-op, nothing invalidated
     lastOk = Date.now()
 
+    // We are online and talking to the app server — the one moment worth re-checking
+    // the signalk-map contract seam. Piggybacking here keeps it to one timer, and it
+    // must never affect cache invalidation, so it is fire-and-forget.
+    if (options.contract) { try { options.contract.check(cfg.upstream) } catch {} }
+
     const families = { ...((m && m.bakes) || {}) }
     if (m && m.app != null) families.app = m.app
 

package/lib/telemetry/contract.js

@@ -0,0 +1,67 @@
+'use strict'
+
+// Drift detector for the highest-risk contract seam in the system.
+//
+// lib/telemetry/signalk-map.js is a hand-ported copy of the app's
+// public/engine/signalk-map.js. It has now drifted TWICE without anyone noticing:
+//   - v0.14.6: nine cases (STW, measured true wind, attitude, rudder, autopilot)
+//   - v0.18.6: the active-waypoint course block + TWA, VMG, sea/air temp, engine rpm
+// Both times the data was sitting on the boat's SignalK bus and the plugin threw it
+// away, so the app looked broken only when connected to the boat — the hardest place
+// to debug and the only place that matters offshore.
+//
+// The server now publishes the content hash of its copy at /health:
+//     { contracts: { signalkMap: "2015ae986cd8" } }
+// We can't compare byte-for-byte — our copy is CommonJS and theirs is an ES module —
+// so we pin the hash of the app file we last ported FROM. If the app changes that
+// file, the published hash stops matching the pin and we say so, loudly, in the
+// Signal K log. It cannot tell us WHAT changed; it tells us to go and look, which is
+// exactly what was missing both times.
+//
+// Updating this pin is part of re-porting signalk-map.js — never on its own:
+//     sha256sum <sailkick>/public/engine/signalk-map.js | cut -c1-12
+
+// sha256(app public/engine/signalk-map.js)[0..12] as ported in v0.18.6
+const PINNED_APP_HASH = '2015ae986cd8'
+
+function createContractCheck (app, options = {}) {
+  const warn = (m) => (app.error ? app.error('[sailkick-boat:contract] ' + m) : console.error('[sailkick-boat:contract]', m))
+  const log = (m) => (app.debug ? app.debug('[contract] ' + m) : console.log('[sailkick-boat:contract]', m))
+  const timeoutMs = options.timeoutMs || 15000
+  let drifted = null // null = unknown (never reached the server, or it predates /health.contracts)
+  let announced = null // last state we logged, so a 5-minute poll doesn't spam the log
+
+  // Best-effort: a boat is offline most of the time, and older servers don't publish
+  // `contracts` at all. Neither is an error — both just leave the state unknown.
+  async function check (upstream) {
+    if (!upstream) return drifted
+    let remote
+    try {
+      const r = await fetch(String(upstream).replace(/\/+$/, '') + '/health', { signal: AbortSignal.timeout(timeoutMs) })
+      if (!r.ok) return drifted
+      const body = await r.json()
+      remote = body && body.contracts && body.contracts.signalkMap
+    } catch { return drifted } // offline → keep whatever we last knew
+    if (!remote) return drifted // server predates the contract hash
+
+    drifted = remote !== PINNED_APP_HASH
+    if (drifted !== announced) {
+      announced = drifted
+      if (drifted) {
+        warn(`signalk-map contract DRIFT: the server runs ${remote}, this plugin was ported from ${PINNED_APP_HASH}. ` +
+          'The app may show blank instrument or waypoint values when connected to this boat. ' +
+          're-port lib/telemetry/signalk-map.js from the app and update the pin.')
+      } else {
+        log(`signalk-map contract in sync (${remote})`)
+      }
+    }
+    return drifted
+  }
+
+  // Only worth a status line when something is wrong; "in sync" is the boring case.
+  function status () { return drifted ? 'contract: signalk-map DRIFTED from the server — see log' : null }
+
+  return { check, status, _state: () => drifted, PINNED_APP_HASH }
+}
+
+module.exports = { createContractCheck, PINNED_APP_HASH }

package/lib/telemetry/signalk-map.js

@@ -10,11 +10,29 @@ const RAD2DEG = 180 / Math.PI
 const wrap360 = (d) => ((d % 360) + 360) % 360
 const wrap180 = (d) => { const w = wrap360(d); return w > 180 ? w - 360 : w }
 
+// Active-waypoint course data. SignalK publishes it under three prefixes
+// depending on server version/config (v1 courseGreatCircle/courseRhumbline,
+// v2 course.calcValues) — all carry the same SI values (rad, m, m/s, s).
+const COURSE_RE = /^navigation\.(?:course(?:GreatCircle|Rhumbline)\.nextPoint|course\.calcValues)\.(bearingTrue|distance|velocityMadeGood|timeToGo)$/
+
 function signalkValuesToPatch (values) {
   const patch = {}
   if (!Array.isArray(values)) return patch
   for (const v of values) {
-    if (!v || v.value == null) continue
+    if (!v || !v.path) continue
+    // Course paths first: unlike sensors, a null here MEANS something — the
+    // destination was cleared — so propagate it instead of skipping, or the
+    // ribbon would show stale waypoint numbers forever.
+    const course = v.path.match(COURSE_RE)
+    if (course) {
+      const suffix = course[1]
+      if (suffix === 'bearingTrue') patch.wptBrgDeg = Number.isFinite(v.value) ? wrap360(v.value * RAD2DEG) : null
+      else if (suffix === 'distance') patch.wptDistNm = Number.isFinite(v.value) ? Math.max(0, v.value / 1852) : null
+      else if (suffix === 'velocityMadeGood') patch.wptVmgKt = Number.isFinite(v.value) ? v.value * MS_TO_KT : null
+      else patch.wptTtgSec = Number.isFinite(v.value) && v.value >= 0 ? v.value : null
+      continue
+    }
+    if (v.value == null) continue
     switch (v.path) {
       case 'navigation.position': {
         const { latitude, longitude } = v.value || {}
@@ -54,10 +72,30 @@ function signalkValuesToPatch (values) {
       case 'environment.wind.directionTrue': // absolute compass direction (not off-bow)
         if (Number.isFinite(v.value)) patch.twdDeg = wrap360(v.value * RAD2DEG)
         break
+      case 'environment.wind.angleTrueWater': // true wind ANGLE off the bow, port negative
+        if (Number.isFinite(v.value)) patch.twaDeg = wrap180(v.value * RAD2DEG)
+        break
+      case 'performance.velocityMadeGood': // signed: negative = losing ground to windward
+        if (Number.isFinite(v.value)) patch.vmgKt = v.value * MS_TO_KT
+        break
       case 'environment.depth.belowSurface':
       case 'environment.depth.belowTransducer':
         if (Number.isFinite(v.value)) patch.depthM = v.value
         break
+      // (active-waypoint course paths are handled above via COURSE_RE — all three
+      //  publish prefixes, with nulls propagated so a cleared goto clears the values)
+      case 'environment.water.temperature': // sea temperature, K → °C
+        if (Number.isFinite(v.value)) patch.seaTempC = v.value - 273.15
+        break
+      case 'environment.outside.temperature': // air temperature, K → °C
+        if (Number.isFinite(v.value)) patch.airTempC = v.value - 273.15
+        break
+      case 'propulsion.port.revolutions': // engine speed, Hz → rpm
+        if (Number.isFinite(v.value)) patch.rpmPort = Math.max(0, v.value * 60)
+        break
+      case 'propulsion.starboard.revolutions':
+        if (Number.isFinite(v.value)) patch.rpmStbd = Math.max(0, v.value * 60)
+        break
       case 'steering.rudderAngle':
         if (Number.isFinite(v.value)) patch.rudderDeg = v.value * RAD2DEG
         break

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "sailkick-boat",
-  "version": "0.18.5",
-  "description": "Run the sailkick app on board with no internet: charts, weather, climatology, trends and AIS all served from the boat itself. With a sailkick account it also syncs your metrics to the cloud in real time. Alpha, invite-only — info@sailkick.io",
+  "version": "0.20.0",
+  "description": "Run the sailkick app on board with no internet: charts, weather, climatology, trends and AIS all served from the boat itself. With a sailkick account it also syncs your metrics to the cloud in real time. Alpha, invite-only \u2014 info@sailkick.io",
   "main": "index.js",
   "scripts": {
     "test": "node --test"
   },
   "keywords": [
     "signalk-node-server-plugin",
+    "signalk-webapp",
     "signalk",
     "sailkick",
     "influxdb",
@@ -15,6 +16,7 @@
     "cache",
     "proxy"
   ],
+  "signalk-plugin-enabled-by-default": true,
   "author": "lauchat",
   "license": "MIT",
   "repository": {
@@ -35,6 +37,7 @@
   "files": [
     "index.js",
     "lib/",
+    "public/",
     "README.md",
     "LICENSE"
   ]

package/public/index.html

@@ -0,0 +1,97 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Sailkick</title>
+<!--
+  Launcher for the Signal K admin menu.
+
+  Signal K mounts <package>/public/ at /<package-name> for any package carrying the
+  `signalk-webapp` keyword, and dedupes the menu by PACKAGE name (interfaces/webapps.js,
+  uniqBy(webapps,'name')) — so one package can only ever produce one entry. Hence one
+  launcher offering both surfaces rather than two menu items.
+
+  The app itself is not served from here: it lives on the plugin's mirror, on a port the
+  owner can change. This page therefore asks the plugin where it is, via the plugin
+  router at /plugins/sailkick-boat/info, and falls back to the default port if that
+  cannot be reached. The host is always taken from the current URL, so this works over
+  whatever address the browser reached Signal K on — LAN IP, .local, or tailnet.
+-->
+<style>
+  :root { color-scheme: light dark; --bg:#f6f7f9; --fg:#12161c; --mut:#5c6672; --card:#fff; --line:#e2e6eb; --accent:#0b6ea9 }
+  @media (prefers-color-scheme: dark) {
+    :root { --bg:#11151a; --fg:#e8edf2; --mut:#96a1ad; --card:#171c23; --line:#252c35; --accent:#4aa8e0 }
+  }
+  * { box-sizing: border-box }
+  body { margin:0; padding:2rem 1rem; background:var(--bg); color:var(--fg);
+         font:16px/1.5 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif }
+  main { max-width:44rem; margin:0 auto }
+  h1 { margin:0 0 .25rem; font-size:1.5rem; letter-spacing:-.01em }
+  .sub { color:var(--mut); margin:0 0 1.5rem }
+  .grid { display:grid; gap:1rem; grid-template-columns:repeat(auto-fit,minmax(15rem,1fr)) }
+  a.card { display:block; padding:1.1rem 1.2rem; background:var(--card); border:1px solid var(--line);
+           border-radius:.7rem; text-decoration:none; color:inherit; transition:border-color .15s, transform .15s }
+  a.card:hover { border-color:var(--accent); transform:translateY(-1px) }
+  a.card strong { display:block; font-size:1.05rem; margin-bottom:.2rem }
+  a.card span { color:var(--mut); font-size:.9rem }
+  .note { margin-top:1.5rem; padding:.85rem 1rem; background:var(--card); border:1px solid var(--line);
+          border-radius:.6rem; color:var(--mut); font-size:.9rem }
+  .note b { color:var(--fg); font-weight:600 }
+  code { font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:.87em }
+  .warn { border-color:#b4791f }
+</style>
+</head>
+<body>
+<main>
+  <h1>Sailkick</h1>
+  <p class="sub">Charts, instruments and AIS, served from this boat.</p>
+
+  <div class="grid">
+    <a class="card" id="desktop" href="#"><strong>Open Sailkick</strong><span>Full app — chart, trends, weather</span></a>
+    <a class="card" id="mobile"  href="#"><strong>Open on phone</strong><span>Mobile view — swipeable instrument decks</span></a>
+  </div>
+
+  <div class="note" id="note">Locating the mirror…</div>
+</main>
+
+<script>
+(function () {
+  var DEFAULT_PORT = 8080;
+  var note = document.getElementById('note');
+
+  function apply (port, info) {
+    var base = location.protocol + '//' + location.hostname + (port ? ':' + port : '');
+    document.getElementById('desktop').href = base + '/';
+    document.getElementById('mobile').href = base + '/mobile.html';
+
+    if (info && info.running === false) {
+      note.className = 'note warn';
+      note.innerHTML = '<b>The mirror is not running.</b> Enable the plugin in ' +
+        'Server → Plugin Config → Sailkick boat companion, then reload this page.';
+      return;
+    }
+    if (port === 0) {
+      note.className = 'note warn';
+      note.innerHTML = '<b>The mirror port is disabled</b> (set to 0 in the plugin config), ' +
+        'so the app cannot be opened from here. Set a port — 8080 is the default.';
+      return;
+    }
+    var paired = info && info.paired;
+    note.innerHTML = 'Serving on <code>' + base + '</code>. Works with no account and no internet — ' +
+      'live data comes from this boat’s own Signal K, and maps are cached locally.' +
+      (paired ? '' : ' <b>Cloud sync is off</b> until you add a sailkick account in the plugin config; ' +
+                     'nothing leaves the boat before then.');
+  }
+
+  fetch('/plugins/sailkick-boat/info', { credentials: 'same-origin' })
+    .then(function (r) { return r.ok ? r.json() : null })
+    .then(function (j) {
+      if (j && typeof j.port === 'number') apply(j.port, j);
+      else apply(DEFAULT_PORT, null);
+    })
+    .catch(function () { apply(DEFAULT_PORT, null); });
+})();
+</script>
+</body>
+</html>