signalk-underkeel 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,95 @@
 
 All notable changes to signalk-underkeel are documented here.
 
+## [0.3.0] - 2026-10-28
+
+### Changed
+
+- Index builds run in a child process (Node `fork`, `MALLOC_ARENA_MAX=2`) instead of a worker
+  thread, and S-57 cells are read with GDAL in a short-lived reader process of their own, so
+  the memory a build used is returned when it ends. After the whole 20-cell Waddenzee build the
+  server held 1.07–1.42 GB; it now holds about 100 MB (x86). A build that crashes or passes its
+  heap limit fails with the reason and keeps the index in use. Region threads default to 1 on
+  machines with up to 4 GB of RAM.
+- Named hazards are saved in `hazards.bin` (CRC-checked columns, depths exact in centimetres)
+  instead of `hazards.json`: 11 MB instead of 89 MB for the Waddenzee set. Loading the saved
+  index takes 0.31–0.35 s instead of 1.5–1.7 s, blocks the event loop for 5–7 ms instead of
+  1.1–1.3 s, and leaves 97–101 MB resident instead of 282–292 MB. A damaged file rebuilds the
+  index; an index saved with `hazards.json` is rebuilt once.
+- Index builds test soundings against survey zones through a zone grid, and coverage through
+  the edge grids, with results identical to before: the 10 km Waddenzee box built in 31.6 s
+  instead of 57.2 s, the whole set in 147 s instead of 216 s (x86, one thread).
+- The look-ahead's chart walk measures footprint-to-tile distances with exact pre-checks and
+  allocates less: ticks on the Waddenzee index take 13–18 ms instead of 22–28 ms (median, x86),
+  with every result byte-identical.
+- UKC overlay tiles are kept encoded (4 MiB) beside their geometry (24 MiB, about 41 % of its
+  former size, source edges stored as float32 rounded outward), and gzipped off the event
+  loop. A 40-tile viewport redrawn unchanged takes about 0 ms instead of 1.4–2.1 s (x86).
+- While the chart box is rebuilding, or the vessel is outside it, the no-coverage reason says
+  so ("outside the chart box, the box is rebuilding around the vessel (last build took 5
+  min)"); the state stays `warn`. `GET /status` `chartBox` reports the rebuild's phase,
+  progress and estimate, and the panel shows it. The box grows with speed and the measured
+  build time up to `boxMaxRadiusKm` (by default from the build heap: 10 km on 1 GB, about 19 km on a
+  4 GB Raspberry Pi 4) and says when no size keeps up. Route legs left unverified past the box say why.
+- `navigation.underKeel.state` and `.envelopeRev` are sent when they change and at least every
+  5 s, no longer every second: at the dock a history logger stored two points a second. Over
+  240 stationary ticks the plugin sent 626 values in 242 deltas, now 242 in 74. A display should
+  read a `state` not received for 15 s as unknown; the status widget does, and only a fresh
+  `state` keeps it current, and the chart runtime withdraws the envelope 15 s after the last
+  `envelopeRev` (it was 10 s). Notifications are unchanged.
+- The plugin status no longer carries the seconds to shoal (`GET /status` still has them), and a
+  status that differs only in its numbers is set at most every 30 s: through the warn zone of a
+  240 s approach the status was set 67 times, now 5.
+- Below 1 kn, or without a fresh SOG, the living chart's CSB export log (`soundings.ndjson`)
+  keeps one sounding per cell per minute. A 10 Hz sounder on a moored boat rewrote the
+  40 000-line file every 33 minutes. Every accepted sounding still updates its cell, so
+  discrepancies are found as before. `GET /status` counts the left-out soundings as
+  `livechart.csbThinned`.
+
+- An index build keeps each S-57 cell's read layers and extent in `cell-cache` in the plugin
+  data directory (at most 512 MB) and reads with GDAL only the cells it holds no valid entry
+  for: changed cells, and cells whose entry is missing or was evicted. The
+  10 km Waddenzee chart box rebuilt in 12–15 s instead of 30–34 s, with no 300–370 MB reader
+  process; the whole 20-cell set in 78–90 s instead of 141 s on one thread (x86). A torn or
+  damaged entry is read from the cell again. The built index is byte for byte the same.
+- A chart box refresh copies from the saved box index each tile down to z15 that lies inside
+  both boxes, or in both boxes' build-area band outside them, and is evaluated from the same
+  cell inputs in both builds; `tiles.json` beside the index holds
+  the digests. On the 10 km Waddenzee box (x86, warm cell cache) a 5 km move copied 66 % of
+  the nodes and built in 6.9–7.2 s instead of 11.6–11.7 s, an 8 km move 54 % in 6.4–6.9 s
+  instead of 10.4–11.6 s. The index is byte for byte the one a fresh build of the new box
+  makes; a changed cell's tiles, another leaf zoom or plugin version, or a missing or foreign
+  `tiles.json` are built afresh. `cells.json` is written in the field order it is read back.
+
+### Added
+
+- A hardware line in the setup check: CPUs, RAM and free RAM, with advice on 1 GB machines
+  (keep the index box, consider leaf zoom 19), on little free RAM, and on large ones (box 0
+  avoids rebuilds for a small chart set). It changes no setting.
+- Descriptions on **Index leaf zoom**, **Rebuild index at start**, **Look-ahead distance** and
+  **Minimum horizon** saying what each costs in CPU or memory.
+- README: what to check before installing on Victron Venus OS, whose Node.js version the
+  repository does not record.
+
+### Fixed
+
+- A larger least position buffer could lower the look-ahead's P: the buffer also set how far
+  apart the footprints were scored, so changing it moved the samples even where the footprints
+  kept the same buffer, and one set of samples could read a shoal up to 1e-4 higher (safety
+  invariant 2). Each footprint now sweeps the hull since the step before, at hull positions that
+  touch with no buffer, so no footprint time or shape depends on the buffer or the position's
+  uncertainty. The step stays 3 s at any speed; a fast boat scores fewer, longer footprints.
+  Beyond the warn window a footprint sweeps at most three hull lengths.
+
+## [0.2.1] - 2026-10-27
+
+### Fixed
+
+- The tests pass in the Signal K plugin registry, which runs them with a read-only home
+  directory. There npm could not write its cache, so the published-package test's
+  `npm pack --dry-run` failed and the plugin lost its "tested" mark. The test now gives npm a
+  cache under the temp directory. The plugin itself is unchanged.
+
 ## [0.2.0] - 2026-10-27
 
 ### Added

