@signalk/tracks-plugin 3.0.0-beta.2 → 3.0.0-beta.4

package/dist/simplify.d.ts

@@ -0,0 +1,46 @@
+import { TimedPosition } from './types.js';
+/**
+ * Metres per degree of latitude. Good to ~0.5% over the WGS84 ellipsoid.
+ *
+ * Exported because the provider derives its automatic tolerance from the same
+ * figure: "one part in a thousand of the diagonal" only holds while both use
+ * one metres-per-degree value.
+ */
+export declare const M_PER_DEG = 111320;
+/**
+ * Douglas-Peucker simplification of a recorded track.
+ *
+ * Distinct from `thin()`, and the difference is the whole point: thinning
+ * decimates by *time*, so it keeps a point every N seconds whether the boat was
+ * turning or holding a course, and a corner falling between two samples is
+ * simply lost. Simplification decimates by *shape* — it keeps the points that
+ * carry the geometry and drops the ones a straight line already describes.
+ *
+ * That is what makes this the piece a route conversion needs. 5,550 points at
+ * 1.2 s spacing is a recording, not a route; thinning it to 30 points gives 30
+ * evenly spaced positions that miss every turn, while simplifying it to 30
+ * gives the turns and nothing else.
+ *
+ * `epsilon` is a tolerance in **metres**: no point of the original track is
+ * further than this from the simplified line.
+ */
+export declare function simplify(points: TimedPosition[], epsilon: number): TimedPosition[];
+/**
+ * The smallest epsilon that simplifies `points` to at most `target` of them.
+ *
+ * Epsilon is meaningful in the physical world but not in the thing a user
+ * cares about: "accurate to 10 m" gives 8 waypoints across an open bay and 400
+ * through an archipelago, so a client asking for a usable route cannot pick a
+ * number in advance. A point budget is predictable; the tolerance that
+ * achieved it is what gets reported back.
+ *
+ *
+ * Not reachable through the v2 API, which takes a tolerance rather than a
+ * budget. It is here for the track-management webapp's "convert to route",
+ * where the user asks for a usable number of waypoints and is told the
+ * accuracy that produced them.
+ */
+export declare function simplifyToBudget(points: TimedPosition[], target: number): {
+    points: TimedPosition[];
+    epsilon: number;
+};

package/dist/simplify.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sourceWatch.d.ts

@@ -1,35 +1,24 @@
 import { Context } from './types.js';
-/**
- * Watches which `$source` each context's positions arrive from.
- *
- * `navigation.position` is a rapid update — a GPS may report at 10Hz — and a
- * typical boat has several receivers: an internal GPS, an AIS transponder, a
- * chart plotter echoing its own fix.
- *
- * Signal K resolves which one wins through source priority, and the bus this
- * plugin listens on is the filtered one: the server applies `toPreferredDelta`
- * before emitting `delta`, which is what feeds `getBus()`. So with a priority
- * rule in place, only the winner arrives and there is nothing to warn about.
- *
- * The gap is when no rule *matches* the path. Then the engine passes every
- * source through, the fixes from receivers metres apart interleave, and the
- * track zigzags between them rather than following the boat. The fix is to
- * configure source priority for `navigation.position`; this watcher exists to
- * say so, because the symptom (a track that looks noisy) does not obviously
- * point at the cause.
- *
- * Detection is therefore empirical rather than reading the priority config:
- * seeing several sources here *is* the evidence that no rule is matching,
- * which a config that merely exists would not tell us.
- */
 export declare class SourceWatch {
+    /** Last time each source produced a position, per context. */
     private readonly seen;
+    /** Sources found competing, per context, with when each was last seen so. */
+    private readonly competing;
+    /** The current alternation per context: who is in it, and how long it is. */
+    private readonly lastSeen;
     /** Record that `context` produced a position from `$source`. */
-    add(context: Context, source: string | undefined): void;
-    /** Sources seen for a context, in the order they first appeared. */
+    add(context: Context, source: string | undefined, now?: number): void;
+    /** Every source seen for a context, in the order they first appeared. */
     sourcesFor(context: Context): string[];
-    /** Contexts receiving positions from more than one source. */
-    conflicted(): Context[];
+    /**
+     * The sources found live at the same time, which is what a warning names.
+     *
+     * Expired entries are dropped rather than merely hidden, so a conflict that
+     * has stopped recurring leaves nothing behind.
+     */
+    competingFor(context: Context, now?: number): string[];
+    /** Contexts that have received positions from two sources at once. */
+    conflicted(now?: number): Context[];
     /**
      * A status line naming the problem, or undefined when nothing is wrong.
      *
@@ -38,7 +27,7 @@ export declare class SourceWatch {
      * vessels are usually AIS, where multiple receivers are expected and less
      * worth nagging about — they are counted, not named.
      */
-    warning(selfContext?: Context): string | undefined;
+    warning(selfContext?: Context, now?: number): string | undefined;
     /** Forget everything seen; used when the plugin restarts. */
     clear(): void;
 }

