signalk-underkeel 0.5.1 → 0.6.1

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 All notable changes to signalk-underkeel are documented here.
 
+## [0.6.1] - 2026-11-13
+
+### Fixed
+
+- The details panel reads in dark mode (#67): it had fixed light-theme colours and no
+  background of its own, so on Freeboard's dark background most of its text was dark grey on
+  dark. The status chip and widget also put white on amber (Alert, 2.4:1) and on green
+  (Normal, 3.7:1), below the 4.5:1 that small text needs.
+- The SignalK plugin CI workflow is pinned to a commit again. Without the `@ref`, GitHub could
+  not read the workflow file, so no plugin CI ran for 0.6.0 and the plugin registry took 10
+  points from its score.
+
+### Changed
+
+- The widget, the details panel and the setup steps share one set of colours in three
+  schemes: day, dusk (the device's dark mode) and night (Freeboard's night mode: black, and
+  nothing brighter than a dim grey). Every text colour reads at WCAG AA in each scheme.
+
+## [0.6.0] - 2026-11-10
+
+### Changed
+
+- Charts Provider sharing its store after this plugin started, as it does at every server
+  start once its charts are loaded, no longer restarts the plugin when the store holds the
+  cells read at start; only the note that it was not running goes.
+- The first chart box is built as soon as the first position arrives, not at the next 10 s
+  check. Until it is in use the reason says the box is being built and how far it has come,
+  for example `building the chart box around the vessel: reading cells 3/7`, and the cells
+  phase counts each cell as it is read instead of jumping from 0 to all.
+- A charts provider still starting, or one that does not download an area, goes to the debug
+  log instead of the error log; one too old to be asked, or whose answer failed, stays an
+  error.
+- Once a chart box is in use, the cells the next box can reach are read into the cell cache by
+  a child process at the lowest CPU priority, so moving the box over them reads none during the
+  rebuild: after a 6 km move the Waddenzee box rebuilt in 8.6 s against 34 s for its first
+  build (x86).
+
 ## [0.5.1] - 2026-11-10
 
 ### Changed

package/README.md

@@ -144,8 +144,10 @@ phase, start and the last build's duration. At speed the box grows past its radi
 **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.
+with the reason `waiting for the vessel position to build the chart box`; the box is built
+as soon as one does, and meanwhile the reason says how far it has come, for example
+`building the chart box around the vessel: reading cells 3/7`. Set the box to 0 to index every
+cell.
 
 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`
@@ -157,8 +159,11 @@ changed; `GET /status` names the cells that caused the rebuild. **Rebuild index
 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.
+rebuilds in 12–15 s instead of 30–34 s on x86. Once a box is in use, a child process at the
+lowest CPU priority reads into it the cells the next box can reach, so a box moved over cells it
+had not met reads none during the rebuild: after a 6 km move the Waddenzee box was rebuilt in
+8.6 s against 34 s for its first build (x86). A rebuild ends that process first. 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: convert the original `.000` cells in the charts provider instead. Such a folder
@@ -270,6 +275,11 @@ Extensions API shows it without any change to Freeboard:
 | Widget grid                     | Under-keel status: state colour, minimum clearance, time to shoal and the reason                                                           |
 | Toolbar button (boat icon)      | details panel: state, water level and source, a leg table per route, and **Open setup** for boat, water level and warning style (Settings) |
 
+The widget, the panel and the setup steps follow Freeboard's look: light by day, dark when the
+device is in dark mode, and a dim night scheme, black with nothing brighter than a dim grey,
+while Freeboard's night mode is on, so a glance at the panel keeps the eyes adapted to the
+dark. Every text colour reads at WCAG AA in each scheme.
+
 Routes shown on the chart are checked 1 s after each edit and every minute; the panel shows
 each result's age and marks it "out of date" after 3 minutes, when the chart draws its legs
 `unverified`. Stale status is shown as Unknown,
@@ -497,7 +507,10 @@ panel with its toolbar button, a hidden background page and the experimental
 - `runtime.js`, the background page, keeps the envelope, route results and tiles current;
 - `widget.js` and `panel.js` render the status and the route legs;
 - `ukc-shared.js` holds their pure logic (freshness, badges, labels), the part the Jest tests
-  cover.
+  cover;
+- `theme.css` holds every colour of the pages in the day, dusk and night schemes, and
+  `theme.js` picks the scheme from Freeboard's night mode (`nightMode`) or the device's dark
+  mode; a test holds each text colour to WCAG AA contrast in every scheme.
 
 The pages talk to the host through the vendored `signalk-plotterext-bus` client, copied into
 `public/vendor/` by the build. The [Plotter Extensions services RFC](docs/rfcs/plotter-extensions-services.md)

package/lib/api/manifest.js

@@ -155,6 +155,7 @@ function buildManifest(version) {
                 "signalk.stream",
                 "routes",
                 "units",
+                "nightMode",
                 "ui",
                 "events.publish",
                 "x-freeboard.services.navigationSafety"

package/lib/box-status.js

@@ -1,9 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPending = void 0;
 exports.rebuildStatus = rebuildStatus;
+exports.noIndexReason = noIndexReason;
+exports.phaseText = phaseText;
 exports.boxSummary = boxSummary;
 const box_sizing_1 = require("./box-sizing");
 const chart_box_1 = require("./engine/chart-box");
+const index_loader_1 = require("./index-loader");
 function rebuildStatus(r, now) {
     return {
         startedAt: new Date(r.startedAt).toISOString(),
@@ -13,6 +17,21 @@ function rebuildStatus(r, now) {
         ...(r.estimateMs === undefined ? {} : { estimateMs: r.estimateMs })
     };
 }
+/** Whether `reason` is one of PENDING_REASONS, maybe with a note (`; …`) or detail (`: …`). */
+const isPending = (reason) => [...index_loader_1.PENDING_REASONS].some((p) => reason.startsWith(p) && /^(?:$|[;:] )/.test(reason.slice(p.length)));
+exports.isPending = isPending;
+/**
+ * Why there is no index: `reason`, or what the first chart box build is doing while it runs,
+ * as the vessel position it waited for has come.
+ */
+function noIndexReason(reason, box) {
+    const why = reason ?? "no chart index loaded";
+    if (box?.rebuilding && why.startsWith(index_loader_1.BOX_WAITING_REASON)) {
+        return box.phase ? `${index_loader_1.BOX_BUILDING_REASON}: ${box.phase}` : index_loader_1.BOX_BUILDING_REASON;
+    }
+    return why;
+}
+/** What a box build in progress is doing, with its count where it gave one. */
 function phaseText(r) {
     const of = r.done !== undefined && r.total !== undefined ? ` ${r.done}/${r.total}` : "";
     switch (r.phase) {

package/lib/cell-warm.js

@@ -0,0 +1,110 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.warmCells = warmCells;
+exports.startWarming = startWarming;
+exports.boxWarmer = boxWarmer;
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const worker_threads_1 = require("worker_threads");
+const child_process_1 = require("./foundation/child-process");
+const index_loader_1 = require("./index-loader");
+const cell_cache_1 = require("./ingest/cell-cache");
+const cell_source_1 = require("./ingest/cell-source");
+const enc_read_process_1 = require("./ingest/enc-read-process");
+const build_box_1 = require("./spatial/build-box");
+/** Reads the cells of `job.around` the cache lacks into it; resolves with how many were read. */
+async function warmCells(job, reader = enc_read_process_1.readInProcess) {
+    const cells = (0, index_loader_1.cellSources)(job.cellsDir).filter(cell_source_1.isEncFile);
+    const cache = cell_cache_1.LayerCache.open(job.cacheDir, cells);
+    if (!cache) {
+        return 0;
+    }
+    cache.hold((0, build_box_1.boxCells)(cells, job.hold, job.cacheDir));
+    const want = (0, build_box_1.boxCells)(cells, job.around, job.cacheDir).filter((f) => !cache.has(f));
+    let read = 0;
+    for (const file of want) {
+        const layers = (await reader([file])).get(file);
+        if (layers) {
+            cache.put(file, layers);
+            read++;
+        }
+        // One cell's layers held at a time.
+        await cache.flush();
+    }
+    return read;
+}
+/**
+ * Runs `job` in a child process from the compiled `script`, its heap capped at `heapMb`;
+ * `done` gets its reply, or why it ended without one, unless it was stopped.
+ */
+function startWarming(job, heapMb, done, script = path_1.default.join(__dirname, "cell-warm.js")) {
+    const { child, stderr } = (0, child_process_1.forkLimited)(script, heapMb, true);
+    let stopped = false;
+    let reply;
+    const closed = new Promise((resolve) => {
+        child.once("close", (code) => {
+            if (!stopped) {
+                done(reply ?? { error: `cell cache warming exited with ${code ?? "a signal"}: ${stderr()}` });
+            }
+            resolve();
+        });
+    });
+    child.once("error", () => undefined);
+    child.on("message", (m) => (reply = m));
+    child.send(job, () => undefined);
+    return {
+        stop: () => {
+            stopped = true;
+            (0, child_process_1.killGroup)(child);
+            return closed;
+        }
+    };
+}
+/** One run at a time through `start`; a run that cannot start is reported to `error`. */
+function boxWarmer(start, error) {
+    let running;
+    let stopped = false;
+    const end = () => {
+        const r = running;
+        running = undefined;
+        return r ? r.stop() : Promise.resolve();
+    };
+    return {
+        boxInUse: (bbox, reachKm) => {
+            if (stopped) {
+                return;
+            }
+            void end();
+            try {
+                running = start((0, build_box_1.growBbox)(bbox, reachKm), bbox);
+            }
+            catch (err) {
+                error(`filling the cell cache failed: ${err.message}`);
+            }
+        },
+        beforeBuild: end,
+        stop: () => {
+            stopped = true;
+            void end();
+        }
+    };
+}
+if (worker_threads_1.isMainThread && require.main === module && process.send) {
+    (0, child_process_1.exitWithParent)();
+    try {
+        // Behind the server and the look-ahead, whatever the cores.
+        os_1.default.setPriority(19);
+    }
+    catch {
+        // Not permitted: it runs at the server's priority.
+    }
+    process.once("message", (job) => {
+        warmCells(job)
+            .then((read) => ({ read }), (err) => ({ error: err.message }))
+            .then(child_process_1.sendToParent)
+            .finally(() => process.exit(0));
+    });
+}

package/lib/index-loader.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.failedLoad = exports.cellCacheDir = exports.SYNC_LOAD_BYTES = exports.PENDING_REASONS = exports.BOX_WAITING_REASON = exports.WFS_WAITING_REASON = exports.LOADING_REASON = exports.BUILDING_REASON = void 0;
+exports.failedLoad = exports.cellCacheDir = exports.SYNC_LOAD_BYTES = exports.PENDING_REASONS = exports.BOX_BUILDING_REASON = exports.BOX_WAITING_REASON = exports.WFS_WAITING_REASON = exports.LOADING_REASON = exports.BUILDING_REASON = void 0;
 exports.cellSources = cellSources;
 exports.cellsMissing = cellsMissing;
 exports.savedCatalogue = savedCatalogue;
@@ -27,12 +27,15 @@ exports.BUILDING_REASON = "building chart index";
 exports.LOADING_REASON = "loading chart index";
 exports.WFS_WAITING_REASON = "waiting for the first Traficom WFS download";
 exports.BOX_WAITING_REASON = "waiting for the vessel position to build the chart box";
+/** Why there is no index while the first chart box around the vessel is built. */
+exports.BOX_BUILDING_REASON = "building the chart box around the vessel";
 /** Reasons that mean the index is on its way, not that loading it failed. */
 exports.PENDING_REASONS = new Set([
     exports.BUILDING_REASON,
     exports.LOADING_REASON,
     exports.WFS_WAITING_REASON,
-    exports.BOX_WAITING_REASON
+    exports.BOX_WAITING_REASON,
+    exports.BOX_BUILDING_REASON
 ]);
 /**
  * A saved pyramid.bin larger than this is read and inflated off the event

package/lib/index.js

@@ -66,7 +66,7 @@ function stopPlugin(app, clock, state) {
  * Restarts the plugin once the shared ENC cells it reads changed: a start compares them with the
  * saved index and rebuilds it when they did. A server without a restart callback logs instead.
  */
-function watchShared(app, clock, collection, restart) {
+function watchShared(app, clock, collection, restart, sameCells) {
     return (0, shared_enc_1.watchSharedCells)(collection, clock, () => {
         if (restart) {
             restart();
@@ -74,7 +74,64 @@ function watchShared(app, clock, collection, restart) {
         else {
             app.error("the shared ENC cells changed; restart the plugin to index them");
         }
-    });
+    }, sameCells ? { sameCells } : {});
+}
+/** The stamps of the S-57 cells under `dir`, as one string; undefined when it cannot be read. */
+function cellsStamp(dir) {
+    try {
+        return (0, index_loader_1.sourceKeys)((0, index_loader_1.cellSources)(dir)).join("\n");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Watches the charts provider's cells in use (`watchShared`). A provider publishing later the
+ * cells read at start restarts nothing: the reason shown loses its note that it had not started.
+ */
+function watchAtStart(app, clock, state, plan, restart) {
+    const { config, load } = state;
+    const collection = config?.chartsProviderEnc;
+    if (!config || collection === undefined) {
+        return undefined;
+    }
+    const same = sameCellsAsStart(config.cellsDir, collection);
+    const renote = () => {
+        if ("load" in plan && state.load === load && load?.reason !== undefined) {
+            const fresh = (0, shared_enc_1.noteSharedCells)(plan.load, config);
+            state.load = fresh;
+            if (!fresh.index && fresh.reason !== undefined) {
+                state.monitor?.noIndex(fresh.reason);
+            }
+        }
+    };
+    const quiet = same &&
+        ((root) => {
+            const unchanged = same(root);
+            if (unchanged) {
+                renote();
+            }
+            return unchanged;
+        });
+    return watchShared(app, clock, collection, restart, quiet);
+}
+/**
+ * Whether a charts provider that publishes its store later than this plugin starts, as it does
+ * once its charts are loaded, publishes the cells read at start: the same directory, the same
+ * cells. Undefined when the provider was there at start, or nothing was read.
+ */
+function sameCellsAsStart(cellsDir, collection) {
+    if ((0, shared_enc_1.sharedEncApi)() !== undefined || cellsDir === undefined) {
+        return undefined;
+    }
+    const stamp = cellsStamp(cellsDir);
+    if (stamp === undefined) {
+        return undefined;
+    }
+    return (root) => {
+        const dir = collection === shared_enc_1.ALL_COLLECTIONS ? root : path_1.default.join(root, collection);
+        return path_1.default.resolve(dir) === path_1.default.resolve(cellsDir) && cellsStamp(dir) === stamp;
+    };
 }
 /**
  * The admin form for this server: the essentials with expert settings
@@ -145,9 +202,7 @@ module.exports = function underkeel(app, clock = monitor_1.SYSTEM_CLOCK, fetch =
                 state.zoneErrors = errors;
                 errors.forEach((e) => app.error(e));
             });
-            shared = config.chartsProviderEnc
-                ? watchShared(app, clock, config.chartsProviderEnc, restart && (() => restart(migration.config)))
-                : undefined;
+            shared = watchAtStart(app, clock, state, plan, restart && (() => restart(migration.config)));
             (0, assets_1.mountAssets)(app);
             app.registerResourceProvider((0, manifest_1.manifestProvider)(VERSION));
         },

package/lib/ingest/cell-cache.js

@@ -68,8 +68,8 @@ function writeQuietly(file, data) {
         fs_1.default.rmSync(tmp, { force: true });
     }
 }
-/** The layers in `bytes` filed under `key`; "stale" for another key, "corrupt" for a damaged entry. */
-function decodeEntry(bytes, key) {
+/** The entry's header and where its body lies; "corrupt" for a damaged entry. */
+function entryHead(bytes) {
     const end = bytes.length - SUM_BYTES;
     const headAt = MAGIC.length + 4;
     if (end < headAt || !bytes.subarray(0, MAGIC.length).equals(MAGIC)) {
@@ -79,16 +79,27 @@ function decodeEntry(bytes, key) {
         return "corrupt";
     }
     const bodyAt = headAt + bytes.readUInt32LE(MAGIC.length);
-    let head;
+    try {
+        return bodyAt > end
+            ? "corrupt"
+            : { head: JSON.parse(bytes.toString("utf8", headAt, bodyAt)), bodyAt, end };
+    }
+    catch {
+        return "corrupt";
+    }
+}
+/** The layers in `bytes` filed under `key`; "stale" for another key, "corrupt" for a damaged entry. */
+function decodeEntry(bytes, key) {
+    const entry = entryHead(bytes);
+    if (entry === "corrupt") {
+        return entry;
+    }
+    const { head, bodyAt, end } = entry;
+    if (head.key !== key) {
+        return "stale";
+    }
     let raw;
     try {
-        if (bodyAt > end) {
-            return "corrupt";
-        }
-        head = JSON.parse(bytes.toString("utf8", headAt, bodyAt));
-        if (head.key !== key) {
-            return "stale";
-        }
         raw = zlib_1.default.brotliDecompressSync(bytes.subarray(bodyAt, end));
     }
     catch {
@@ -188,6 +199,36 @@ class LayerCache {
         }
         return typeof layers === "string" ? undefined : layers;
     }
+    /**
+     * Whether an entry for `file` as its files are now is kept, checked whole but not
+     * decompressed; a damaged one is removed.
+     */
+    has(file) {
+        try {
+            const { name, key } = this.identify(file, (0, enc_wasm_1.encStamp)(file));
+            const entry = path_1.default.join(this.dir, name);
+            const found = entryHead(fs_1.default.readFileSync(entry));
+            if (found === "corrupt") {
+                fs_1.default.rmSync(entry, { force: true });
+                return false;
+            }
+            return found.head.key === key;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Keeps the entries of `files` from being dropped to make room, as if this build used them. */
+    hold(files) {
+        for (const file of files) {
+            try {
+                this.used.add(entryName(fs_1.default.realpathSync(file)));
+            }
+            catch {
+                // Gone: nothing to keep.
+            }
+        }
+    }
     /**
      * Files the layers just read from `file`, compressed off the event loop; `flush` waits for
      * the write. Layers of a cell whose files changed while it was read are not kept: they are
@@ -276,19 +317,20 @@ exports.LayerCache = LayerCache;
  * from, and filing those it reads. With every cell kept, gdal3.js is not started.
  */
 function cachedReader(reader, cache) {
-    return async (files) => {
+    return async (files, onRead) => {
         const out = new Map();
         const read = [];
         for (const file of new Set(files)) {
             const layers = cache.get(file);
             if (layers) {
                 out.set(file, layers);
+                onRead?.(file);
             }
             else {
                 read.push(file);
             }
         }
-        for (const [file, layers] of await reader(read)) {
+        for (const [file, layers] of await reader(read, onRead)) {
             out.set(file, layers);
             cache.put(file, layers);
         }

package/lib/ingest/enc-read-process.js

@@ -6,10 +6,11 @@ const worker_threads_1 = require("worker_threads");
 const child_process_1 = require("../foundation/child-process");
 const enc_wasm_1 = require("./enc-wasm");
 /** Reads on the calling thread; the WebAssembly memory stays with it. */
-const readInProcess = async (files) => {
+const readInProcess = async (files, onRead) => {
     const out = new Map();
-    for (const file of files) {
+    for (const file of new Set(files)) {
         out.set(file, await (0, enc_wasm_1.readEncLayers)(file));
+        onRead?.(file);
     }
     return out;
 };
@@ -20,7 +21,7 @@ exports.readInProcess = readInProcess;
  * that exits before every cell has come back fails the read.
  */
 function readInChild(heapMb, script = __filename) {
-    return (files) => {
+    return (files, onRead) => {
         const want = [...new Set(files)];
         if (want.length === 0) {
             return Promise.resolve(new Map());
@@ -35,6 +36,7 @@ function readInChild(heapMb, script = __filename) {
                 }
                 else if (m.file !== undefined && m.layers) {
                     out.set(m.file, (0, enc_wasm_1.sharedLayers)(new Map(Object.entries(m.layers))));
+                    onRead?.(m.file);
                 }
             });
             child.once("error", (err) => (failure ??= err));

package/lib/monitor.js

@@ -11,7 +11,7 @@ const notify_1 = require("./engine/notify");
 const state_1 = require("./foundation/state");
 const integrity_1 = require("./model/integrity");
 const vessel_1 = require("./model/vessel");
-const index_loader_1 = require("./index-loader");
+const box_status_1 = require("./box-status");
 const wfs_1 = require("./ingest/wfs");
 const water_level_service_1 = require("./water-level-service");
 const notifications_1 = require("./notifications");
@@ -262,7 +262,7 @@ class Monitor {
         if (!this.index) {
             return {
                 state: "off",
-                reason: this.indexReason ?? "no chart index loaded",
+                reason: (0, box_status_1.noIndexReason)(this.indexReason, this.chartBox?.()),
                 clearance: null,
                 clearanceSigma: null,
                 risk: null,
@@ -331,8 +331,8 @@ class Monitor {
         const now = this.clock.now();
         if (!this.index) {
             // The engine is off either way; a pending reason is a status, any other an error.
-            const reason = this.indexReason ?? "no chart index loaded";
-            if (index_loader_1.PENDING_REASONS.has(reason)) {
+            const reason = (0, box_status_1.noIndexReason)(this.indexReason, this.chartBox?.());
+            if ((0, box_status_1.isPending)(reason)) {
                 this.status.status(boxNote ? `${reason} · ${boxNote}` : reason, now);
             }
             else {

package/lib/shared-enc.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AREA_ERROR_RETRY_MS = exports.ALL_COLLECTIONS = exports.CHARTS_PROVIDER_ID = void 0;
+exports.AREA_ERROR_RETRY_MS = exports.PROVIDER_ABSENT = exports.ALL_COLLECTIONS = exports.CHARTS_PROVIDER_ID = void 0;
 exports.sharedEncApi = sharedEncApi;
 exports.sharedEncRoot = sharedEncRoot;
 exports.sharedCellsDir = sharedCellsDir;
@@ -97,14 +97,20 @@ function collectionsHint(api = sharedEncApi()) {
             .map((c) => `${c.id} (${c.kind === "chart-set" ? "chart set" : "converted chart"}, ${c.cellCount} cells)`)
             .join(", ")}.`;
 }