package/README.md

@@ -89,6 +89,16 @@ Restart the server, then enable **Under-Keel Awareness** under _Server → Plugi
 Signal K admin UI. Its one runtime dependency is gdal3.js (about 40 MB), which reads the S-57
 cells.
 
+**Victron Venus OS (Cerbo GX).** `package.json` asks for Node.js 22 or newer (`engines`), and CI
+tests Node 22 and 24 only. Venus OS runs Signal K on the Node.js it ships, and this repository
+does not record which version that is: check with `node --version` over SSH on the device before
+installing. On an older Node, npm prints an `EBADENGINE` warning and installs anyway unless
+`engine-strict` is set, and the plugin runs untested.
+
+On a 1 GB machine such as a Raspberry Pi 3 or a Cerbo GX, keep the index box (the default
+10 km) rather than indexing every cell, and consider **Index leaf zoom** 19. The setup check
+shows the RAM and CPUs it finds and says the same; it never changes a setting.
+
 ## Prepare the charts
 
 The plugin reads unencrypted S-57 ENC cells as they are delivered: each `.000` base cell with
@@ -114,18 +124,27 @@ The index covers a box around the vessel, **Index box around the vessel (km)** (
 each way), and is rebuilt off the event loop as the vessel moves, so a large exchange set such
 as NOAA's 698 East and Gulf coast cells is never indexed whole: only the cells reaching the box
 are read (21 of them around Miami, 22 s at leaf zoom 20 on x86). Outside the box the plugin
-reports no coverage, never clear water; a radius under 2 km is raised to 2. Until the first position arrives the engine is `off`
+reports no coverage, never clear water, and the reason says the vessel is outside the chart box
+and whether it is being rebuilt; the plugin status and the details panel show the rebuild's
+phase, start and the last build's duration. At speed the box grows past its radius, up to
+**Largest index box at speed** (0 sizes it from the RAM), so the vessel cannot reach the edge
+before the next box is built (docs/HOW-IT-WORKS.md §12). A radius under 2 km is raised to 2.
+Until the first position arrives the engine is `off`
 with the reason `waiting for the vessel position to build the chart box`. Set the box to 0 to
 index every cell.
 