package/dist/style.css

@@ -0,0 +1,49 @@
+:root {
+  color-scheme: light dark;
+  font-family: system-ui, sans-serif;
+}
+
+body {
+  margin: 0;
+  padding: 1rem;
+}
+
+h1 {
+  font-size: 1.25rem;
+  margin: 0 0 0.25rem;
+}
+
+#status {
+  color: GrayText;
+  margin: 0 0 1rem;
+}
+
+#status[data-state='error'] {
+  color: crimson;
+}
+
+table {
+  border-collapse: collapse;
+  width: 100%;
+}
+
+th,
+td {
+  border-bottom: 1px solid ButtonBorder;
+  padding: 0.4rem 0.6rem;
+  text-align: left;
+}
+
+/* Point counts are compared down the column, so they line up on the right. */
+.num {
+  text-align: right;
+  font-variant-numeric: tabular-nums;
+}
+
+tbody tr:hover {
+  background: Canvas;
+}
+
+.self {
+  font-weight: 600;
+}

package/dist/trackApi.d.ts

@@ -15,18 +15,16 @@ export type TrackBoundingBox = [number, number, number, number];
 /**
  * A request as the server hands it to a provider.
  *
- * Not every field is honoured here. `simplify`, `epsilon` and `properties` are
- * accepted by the API and ignored by this provider: it serves positions, and
- * has no co-recorded values to attach or geometry simplifier to run. Geometry
- * comes back unsimplified, which is a superset of what such a request asked for
- * rather than a wrong answer.
+ * Not every field is honoured here. `properties` is accepted by the API and
+ * ignored by this provider: it serves positions, and has no co-recorded values
+ * to attach. Geometry comes back without them, which is a superset of what such
+ * a request asked for rather than a wrong answer.
  *
- * `resolution` and `maxPoints` are both applied, and the response reports the
- * spacing actually used — which is not always the one asked for, since a
- * budget widens it.
- *
- * Simplification and co-recorded properties are tracked separately; see
- * SignalK/tracks.
+ * `resolution`, `maxPoints`, `simplify` and `epsilon` are all applied, and the
+ * response reports the spacing and tolerance actually used — neither is always
+ * the one asked for, since a budget widens the spacing and `simplify` without
+ * an epsilon leaves the tolerance to the provider.
+
  */
 export interface TracksRequest {
     contexts?: string[];

package/dist/trackProvider.d.ts

@@ -18,6 +18,15 @@ export interface TrackProviderDeps {
     selfContext: () => string;
     /** Gap in ms that starts a new segment; 0 leaves the track as one line. */
     segmentGap: () => number;
+    /**
+     * The vessel's name for `contextName`, or undefined when unknown.
+     *
+     * Injected like the rest: resolving it needs the server's data model, which
+     * the provider has no handle on. Called per query rather than cached,
+     * because an AIS target's static report routinely lands well after its
+     * first position.
+     */
+    contextName: (context: string) => string | undefined;
     /**
      * Positions a history provider holds for a context and window, reconciled
      * with the store's own.

package/dist/tracks.js

@@ -0,0 +1,192 @@
+/**
+ * Track list for the management webapp.
+ *
+ * Reads the v2 Track API with `geometry=false`, which answers with each
+ * track's metadata and no coordinates — the same query the API already serves,
+ * so listing hundreds of tracks costs nothing like fetching them.
+ *
+ * Plain modules and no build step: the plugin ships `public/` as static files
+ * and the server mounts it directly, so anything needing a bundler would mean
+ * a second build output for a page this size.
+ */
+
+/**
+ * How far back the list reaches.
+ *
+ * The API refuses an unbounded multi-context query — "a time window (from or
+ * duration) is required unless a single context is given" — because listing
+ * every track a server ever saw is a question with no cheap answer. Thirty
+ * days covers the passage someone is looking for while keeping the query
+ * something the store can serve.
+ */
+const WINDOW = 'P30D'
+
+/**
+ * Ceiling on the list request.
+ *
+ * Generous, because a month of tracks on a busy receiver is a real query, not
+ * a hung one — this exists to end a request that will never answer, not to
+ * hurry a slow store.
+ */
+const REQUEST_TIMEOUT_MS = 30_000
+
+/** Relative, because the server mounts this under /@signalk/tracks-plugin. */
+const TRACKS_URL = `../../signalk/v2/api/tracks?geometry=false&duration=${WINDOW}`
+
+const status = document.getElementById('status')
+const table = document.getElementById('tracks')
+const tbody = table.querySelector('tbody')
+
+/**
+ * The label for a track, matching `trackLabel()` on the server.
+ *
+ * The API gives `contextName` — the vessel's own name, undecorated and absent
+ * when unknown — plus `isSelf`. Turning those into something a person
+ * recognises is the client's job, and it has to agree with what v1 returns or
+ * the same track reads differently depending on which screen it is on.
+ */
+function label({ context, contextName, isSelf }) {
+  if (isSelf) {
+    return 'Own Ship'
+  }
+  if (contextName) {
+    return `AIS ${contextName}`
+  }
+  const mmsi = /urn:mrn:imo:mmsi:(\d+)$/.exec(context)
+  return mmsi ? `AIS ${mmsi[1]}` : context
+}
+
+/** ISO-8601 from the API, rendered in the viewer's own locale and zone. */
+function when(iso) {
+  const at = new Date(iso)
+  return Number.isNaN(at.getTime()) ? '—' : at.toLocaleString()
+}
+
+function row(properties) {
+  const tr = document.createElement('tr')
+  const name = document.createElement('td')
+  name.textContent = label(properties)
+  if (properties.isSelf) {
+    name.className = 'self'
+  }
+  tr.append(
+    name,
+    cell(when(properties.from)),
+    cell(when(properties.to)),
+    cell(properties.pointCount, 'num'),
+    exportCell(properties),
+  )
+  return tr
+}
+
+/**
+ * A link that downloads this track as GPX.
+ *
+ * A plain link rather than a fetch: the browser already knows how to save a
+ * response with a Content-Disposition on it, and the server sets one. Doing it
+ * by hand would mean holding a whole track in memory to build a blob.
+ */
+function exportCell({ context, isSelf }) {
+  const td = document.createElement('td')
+  const link = document.createElement('a')
+  // `self` resolves server-side; using it keeps the URL short and avoids
+  // guessing how the own vessel's context should be spelled.
+  const vessel = isSelf ? 'self/track.gpx' : `vessels/${encodeURIComponent(context)}/track.gpx`
+  link.href = `../../signalk/v1/api/${vessel}?duration=${WINDOW}`
+  link.textContent = 'GPX'
+  link.rel = 'nofollow'
+  td.append(link)
+  return td
+}
+
+function cell(text, className) {
+  const td = document.createElement('td')
+  // textContent, never innerHTML: a vessel name arrives from an AIS
+  // transmission and is not ours to trust as markup.
+  td.textContent = String(text)
+  if (className) {
+    td.className = className
+  }
+  return td
+}
+
+function show(message, state) {
+  status.textContent = message
+  if (state) {
+    status.dataset.state = state
+  } else {
+    delete status.dataset.state
+  }
+}
+
+async function load() {
+  let response
+  // Bounded, because an unsettled fetch is the one failure the page cannot
+  // recover from: every other path ends in an error message, while a stalled
+  // server or proxy leaves it on "Loading…" indefinitely, which reads as a
+  // hang rather than a failure. The signal stays armed through json() below,
+  // so a response that stops mid-body is caught too.
+  const deadline = AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+  try {
+    response = await fetch(TRACKS_URL, { credentials: 'include', signal: deadline })
+  } catch {
+    show(deadline.aborted ? 'The server did not answer in time.' : 'Could not reach the server.', 'error')
+    return
+  }
+  // 501 is the server saying no provider is registered, which is a different
+  // thing from an error and worth telling the user plainly.
+  if (response.status === 501) {
+    show('No track provider is registered on this server.', 'error')
+    return
+  }
+  if (!response.ok) {
+    show(`The server answered ${response.status}.`, 'error')
+    return
+  }
+
+  let body
+  try {
+    body = await response.json()
+  } catch {
+    // A 200 carrying something that is not JSON: a proxy's error page, or a
+    // body that stops mid-stream, which the deadline above aborts here rather
+    // than at the fetch. Without this the rejection escapes `void load()` and
+    // the page sits on "Loading…" forever, which looks like a hang.
+    show(
+      deadline.aborted ? 'The server did not answer in time.' : 'The server sent a response this page could not read.',
+      'error',
+    )
+    return
+  }
+  // A 200 carrying something else entirely -- an error object, a login page --
+  // is a failure, not an empty list. Reporting "no tracks" for it would tell
+  // the user the opposite of what happened.
+  if (body?.type !== 'FeatureCollection' || !Array.isArray(body.features)) {
+    show('The server sent a response this page could not read.', 'error')
+    return
+  }
+  // Individual entries are still skipped rather than thrown on: one malformed
+  // feature should not blank a list that is otherwise fine.
+  const features = body.features
+  // Newest first: the track someone came to look at is almost always the one
+  // that just finished.
+  const sorted = features
+    .map((feature) => feature?.properties)
+    .filter(
+      (properties) => properties && typeof properties.context === 'string' && Number.isFinite(properties.pointCount),
+    )
+    .sort((a, b) => String(b.to ?? '').localeCompare(String(a.to ?? '')))
+
+  // Checked after filtering, not before: a response of nothing but malformed
+  // features would otherwise draw an empty table reading "0 tracks".
+  if (sorted.length === 0) {
+    show('No tracks in the last 30 days.')
+    return
+  }
+
+  tbody.replaceChildren(...sorted.map(row))
+  table.hidden = false
+  show(`${sorted.length} track${sorted.length === 1 ? '' : 's'} in the last 30 days.`)
+}
+
+void load()

package/dist/utils.d.ts

@@ -38,3 +38,63 @@ export declare function createMatcher(params: TrackParams, selfPosition?: LatLng
  * track rather than a failure anybody can see.
  */
 export declare const historyRowPosition: (row: unknown) => LatLngTuple | undefined;
+/**
+ * The name of the vessel (or aircraft, or aton) a context refers to.
+ *
+ * Deliberately bare — `Ariadne`, not `AIS Ariadne` and not `Own Ship`. This is
+ * the v2 Track API's `contextName`, whose spec says "Name of the vessel,
+ * aircraft or other context, where known. Not a name for the track itself."
+ * Decoration belongs to whoever is drawing a list; see `trackLabel`.
+ *
+ * `lookup` reads the data model (`app.getPath`). Note the shape: a vessel's
+ * `name` is a bare string in the full model, not the `{value}` wrapper that
+ * `navigation.position` and friends carry, so both are accepted rather than
+ * guessed at.
+ *
+ * Resolves `name` and nothing else, matching the server's own `findContextName`
+ * (`packages/server-admin-ui/src/utils/pathKeys.ts`), which returns undefined
+ * rather than substituting an identifier. An MMSI is how a vessel is addressed,
+ * not what it is called, so it belongs in `trackLabel` where something has to
+ * render — putting it here would make "where known" untrue.
+ */
+export declare function contextName(context: string, lookup: (path: string) => unknown): string | undefined;
+/**
+ * A display label for a track, as a chart plotter would show it.
+ *
+ * TimeZero's GPX exports label tracks `Own Ship` and `AIS <shipname>` — never a
+ * serial number — and that is what makes a list of tracks readable. A UI
+ * listing `vessels.urn:mrn:imo:mmsi:211234567` is unusable.
+ *
+ * Distinct from `contextName`: this one *is* a name for the track, so it says
+ * whose track it is and where the identity came from. Falls back to the raw
+ * context, because a label has to render something.
+ */
+export declare function trackLabel(context: string, selfContext: string | undefined, lookup: (path: string) => unknown): string;
+/**
+ * A track label as a filename a browser can save.
+ *
+ * A vessel name arrives from an AIS transmission and is not ours to trust in a
+ * path, so the characters that could break out of one — separators, quotes,
+ * controls — are replaced. Everything else is kept, including non-ASCII: a
+ * boat called `Ärger` keeps its name.
+ */
+export declare function gpxFilename(label: string): string;
+/**
+ * The ASCII-only form of a filename, for the quoted `Content-Disposition`
+ * parameter.
+ *
+ * An HTTP header carries bytes: anything outside Latin-1 makes `setHeader`
+ * throw, and anything outside ASCII is reinterpreted byte-wise by the client,
+ * so `Ärger.gpx` arrives as mojibake. The real name travels in the `filename*`
+ * parameter; this is the fallback for readers that do not implement it.
+ */
+export declare function asciiFilename(filename: string): string;
+/**
+ * A filename as an RFC 8187 extended value, for `filename*`.
+ *
+ * `encodeURIComponent` is close but not exact: it leaves `!'()*` unescaped,
+ * and RFC 8187's `attr-char` set excludes them. A vessel called
+ * `Boat (Test)` would otherwise put raw parentheses into the header, which is
+ * not a valid extended value.
+ */
+export declare function rfc8187(filename: string): string;

package/dist/webapp.e2e.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/webapp.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalk/tracks-plugin",
-  "version": "3.0.0-beta.2",
+  "version": "3.0.0-beta.4",
   "description": "Plugin to keep track of tracks of vessels",
   "type": "module",
   "exports": {
@@ -15,14 +15,16 @@
   "//files": "app-icon.svg ships alongside dist because `files` is an allowlist: the app store probes the declared signalk.appIcon path inside the published tarball, so an icon left out here 404s and the plugin falls back to a placeholder.",
   "files": [
     "dist",
+    "public",
     "app-icon.svg"
   ],
   "signalk": {
     "displayName": "Tracks",
-    "appIcon": "app-icon.svg"
+    "appIcon": "./app-icon.svg"
   },
   "keywords": [
     "signalk-node-server-plugin",
+    "signalk-webapp",
     "signalk-category-utility"
   ],
   "author": "Teppo Kurki <teppo.kurki@iki.fi>",
@@ -52,6 +54,7 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@js-temporal/polyfill": "^0.5.1",
+    "@xmldom/xmldom": "^0.9.12",
     "rxjs": "^7.8.2",
     "s2js": "^1.44.0",
     "typebox": "^1.3.11"
@@ -72,6 +75,6 @@
     "typescript-eslint": "^8.66.0",
     "vite": "^8.2.2",
     "vite-plugin-dts": "^5.0.3",
-    "vitest": "^4.1.10"
+    "vitest": "^5.0.0"
   }
 }

package/public/index.html

@@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Tracks</title>
+    <link rel="stylesheet" href="./style.css" />
+  </head>
+  <body>
+    <header>
+      <h1>Tracks</h1>
+      <p id="status" role="status">Loading…</p>
+    </header>
+    <main>
+      <table id="tracks" hidden>
+        <thead>
+          <tr>
+            <th scope="col">Vessel</th>
+            <th scope="col">From</th>
+            <th scope="col">To</th>
+            <th scope="col" class="num">Points</th>
+            <th scope="col">Export</th>
+          </tr>
+        </thead>
+        <tbody></tbody>
+      </table>
+    </main>
+    <script type="module" src="./tracks.js"></script>
+  </body>
+</html>

package/public/style.css

@@ -0,0 +1,49 @@
+:root {
+  color-scheme: light dark;
+  font-family: system-ui, sans-serif;
+}
+
+body {
+  margin: 0;
+  padding: 1rem;
+}
+
+h1 {
+  font-size: 1.25rem;
+  margin: 0 0 0.25rem;
+}
+
+#status {
+  color: GrayText;
+  margin: 0 0 1rem;
+}
+
+#status[data-state='error'] {
+  color: crimson;
+}
+
+table {
+  border-collapse: collapse;
+  width: 100%;
+}
+
+th,
+td {
+  border-bottom: 1px solid ButtonBorder;
+  padding: 0.4rem 0.6rem;
+  text-align: left;
+}
+
+/* Point counts are compared down the column, so they line up on the right. */
+.num {
+  text-align: right;
+  font-variant-numeric: tabular-nums;
+}
+
+tbody tr:hover {
+  background: Canvas;
+}
+
+.self {
+  font-weight: 600;
+}