sailkick-boat 0.13.4

package/lib/proxy/tiles.js

@@ -0,0 +1,62 @@
+'use strict'
+
+// Slippy-map (XYZ / Web-Mercator) tile math. Pure, dependency-free — shared by the
+// global-base seeder and the region-prefetch handler. Matches the app's tile scheme
+// (public/viewer/coastline-overlay.js): top-left origin, latitude clamped to the
+// Web-Mercator limit.
+
+const MAX_LAT = 85.05112878
+
+// (lat,lon,z) -> [x,y] tile indices, clamped into [0, 2^z-1].
+function deg2tile (lat, lon, z) {
+  const n = 2 ** z
+  const clat = Math.max(-MAX_LAT, Math.min(MAX_LAT, lat))
+  const latR = clat * Math.PI / 180
+  let x = Math.floor((lon + 180) / 360 * n)
+  let y = Math.floor((1 - Math.asinh(Math.tan(latR)) / Math.PI) / 2 * n)
+  const clamp = (v) => Math.max(0, Math.min(n - 1, v))
+  return [clamp(x), clamp(y)]
+}
+
+// bbox [w,s,e,n] -> inclusive tile range at zoom z. North maps to the smaller y
+// (top), west to the smaller x. Antimeridian-crossing bboxes (w > e) are not split
+// here — callers pass single-hemisphere passage boxes.
+function bboxTileRange (bbox, z) {
+  const [w, s, e, n] = bbox
+  const [xw, yn] = deg2tile(n, w, z) // north-west
+  const [xe, ys] = deg2tile(s, e, z) // south-east
+  return { x0: Math.min(xw, xe), x1: Math.max(xw, xe), y0: Math.min(yn, ys), y1: Math.max(yn, ys) }
+}
+
+// Total tiles a bbox covers across [minZoom, maxZoom] inclusive (for the estimate/cap).
+function countBboxTiles (bbox, minZoom, maxZoom) {
+  let total = 0
+  for (let z = minZoom; z <= maxZoom; z++) {
+    const { x0, x1, y0, y1 } = bboxTileRange(bbox, z)
+    total += (x1 - x0 + 1) * (y1 - y0 + 1)
+  }
+  return total
+}
+
+// Yield every "z/x/y" for a bbox across [minZoom, maxZoom] (generator — no big array).
+function * bboxTiles (bbox, minZoom, maxZoom) {
+  for (let z = minZoom; z <= maxZoom; z++) {
+    const { x0, x1, y0, y1 } = bboxTileRange(bbox, z)
+    for (let x = x0; x <= x1; x++) {
+      for (let y = y0; y <= y1; y++) yield { z, x, y }
+    }
+  }
+}
+
+// Bounding box [w,s,e,n] of `radiusNm` nautical miles around a point. 1 nm ≈ 1/60°
+// of latitude; longitude degrees shrink with cos(lat) (clamped near the poles).
+function boxAround (lat, lon, radiusNm) {
+  const dLat = radiusNm / 60
+  const dLon = radiusNm / 60 / Math.max(0.05, Math.cos(lat * Math.PI / 180))
+  return [
+    Math.max(-180, lon - dLon), Math.max(-85, lat - dLat),
+    Math.min(180, lon + dLon), Math.min(85, lat + dLat)
+  ]
+}
+
+module.exports = { deg2tile, bboxTileRange, countBboxTiles, bboxTiles, boxAround, MAX_LAT }

package/lib/sync/index.js