+/**
+ * What is said of a charts provider whose store is not published: at a server start it is
+ * published only once the provider's charts are loaded, after this plugin has started.
+ */
+exports.PROVIDER_ABSENT = "Charts Provider is not running or still starting";
 /**
  * Why the charts provider's `collection` holds no cells to read, as it tells it, or that it is
  * not running; undefined when it is ready, or cannot tell. A provider started later restarts
- * the plugin (`watchShared`), so the note is read again then.
+ * the plugin (`watchShared`) unless it shares the cells read at start; then only this note is
+ * read again (`watchAtStart` in index.ts).
  */
 function sharedCellsNote(collection, api = sharedEncApi()) {
     if (!api) {
-        return "Charts Provider is not running";
+        return exports.PROVIDER_ABSENT;
     }
     if (collection === exports.ALL_COLLECTIONS) {
         return collectionsHint(api)?.startsWith("Charts Provider shares no")
@@ -166,18 +172,28 @@ function requestSharedArea(bbox, api = sharedEncApi()) {
             accepted: false,
             started: false,
             reason: err.message,
-            retryAfterMs: exports.AREA_ERROR_RETRY_MS
+            retryAfterMs: exports.AREA_ERROR_RETRY_MS,
+            failed: true
         };
     }
 }
+/** A comparison that throws counts as cells changed, so the plugin restarts rather than keep them. */
+function safely(f) {
+    try {
+        return f();
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Calls `onChange` once the cells of `collection` (any, for ALL_COLLECTIONS) changed and
  * settled. While the charts provider has not published its API, looks for it every `pollMs`,
  * and after `waitMs` every `slowPollMs` for as long as the watch runs, since it may start any
  * time; meanwhile the cells are read as found at start. An API that appears later counts as
- * a change: the provider may have written cells meanwhile, or keep its store elsewhere than
- * the default path the cells were read from, and the restart rebuilds the index only when
- * the cells it finds differ.
+ * a change, unless `sameCells` finds its store holds the cells read at start: the provider
+ * may have written cells meanwhile, or keep its store elsewhere than the default path the
+ * cells were read from. It is asked once subscribed, so a write after it is heard.
  */
 function watchSharedCells(collection, clock, onChange, opts = {}) {
     const settleMs = opts.settleMs ?? 5_000;
@@ -185,6 +201,7 @@ function watchSharedCells(collection, clock, onChange, opts = {}) {
     const pollMs = opts.pollMs ?? 5_000;
     const slowPollMs = opts.slowPollMs ?? 60_000;
     const started = clock.now();
+    const sameAsStart = (root) => safely(() => opts.sameCells?.(root) ?? false);
     let unsubscribe;
     let changedAt;
     let timer;
@@ -212,7 +229,9 @@ function watchSharedCells(collection, clock, onChange, opts = {}) {
         });
         if (late) {
             stopTimer();
-            changed();
+            if (!sameAsStart(api.root)) {
+                changed();
+            }
         }
         return true;
     };

package/lib/spatial/build-survey.js

@@ -28,9 +28,14 @@ class EncReads {
         if (files.length === 0) {
             return;
         }
-        const done = this.layers.size;
-        (0, build_progress_1.reportProgress)({ phase: "cells", done, total: done + files.length });
-        for (const [file, layers] of await this.reader(files)) {
+        const total = this.layers.size + new Set(files).size;
+        let done = this.layers.size;
+        (0, build_progress_1.reportProgress)({ phase: "cells", done, total });
+        const read = await this.reader(files, () => {
+            done = Math.min(total, done + 1);
+            (0, build_progress_1.reportProgress)({ phase: "cells", done, total });
+        });
+        for (const [file, layers] of read) {
             this.layers.set(file, layers);
         }
         (0, build_progress_1.reportProgress)({ phase: "cells", done: this.layers.size, total: this.layers.size });

package/lib/status-report.js

@@ -3,12 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.statusReport = statusReport;
 const public_text_1 = require("./foundation/public-text");
 /** Body of `GET /status`: engine state, index provenance and look-ahead summary; `?summary` without the per-cell lists. */
-function indexSection(load, summary) {
+function indexSection(load, monitor, summary) {
     const index = load?.index;
+    // Without an index the engine's reason is why, and follows a first box build as it runs.
+    const reason = !index && monitor?.last.state === "off" ? monitor.last.reason : load?.reason;
     return {
         loaded: index !== undefined,
         built: load?.built ?? false,
-        reason: (0, public_text_1.publicReason)(load?.reason),
+        reason: (0, public_text_1.publicReason)(reason),
         nodes: index?.pyramid.count ?? 0,
         hazards: index?.hazards.size ?? 0,
         ...(summary ? {} : { cells: index?.catalogue.cells ?? [] })
@@ -38,7 +40,7 @@ function statusReport(s) {
     const wfs = s.wfs?.status();
     return {
         ...(s.monitor ? monitorSection(s.monitor, summary) : { engine: s.stopped, vessel: [] }),
-        index: indexSection(s.load, summary),
+        index: indexSection(s.load, s.monitor, summary),
         livechart: s.livechart?.status() ?? null,
         wfs: wfs && s.wfs?.downloads ? { ...wfs, lastError: (0, public_text_1.publicReason)(wfs.lastError) } : null,
         chartBox: s.wfs ? boxSection(s.wfs) : null,