-At the first start the plugin builds a chart index from the cells in a worker thread and saves
+At the first start the plugin builds a chart index from the cells in a child process and saves
 it under the plugin data directory, `~/.signalk/plugin-config-data/signalk-underkeel/index`
 unless **Chart index directory** says otherwise. Until the index is ready the engine is `off`
 with the reason `building chart index`. The 12 NOAA cells around Miami (6.8 MB of `.000` and
 updates) build in 19 s at leaf zoom 18 on x86. Later starts load the saved index, 0.1 s for
 those cells, and rebuild it when a cell was added or removed, or a cell's `.000` or update files
 changed; `GET /status` names the cells that caused the rebuild. **Rebuild index at start**
-forces a rebuild on every start. A cell folder may be a symbolic link.
+forces a rebuild on every start. A cell folder may be a symbolic link. What the build read
+from each cell is kept, compressed, in `cell-cache` in the plugin data directory (at most 512 MB), so a
+chart box refresh reads again only the cells whose files changed: the 10 km Waddenzee box
+rebuilds in 12–15 s instead of 30–34 s on x86. Deleting the folder is safe; the cells are then
+read again.
 
 Folders of GeoJSON layers exported by `scripts/enc-to-geojson.sh` for earlier versions are no
 longer read: point **ENC cells directory** at the original `.000` cells instead. Such a folder
@@ -140,7 +159,8 @@ There are two places to set the plugin up, and both write the same configuration
   level and warnings, in the same panel with a link back to the details. Drag the keel, the margin
   line and the sounder on a side view of the hull, or type the numbers. The page shows the draft
   Signal K already states, the vertical datum of your charts with the water-level source that fits
-  it, and a setup check. **Save and restart** needs a Signal K admin login.
+  it, and a setup check, which also lists the machine's RAM and CPUs with advice on the index
+  settings. **Save and restart** needs a Signal K admin login.
 - The plugin's page in the admin UI. It asks for the same essentials first; **Show expert
   settings** opens the rest, and an optional feature's fields appear once it is enabled. Admin
   UIs older than Signal K 2.32 show every field at once.
@@ -257,7 +277,9 @@ screenshots, including the plugin layers in the chart list and the setup steps i
 | `notifications.grounding`                    | only from the optional grounding detector, when the boat has gone aground                       |
 
 Any Signal K app can show these; the status line on the plugin's admin page reads, for
-example, `Monitoring: unknown — position stale`.
+example, `Monitoring: unknown — position stale`. Each value is sent when it changes; `state` and
+`envelopeRev` at least every 5 s, the others every 10 s. A display that shows them should read a
+`state` older than 15 s as unknown, as the plugin's own widget does.
 
 ## Optional features
 

package/lib/api/routes.js

@@ -144,13 +144,7 @@ function registerRoutes(router, api, log = console.error) {
         res.setHeader("Cache-Control", "no-cache");
         if (reply.body instanceof Uint8Array) {
             res.setHeader("Vary", "Accept-Encoding");
-            // Signal K's compression() skips this content type; it leaves an encoded body alone.
-            const gzip = reply.body.length >= GZIP_MIN_BYTES && acceptsGzip(req.headers?.["accept-encoding"]);
-            if (gzip) {
-                res.setHeader("Content-Encoding", "gzip");
-            }
-            const body = gzip ? (0, zlib_1.gzipSync)(reply.body) : Buffer.from(reply.body);
-            res.status(reply.status).type(reply.contentType).send(body);
+            sendTile(res, reply, reply.body, acceptsGzip(req.headers?.["accept-encoding"]));
         }
         else {
             res.status(reply.status).json(publicBody(reply.status, reply.body));
@@ -191,6 +185,40 @@ function registerSettings(router, api, log) {
             .catch((err) => fail(res, err, log));
     });
 }
+/**
+ * Sends a tile body, gzipped when the client takes it and the body is worth it.
+ * Signal K's compression() skips the tile content type and leaves an encoded body alone.
+ */
+function sendTile(res, reply, raw, gzip) {
+    const sendBody = (body, encoded) => {
+        if (encoded) {
+            res.setHeader("Content-Encoding", "gzip");
+        }
+        res
+            .status(reply.status)
+            .type(reply.contentType)
+            .send(Buffer.from(body.buffer, body.byteOffset, body.byteLength));
+    };
+    if (raw.length < GZIP_MIN_BYTES || !gzip) {
+        sendBody(raw, false);
+    }
+    else if (reply.memo?.gzip) {
+        sendBody(reply.memo.gzip, true);
+    }
+    else {
+        // Off the event loop: a tile of some kilobytes takes a millisecond or more on a Pi.
+        (0, zlib_1.gzip)(raw, (err, packed) => {
+            if (err) {
+                sendBody(raw, false);
+                return;
+            }
+            if (reply.memo) {
+                reply.memo.gzip = packed;
+            }
+            sendBody(packed, true);
+        });
+    }
+}
 /** Smaller bodies gain less from gzip than its header costs; compression() uses the same. */
 const GZIP_MIN_BYTES = 1024;
 /** Whether an Accept-Encoding header accepts gzip, by name or `*`, with a q above 0. */