@@ -0,0 +1,150 @@
+'use strict'
+
+// Telemetry sync module: durable, gapless store-and-forward of self-vessel data
+// to InfluxDB v2 (survives offline periods + Signal K restarts). Lifted verbatim
+// from signalk-to-influxdb-gapless, wrapped as createSync(app, options) ->
+// { start, stop, status } so it can live alongside the proxy module in one plugin.
+
+const fs = require('fs')
+const path = require('path')
+const { Spool, DEFAULT_MAX_BYTES } = require('./spool')
+const { writeLines } = require('./influxWrite')
+const { deltaToLines } = require('./lineprotocol')
+
+function createSync (app, options) {
+  const log = (m) => (app.debug ? app.debug('[sync] ' + m) : console.log('[sailkick-boat:sync]', m))
+  let state = null
+
+  function start () {
+    const cfg = {
+      influxUrl: options.influxUrl,
+      org: options.org || 'sailkick',
+      bucket: options.bucket,
+      token: options.token,
+      timeoutMs: options.requestTimeoutMs || 30000
+    }
+    if (!cfg.influxUrl || !cfg.bucket || !cfg.token) {
+      log('not started — missing influxUrl / bucket / token')
+      state = { statusLine: 'sync: not configured', stopped: true }
+      return
+    }
+
+    const dataDir = (app.getDataDirPath && app.getDataDirPath()) || '.'
+    const spoolDir = options.spoolDir || path.join(dataDir, 'spool')
+    const spool = new Spool({ dir: spoolDir, maxBytes: options.maxBufferBytes || DEFAULT_MAX_BYTES, logger: log })
+    const selfContext = app.selfContext || ('vessels.' + (app.selfId || 'self'))
+
+    state = {
+      cfg, spool, log, batch: [], batchSize: options.batchSize || 1000,
+      flushTimer: null, pumpTimer: null, stopped: false, unsubscribes: [],
+      retryMin: options.retryMinMs || 1000, retryMax: options.retryMaxMs || 60000,
+      backoff: options.retryMinMs || 1000, idlePoll: Math.max(500, options.flushIntervalMs || 1000),
+      lastOkAt: null, pumping: false, statusLine: 'sync: starting'
+    }
+
+    const handleDelta = (delta) => {
+      try {
+        const lines = deltaToLines(delta, { context: selfContext })
+        if (lines.length) state.batch.push(...lines)
+        if (state.batch.length >= state.batchSize) flush()
+      } catch (e) { log('delta error: ' + e.message) }
+    }
+
+    const flush = () => {
+      if (state.stopped || !state.batch.length) return
+      const lines = state.batch
+      state.batch = []
+      spool.append(lines).then(() => pump()).catch((e) => {
+        log('spool append failed: ' + e.message)
+        state.batch.unshift(...lines)
+      })
+    }
+
+    async function pump () {
+      if (state.stopped || state.pumping) return
+      state.pumping = true
+      try {
+        const files = await spool.pending()
+        for (const file of files) {
+          if (state.stopped) break
+          let body
+          try { body = await fs.promises.readFile(file, 'utf8') } catch { continue }
+          if (!body.trim()) { await spool.remove(file); continue }
+          const res = await writeLines(cfg, body)
+          if (res.ok) {
+            await spool.remove(file); state.lastOkAt = new Date(); state.backoff = state.retryMin
+          } else if (res.retryable) {
+            state.pumping = false; scheduleRetry(res); return
+          } else {
+            log(`batch rejected (HTTP ${res.status}) — quarantined`); await spool.quarantine(file)
+          }
+        }
+      } catch (e) {
+        log('pump error: ' + e.message); state.pumping = false; scheduleRetry(); return
+      }
+      state.pumping = false; scheduleIdle(); refreshStatus()
+    }
+
+    function scheduleRetry (res) {
+      if (state.stopped) return
+      clearTimeout(state.pumpTimer)
+      const delay = state.backoff
+      state.backoff = Math.min(state.backoff * 2, state.retryMax)
+      state.pumpTimer = setTimeout(pump, delay)
+      refreshStatus(`${res && res.status ? 'HTTP ' + res.status : 'offline'} — retry ${Math.round(delay / 1000)}s`)
+    }
+    function scheduleIdle () {
+      if (state.stopped) return
+      clearTimeout(state.pumpTimer)
+      state.pumpTimer = setTimeout(pump, state.idlePoll)
+    }
+    async function refreshStatus (suffix) {
+      try {
+        const { count, bytes } = await spool.stats()
+        const last = state.lastOkAt ? state.lastOkAt.toISOString() : 'never'
+        state.statusLine = `sync: buffered ${count}f/${Math.round(bytes / 1024)}KB; last ok ${last}${suffix ? '; ' + suffix : ''}`
+      } catch {}
+    }
+
+    spool.init().then(() => {
+      state.flushTimer = setInterval(flush, options.flushIntervalMs || 1000)
+      subscribe(handleDelta)
+      pump()
+      log(`started; buffer dir ${spoolDir}; context ${selfContext}`)
+    }).catch((e) => log('init failed: ' + e.message))
+
+    function subscribe (onDelta) {
+      const sub = { context: 'vessels.self', subscribe: [{ path: '*', period: options.subscribePeriodMs || 1000 }] }
+      if (app.subscriptionmanager && app.subscriptionmanager.subscribe) {
+        app.subscriptionmanager.subscribe(sub, state.unsubscribes, (err) => log('subscription error: ' + err), onDelta)
+      } else if (app.signalk && app.signalk.on) {
+        const h = (d) => { if (!d.context || d.context === selfContext) onDelta(d) }
+        app.signalk.on('delta', h)
+        state.unsubscribes.push(() => app.signalk.removeListener('delta', h))
+      } else {
+        log('no subscription mechanism available')
+      }
+    }
+  }
+
+  function stop () {
+    if (!state) return
+    state.stopped = true
+    clearInterval(state.flushTimer)
+    clearTimeout(state.pumpTimer)
+    for (const u of (state.unsubscribes || [])) { try { u() } catch {} }
+    if (state.batch && state.batch.length) {
+      try {
+        const name = `${Date.now().toString().padStart(15, '0')}-final.lp`
+        fs.writeFileSync(path.join(state.spool.dir, name), state.batch.join('\n') + '\n')
+        state.batch = []
+      } catch (e) { /* best effort */ }
+    }
+  }
+
+  function status () { return state ? state.statusLine : 'sync: off' }
+
+  return { start, stop, status }
+}
+
+module.exports = { createSync }

