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

package/dist/index.js

@@ -3,11 +3,123 @@ import { join } from "node:path";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 import { DatabaseSync } from "node:sqlite";
+import { DOMParser } from "@xmldom/xmldom";
 import { BehaviorSubject, ReplaySubject, Subject, combineLatest, connectable, firstValueFrom } from "rxjs";
 import { map, scan, startWith, throttleTime } from "rxjs/operators";
 //#region \0rolldown/runtime.js
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 //#endregion
+//#region src/simplify.ts
+var LAT$2 = 0;
+var LNG$2 = 1;
+/**
+* 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.
+*/
+var M_PER_DEG = 111320;
+/**
+* Span, in scaled degrees, beyond which the flat projection is not trusted.
+*
+* Ten degrees is ~1,100 km, where the projection still agrees with a spherical
+* cross-track calculation to 0.1%. No leg between two recorded positions comes
+* close; a segment that does is a data artefact rather than a passage.
+*/
+var SPAN_LIMIT = 10;
+/**
+* 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.
+*/
+function simplify(points, epsilon) {
+	if (!(epsilon > 0) || points.length <= 2) return points;
+	const keep = new Uint8Array(points.length);
+	keep[0] = 1;
+	keep[points.length - 1] = 1;
+	const stack = [[0, points.length - 1]];
+	while (stack.length > 0) {
+		const [first, last] = stack.pop();
+		if (last <= first + 1) continue;
+		let worst = 0;
+		let worstAt = -1;
+		for (let i = first + 1; i < last; i++) {
+			const d = perpendicularDistance(points[i], points[first], points[last]);
+			if (d > worst) {
+				worst = d;
+				worstAt = i;
+			}
+		}
+		if (worstAt >= 0 && worst > epsilon) {
+			keep[worstAt] = 1;
+			stack.push([first, worstAt], [worstAt, last]);
+		}
+	}
+	return points.filter((_, i) => keep[i] === 1);
+}
+/**
+* Distance in metres from `p` to the segment `a`-`b`.
+*
+* Positions are projected to a local plane with longitude scaled by
+* cos(latitude) at the segment's midpoint. Measured against a spherical
+* cross-track reference the error is 0.1% for segments spanning up to ten
+* degrees of latitude — some 1,100 km, longer than any leg between two
+* recorded fixes — which is far below the metre-scale tolerances this runs
+* with, and it avoids trigonometry per point per recursion level (2.9 ms for
+* 5,550 points, and `simplifyToBudget` calls this ~40 times).
+*
+* One flat scale cannot hold across a segment spanning most of a hemisphere:
+* an 80N-to-equator segment reads 85 km where the truth is 111 km. Such a
+* segment means two consecutive fixes an ocean and a continent apart, which
+* recorded data does not contain — but the tolerance is documented in metres,
+* so `SPAN_LIMIT` refuses to answer rather than answer wrongly, in either
+* axis.
+*/
+function perpendicularDistance(p, a, b) {
+	const cos = Math.cos((a.position[LAT$2] + b.position[LAT$2]) / 2 * Math.PI / 180);
+	const originLng = a.position[LNG$2];
+	if (Math.abs(a.position[LAT$2] - b.position[LAT$2]) > SPAN_LIMIT || Math.abs(nearestLongitude(b.position[LNG$2], originLng) - originLng) * cos > SPAN_LIMIT) return Infinity;
+	const ax = originLng * cos;
+	const ay = a.position[LAT$2];
+	const bx = nearestLongitude(b.position[LNG$2], originLng) * cos;
+	const by = b.position[LAT$2];
+	const px = nearestLongitude(p.position[LNG$2], originLng) * cos;
+	const py = p.position[LAT$2];
+	const dx = bx - ax;
+	const dy = by - ay;
+	let t = 0;
+	const lenSq = dx * dx + dy * dy;
+	if (lenSq > 0) t = Math.min(1, Math.max(0, ((px - ax) * dx + (py - ay) * dy) / lenSq));
+	const cx = ax + t * dx;
+	const cy = ay + t * dy;
+	return Math.hypot(px - cx, py - cy) * M_PER_DEG;
+}
+/**
+* `lng` shifted by whole turns to sit within 180 degrees of `origin`.
+*
+* A track crossing the antimeridian is stored as 179.9 then -179.9, a tenth of
+* a degree apart on the ground but 359.8 apart numerically. Without this, a
+* straight line across it reads as a segment spanning almost the whole globe,
+* and points that lie exactly on that line measure kilometres away from it —
+* so simplification keeps every one of them.
+*/
+function nearestLongitude(lng, origin) {
+	return lng - 360 * Math.round((lng - origin) / 360);
+}
+//#endregion
 //#region src/timeWindow.ts
 /**
 * Time-window and resolution query parameters.
@@ -232,8 +344,8 @@ function segment(points, gap) {
 }
 //#endregion
 //#region src/utils.ts
-var LAT = 0;
-var LNG = 1;
+var LAT$1 = 0;
+var LNG$1 = 1;
 /**
 * The recording times of a segment, as ISO-8601 UTC, positionally aligned with
 * the segment's coordinates.
@@ -247,13 +359,13 @@ function toIsoTimes(segment) {
 	return segment.map(({ timestamp }) => new Date(timestamp).toISOString());
 }
 function createInBounds(bounds) {
-	const minLat = bounds.sw[LAT];
-	const maxLat = bounds.ne[LAT];
+	const minLat = bounds.sw[LAT$1];
+	const maxLat = bounds.ne[LAT$1];
 	if (minLat > maxLat) throw new Error(`Bounding box south must be <=  north, got ${JSON.stringify(bounds)}`);
-	const minLng = bounds.sw[LNG];
-	const maxLng = (bounds.sw[LNG] > bounds.ne[LNG] ? 360 : 0) + bounds.ne[LNG];
+	const minLng = bounds.sw[LNG$1];
+	const maxLng = (bounds.sw[LNG$1] > bounds.ne[LNG$1] ? 360 : 0) + bounds.ne[LNG$1];
 	return (p) => {
-		return p !== null && p[LAT] >= minLat && p[LAT] <= maxLat && (p[LNG] >= minLng && p[LNG] <= maxLng || p[LNG] + 360 >= minLng && p[LNG] + 360 <= maxLng);
+		return p !== null && p[LAT$1] >= minLat && p[LAT$1] <= maxLat && (p[LNG$1] >= minLng && p[LNG$1] <= maxLng || p[LNG$1] + 360 >= minLng && p[LNG$1] + 360 <= maxLng);
 	};
 }
 /**
@@ -271,11 +383,11 @@ function createInBounds(bounds) {
 * iterate the result.
 */
 function splitAtAntimeridian(bounds) {
-	const west = bounds.sw[LNG];
-	const east = bounds.ne[LNG];
+	const west = bounds.sw[LNG$1];
+	const east = bounds.ne[LNG$1];
 	if (west <= east) return [bounds];
-	const south = bounds.sw[LAT];
-	const north = bounds.ne[LAT];
+	const south = bounds.sw[LAT$1];
+	const north = bounds.ne[LAT$1];
 	return [{
 		sw: [south, west],
 		ne: [north, 180]
@@ -378,6 +490,91 @@ var historyRowPosition = (row) => {
 		if (Number.isFinite(latitude) && Number.isFinite(longitude)) return [latitude, longitude];
 	}
 };
+/**
+* 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.
+*/
+function contextName(context, lookup) {
+	return unwrapString(lookup(`${context}.name`));
+}
+/**
+* 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.
+*/
+function trackLabel(context, selfContext, lookup) {
+	if (context === selfContext) return "Own Ship";
+	const identity = contextName(context, lookup) ?? unwrapString(lookup(`${context}.mmsi`)) ?? mmsiFromContext(context);
+	return identity === void 0 ? context : `AIS ${identity}`;
+}
+/** Accepts both a bare string and the `{value}` wrapper deltas arrive in. */
+function unwrapString(raw) {
+	const value = raw && typeof raw === "object" && "value" in raw ? raw.value : raw;
+	if (typeof value !== "string") return;
+	const trimmed = value.trim();
+	return trimmed === "" ? void 0 : trimmed;
+}
+/** `vessels.urn:mrn:imo:mmsi:211234567` -> `211234567`. */
+function mmsiFromContext(context) {
+	return /urn:mrn:imo:mmsi:(\d+)$/.exec(context)?.[1];
+}
+/**
+* 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.
+*/
+function gpxFilename(label) {
+	const safe = label.replace(/[\p{Cc}\p{Cf}"'\\/:*?<>|]+/gu, "-").replace(/\s+/g, "-").replace(/-+/g, "-").replace(/^[-.]+|[-.]+$/g, "");
+	return `${safe === "" ? "track" : safe}.gpx`;
+}
+/**
+* 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.
+*/
+function asciiFilename(filename) {
+	const trimmed = [...filename].map((character) => character < "€" ? character : "-").join("").replace(/-{2,}/g, "-").replace(/^-+/, "");
+	return trimmed === ".gpx" || trimmed === "" ? "track.gpx" : trimmed;
+}
+/**
+* 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.
+*/
+function rfc8187(filename) {
+	return encodeURIComponent(filename).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+}
 //#endregion
 //#region src/trackProvider.ts
 /** v2 sends `[west, south, east, north]`; a bounds here is `[lat, lng]` corners. */
@@ -537,8 +734,11 @@ function createTrackProvider(deps) {
 					resolution: requested
 				} : thinToBudget(all, query.maxPoints, requested);
 				if (points.length === 0) continue;
-				const segments = segment(points, gap);
-				const bbox = boundsOf(points);
+				const chosenEpsilon = chooseEpsilon(points, query);
+				const segments = segment(points, gap).map((s) => chosenEpsilon === void 0 ? s : simplify(s, chosenEpsilon));
+				const shaped = segments.flat();
+				const bbox = boundsOf(shaped);
+				const name = deps.contextName(context);
 				features.push({
 					type: "Feature",
 					geometry: query.geometry === false ? null : {
@@ -548,11 +748,13 @@ function createTrackProvider(deps) {
 					properties: {
 						context,
 						isSelf: context === selfContext,
-						from: new Date(points[0].timestamp).toISOString(),
-						to: new Date(points[points.length - 1].timestamp).toISOString(),
+						...name === void 0 ? {} : { contextName: name },
+						from: new Date(shaped[0].timestamp).toISOString(),
+						to: new Date(shaped[shaped.length - 1].timestamp).toISOString(),
 						...bbox ? { bbox } : {},
-						pointCount: points.length,
+						pointCount: shaped.length,
 						...appliedMs === void 0 ? {} : { resolution: msToDuration(appliedMs).toString() },
+						...chosenEpsilon === void 0 ? {} : { epsilon: chosenEpsilon },
 						...query.times ? { coordTimes: segments.map(toIsoTimes) } : {}
 					}
 				});
@@ -567,6 +769,67 @@ function createTrackProvider(deps) {
 		}
 	};
 }
+/**
+* The tolerance to simplify with, or undefined to leave the geometry alone.
+*
+* `epsilon` implies `simplify=true`, so an explicit tolerance is honoured
+* whether or not the flag came with it. `simplify` alone leaves the tolerance
+* to the provider: the spec says "a tolerance suited to the size of the box",
+* and the extent of the track *as thinning left it* is the honest basis for
+* that — a query bbox may be absent, and when present it is what the client
+* searched in rather than what came back. It cannot be the simplified extent,
+* since that is the thing being computed.
+*
+* Chosen from the whole track rather than per segment, so every leg of one
+* track is simplified to the same tolerance and the single reported `epsilon`
+* describes all of them.
+*
+* A non-positive `epsilon` is not reachable through the API — the schema
+* declares `exclusiveMinimum: 0`, so the server rejects it — and is treated
+* here as no tolerance given, falling through to `simplify` if that was asked
+* for. Simplifying by zero would be a no-op reported as if it had done
+* something.
+*/
+function chooseEpsilon(points, query) {
+	const explicit = query.epsilon;
+	if (explicit !== void 0 && explicit > 0) return explicit;
+	return query.simplify === true ? autoEpsilon(points) : void 0;
+}
+/**
+* How much of a track's own extent the automatic tolerance may deviate by.
+*
+* One part in a thousand. Provisional while the v2 API is designed in
+* SignalK/signalk-server#2504: it is only a provider-chosen default for
+* `simplify` without an explicit epsilon, and a client that calibrates against
+* the exact ratio rather than reading the reported `epsilon` back would make
+* it expensive to change.
+*/
+var AUTO_EPSILON_DIVISOR = 1e3;
+/**
+* Floor, in metres, under the automatic tolerance.
+*
+* Below the noise of any GPS fix, so it collapses the thousands of near
+* identical points a vessel records at anchor without altering a track that
+* actually moved.
+*/
+var MIN_AUTO_EPSILON = 1;
+/**
+* A tolerance scaled to how much ground a track covers.
+*
+* One part in a thousand of the track's diagonal: enough to drop the jitter of
+* a boat holding station while keeping every turn a passage is made of. A
+* fixed metre value cannot do both — 10 m erases nothing on an ocean crossing
+* and erases a marina approach entirely.
+*/
+function autoEpsilon(points) {
+	const bounds = boundsOf(points);
+	if (!bounds) return;
+	const [west, south, east, north] = bounds;
+	const midLat = (south + north) / 2;
+	const height = (north - south) * M_PER_DEG;
+	const width = (east >= west ? east - west : east + 360 - west) * M_PER_DEG * Math.cos(midLat * Math.PI / 180);
+	return Math.max(Math.hypot(width, height) / AUTO_EPSILON_DIVISOR, MIN_AUTO_EPSILON);
+}
 /** v2 accepts the `self` alias; the store keys on the qualified context. */
 var resolveSelf = (selfContext) => (context) => context === "self" || context === "vessels.self" ? selfContext : context;
 //#endregion
@@ -12337,6 +12600,285 @@ var StateGate = class {
 	}
 };
 //#endregion
+//#region src/gpx.ts
+/**
+* GPX 1.1 serialisation and parsing for recorded tracks.
+*
+* Hand-written rather than through a library: the vocabulary is `gpx`,
+* `metadata`, `trk`, `name`, `extensions`, `signalk:context`, `trkseg`,
+* `trkpt` and `time` — nine element types — and a dependency for that would be
+* more surface than the code it replaces.
+* What matters is getting the details right, and those are documented below.
+*/
+var LAT = 0;
+var LNG = 1;
+/**
+* Serialise tracks as a GPX 1.1 document.
+*
+* Several tracks go in one file, each as its own `<trk>`. GPX allows it, and
+* it is what makes "select three trips, export" produce one file rather than
+* three — TimeZero writes one file per vessel, which is a choice rather than a
+* constraint of the format.
+*
+* The Signal K context travels in `<extensions>`. TimeZero puts an opaque
+* GUID there and drops the MMSI entirely, so its exports cannot round-trip an
+* identity; carrying the context means ours can, while staying readable by
+* anything else, since `<extensions>` is ignorable by specification.
+*/
+function toGpx(tracks, now = /* @__PURE__ */ new Date()) {
+	const lines = [
+		"<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
+		"<gpx version=\"1.1\" creator=\"@signalk/tracks-plugin\" xmlns=\"http://www.topografix.com/GPX/1/1\">",
+		"  <metadata>",
+		`    <time>${iso(now.getTime())}</time>`,
+		"  </metadata>"
+	];
+	for (const track of tracks) {
+		const segments = track.segments.map((points) => points.filter((p) => inRange(p.position[LAT], p.position[LNG]))).filter((points) => points.length > 0);
+		if (segments.length === 0) continue;
+		lines.push("  <trk>");
+		lines.push(`    <name>${escapeXml(track.name)}</name>`);
+		if (track.context !== void 0) {
+			lines.push("    <extensions>");
+			lines.push(`      <signalk:context xmlns:signalk="${NAMESPACE}">${escapeXml(track.context)}</signalk:context>`);
+			lines.push("    </extensions>");
+		}
+		for (const points of segments) {
+			lines.push("    <trkseg>");
+			for (const { position, timestamp } of points) {
+				lines.push(`      <trkpt lat="${coordinate(position[LAT])}" lon="${coordinate(position[LNG])}">`);
+				lines.push(`        <time>${iso(timestamp)}</time>`);
+				lines.push("      </trkpt>");
+			}
+			lines.push("    </trkseg>");
+		}
+		lines.push("  </trk>");
+	}
+	lines.push("</gpx>");
+	return lines.join("\n") + "\n";
+}
+/** GPX's own namespace, which structural elements must be in. */
+var GPX_NAMESPACE = "http://www.topografix.com/GPX/1/1";
+/** Namespace for the one extension element this plugin writes. */
+var NAMESPACE = "https://signalk.org/specification/1.7.0/";
+/**
+* Parse a GPX document into tracks.
+*
+* Structure follows GPX's own hierarchy: the root is `<gpx>`, tracks are its
+* children, segments are a track's, points are a segment's. Anything else —
+* a `<trkseg>` inside an `<extensions>` payload, a `<trk>` below the root — is
+* not track data, and a namespace check alone cannot tell the difference,
+* since a payload declaring no namespace inherits GPX's own.
+*
+* Deliberately forgiving about structure and strict about values: elements it
+* does not recognise are ignored rather than rejected, but a coordinate that is
+* not an `xsd:decimal` in range, or a time that is not an `xsd:dateTime`, is
+* refused. One NaN reaching the store stretches every bounding box that track
+* appears in.
+*
+* **Points are sorted by time within each segment.** TimeZero paginates its
+* export in blocks of 150 and the block seams overlap: the last point of a
+* block can be a few milliseconds newer than the first point of the next. Out
+* of 5,550 points in a real export, 16 pairs are out of order, every one on a
+* 150-point boundary. Anything downstream that assumes ordering — time-window
+* queries, the history reconciliation — would quietly misbehave on such a file.
+*
+* Sorting stops at the segment boundary, deliberately: a segment is a stretch
+* of continuous recording, and reordering points across a gap would merge two
+* passages into one line. So `segments.flat()` is not globally sorted for a
+* file whose segments interleave in time, and a caller that needs that must
+* sort for itself.
+*
+* A document the parser rejects yields no tracks rather than throwing: this
+* reads files the plugin did not write, and an import that fails should say so
+* by returning nothing rather than by taking the caller down.
+*/
+function fromGpx(xml) {
+	let document;
+	try {
+		document = new DOMParser({ onError: (level) => {
+			if (level !== "warning") throw new Error("malformed XML");
+		} }).parseFromString(xml, "text/xml");
+	} catch {
+		return [];
+	}
+	const root = document.documentElement;
+	if (root === null || root.localName !== "gpx" || !isGpxNamespace(root)) return [];
+	const tracks = [];
+	for (const trk of gpxChildren(root, "trk")) {
+		const segments = [];
+		for (const trkseg of gpxChildren(trk, "trkseg")) {
+			const points = readPoints(trkseg);
+			if (points.length > 0) segments.push(points);
+		}
+		if (segments.length === 0) continue;
+		const name = childText(trk, "name").trim() || "Track";
+		const context = signalKContext(trk);
+		tracks.push({
+			name,
+			segments,
+			...context === void 0 ? {} : { context }
+		});
+	}
+	return tracks;
+}
+/**
+* The text of a direct GPX child with this local name.
+*
+* Direct rather than `getElementsByTagName`, which would reach a `<name>`
+* inside an `<extensions>` payload and label the track with a vendor's string.
+*/
+function childText(trk, local) {
+	for (const child of Array.from(trk.childNodes)) if (isElement(child) && child.localName === local && isGpxNamespace(child)) return child.textContent ?? "";
+	return "";
+}
+/**
+* The Signal K context declared in a track's own `<extensions>`.
+*
+* Matched on namespace URI, which is what the prefix actually means: GPX
+* extensions are an open field any vendor may write into, so a foreign
+* `<context>` — or one under a different prefix bound elsewhere — must not
+* claim the track's identity. Read only from the track's direct
+* `<extensions>` children, because a trackpoint carries its own and those
+* belong to that point.
+*/
+function signalKContext(trk) {
+	for (const child of Array.from(trk.childNodes)) {
+		if (!isElement(child) || child.localName !== "extensions" || !isGpxNamespace(child)) continue;
+		for (const candidate of Array.from(child.getElementsByTagNameNS(NAMESPACE, "context"))) {
+			const value = (candidate.textContent ?? "").trim();
+			if (value !== "") return value;
+		}
+	}
+}
+/** The points of one `<trkseg>`, oldest first. */
+function readPoints(trkseg) {
+	const points = [];
+	for (const trkpt of gpxChildren(trkseg, "trkpt")) {
+		const latitude = decimal(trkpt.getAttribute("lat") ?? void 0);
+		const longitude = decimal(trkpt.getAttribute("lon") ?? void 0);
+		if (!inRange(latitude, longitude)) continue;
+		const raw = childText(trkpt, "time").trim();
+		const timestamp = raw === "" ? NaN : dateTime(raw);
+		points.push({
+			position: [latitude, longitude],
+			timestamp: Number.isFinite(timestamp) ? timestamp : 0
+		});
+	}
+	return points.sort((a, b) => a.timestamp - b.timestamp);
+}
+/**
+* Direct GPX children of `root` with this local name.
+*
+* Direct, because GPX fixes the hierarchy: a `<trkseg>` is a child of `<trk>`
+* and a `<trkpt>` a child of `<trkseg>`. Scanning descendants instead lets an
+* `<extensions>` payload contribute track data — and a payload that declares
+* no namespace of its own inherits GPX's, so a namespace check cannot catch
+* it. A vendor's `<trkseg>` inside `<extensions>` became a phantom segment.
+*/
+function gpxChildren(root, local) {
+	return Array.from(root.childNodes).filter((node) => isElement(node) && node.localName === local && isGpxNamespace(node));
+}
+/**
+* Whether an element is GPX's own.
+*
+* A null namespace counts: a great many files in the wild omit the xmlns
+* declaration entirely, and refusing those would reject most of what users
+* actually have.
+*/
+function isGpxNamespace(element) {
+	return element.namespaceURI === null || element.namespaceURI === GPX_NAMESPACE;
+}
+/** Narrow a DOM node to an element without relying on a global Node. */
+function isElement(node) {
+	return node.nodeType === 1;
+}
+/**
+* Coordinates at seven decimal places: ~11 mm, finer than any GPS fix and
+* short enough that a long track does not carry pointless digits.
+*/
+function coordinate(value) {
+	const fixed = value.toFixed(7).replace(/\.?0+$/, "");
+	return fixed === "-0" ? "0" : fixed;
+}
+/**
+* A GPX `<time>` as epoch milliseconds, or NaN when it is not one.
+*
+* GPX types the element as `xsd:dateTime`, and `Date.parse` is far looser: it
+* reads a bare `2024` and `Jan 1 2024` as instants, and silently rolls
+* `2024-02-30` forward to March. A date that never existed should reach the
+* caller's fallback rather than arrive as a real -- and wrong -- position in
+* time.
+*/
+function dateTime(value) {
+	const match = /^(\d{4})-(\d{2})-(\d{2})T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.exec(value);
+	if (!match) return NaN;
+	const parsed = Date.parse(value);
+	if (Number.isNaN(parsed)) return NaN;
+	const year = Number(match[1]);
+	const month = Number(match[2]);
+	const day = Number(match[3]);
+	const utc = new Date(Date.UTC(year, month - 1, day));
+	return utc.getUTCFullYear() === year && utc.getUTCMonth() === month - 1 && utc.getUTCDate() === day ? parsed : NaN;
+}
+/**
+* ISO-8601 UTC, because a track outlives the timezone it was recorded in.
+*
+* A timestamp outside the Date range throws out of `toISOString`, and one bad
+* point would abort the export of every track in the file. It is dated to the
+* start of time instead, which is what `fromGpx` does with a time it cannot
+* read -- losing one point's time beats losing the document.
+*/
+function iso(timestamp) {
+	const at = new Date(timestamp);
+	return Number.isNaN(at.getTime()) ? (/* @__PURE__ */ new Date(0)).toISOString() : at.toISOString();
+}
+/**
+* XML-escape a value for element content.
+*
+* Characters XML cannot express are dropped rather than escaped, because they
+* have no entity form: emitting one produces a document no conformant reader
+* will load, and losing the character beats losing the file.
+*/
+function escapeXml(value) {
+	return [...value].filter((character) => isXmlChar(character.codePointAt(0) ?? -1)).join("").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+/**
+* Whether a code point is one XML 1.0 permits in content.
+*
+* The range has holes: NUL, most C0 controls and the surrogate block are all
+* excluded. Decoding `&#0;` or `&#xD800;` puts a character into a track name
+* that cannot be written back out as well-formed XML, so the reference is
+* kept verbatim instead -- the same treatment as one that names no character
+* at all.
+*/
+function isXmlChar(value) {
+	if (!Number.isInteger(value)) return false;
+	return value === 9 || value === 10 || value === 13 || value >= 32 && value <= 55295 || value >= 57344 && value <= 65533 || value >= 65536 && value <= 1114111;
+}
+/**
+* An attribute value as an XSD decimal, or NaN when it is not one.
+*
+* GPX types lat and lon as `xsd:decimal`, which is digits with an optional
+* sign and point -- no exponent, no hexadecimal. `Number()` is far more
+* generous: it reads `0x10` as 16 and `1e1` as 10, so a file using either
+* imported a position it never expressed.
+*/
+function decimal(value) {
+	return value !== void 0 && /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/.test(value) ? Number(value) : NaN;
+}
+/**
+* Whether a position is one GPX can express.
+*
+* Latitude beyond ±90 or longitude beyond ±180 is not a place. Such a value
+* reaching the store stretches every bounding box the track appears in, and
+* writing one produces a document a validating reader rejects — so it is
+* refused in both directions rather than trusted from a file or passed on.
+*/
+function inRange(latitude, longitude) {
+	return Number.isFinite(latitude) && Number.isFinite(longitude) && latitude >= -90 && latitude <= 90 && longitude >= -180 && longitude <= 180;
+}
+//#endregion
 //#region src/tracks.ts
 /**
 * The in-memory store: a bounded sliding window of positions per context, held
@@ -12503,6 +13045,45 @@ var HISTORY_QUERY_TIMEOUT_MS = 5e3;
 */
 var WINDOWLESS_HISTORY_SPAN_MS = 864e5;
 /**
+* The earliest instant the existence probe asks about.
+*
+* The probe has to name a bound: the History API's time range has no
+* unbounded form, every branch of `TimeRangeParams` carries one. A provider
+* filters its context list by the range it is given — questdb builds a SQL
+* `WHERE` from it — so any bound later than the provider's oldest row can
+* still miss a vessel and 404 it, which is the case the probe exists to catch.
+*
+* The Unix epoch is the bound rather than some span of years: it predates
+* satellite navigation, so no position fix can lie before it, and unlike a
+* fixed "wide enough" window it cannot be outlived. The cost lands only on the
+* branch that was already about to 404, and the answer is cached.
+*/
+var EXISTENCE_PROBE_FROM_MS = 0;
+/**
+* How long a provider's context list is reused before asking again.
+*
+* The probe runs only for a vessel about to 404, which is precisely the
+* request a client can repeat without limit — the routes are open, so
+* enumerating vessel ids would otherwise drive one epoch-wide `getContexts`
+* per request, each able to block for the timeout.
+*
+* The whole list is cached rather than a per-context answer, or enumeration
+* would simply fill the cache with distinct keys and query just as often. The
+* cost is that a vessel a provider learns about becomes visible up to this
+* long after the fact, which is not a delay anyone can perceive in a track
+* that is already minutes old.
+*/
+var KNOWN_CONTEXTS_TTL_MS = 3e4;
+/**
+* How long a *failed* context query is remembered.
+*
+* Short, so a provider that recovers is noticed quickly, but not zero: with
+* the entry simply dropped, a provider that hangs is asked again by every
+* subsequent miss while the earlier calls are still pending — reinstating per
+* request exactly the cost the cache exists to prevent.
+*/
+var KNOWN_CONTEXTS_FAILURE_TTL_MS = 1e3;
+/**
 * Config values arrive from the plugin UI as numbers, but a hand-edited
 * settings file can supply strings. Accept both, reject anything non-finite so
 * a bad value falls back to the default instead of poisoning arithmetic with NaN.
@@ -12518,6 +13099,15 @@ var notAvailable = (res) => {
 	res.status(404);
 	res.json({ message: "Tracks API not available because tracks plugin is not enabled" });
 };
+/**
+* The history provider could not answer, and nothing else could either.
+*
+* Distinct from a missing track: a 404 asserts that no source knows the
+* vessel, which a failed provider read cannot support. Reporting the failure
+* as an empty track would present an outage as "this vessel has no positions
+* here" — the one answer that is certainly wrong.
+*/
+var HistoryUnavailableError = class extends Error {};
 var errorDetail = (err) => err instanceof Error && err.stack ? err.stack : String(err);
 /**
 * A window covering everything the store holds, up to now.
@@ -12548,9 +13138,15 @@ function windowSpanning(stored, fallbackMs) {
 * promise wins. A race leaves it armed, holding the event loop open for the
 * remainder of the timeout on every call that succeeds.
 */
+/**
+* A bound expired. Distinct from the error a provider itself raises, because
+* "did not answer in time" and "is not installed" are different answers and
+* only one of them is an outage.
+*/
+var HistoryTimeoutError = class extends Error {};
 function withTimeout(promise, ms) {
 	return new Promise((resolve, reject) => {
-		const timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`timed out after ${ms}ms`)), ms);
+		const timer = setTimeout(() => reject(new HistoryTimeoutError(`timed out after ${ms}ms`)), ms);
 		promise.then((value) => {
 			clearTimeout(timer);
 			resolve(value);
@@ -12561,6 +13157,48 @@ function withTimeout(promise, ms) {
 	});
 }
 /**
+* Whether a history provider holds anything at all for a context.
+*
+* Asked only when a track is about to 404: `getValues` narrowed to a window
+* cannot tell "this vessel is unknown" from "this vessel has nothing *here*",
+* and 404ing on the second is wrong — the contract is that a 404 means neither
+* source knows the vessel. A vessel whose history lies wholly outside the
+* asked window is known, and deserves an empty track.
+*
+* Best-effort, like every other provider call here: a provider that lacks the
+* method, errors, or hangs leaves the 404 standing rather than holding the
+* request open.
+*/
+async function historyKnowsContext(app, context, debug, cache) {
+	const getHistoryApi = app.getHistoryApi;
+	if (!getHistoryApi) return false;
+	try {
+		const now = Date.now();
+		const cached = cache.current;
+		if (cached === void 0 || now - cached.at >= KNOWN_CONTEXTS_TTL_MS) {
+			const contexts = withTimeout(getHistoryApi(app.config?.settings?.historyApi?.defaultProvider).then((historyApi) => historyApi.getContexts ? historyApi.getContexts({
+				from: Temporal.Instant.from((/* @__PURE__ */ new Date(EXISTENCE_PROBE_FROM_MS)).toISOString()),
+				to: Temporal.Instant.from(new Date(now).toISOString())
+			}) : []).then((listed) => new Set((listed ?? []).filter((c) => typeof c === "string").map((c) => c === "vessels.self" ? app.selfContext : c))), HISTORY_QUERY_TIMEOUT_MS);
+			const entry = {
+				at: now,
+				contexts
+			};
+			contexts.catch(() => {
+				if (cache.current === entry) cache.current = {
+					at: now - KNOWN_CONTEXTS_TTL_MS + KNOWN_CONTEXTS_FAILURE_TTL_MS,
+					contexts
+				};
+			});
+			cache.current = entry;
+		}
+		return (await cache.current.contexts).has(context);
+	} catch (err) {
+		debug(`History contexts unavailable for ${context}: ${errorDetail(err)}`);
+		return false;
+	}
+}
+/**
 * Positions a history provider holds for a window, or none.
 *
 * Best-effort by design: a provider that is absent, slow, or failing must not
@@ -12573,10 +13211,23 @@ async function historyPositions(app, context, window, resolutionMs, debug) {
 	const getHistoryApi = app.getHistoryApi;
 	if (!getHistoryApi) return {
 		points: [],
-		resolutionMs: applied
+		resolutionMs: applied,
+		failed: false
 	};
+	let historyApi;
+	try {
+		historyApi = await withTimeout(getHistoryApi(app.config?.settings?.historyApi?.defaultProvider), HISTORY_QUERY_TIMEOUT_MS);
+	} catch (err) {
+		const timedOut = err instanceof HistoryTimeoutError;
+		if (debug.enabled) debug(`${timedOut ? "History provider timed out" : "No history provider"} for ${context}: ${errorDetail(err)}`);
+		return {
+			points: [],
+			resolutionMs: applied,
+			failed: timedOut
+		};
+	}
 	try {
-		const response = await withTimeout((await withTimeout(getHistoryApi(app.config?.settings?.historyApi?.defaultProvider), HISTORY_QUERY_TIMEOUT_MS)).getValues({
+		const response = await withTimeout(historyApi.getValues({
 			context,
 			from: Temporal.Instant.from(new Date(window.from).toISOString()),
 			to: Temporal.Instant.from(new Date(window.to).toISOString()),
@@ -12601,13 +13252,15 @@ async function historyPositions(app, context, window, resolutionMs, debug) {
 		if (debug.enabled) debug(`History supplied ${points.length} position(s) for ${context}`);
 		return {
 			points,
-			resolutionMs: applied
+			resolutionMs: applied,
+			failed: false
 		};
 	} catch (err) {
 		if (debug.enabled) debug(`History unavailable for ${context}: ${errorDetail(err)}`);
 		return {
 			points: [],
-			resolutionMs: applied
+			resolutionMs: applied,
+			failed: true
 		};
 	}
 }
@@ -12633,6 +13286,13 @@ function ThePlugin(app) {
 	const sourceWatch = new SourceWatch();
 	let glitchFilter = new GlitchFilter({ maxSpeedKnots: 100 });
 	let stateGate = new StateGate(app.selfContext, DEFAULT_PAUSE_STATES);
+	/**
+	* The history provider's context list, cached between existence probes.
+	*
+	* Per plugin instance rather than module-global: two instances would
+	* otherwise answer from each other's provider.
+	*/
+	const knownContexts = { current: void 0 };
 	/** The own vessel's navigation.state, or undefined when it reports none. */
 	function getVesselState() {
 		const s = app.getSelfPath("navigation.state");
@@ -12704,6 +13364,7 @@ function ThePlugin(app) {
 				store: () => tracks,
 				selfContext: () => app.selfContext,
 				segmentGap: () => segmentGap,
+				contextName: (context) => contextName(context, (path) => app.getPath?.(path)),
 				reconcileWithHistory: async (context, stored, window, resolutionMs) => {
 					const effective = resolutionMs ?? storeResolution;
 					const history = await historyPositions(app, context, window ?? windowSpanning(stored, WINDOWLESS_HISTORY_SPAN_MS), effective, app.debug);
@@ -12723,6 +13384,7 @@ function ThePlugin(app) {
 			sourceWatch.clear();
 			glitchFilter.clear();
 			stateGate.clear();
+			knownContexts.current = void 0;
 			try {
 				tracks?.close?.();
 			} catch (err) {
@@ -12732,6 +13394,34 @@ function ThePlugin(app) {
 			}
 		},
 		signalKApiRoutes: function(router) {
+			const nameOf = (context) => trackLabel(context, app.selfContext, (path) => app.getPath?.(path));
+			/**
+			* The points of one context, reconciled with history and segmented.
+			*
+			* Shared by the JSON and GPX routes so the two cannot answer the same
+			* question differently: the history reconciliation, the windowless
+			* fallback and the 404-only-for-an-unknown-vessel rule are subtle enough
+			* that a second copy would drift.
+			*
+			* Rejects with `undefined` when neither source knows the vessel at all.
+			*/
+			const readSegments = async (context, query) => {
+				const effectiveResolution = query.resolution ?? storeResolution;
+				const { points: stored, known } = await tracks.getTimed(context, query.window).then((points) => ({
+					points,
+					known: true
+				})).catch(() => ({
+					points: [],
+					known: false
+				}));
+				const history = await historyPositions(app, context, query.window ?? windowSpanning(stored, WINDOWLESS_HISTORY_SPAN_MS), effectiveResolution, app.debug);
+				const points = history.points.length ? reconcile(history.points, stored, history.resolutionMs).positions : stored;
+				if (points.length === 0) {
+					if (!(known || await historyKnowsContext(app, context, app.debug, knownContexts))) return;
+					if (history.failed) throw new HistoryUnavailableError(`History provider could not be read for ${context}`);
+				}
+				return segment(thin(points, query.resolution), segmentGap);
+			};
 			const singleTrackHandler = (contextOf) => (req, res) => {
 				if (!tracks) {
 					notAvailable(res);
@@ -12746,37 +13436,89 @@ function ThePlugin(app) {
 					res.json({ message: err instanceof TimeWindowError ? err.message : "Invalid query parameters" });
 					return;
 				}
-				const effectiveResolution = query.resolution ?? storeResolution;
-				tracks.getTimed(context, query.window).then((points) => ({
-					points,
-					known: true
-				})).catch(() => ({
-					points: [],
-					known: false
-				})).then(async ({ points: stored, known }) => {
-					const window = query.window ?? windowSpanning(stored, WINDOWLESS_HISTORY_SPAN_MS);
-					const history = await historyPositions(app, context, window, effectiveResolution, app.debug);
-					const points = history.points.length ? reconcile(history.points, stored, history.resolutionMs).positions : stored;
-					if (points.length === 0 && !known) {
+				readSegments(context, query).then((segments) => {
+					if (segments === void 0) {
 						res.status(404);
 						res.json({ message: `No track available for ${context}` });
 						return;
 					}
-					const segments = segment(thin(points, query.resolution), segmentGap);
 					res.json({
 						type: "MultiLineString",
 						coordinates: segments.map((points) => points.map(({ position }) => toLngLat(position))),
 						...query.times ? { times: segments.map(toIsoTimes) } : {},
 						context,
-						isSelf: context === app.selfContext
+						isSelf: context === app.selfContext,
+						name: nameOf(context)
 					});
-				}).catch(() => {
+				}).catch((err) => {
+					if (err instanceof HistoryUnavailableError) {
+						app.error(`${err.message}`);
+						res.status(503);
+						res.json({ message: `Track history is temporarily unavailable for ${context}` });
+						return;
+					}
 					res.status(404);
 					res.json({ message: `No track available for ${context}` });
 				});
 			};
+			/**
+			* One vessel's track as a GPX file.
+			*
+			* Serialised by `toGpx` rather than assembled here, so the export a user
+			* downloads is the same document the module produces everywhere else.
+			* The webapp cannot reach that module — it ships as static files with no
+			* bundler — which is why the conversion lives behind a route instead of
+			* being duplicated in the page.
+			*/
+			const gpxHandler = (contextOf) => (req, res) => {
+				if (!tracks) {
+					notAvailable(res);
+					return;
+				}
+				const context = contextOf(req);
+				let query;
+				try {
+					query = parseTrackQuery(req.query);
+				} catch (err) {
+					res.status(400);
+					res.json({ message: err instanceof TimeWindowError ? err.message : "Invalid query parameters" });
+					return;
+				}
+				readSegments(context, query).then((segments) => {
+					if (segments === void 0) {
+						res.status(404);
+						res.json({ message: `No track available for ${context}` });
+						return;
+					}
+					const label = nameOf(context);
+					const filename = gpxFilename(label);
+					res.type("application/gpx+xml");
+					res.setHeader("Content-Disposition", `attachment; filename="${asciiFilename(filename)}"; filename*=UTF-8''${rfc8187(filename)}`);
+					res.send(toGpx([{
+						name: label,
+						context,
+						segments
+					}]));
+				}).catch((err) => {
+					if (err instanceof HistoryUnavailableError) {
+						app.error(`${err.message}`);
+						if (!res.headersSent) {
+							res.status(503);
+							res.json({ message: `Track history is temporarily unavailable for ${context}` });
+						}
+						return;
+					}
+					app.error(`Could not export GPX for ${context}: ${errorDetail(err)}`);
+					if (!res.headersSent) {
+						res.status(500);
+						res.json({ message: `Could not export the track for ${context}` });
+					}
+				});
+			};
 			const trackHandler = singleTrackHandler((req) => resolveContext(String(req.params.vesselId), app.selfContext));
 			router.get("/vessels/:vesselId/track", trackHandler);
+			router.get("/vessels/:vesselId/track.gpx", gpxHandler((req) => resolveContext(String(req.params.vesselId), app.selfContext)));
+			router.get("/self/track.gpx", gpxHandler(() => app.selfContext));
 			router.get("/self/track", singleTrackHandler(() => app.selfContext));
 			const allTracksHandler = (req, res) => {
 				app.debug(req.query);
@@ -12800,14 +13542,16 @@ function ThePlugin(app) {
 						type: "MultiLineString",
 						coordinates: segments.map((s) => s.map(({ position }) => toLngLat(position))),
 						times: segments.map(toIsoTimes),
-						isSelf: context === app.selfContext
+						isSelf: context === app.selfContext,
+						name: nameOf(context)
 					};
 					return acc;
 				}, {})) : tracks.getFilteredTracks(params, selfPosition, app.debug, query).then((tc) => Object.entries(tc).reduce((acc, [context, track]) => {
 					acc[context] = {
 						type: "MultiLineString",
 						coordinates: [track.map(toLngLat)],
-						isSelf: context === app.selfContext
+						isSelf: context === app.selfContext,
+						name: nameOf(context)
 					};
 					return acc;
 				}, {}))).then((trks) => {
@@ -12877,6 +13621,6 @@ function ThePlugin(app) {
 	};
 }
 //#endregion
-export { TrackAccumulator, Tracks, ThePlugin as default };
+export { TrackAccumulator, Tracks, ThePlugin as default, fromGpx, toGpx };
 
 //# sourceMappingURL=index.js.map