signalk-underkeel 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,114 @@
 
 All notable changes to signalk-underkeel are documented here.
 
+## [0.4.0] - 2026-11-02
+
+### Added
+
+- **ENC from Charts Provider** reads the ENC cells signalk-charts-provider-simple (2.16.0 or
+  later) shares in its ENC store: one chart set's or converted chart's cells by name, or all
+  of them with `*`, in place of **ENC cells directory**. The plugin restarts itself and
+  rebuilds the index when the charts provider writes new editions or updates of those cells,
+  and the admin form names the collections shared at the moment.
+- When the Charts Provider collection in use has no cells, the reason says why, as
+  signalk-charts-provider-simple tells it: a chart set not downloaded yet or downloading, its
+  cells being written, or no such collection.
+- **Ask Charts Provider for the ENC around the vessel** (expert, off by default): while all
+  of the charts provider's shared ENC is read, each new index box asks it to download the free
+  ENC cells of that area, when the charts provider allows such downloads. The cells arrive in
+  a chart set of their own and the index is rebuilt with them. An answer that may change
+  without the box changing is asked again later.
+
+### Changed
+
+- The index records the ENC source it was built from: the cells directory, or the Charts
+  Provider collection by its id. A cells directory that is gone or empty keeps the saved index
+  only when that index was built from it, as an unmounted drive leaves it; switching to a
+  source with no cells yet no longer keeps using the previous source's index, and the reason
+  says why. Clearing the ENC source leaves no index in use rather than the previous source's,
+  again with the reason. An index saved by an earlier version, which records no source, is
+  kept as before.
+
+## [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

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
@@ -96,7 +106,20 @@ its `.001`, `.002`, … updates beside it. Copy the exchange set, for example it
 folder, under one directory and set **ENC cells directory** to it; `.000` files are found down
 to three folders deep, and down to six below a folder holding the exchange set's `CATALOG.031`,
 so an unzipped Inland ENC download (`<set>/ENC_ROOT/1R/7/1R7WAD07/1R7WAD07.000`) can be pointed
-at as it is. The cells are read in place with GDAL compiled to WebAssembly
+at as it is.
+
+Cells downloaded with signalk-charts-provider-simple (2.16.0 or later) are read where that
+plugin shares them, in its ENC store: set **ENC from Charts Provider** to one of the chart sets
+or converted charts the admin form lists as shared, or to `*` for all of them. It is used
+instead of **ENC cells directory**. When the charts provider writes new editions or updates of
+those cells, the plugin restarts itself and rebuilds the index from them. When the collection
+has no cells yet, the reason says why, as the charts provider tells it: a chart set not
+downloaded or still downloading, cells being written, or no such collection. With `*` and
+**Ask Charts Provider for the ENC around the vessel** on (an expert setting, off by default),
+each new index box asks the charts provider to download the free ENC cells of that area, when
+its **Download the ENC cells around the vessel** is on too; they arrive in its chart set
+"Around the vessel" and the index is rebuilt with them. The cells are
+read in place with GDAL compiled to WebAssembly
 (gdal3.js), which the plugin installs with it, and the updates are applied as they are read.
 Nothing is converted or written next to the cells. A cell without an `M_COVR` coverage layer
 is rejected. A cell's usage band comes from the third character of its name, else from its
@@ -114,18 +137,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,20 +172,22 @@ 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.
 
 ![The setup steps: boat, water level and warnings](docs/images/how-it-works/setup-panel.png)
 
-| Setting             | What it does                                                                                                                                                                 |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| ENC cells directory | where the `.000` cells are                                                                                                                                                   |
-| Boat                | draft (empty uses Signal K `design.draft.maximum`) and safety margin under the keel (0 m); only the keel's lowest point counts, and squat and waves are added on top (below) |
-| Water level         | source (`none`, `manual`, `signalk-tide`, `fmi`, see below); only the chosen source's fields are shown                                                                       |
-| Warnings            | Early, Balanced or Late, in the table below                                                                                                                                  |
-| Optional features   | living chart (own soundings), Traficom WFS depths, grounding detector; each off until enabled                                                                                |
+| Setting                  | What it does                                                                                                                                                                 |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ENC cells directory      | where the `.000` cells are                                                                                                                                                   |
+| ENC from Charts Provider | or a chart set or converted chart whose cells signalk-charts-provider-simple shares, `*` for all of them; used instead of the directory                                      |
+| Boat                     | draft (empty uses Signal K `design.draft.maximum`) and safety margin under the keel (0 m); only the keel's lowest point counts, and squat and waves are added on top (below) |
+| Water level              | source (`none`, `manual`, `signalk-tide`, `fmi`, see below); only the chosen source's fields are shown                                                                       |
+| Warnings                 | Early, Balanced or Late, in the table below                                                                                                                                  |
+| Optional features        | living chart (own soundings), Traficom WFS depths, grounding detector; each off until enabled                                                                                |
 
 | Warning style      | Looks ahead | Alert at | Warn at, within | Alarm at, within | Alarm on negative mean UKC |
 | ------------------ | ----------- | -------- | --------------- | ---------------- | -------------------------- |
@@ -180,7 +214,7 @@ Expert settings, with their defaults:
 
 | Group        | Settings                                                                                                                                                                                                                               |
 | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Chart index  | index directory, rebuild at start, index leaf zoom (20), box around the vessel (10 km)                                                                                                                                                 |
+| Chart index  | index directory, rebuild at start, index leaf zoom (20), box around the vessel (10 km), ask Charts Provider for the ENC around the vessel                                                                                              |
 | Boat         | length, beam (fallback: Signal K `design.*`); draft σ (0.05 m); block coefficient and heel effect (none, fin keel or a table); double squat in narrow channels; wave allowance factor (0.4 × Hs)                                       |
 | Look-ahead   | minimum horizon (60 s); position buffer (10 m, 2σ); fan spread (COG 5°, rate of turn 0.1°/s); escape-heading rate of turn (3°/s); and the distance, probabilities and windows of the warning style, each overriding the style when set |
 | Water level  | manual height and σ; FMI refresh (600 s); chart-datum mappings for FMI                                                                                                                                                                 |
@@ -257,7 +291,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 };
+    };
+}