package/lib/sync/influxWrite.js

@@ -0,0 +1,49 @@
+'use strict'
+
+// POST gzipped line protocol to InfluxDB v2's /api/v2/write.
+//
+// Return shape:
+//   { ok: true, status: 204 }
+//   { ok: false, retryable: true,  networkError: true }   connection failed
+//   { ok: false, retryable: true,  status }                429 / 5xx (transient)
+//   { ok: false, retryable: false, status, body }          4xx (bad data/auth)
+//
+// 4xx is non-retryable: retrying a malformed or unauthorized batch forever would
+// wedge the queue, so the caller quarantines it instead.
+
+const zlib = require('zlib')
+
+async function writeLines (cfg, body) {
+  const base = cfg.influxUrl.replace(/\/+$/, '')
+  const url = `${base}/api/v2/write` +
+    `?org=${encodeURIComponent(cfg.org)}` +
+    `&bucket=${encodeURIComponent(cfg.bucket)}` +
+    '&precision=ns'
+
+  const gz = zlib.gzipSync(Buffer.from(body, 'utf8'))
+
+  let res
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Token ${cfg.token}`,
+        'Content-Type': 'text/plain; charset=utf-8',
+        'Content-Encoding': 'gzip'
+      },
+      body: gz,
+      signal: cfg.timeoutMs ? AbortSignal.timeout(cfg.timeoutMs) : undefined
+    })
+  } catch (e) {
+    return { ok: false, retryable: true, networkError: true, error: e.message }
+  }
+
+  if (res.status === 204) return { ok: true, status: 204 }
+
+  let text = ''
+  try { text = await res.text() } catch {}
+  const retryable = res.status === 429 || res.status >= 500
+  return { ok: false, retryable, status: res.status, body: text }
+}
+
+module.exports = { writeLines }

package/lib/sync/lineprotocol.js

@@ -0,0 +1,121 @@
+'use strict'
+
+// Convert Signal K deltas to InfluxDB line protocol, matching the schema written
+// by the community `signalk-to-influxdb-v2` plugin — so this plugin's output
+// unifies seamlessly with data already collected under that schema.
+//
+//   measurement = Signal K path            e.g. navigation.speedOverGround
+//   field       = "value"                  the scalar reading
+//   tags        = context, self, source    context = "vessels.<urn>", self = "true"
+//
+// Value handling:
+//   number / boolean / string -> measurement=path, field value
+//   navigation.position (object w/ lat+lon) -> SPECIAL CASE: fields lat, lon (+altitude)
+//   any other object -> flattened RECURSIVELY into dotted measurements,
+//       e.g. navigation.attitude {roll,pitch} -> navigation.attitude.roll,
+//            navigation.attitude.pitch  (each field "value")
+//
+// (The upstream schema also tags position with an s2_cell_id; we intentionally
+// omit it — it needs an S2 library and adds cardinality. lat/lon are identical,
+// so position queries still line up; only that one extra tag is absent on our
+// rows. Add later if geo-binning is needed.)
+//
+// Timestamps use nanosecond precision, so writes are idempotent on
+// (measurement, tagset, timestamp): replaying after a reconnect never dupes.
+
+function escapeMeasurement (s) {
+  return String(s).replace(/([,\s])/g, '\\$1')
+}
+
+function escapeTag (s) {
+  return String(s).replace(/([,=\s])/g, '\\$1')
+}
+
+function escapeStringField (s) {
+  return '"' + String(s).replace(/(["\\])/g, '\\$1') + '"'
+}
+
+// ms (number) or ISO string / Date -> nanosecond string, or null if unparseable.
+function toNs (ts) {
+  let ms
+  if (typeof ts === 'number') ms = ts
+  else if (ts instanceof Date) ms = ts.getTime()
+  else {
+    const p = Date.parse(ts)
+    ms = Number.isNaN(p) ? null : p
+  }
+  if (ms == null) return null
+  return (BigInt(Math.round(ms)) * 1000000n).toString()
+}
+
+function line (measurement, fieldset, tags, ns) {
+  const m = escapeMeasurement(measurement)
+  return ns != null ? `${m},${tags} ${fieldset} ${ns}` : `${m},${tags} ${fieldset}`
+}
+
+// Emit line(s) for one path/value, recursing into objects. Appends to `lines`.
+function emit (path, value, tags, ns, lines) {
+  if (value == null) return
+  if (typeof value === 'number') {
+    if (Number.isFinite(value)) lines.push(line(path, `value=${value}`, tags, ns))
+    return
+  }
+  if (typeof value === 'boolean') {
+    lines.push(line(path, `value=${value ? 'true' : 'false'}`, tags, ns))
+    return
+  }
+  if (typeof value === 'string') {
+    if (value.length) lines.push(line(path, `value=${escapeStringField(value)}`, tags, ns))
+    return
+  }
+  if (Array.isArray(value)) return // arrays are not stored
+  if (typeof value === 'object') {
+    // navigation.position and similar: store as lat/lon (+altitude) fields.
+    if (Number.isFinite(value.latitude) && Number.isFinite(value.longitude)) {
+      let f = `lat=${value.latitude},lon=${value.longitude}`
+      if (Number.isFinite(value.altitude)) f += `,altitude=${value.altitude}`
+      lines.push(line(path, f, tags, ns))
+      return
+    }
+    // any other object: flatten recursively into dotted measurements.
+    for (const [k, v] of Object.entries(value)) emit(`${path}.${k}`, v, tags, ns, lines)
+    return
+  }
+}
+
+// delta -> array of line-protocol strings.
+// opts.context = fallback self context ("vessels.<urn>") when delta.context absent.
+function deltaToLines (delta, opts) {
+  const lines = []
+  if (!delta || !Array.isArray(delta.updates)) return lines
+  const ctx = escapeTag(delta.context || (opts && opts.context) || 'vessels.self')
+
+  for (const update of delta.updates) {
+    if (!update || !Array.isArray(update.values)) continue
+    const source = escapeTag(update.$source || sourceLabel(update.source) || 'unknown')
+    const ns = toNs(update.timestamp != null ? update.timestamp : Date.now())
+    const tags = `context=${ctx},self=true,source=${source}`
+    for (const pv of update.values) {
+      if (!pv || !pv.path) continue // skip vessel-level '' path objects
+      emit(pv.path, pv.value, tags, ns, lines)
+    }
+  }
+  return lines
+}
+
+function sourceLabel (source) {
+  if (!source) return null
+  if (typeof source === 'string') return source
+  return [source.label, source.type, source.src, source.talker]
+    .filter(Boolean)
+    .join('.') || null
+}
+
+module.exports = {
+  deltaToLines,
+  emit,
+  toNs,
+  escapeMeasurement,
+  escapeTag,
+  escapeStringField
+}

package/lib/sync/spool.js

@@ -0,0 +1,101 @@
+'use strict'
+
+// Durable on-disk spool: the heart of "gapless".
+//
+// Each flushed batch becomes one atomically-published `.lp` file (write to a
+// temp name, then rename). A file existing == not yet acknowledged by InfluxDB;
+// the uploader deletes it only after a 204. Because the spool lives on disk, an
+// offline stretch or a full Signal K restart simply leaves files to be uploaded
+// on next start — nothing is lost. The buffer is bounded by total bytes; on
+// overflow the oldest files are dropped (and logged) so a long-offline boat
+// never fills its own disk.
+
+const fs = require('fs')
+const fsp = fs.promises
+const path = require('path')
+
+const DEFAULT_MAX_BYTES = 500 * 1024 * 1024 // 500 MB
+
+class Spool {
+  constructor ({ dir, maxBytes, logger } = {}) {
+    this.dir = dir
+    this.deadDir = path.join(dir, 'dead')
+    this.maxBytes = maxBytes || DEFAULT_MAX_BYTES
+    this.log = logger || (() => {})
+    this.seq = 0
+  }
+
+  async init () {
+    await fsp.mkdir(this.dir, { recursive: true })
+    await fsp.mkdir(this.deadDir, { recursive: true })
+    // Remove temp files orphaned by a crash mid-write.
+    for (const f of await fsp.readdir(this.dir)) {
+      if (f.startsWith('.tmp-')) {
+        await fsp.unlink(path.join(this.dir, f)).catch(() => {})
+      }
+    }
+  }
+
+  // Persist a batch of line-protocol strings as one atomic .lp file.
+  async append (lines) {
+    if (!lines || !lines.length) return null
+    const body = lines.join('\n') + '\n'
+    const name = `${Date.now().toString().padStart(15, '0')}-${(this.seq++)
+      .toString().padStart(9, '0')}.lp`
+    const tmp = path.join(this.dir, `.tmp-${name}`)
+    const dst = path.join(this.dir, name)
+    await fsp.writeFile(tmp, body)
+    await fsp.rename(tmp, dst) // atomic publish
+    await this.enforceBound()
+    return dst
+  }
+
+  // Pending .lp files, oldest first (zero-padded names sort chronologically).
+  async pending () {
+    const files = (await fsp.readdir(this.dir))
+      .filter(f => f.endsWith('.lp') && !f.startsWith('.tmp-'))
+      .sort()
+    return files.map(f => path.join(this.dir, f))
+  }
+
+  async stats () {
+    let bytes = 0
+    let count = 0
+    for (const f of await this.pending()) {
+      try { bytes += (await fsp.stat(f)).size; count++ } catch {}
+    }
+    return { count, bytes }
+  }
+
+  async enforceBound () {
+    let { bytes } = await this.stats()
+    if (bytes <= this.maxBytes) return 0
+    let dropped = 0
+    let droppedBytes = 0
+    for (const f of await this.pending()) {
+      if (bytes <= this.maxBytes) break
+      try {
+        const sz = (await fsp.stat(f)).size
+        await fsp.unlink(f)
+        bytes -= sz; droppedBytes += sz; dropped++
+      } catch {}
+    }
+    if (dropped) {
+      this.log(`buffer exceeded ${this.maxBytes} bytes — dropped ${dropped} oldest file(s) (${droppedBytes} bytes)`)
+    }
+    return dropped
+  }
+
+  async remove (file) {
+    await fsp.unlink(file).catch(() => {})
+  }
+
+  // Move a permanently-rejected (4xx) batch aside so it can't block the queue.
+  async quarantine (file) {
+    const dst = path.join(this.deadDir, path.basename(file))
+    await fsp.rename(file, dst).catch(async () => { await this.remove(file) })
+    return dst
+  }
+}
+
+module.exports = { Spool, DEFAULT_MAX_BYTES }

package/lib/telemetry/index.js

@@ -0,0 +1,123 @@
+'use strict'
+
+const crypto = require('crypto')
+const { signalkValuesToPatch, resolveHeadingDeg } = require('./signalk-map')
+
+// Serves the sailkick app's /ws/telemetry bus FROM the boat's local SignalK, so
+// the app uses the identical telemetry contract whether it talks to the cloud
+// sailkick server or this on-boat plugin. Faithful port of the server's
+// SignalKSource (SEED, gate-on-first-fix, accumulate, resolve headingDeg,
+// updatedAt) + bus wire format ({type:'hello'|'telemetry/update', state}).
+// Dependency-free WebSocket server (handshake + text frames).
+
+const WS_GUID = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11'
+const SUBPROTOCOL = 'sailkick.telemetry.v1'
+const SEED = { sogKt: 0, cogDeg: 0, headingDeg: 0, awsKt: null, awaDeg: null }
+
+function encodeTextFrame (str) {
+  const payload = Buffer.from(str, 'utf8')
+  const len = payload.length
+  let header
+  if (len < 126) header = Buffer.from([0x81, len])
+  else if (len < 65536) { header = Buffer.alloc(4); header[0] = 0x81; header[1] = 126; header.writeUInt16BE(len, 2) } else { header = Buffer.alloc(10); header[0] = 0x81; header[1] = 127; header.writeBigUInt64BE(BigInt(len), 2) }
+  return Buffer.concat([header, payload])
+}
+
+function createTelemetry (app, options = {}) {
+  const log = (m) => (app.debug ? app.debug('[telemetry] ' + m) : console.log('[sailkick-boat:telemetry]', m))
+  let state = null
+  let magSource = null // lock the $source for navigation.headingMagnetic (dual-source guard)
+  const clients = new Set()
+  const unsubscribes = []
+
+  function send (socket, obj) {
+    try { socket.write(encodeTextFrame(JSON.stringify(obj))) } catch { clients.delete(socket) }
+  }
+  function broadcast (obj) {
+    const frame = encodeTextFrame(JSON.stringify(obj))
+    for (const s of clients) { try { s.write(frame) } catch { clients.delete(s) } }
+  }
+
+  function onDelta (delta) {
+    if (!delta || !Array.isArray(delta.updates)) return
+    const patch = {}
+    let ts = null
+    for (const u of delta.updates) {
+      if (!u || !Array.isArray(u.values)) continue
+      const src = u.$source || (u.source && u.source.label) || ''
+      const vals = u.values.filter((v) => {
+        if (!v || v.path !== 'navigation.headingMagnetic') return true
+        if (!magSource) magSource = src
+        return src === magSource
+      })
+      Object.assign(patch, signalkValuesToPatch(vals))
+      if (u.timestamp) ts = u.timestamp
+    }
+    if (Object.keys(patch).length === 0) return
+    if (!state) {
+      if (!Number.isFinite(patch.lat) || !Number.isFinite(patch.lon)) return // wait for the first fix
+      state = { ...SEED }
+    }
+    state = { ...state, ...patch, updatedAt: ts || new Date().toISOString() }
+    const hd = resolveHeadingDeg(state)
+    state.headingDeg = Number.isFinite(hd) ? hd : (state.headingDeg || state.cogDeg || 0)
+    broadcast({ type: 'telemetry/update', state })
+  }
+
+  function start () {
+    const sub = { context: 'vessels.self', subscribe: [{ path: '*', period: options.periodMs || 1000 }] }
+    if (app.subscriptionmanager && app.subscriptionmanager.subscribe) {
+      app.subscriptionmanager.subscribe(sub, unsubscribes, (err) => log('subscription error: ' + err), onDelta)
+    } else if (app.signalk && app.signalk.on) {
+      const selfCtx = app.selfContext || ('vessels.' + (app.selfId || 'self'))
+      const h = (d) => { if (!d.context || d.context === selfCtx) onDelta(d) }
+      app.signalk.on('delta', h)
+      unsubscribes.push(() => app.signalk.removeListener('delta', h))
+    } else {
+      log('no subscription mechanism available — telemetry inactive')
+    }
+    log('/ws/telemetry provider started (from local SignalK self stream)')
+  }
+
+  function stop () {
+    for (const u of unsubscribes) { try { u() } catch {} }
+    unsubscribes.length = 0
+    for (const s of clients) { try { s.destroy() } catch {} }
+    clients.clear()
+    state = null
+    magSource = null
+  }
+
+  function status () {
+    return `telemetry: ${clients.size} client(s), ${state ? 'live' : 'waiting for fix'}`
+  }
+
+  // Handle a WebSocket upgrade for /ws/telemetry: handshake, add client, hello.
+  function handleUpgrade (req, socket, head) {
+    const key = req.headers['sec-websocket-key']
+    if (!key) { socket.destroy(); return }
+    const accept = crypto.createHash('sha1').update(key + WS_GUID).digest('base64')
+    const offered = String(req.headers['sec-websocket-protocol'] || '').split(',').map((s) => s.trim())
+    let resp = 'HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n' +
+      `Sec-WebSocket-Accept: ${accept}\r\n`
+    if (offered.includes(SUBPROTOCOL)) resp += `Sec-WebSocket-Protocol: ${SUBPROTOCOL}\r\n`
+    resp += '\r\n'
+    socket.write(resp)
+    clients.add(socket)
+    const drop = () => clients.delete(socket)
+    socket.on('close', drop)
+    socket.on('error', () => { drop(); try { socket.destroy() } catch {} })
+    socket.on('data', (buf) => { if (buf && buf.length && (buf[0] & 0x0f) === 0x8) { drop(); try { socket.destroy() } catch {} } }) // client close frame
+    send(socket, { type: 'hello', source: 'signalk-local', state })
+  }
+
+  // current BoatState (or null before the first fix) — used as the DB-less ring
+  // history source, and by tests.
+  function getState () { return state }
+  function _ingest (delta) { onDelta(delta) } // for tests
+  const _state = getState
+
+  return { start, stop, status, handleUpgrade, getState, _ingest, _state }
+}
+
+module.exports = { createTelemetry, encodeTextFrame, SUBPROTOCOL }

package/lib/telemetry/signalk-map.js

@@ -0,0 +1,71 @@
+'use strict'
+
+// SignalK -> BoatState mapping. Ported VERBATIM from the sailkick app
+// (public/engine/signalk-map.js) so the plugin's /ws/telemetry is identical to
+// the server's SignalKSource. SignalK emits SI units (m/s, radians); BoatState
+// uses knots + degrees. Keep in sync with the app copy.
+
+const MS_TO_KT = 1.94384
+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 }
+
+function signalkValuesToPatch (values) {
+  const patch = {}
+  if (!Array.isArray(values)) return patch
+  for (const v of values) {
+    if (!v || v.value == null) continue
+    switch (v.path) {
+      case 'navigation.position': {
+        const { latitude, longitude } = v.value || {}
+        if (Number.isFinite(latitude) && Number.isFinite(longitude)) {
+          patch.lat = latitude
+          patch.lon = longitude
+        }
+        break
+      }
+      case 'navigation.speedOverGround':
+        if (Number.isFinite(v.value)) patch.sogKt = Math.max(0, v.value * MS_TO_KT)
+        break
+      case 'navigation.courseOverGroundTrue':
+        if (Number.isFinite(v.value)) patch.cogDeg = wrap360(v.value * RAD2DEG)
+        break
+      case 'navigation.headingTrue':
+        if (Number.isFinite(v.value)) patch.hdgTrueDeg = wrap360(v.value * RAD2DEG)
+        break
+      case 'navigation.headingMagnetic':
+        if (Number.isFinite(v.value)) patch.hdgMagDeg = v.value * RAD2DEG
+        break
+      case 'navigation.magneticVariation':
+        if (Number.isFinite(v.value) && v.value !== 0) patch.magVarDeg = v.value * RAD2DEG
+        break
+      case 'environment.wind.speedApparent':
+        if (Number.isFinite(v.value)) patch.awsKt = Math.max(0, v.value * MS_TO_KT)
+        break
+      case 'environment.wind.angleApparent':
+        if (Number.isFinite(v.value)) patch.awaDeg = wrap180(v.value * RAD2DEG)
+        break
+      case 'environment.depth.belowSurface':
+      case 'environment.depth.belowTransducer':
+        if (Number.isFinite(v.value)) patch.depthM = v.value
+        break
+      case 'navigation.datetime':
+        if (typeof v.value === 'string') patch.gpsTime = v.value
+        break
+      default:
+        break
+    }
+  }
+  return patch
+}
+
+function resolveHeadingDeg (state) {
+  if (!state) return undefined
+  if (Number.isFinite(state.hdgMagDeg)) {
+    return wrap360(state.hdgMagDeg + (Number.isFinite(state.magVarDeg) ? state.magVarDeg : 0))
+  }
+  if (Number.isFinite(state.hdgTrueDeg)) return state.hdgTrueDeg
+  return undefined
+}
+
+module.exports = { signalkValuesToPatch, resolveHeadingDeg, MS_TO_KT }