package/lib/api-wiring.js

@@ -4,7 +4,7 @@ exports.apiFor = apiFor;
 const ack_service_1 = require("./ack-service");
 const manifest_1 = require("./api/manifest");
 const ukc_tile_changes_1 = require("./api/ukc-tile-changes");
-const ukc_tile_geometry_1 = require("./engine/ukc-tile-geometry");
+const ukc_tile_cache_1 = require("./engine/ukc-tile-cache");
 const config_1 = require("./config");
 const water_level_1 = require("./model/water-level");
 const query_service_1 = require("./query-service");
@@ -19,7 +19,7 @@ function livechartReply(s, body) {
 }
 function apiFor(app, clock, s) {
     const tileChanges = new ukc_tile_changes_1.UkcTileChanges();
-    const tileCache = new ukc_tile_geometry_1.UkcTileCache();
+    const tileCache = new ukc_tile_cache_1.UkcTileCache();
     const queryDeps = () => ({
         index: s.load?.index,
         indexReason: s.load?.reason ?? "plugin not started",
@@ -39,7 +39,8 @@ function apiFor(app, clock, s) {
         waveHeight: () => s.monitor?.nav.waveHeight?.value,
         getRoute: (id) => app.resourcesApi.getResource("routes", id),
         now: () => clock.now(),
-        queue: s.requests
+        queue: s.requests,
+        chartBox: () => s.wfs?.view().bbox
     });
     const withAcks = (fn) => {
         const m = s.monitor;

package/lib/box-sizing.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_BOX_KM = exports.SHRINK_BELOW = exports.SPEED_HEADROOM = exports.STEP_KM = void 0;
+exports.autoCapKm = autoCapKm;
+exports.buildMsAt = buildMsAt;
+exports.fits = fits;
+exports.nextSize = nextSize;
+const build_items_1 = require("./spatial/build-items");
+/**
+ * The radius of the chart box around the vessel (plan §4.2). A box must let the vessel run,
+ * from its centre, the distance it covers while the next box is built (with the refresh
+ * margin) plus the look-ahead's reach and the no-coverage band inside the edge; otherwise
+ * rebuilds run back to back and a slow machine at speed lets the vessel reach the edge. The
+ * box grows for that from the configured radius up to a cap, and shrinks back only once the
+ * speed needs much less, so the radius does not change with every gust.
+ */
+/** Radii are chosen in steps of this many km. */
+exports.STEP_KM = 0.5;
+/** A new box is sized for this much more than the current speed. */
+exports.SPEED_HEADROOM = 1.25;
+/** A box is kept at its size while the size the speed needs is above this share of it. */
+exports.SHRINK_BELOW = 0.7;
+/** The automatic cap: this radius on a 256 MB build heap, growing with the heap's root. */
+const CAP_AT_256_MB_KM = 10;
+/** The largest box the configuration allows, km. */
+exports.MAX_BOX_KM = 50;
+/**
+ * The automatic cap for a build heap of `heapMb`: 10 km at 256 MB (a 1 GB Pi 3 or Cerbo GX),
+ * 20 km at 1 GB, 28 km at 2 GB, rounded down to STEP_KM. The heap is a quarter of the RAM the
+ * system reports, which on a 4 GB Pi 4 is about 3.8 GiB: 19 km. A build's memory grows with the box's area,
+ * and the 10 km box with the ENC pair at leaf zoom 20 builds in under 96 MB.
+ */
+function autoCapKm(heapMb) {
+    const km = CAP_AT_256_MB_KM * Math.sqrt(heapMb / 256);
+    return Math.min(exports.MAX_BOX_KM, Math.floor(km / exports.STEP_KM) * exports.STEP_KM);
+}
+/**
+ * The build time of a box of `km`: the measured one, grown with the build area past the
+ * radius it was measured at. Tiles are built to BOX_REACH past the box, so the area grows
+ * with (radius + reach)². Never shorter than measured, so a smaller box is not assumed to
+ * build faster until it has.
+ */
+function buildMsAt(km, i) {
+    const reach = build_items_1.BOX_REACH / 1000;
+    return i.buildMs * Math.max(1, ((km + reach) / (i.builtKm + reach)) ** 2);
+}
+/** Whether a box of `km` holds a refresh's run at `sog` plus the reach between its centre and edge. */
+function fits(km, i, sog = i.sog) {
+    return km * 1000 >= (i.margin * sog * buildMsAt(km, i)) / 1000 + i.reachM;
+}
+/** The smallest radius on the STEP_KM grid in [from, to] that fits at `sog`. */
+function smallestFit(from, to, i, sog) {
+    for (let km = from; km <= to + 1e-9; km = nextStep(km)) {
+        if (fits(km, i, sog)) {
+            return km;
+        }
+    }
+    return undefined;
+}
+const nextStep = (km) => (Math.floor(km / exports.STEP_KM + 1e-9) + 1) * exports.STEP_KM;
+/** The radius at which the box's spare reach is greatest, when none fits. */
+function roomiest(i) {
+    let best = i.minKm;
+    const spare = (km) => km * 1000 - (i.margin * i.sog * buildMsAt(km, i)) / 1000;
+    for (let km = i.minKm; km <= i.capKm + 1e-9; km = nextStep(km)) {
+        if (spare(km) > spare(best)) {
+            best = km;
+        }
+    }
+    return best;
+}
+/**
+ * The radius for the next box, given the radius of the box in use. Stopped or without a
+ * speed the box in use keeps its size, within the configured radius and the cap.
+ */
+function nextSize(i, currentKm) {
+    const minKm = Math.min(i.minKm, i.capKm);
+    const within = currentKm !== undefined && currentKm >= minKm && currentKm <= i.capKm;
+    if (!(i.sog > 0)) {
+        return { radiusKm: within ? currentKm : minKm, enough: true };
+    }
+    const want = smallestFit(minKm, i.capKm, i, i.sog * exports.SPEED_HEADROOM);
+    if (want === undefined) {
+        const radiusKm = smallestFit(minKm, i.capKm, i, i.sog) ?? roomiest(i);
+        const enough = fits(radiusKm, i);
+        const neededKm = enough ? undefined : smallestFit(i.capKm, exports.MAX_BOX_KM, i, i.sog);
+        return { radiusKm, enough, ...(neededKm === undefined ? {} : { neededKm }) };
+    }
+    // Kept while it holds the speed and the speed does not need much less.
+    if (within && fits(currentKm, i) && want <= currentKm && want > exports.SHRINK_BELOW * currentKm) {
+        return { radiusKm: currentKm, enough: true };
+    }
+    return { radiusKm: want, enough: true };
+}

package/lib/box-status.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rebuildStatus = rebuildStatus;
+exports.boxSummary = boxSummary;
+const box_sizing_1 = require("./box-sizing");
+const chart_box_1 = require("./engine/chart-box");
+function rebuildStatus(r, now) {
+    return {
+        startedAt: new Date(r.startedAt).toISOString(),
+        elapsedMs: now - r.startedAt,
+        radiusKm: r.radiusKm,
+        ...r.progress,
+        ...(r.estimateMs === undefined ? {} : { estimateMs: r.estimateMs })
+    };
+}
+function phaseText(r) {
+    const of = r.done !== undefined && r.total !== undefined ? ` ${r.done}/${r.total}` : "";
+    switch (r.phase) {
+        case "download":
+            return "downloading WFS depths";
+        case "cells":
+            return `reading cells${of}`;
+        case "roots":
+            return `building roots${of}`;
+        case "save":
+            return "saving the index";
+        default:
+            return "starting";
+    }
+}
+function rebuildText(r, lastMs) {
+    const expected = r.estimateMs === undefined
+        ? "first build"
+        : r.estimateMs === lastMs
+            ? `last build took ${(0, chart_box_1.spoken)(r.estimateMs)}`
+            : `about ${(0, chart_box_1.spoken)(r.estimateMs)} expected`;
+    const ago = (0, chart_box_1.spoken)(r.elapsedMs);
+    return `chart box rebuilding (${r.radiusKm} km): ${phaseText(r)}, started ${ago} ago, ${expected}`;
+}
+function tooSmallText(s, i) {
+    const kn = ((s.sog * 3600) / 1852).toFixed(1);
+    const builds = (0, chart_box_1.spoken)((0, box_sizing_1.buildMsAt)(s.radiusKm, i));
+    const need = s.neededKm === undefined
+        ? "no box size keeps up"
+        : `needs ${s.neededKm} km, limit ${s.capKm} km`;
+    return `chart box ${s.radiusKm} km is too small for ${kn} kn with ${builds} builds: ${need}`;
+}
+/** One line on the rebuild in progress and the box size; undefined when neither needs saying. */
+function boxSummary(s) {
+    const parts = [];
+    if (s.rebuild) {
+        parts.push(rebuildText(s.rebuild, s.lastMs));
+    }
+    if (!s.sizing.enough) {
+        parts.push(tooSmallText(s.sizing, s.input));
+    }
+    if (s.ceilingKm !== undefined) {
+        parts.push(`chart box limited to ${s.ceilingKm} km: a larger one ran out of memory`);
+    }
+    return parts.length > 0 ? parts.join("; ") : undefined;
+}

package/lib/build-process.js

@@ -0,0 +1,174 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.workerRefresher = exports.workerBuilder = void 0;
+exports.workerHeapLimitMb = workerHeapLimitMb;
+exports.runBuildProcess = runBuildProcess;
+exports.inThreadRefresher = inThreadRefresher;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("./foundation/child-process");
+const memory_1 = require("./foundation/memory");
+const wfs_1 = require("./ingest/wfs");
+const wfs_worker_1 = require("./wfs-worker");
+const build_progress_1 = require("./spatial/build-progress");
+const build_worker_1 = require("./spatial/build-worker");
+const block_reader_1 = require("./spatial/block-reader");
+const chart_index_1 = require("./spatial/chart-index");
+/** Settles once every build process aborted so far has exited. */
+let exits = Promise.resolve();
+/**
+ * Old-generation heap for a build process: a quarter of the RAM, 256 MB to 2 GB. The ENC pair
+ * plus a 10 km WFS box at leaf zoom 20 builds in under 96 MB; without a limit an oversized
+ * build grows until the kernel ends the whole Signal K server on a 1 GB Pi 3 or Cerbo GX.
+ */
+function workerHeapLimitMb(totalBytes = (0, memory_1.usableMemory)()) {
+    return Math.min(2048, Math.max(256, Math.floor(totalBytes / 4 / 2 ** 20)));
+}
+/**
+ * Runs the compiled `script` in a child process (`forkLimited`) with `data` and resolves with
+ * its staged reply. The child only stages; the caller moves the result into place on the main
+ * thread, and never for an aborted run, so a build still exiting cannot replace an index
+ * saved after it was aborted. An abort kills the child and its S-57 reader (`killGroup`); its
+ * run rejects once the child has exited and its staging is removed, and the next run starts
+ * only then. stop() itself returns at once. A child that ends without a reply fails the run.
+ * Progress messages the child sends before its reply go to `progress`.
+ */
+async function runBuildProcess(script, data, signal, indexDir, heapMb = workerHeapLimitMb(), progress) {
+    await exits;
+    if (signal.aborted) {
+        throw new Error("aborted");
+    }
+    return new Promise((resolve, reject) => {
+        const { child, stderr, outOfMemory } = (0, child_process_1.forkLimited)(script, heapMb, true);
+        const { pid } = child;
+        let replied = false;
+        // Staging the child left half-written: once it has exited nothing else writes there.
+        const cleanup = () => {
+            if (indexDir !== undefined && pid !== undefined) {
+                (0, chart_index_1.removeStaging)(indexDir, (p) => p === pid);
+            }
+        };
+        const closed = new Promise((r) => child.once("close", () => r()));
+        const abort = () => {
+            (0, child_process_1.killGroup)(child);
+            const exit = closed.then(cleanup).catch(() => undefined);
+            exits = Promise.all([exits, exit]);
+            void exit.then(() => reject(new Error("aborted")));
+        };
+        signal.addEventListener("abort", abort, { once: true });
+        child.on("message", (m) => {
+            if ((0, build_progress_1.isProgress)(m)) {
+                if (!replied && !signal.aborted) {
+                    progress?.(m.progress);
+                }
+                return;
+            }
+            replied = true;
+            // It exits once the reply is sent; killed, it cannot linger holding its memory.
+            child.kill("SIGKILL");
+            if (signal.aborted) {
+                if (m.staging) {
+                    fs_1.default.rmSync(m.staging, { recursive: true, force: true });
+                }
+                return;
+            }
+            signal.removeEventListener("abort", abort);
+            if (m.ok && m.staging) {
+                resolve(m);
+            }
+            else {
+                reject(new Error(m.error ?? "index build failed"));
+            }
+        });
+        // A child that could not start, or ended without a reply: the index in use stays.
+        child.once("error", (err) => {
+            if (!signal.aborted && !replied) {
+                signal.removeEventListener("abort", abort);
+                (0, child_process_1.killGroup)(child);
+                reject(err);
+            }
+        });
+        child.once("close", (code, end) => {
+            if (signal.aborted || replied) {
+                return;
+            }
+            signal.removeEventListener("abort", abort);
+            try {
+                cleanup();
+            }
+            catch {
+                // Left for the next start's recovery, which removes staging of exited processes.
+            }
+            const how = code === null ? `signal ${end ?? "?"}` : `code ${code}`;
+            const tail = stderr() === "" ? "" : `: ${stderr()}`;
+            reject(new Error(outOfMemory()
+                ? `index build stopped at the ${heapMb} MB heap limit${tail}`
+                : `index build process exited with ${how} without a result${tail}`));
+        });
+        // A child that cannot take the job exits, and "close" reports it.
+        child.send(data, () => undefined);
+    });
+}
+/**
+ * Moves a staged index into `indexDir` and adopts the one the build posted, unless the run
+ * was aborted meanwhile. Reading the saved index back blocked the event loop for 52–61 ms
+ * with the Nauvo pair and a 10 km WFS box at leaf zoom 20, 258–292 ms with 32 cells (x86).
+ */
+async function commit(indexDir, m, signal) {
+    await (0, block_reader_1.readsSettled)(indexDir);
+    if (signal.aborted) {
+        fs_1.default.rmSync(m.staging, { recursive: true, force: true });
+        throw new Error("aborted");
+    }
+    (0, chart_index_1.commitChartIndex)(indexDir, m.staging);
+    if (m.index) {
+        return (0, build_worker_1.adoptIndex)(m.index);
+    }
+    // A pyramid above HELD_WHOLE_NODES is not posted: the committed file is read block by block,
+    // its blocks verified off the event loop.
+    const index = await (0, chart_index_1.loadChartIndexAsync)(indexDir);
+    if (signal.aborted) {
+        throw new Error("aborted");
+    }
+    return index;
+}
+/** Builds in a child process from the compiled `lib/spatial/build-worker.js`. */
+const workerBuilder = async (job, signal, progress) => {
+    const script = path_1.default.join(__dirname, "spatial", "build-worker.js");
+    const heapMb = workerHeapLimitMb();
+    const data = { ...job, heapMb };
+    const m = await runBuildProcess(script, data, signal, job.indexDir, heapMb, progress);
+    return await commit(job.indexDir, m, signal);
+};
+exports.workerBuilder = workerBuilder;
+/**
+ * The whole refresh in a child process from the compiled `lib/wfs-worker.js`, which fetches
+ * with its own global fetch.
+ */
+const workerRefresher = async (job, signal, progress) => {
+    const script = path_1.default.join(__dirname, "wfs-worker.js");
+    const heapMb = workerHeapLimitMb();
+    const data = { ...job, build: { ...job.build, heapMb } };
+    const { indexDir } = job.build;
+    const m = await runBuildProcess(script, data, signal, indexDir, heapMb, progress);
+    const features = m.features ?? wfs_worker_1.NO_FEATURES;
+    return { index: await commit(job.build.indexDir, m, signal), features };
+};
+exports.workerRefresher = workerRefresher;
+/** The download on this thread with `fetch`, then `build`: for an injected fetch or builder. */
+function inThreadRefresher(fetch, build) {
+    return async (job, signal, progress) => {
+        const cells = (0, wfs_worker_1.refreshCells)(job);
+        if (job.download) {
+            progress?.({ phase: "download" });
+        }
+        const features = job.download
+            ? await (0, wfs_1.downloadWfsCell)({ ...job.download, now: new Date(job.download.now), fetch, signal })
+            : wfs_worker_1.NO_FEATURES;
+        await (0, block_reader_1.readsSettled)(job.build.indexDir);
+        return { index: await build((0, wfs_worker_1.refreshBuild)(job, cells), signal, progress), features };
+    };
+}

package/lib/config-schema.js

@@ -202,13 +202,14 @@ const LOOKAHEAD = {
         distance: {
             type: "number",
             title: "Look-ahead distance (m)",
-            description: FOLLOWS_STYLE,
+            description: `${FOLLOWS_STYLE} Each second the look-ahead scores footprints out to this distance, at most 400; a longer one costs more CPU per tick, which counts on a Raspberry Pi 3 or Cerbo GX.`,
             minimum: 0,
             maximum: lookahead_1.LOOKAHEAD_LIMITS.distance
         },
         minHorizon: {
             type: "number",
             title: "Minimum horizon (s)",
+            description: "The look-ahead reaches at least this far in time at speed. A longer horizon scores more footprints each second, at most 400, so more CPU per tick.",
             default: 60,
             minimum: 0,
             maximum: lookahead_1.LOOKAHEAD_LIMITS.minHorizon
@@ -239,22 +240,31 @@ const LOOKAHEAD = {
         }
     }
 };
+/** A chart box half-width field, km. */
+const BOX_KM = { type: "number", minimum: 0, maximum: 50 };
+const boxKm = (title, def, description) => Object.assign({ title, description, default: def }, BOX_KM);
 const CHART_INDEX = {
     indexDir: {
         type: "string",
         title: "Chart index directory (optional)",
         description: "Where the depth index built from the cells is kept between restarts. Default: <plugin data dir>/index"
     },
-    rebuildIndex: { type: "boolean", title: "Rebuild index at start", default: false },
-    leafZoom: { type: "number", title: "Index leaf zoom", default: 20, minimum: 14, maximum: 22 },
-    boxRadiusKm: {
+    rebuildIndex: {
+        type: "boolean",
+        title: "Rebuild index at start",
+        description: "Builds the index again at every start, with the CPU, memory and flash writes of a first build. The index is rebuilt anyway when a cell changes; leave this off.",
+        default: false
+    },
+    leafZoom: {
         type: "number",
-        title: "Index box around the vessel (km)",
-        description: "Half-width of the area the index is built in around the vessel; it is rebuilt as the vessel moves. Outside it the plugin reports no coverage. 0 indexes every cell (slow for large chart sets); a radius under 2 km is raised to 2. With the Traficom WFS on, its radius is used.",
-        default: 10,
-        minimum: 0,
-        maximum: 50
-    }
+        title: "Index leaf zoom",
+        description: "Size of the smallest index tile: about 19 m across at 20 and 38 m at 19 at 60° N. Each step down needs fewer tiles, so less memory, disk and build time. A tile keeps the shallowest depth inside it, so a coarser index warns more, never less. Consider 19 on a 1 GB Raspberry Pi 3 or Cerbo GX. Changing it rebuilds the index.",
+        default: 20,
+        minimum: 14,
+        maximum: 22
+    },
+    boxRadiusKm: boxKm("Index box around the vessel (km)", 10, "Half-width of the area the index is built in around the vessel; it is rebuilt as the vessel moves. Outside it the plugin reports no coverage, and the reason says the vessel is outside the chart box. At speed the box grows past this radius, up to the largest index box, so the vessel cannot reach its edge, less the look-ahead, before the next box is built: a box must hold 1.5 times the distance run during the last build (grown with the build area) plus the look-ahead and a 2.4 km band. It grows at once when too small, and shrinks only at the next rebuild once the speed needs under 70% of it. 0 indexes every cell (slow for large chart sets); a radius under 2 km is raised to 2. With the Traficom WFS on, its radius is used, and the box grows to 25 km at most."),
+    boxMaxRadiusKm: boxKm("Largest index box at speed (km)", 0, "The box around the vessel grows up to this half-width at speed. 0 sizes it from the RAM the system reports: 10 km on a 1 GB Raspberry Pi or Cerbo GX, about 19 km on a 4 GB Raspberry Pi 4, about 27 km with 8 GB. The status says when even this box is too small for the speed and build time.")
 };
 const EXPERT = {
     ...CHART_INDEX,

package/lib/config.js

@@ -9,6 +9,7 @@ const vessel_1 = require("./model/vessel");
 const route_request_1 = require("./api/route-request");
 const wfs_1 = require("./ingest/wfs");
 const config_presets_1 = require("./config-presets");
+const box_sizing_1 = require("./box-sizing");
 var config_schema_1 = require("./config-schema");
 Object.defineProperty(exports, "SCHEMA", { enumerable: true, get: function () { return config_schema_1.SCHEMA; } });
 exports.DEFAULT_ROUTE_CHECK = { speed: 2.5, xteLimit: 30, probability: 0.01 };
@@ -161,6 +162,7 @@ function parseConfig(raw) {
         rebuildIndex: r.rebuildIndex === true,
         leafZoom: Math.round(num(r.leafZoom, 20, 14, 22)),
         boxRadiusKm: boxRadius(r.boxRadiusKm),
+        boxMaxRadiusKm: num(r.boxMaxRadiusKm, 0, 0, box_sizing_1.MAX_BOX_KM),
         warningStyle: style,
         vessel: {
             draft: optionalPositive(v.draft),