signalk-underkeel 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 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

package/README.md

@@ -106,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
@@ -167,13 +180,14 @@ There are two places to set the plugin up, and both write the same configuration
 
 ![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 |
 | ------------------ | ----------- | -------- | --------------- | ---------------- | -------------------------- |
@@ -200,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                                                                                                                                                                 |

package/lib/config-charts.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CHART_AREA_FIELD = void 0;
+exports.chartFields = chartFields;
+const shared_enc_1 = require("./shared-enc");
+/**
+ * The admin form's chart fields: a directory of S-57 cells, or the cells
+ * signalk-charts-provider-simple shares (`shared-enc.ts`).
+ */
+function chartFields(sharedNow) {
+    return {
+        cellsDir: {
+            type: "string",
+            title: "ENC cells directory",
+            description: "S-57 ENC cells as delivered: .000 files with their .001, .002 … updates, also in sub-folders such as ENC_ROOT. Read directly with GDAL (WebAssembly); nothing is converted."
+        },
+        chartsProviderEnc: {
+            type: "string",
+            pattern: shared_enc_1.COLLECTION_CHOICE_PATTERN,
+            title: "ENC from Charts Provider",
+            description: "Or read the ENC cells signalk-charts-provider-simple keeps: the name of an ENC Charts set there (Gulf of Finland is Gulf_of_Finland) or of a converted chart whose cells it keeps, or * for all of them. Used instead of the ENC cells directory; the index is rebuilt when the cells change." +
+                (sharedNow ? ` ${sharedNow}` : "")
+        }
+    };
+}
+/** The expert field asking Charts Provider for the cells around the vessel (`shared-enc.ts`). */
+exports.CHART_AREA_FIELD = {
+    chartsProviderArea: {
+        type: "boolean",
+        title: "Ask Charts Provider for the ENC around the vessel",
+        description: 'With ENC from Charts Provider set to * and Charts Provider\'s "Download the ENC cells around the vessel" on, each new index box asks it to download the free ENC cells of that area; they arrive in its chart set "Around the vessel" and the index is rebuilt with them. Off: only the cells already shared are read.',
+        default: false
+    }
+};

package/lib/config-schema.js

@@ -5,6 +5,7 @@ exports.adminSchema = adminSchema;
 exports.flatten = flatten;
 exports.formsFollowDependencies = formsFollowDependencies;
 const lookahead_1 = require("./engine/lookahead");
+const config_charts_1 = require("./config-charts");
 const ADVISORY = "Advisory navigation aid. Not for navigation; does not replace official charts or a proper lookout.";
 /** Shown under each field whose empty value follows a preset. */
 const FOLLOWS_STYLE = "Empty follows the warning style.";
@@ -264,7 +265,8 @@ const CHART_INDEX = {
         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.")
+    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."),
+    ...config_charts_1.CHART_AREA_FIELD
 };
 const EXPERT = {
     ...CHART_INDEX,
@@ -301,11 +303,7 @@ function adminSchema(hints = {}) {
         type: "object",
         description: `${ADVISORY}${checks}`,
         properties: {
-            cellsDir: {
-                type: "string",
-                title: "ENC cells directory",
-                description: "S-57 ENC cells as delivered: .000 files with their .001, .002 … updates, also in sub-folders such as ENC_ROOT. Read directly with GDAL (WebAssembly); nothing is converted."
-            },
+            ...(0, config_charts_1.chartFields)(hints.encCollections),
             vessel: {
                 ...VESSEL_ESSENTIAL,
                 properties: { ...VESSEL_ESSENTIAL.properties, draft: draftField(hints.signalkDraft) }

package/lib/config.js

@@ -10,6 +10,7 @@ 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");
+const shared_enc_1 = require("./shared-enc");
 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 };
@@ -22,6 +23,14 @@ function optionalPositive(v) {
 function str(v) {
     return typeof v === "string" && v.trim() !== "" ? v : undefined;
 }
+/**
+ * A charts provider collection id or `*`, trimmed. Anything else, a path out of the store
+ * among them, is no choice, and the ENC cells directory stays in use.
+ */
+function collectionChoice(v) {
+    const s = str(v)?.trim();
+    return s !== undefined && (0, shared_enc_1.isCollectionChoice)(s) ? s : undefined;
+}
 function record(v) {
     return typeof v === "object" && v !== null ? v : {};
 }
@@ -159,6 +168,8 @@ function parseConfig(raw) {
     return {
         indexDir: str(r.indexDir),
         cellsDir: str(r.cellsDir),
+        chartsProviderEnc: collectionChoice(r.chartsProviderEnc),
+        chartsProviderArea: r.chartsProviderArea === true,
         rebuildIndex: r.rebuildIndex === true,
         leafZoom: Math.round(num(r.leafZoom, 20, 14, 22)),
         boxRadiusKm: boxRadius(r.boxRadiusKm),

package/lib/index-loader.js

@@ -14,6 +14,8 @@ exports.savedLoad = savedLoad;
 exports.sourceKeys = sourceKeys;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const index_source_1 = require("./index-source");
+const build_source_1 = require("./spatial/build-source");
 const cell_cache_1 = require("./ingest/cell-cache");
 const cells_1 = require("./ingest/cells");
 const cell_source_1 = require("./ingest/cell-source");
@@ -139,7 +141,8 @@ async function settle(p) {
             cells.push(await (0, cell_source_1.readCell)(d, i));
         }
         const index = (0, chart_index_1.buildChartIndex)(cells, { leafZoom: p.build.leafZoom });
-        (0, chart_index_1.saveChartIndex)(p.indexDir, index);
+        const { source } = p.build;
+        (0, chart_index_1.saveChartIndex)(p.indexDir, index, source ? (dir) => (0, build_source_1.writeSource)(dir, source) : undefined);
         return builtLoad(p, index);
     }
     catch (err) {
@@ -182,11 +185,11 @@ function scanCells(cellsDir, saved) {
 }
 function plan(cfg, indexDir, extraDirs, syncLoadBytes) {
     const { cells: saved, error } = readSaved(indexDir);
-    const { stale, mismatch } = savedMatches(cfg, indexDir, saved, extraDirs);
-    const fromSaved = (notes, unreadable) => stale
-        ? { load: { indexDir, built: false, reason: missingReason(cfg, indexDir, true) } }
-        : savedPlan(indexDir, notes, unreadable, syncLoadBytes);
-    const found = scanCells(cfg.cellsDir, saved);
+    const { refused, mismatch } = savedMatches(cfg, indexDir, saved, extraDirs);
+    const fromSaved = (notes, unreadable) => refused === undefined
+        ? savedPlan(indexDir, notes, unreadable, syncLoadBytes)
+        : { load: { indexDir, built: false, reason: refused } };
+    const found = (0, index_source_1.cellsNow)(scanCells(cfg.cellsDir, saved), cfg, indexDir);
     if ("away" in found) {
         return fromSaved([`${found.away}; using the saved index`], (err) => ({
             load: (0, exports.failedLoad)(indexDir, err)
@@ -197,7 +200,8 @@ function plan(cfg, indexDir, extraDirs, syncLoadBytes) {
     let stamps;
     const encKeys = () => (stamps ??= scan.sources.map(sourceKey));
     const change = cellsChange(cfg.cellsDir, saved, encKeys);
-    const notes = [...(change ? [change] : []), ...skippedNote(cfg.cellsDir, scan)];
+    const away = found.note === undefined ? [] : [found.note];
+    const notes = [...away, ...(change ? [change] : []), ...skippedNote(cfg.cellsDir, scan)];
     const sources = Boolean(cfg.cellsDir) || extraDirs.length > 0;
     const dirs = [...scan.sources, ...extraDirs];
     const keys = () => [...encKeys(), ...extraDirs.map(sourceKey)].sort();
@@ -220,7 +224,7 @@ function plan(cfg, indexDir, extraDirs, syncLoadBytes) {
         return boxPlan(cfg, indexDir, dirs, keys, {
             mismatch,
             fromSaved: (why) => fromSaved(why, unreadable),
-            notes: skippedNote(cfg.cellsDir, scan)
+            notes: [...away, ...skippedNote(cfg.cellsDir, scan)]
         });
     }
     // With no index saved, `mismatch` says so.
@@ -235,7 +239,7 @@ function plan(cfg, indexDir, extraDirs, syncLoadBytes) {
         ]);
     }
     if (!saved) {
-        return { load: { indexDir, built: false, reason: missingReason(cfg, indexDir, false) } };
+        return { load: { indexDir, built: false, reason: missingReason(cfg, indexDir) } };
     }
     return fromSaved(notes, unreadable);
 }
@@ -312,23 +316,24 @@ function buildPlan(cfg, indexDir, dirs, notes, box) {
     if (refused !== undefined) {
         return { load: (0, exports.failedLoad)(indexDir, new Error(refused)) };
     }
-    const build = { dirs, leafZoom: cfg.leafZoom, indexDir };
+    const source = (0, index_source_1.indexSource)(cfg);
+    const build = { dirs, leafZoom: cfg.leafZoom, indexDir, ...(source ? { source } : {}) };
     return { build: box ? { ...build, box } : build, indexDir, notes };
 }
-function missingReason(cfg, indexDir, stale) {
-    if (stale) {
-        return "the saved index holds Traficom WFS depths and that source is off; set cellsDir";
-    }
+function missingReason(cfg, indexDir) {
     return cfg.wfs ? exports.WFS_WAITING_REASON : `no chart index in ${indexDir}; set cellsDir`;
 }
 /**
- * `stale`: the saved index holds WFS depths and the source is off. `mismatch`, why the saved
- * index is not used as is: none is saved, that, the source is on and the saved index lacks
- * its cell, or the index was saved by an older version of its pyramid or hazard file.
+ * `refused`, why the saved index is not used even with nothing to build another from: it holds
+ * WFS depths and that source is off, or it records an ENC source and none is set now.
+ * `mismatch`, why the saved index is not used as is: none is saved, those, the source is on
+ * and the saved index lacks its cell, or the index was saved by an older version of its
+ * pyramid or hazard file.
  */
 function savedMatches(cfg, indexDir, saved, extraDirs) {
     const holds = saved?.some((c) => c.source === wfs_1.WFS_SOURCE) ?? false;
     const stale = holds && !cfg.wfs;
+    const dropped = saved && (0, index_source_1.sourceDropped)(cfg, indexDir);
     const mismatch = saved === undefined
         ? `no index saved in ${indexDir}`
         : stale
@@ -337,8 +342,13 @@ function savedMatches(cfg, indexDir, saved, extraDirs) {
                 ? "the saved one is from an older index version or its header is damaged"
                 : extraDirs.length > 0 && !holds
                     ? "the saved one lacks the Traficom WFS cell"
-                    : undefined;
-    return { stale, mismatch };
+                    : dropped;
+    const refused = stale
+        ? "the saved index holds Traficom WFS depths and that source is off; set cellsDir"
+        : dropped && extraDirs.length === 0
+            ? `not using the saved index: ${dropped}; set cellsDir`
+            : undefined;
+    return { refused, mismatch };
 }
 function savedCells(indexDir) {
     return (0, cells_1.parseCatalogue)(JSON.parse(fs_1.default.readFileSync(path_1.default.join(indexDir, "cells.json"), "utf8")))

package/lib/index-source.js

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.indexSource = indexSource;
+exports.sourceChanged = sourceChanged;
+exports.cellsNow = cellsNow;
+exports.sourceDropped = sourceDropped;
+const path_1 = __importDefault(require("path"));
+const build_source_1 = require("./spatial/build-source");
+/**
+ * The ENC source an index was built from, as the settings name it: a cells directory, or a
+ * collection signalk-charts-provider-simple shares. Recorded with the index, so a source left
+ * without cells can be told apart from the source the index came from: a cells directory that
+ * is gone or empty most likely sits on a drive that is not mounted, and its saved index is
+ * used meanwhile, while a source the user chose since was never the saved index's.
+ *
+ * A collection is recorded by its id, not the directory it resolves to: the charts provider
+ * may keep its store elsewhere than the default path read while it is still starting.
+ */
+/** The source `cfg` reads its S-57 cells from; undefined without one. */
+function indexSource(cfg) {
+    if (cfg.chartsProviderEnc !== undefined) {
+        return `charts-provider:${cfg.chartsProviderEnc}`;
+    }
+    return cfg.cellsDir ? `dir:${path_1.default.resolve(cfg.cellsDir)}` : undefined;
+}
+/**
+ * Why the index in `indexDir` was not built from the source `cfg` reads, or undefined when it
+ * was, or records no source (an index saved by an older version).
+ */
+function sourceChanged(cfg, indexDir) {
+    const saved = (0, build_source_1.readSource)(indexDir);
+    const now = indexSource(cfg);
+    return saved !== undefined && saved !== now
+        ? `the saved index was built from ${describe(saved)}, not ${now === undefined ? "the cells now set" : describe(now)}`
+        : undefined;
+}
+function describe(source) {
+    return source.startsWith("charts-provider:")
+        ? `Charts Provider's ${source.slice("charts-provider:".length)}`
+        : source.slice(source.indexOf(":") + 1);
+}
+/**
+ * `found`, a scan of the cells directory or why it says nothing of the saved index, except
+ * that cells away from a source the saved index was not built from are none: an unmounted
+ * drive keeps the saved index, but only one built from the cells now set.
+ */
+function cellsNow(found, cfg, indexDir) {
+    const moved = "away" in found ? sourceChanged(cfg, indexDir) : undefined;
+    return "away" in found && moved !== undefined
+        ? {
+            scan: { sources: [], skipped: [] },
+            note: `${found.away}; not using the saved index: ${moved}`
+        }
+        : found;
+}
+/**
+ * Why the index in `indexDir` is not this configuration's when `cfg` sets no ENC source at
+ * all, as when the source is cleared, though the index records one; undefined otherwise.
+ */
+function sourceDropped(cfg, indexDir) {
+    return indexSource(cfg) === undefined ? sourceChanged(cfg, indexDir) : undefined;
+}

package/lib/index.js

@@ -23,6 +23,7 @@ const block_keeper_1 = require("./block-keeper");
 const livechart_service_1 = require("./livechart-service");
 const wfs_service_1 = require("./wfs-service");
 const wfs_wiring_1 = require("./wfs-wiring");
+const shared_enc_1 = require("./shared-enc");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 // lib/index.js and src/index.ts both sit one level below package.json.
@@ -61,6 +62,20 @@ 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) {
+    return (0, shared_enc_1.watchSharedCells)(collection, clock, () => {
+        if (restart) {
+            restart();
+        }
+        else {
+            app.error("the shared ENC cells changed; restart the plugin to index them");
+        }
+    });
+}
 /**
  * The admin form for this server: the essentials with expert settings
  * behind a checkbox where the admin UI forwards `dependencies`, every field
@@ -87,6 +102,7 @@ module.exports = function underkeel(app, clock = monitor_1.SYSTEM_CLOCK, fetch =
         requests: new route_service_1.RequestQueue()
     };
     let startup;
+    let shared;
     return {
         id: manifest_1.PLUGIN_ID,
         name: "Under-Keel Awareness",
@@ -96,10 +112,10 @@ module.exports = function underkeel(app, clock = monitor_1.SYSTEM_CLOCK, fetch =
         start(options, restart) {
             const migration = (0, config_migrate_1.migrateConfig)(options);
             (0, settings_service_1.persistMigration)(app, options, migration);
-            const config = (0, config_1.parseConfig)(migration.config);
+            const config = (0, shared_enc_1.withSharedCells)((0, config_1.parseConfig)(migration.config), app.getDataDirPath());
             const wfs = (0, wfs_wiring_1.startBox)({ app, clock, state, config, fetch, build });
             const plan = (0, index_loader_1.planIndex)(config, app.getDataDirPath(), wfs?.savedCell() ? [wfs.cellDir] : []);
-            const load = "load" in plan ? plan.load : (0, index_startup_1.pendingLoad)(plan);
+            const load = "load" in plan ? (0, shared_enc_1.noteSharedCells)(plan.load, config) : (0, index_startup_1.pendingLoad)(plan);
             const monitor = new monitor_1.Monitor(app, manifest_1.PLUGIN_ID, config, load.index, load.reason, clock, fetch);
             const acks = new ack_store_1.AckStore(path_1.default.join(app.getDataDirPath(), "acks.json"));
             if (acks.error) {
@@ -127,10 +143,15 @@ 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;
             (0, assets_1.mountAssets)(app);
             app.registerResourceProvider((0, manifest_1.manifestProvider)(VERSION));
         },
         stop() {
+            shared?.stop();
+            shared = undefined;
             startup?.abort();
             startup = undefined;
             stopPlugin(app, clock, state);

package/lib/setup-checks.js

@@ -14,6 +14,7 @@ const memory_1 = require("./foundation/memory");
 const public_text_1 = require("./foundation/public-text");
 const water_level_1 = require("./model/water-level");
 const nav_inputs_1 = require("./nav-inputs");
+const shared_enc_1 = require("./shared-enc");
 function hostFacts() {
     const memory = (0, memory_1.usableMemory)();
     return { memory, available: Math.min(os_1.default.freemem(), memory), cpus: os_1.default.availableParallelism() };
@@ -64,7 +65,11 @@ function chartsCheck(s, facts) {
         return { id: "charts", level: "ok", text: `Charts: ${facts.cells} cells indexed` };
     }
     if (!s.config?.cellsDir && !s.config?.wfs) {
-        return { id: "charts", level: "todo", text: "Charts: set the ENC cells directory" };
+        return {
+            id: "charts",
+            level: "todo",
+            text: "Charts: set the ENC cells directory or ENC from Charts Provider"
+        };
     }
     const reason = (0, public_text_1.publicReason)(s.load?.reason) ?? "no chart index loaded";
     return { id: "charts", level: "warn", text: `Charts: ${reason}` };
@@ -177,6 +182,7 @@ function schemaHints(app, s) {
     return {
         checks: setupChecks(s, facts).map((c) => `${MARK[c.level]} ${c.text}`),
         signalkDraft: facts.signalk.draft,
-        source: sourceHint(facts)
+        source: sourceHint(facts),
+        encCollections: (0, shared_enc_1.collectionsHint)()
     };
 }

package/lib/shared-enc.js

@@ -0,0 +1,214 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COLLECTION_CHOICE_PATTERN = exports.ALL_COLLECTIONS = exports.CHARTS_PROVIDER_ID = void 0;
+exports.isCollectionChoice = isCollectionChoice;
+exports.sharedEncApi = sharedEncApi;
+exports.sharedEncRoot = sharedEncRoot;
+exports.sharedCellsDir = sharedCellsDir;
+exports.withSharedCells = withSharedCells;
+exports.collectionsHint = collectionsHint;
+exports.sharedCellsNote = sharedCellsNote;
+exports.noteSharedCells = noteSharedCells;
+exports.requestSharedArea = requestSharedArea;
+exports.watchSharedCells = watchSharedCells;
+const path_1 = __importDefault(require("path"));
+/**
+ * ENC cells shared by signalk-charts-provider-simple. Its ENC store keeps the
+ * cells behind its ENC charts as delivered, one folder per collection (an
+ * ENC Charts set's cells, or a converted chart's):
+ * `<root>/<collection>/<CELL>/<CELL>.000` with the updates beside it. The
+ * plugin reads a collection, or the whole store, as its cells directory,
+ * and is told when the cells change. See that plugin's docs/enc-store.md.
+ */
+exports.CHARTS_PROVIDER_ID = "signalk-charts-provider-simple";
+/** Every collection the charts provider shares. */
+exports.ALL_COLLECTIONS = "*";
+const COLLECTION_ID = /^[A-Za-z0-9_-]{1,80}$/;
+/** A collection choice for the admin form, with the space around it that parsing trims. */
+exports.COLLECTION_CHOICE_PATTERN = "^\\s*(\\*|[A-Za-z0-9_-]{1,80})?\\s*$";
+/** A collection's id, or ALL_COLLECTIONS. */
+function isCollectionChoice(value) {
+    return value === exports.ALL_COLLECTIONS || COLLECTION_ID.test(value);
+}
+/** The charts provider's ENC store API, while that plugin runs in this server. */
+function sharedEncApi(scope = globalThis) {
+    const api = scope.__signalk_chartsProviderEnc;
+    if (typeof api !== "object" || api === null) {
+        return undefined;
+    }
+    const a = api;
+    return a.apiVersion === 1 &&
+        typeof a.root === "string" &&
+        typeof a.collections === "function" &&
+        typeof a.onChange === "function"
+        ? a
+        : undefined;
+}
+/**
+ * The charts provider's ENC store: where its API says, else where that plugin keeps it,
+ * beside this plugin's data directory, so the cells are found while it is still starting.
+ */
+function sharedEncRoot(dataDir, api = sharedEncApi()) {
+    return api?.root ?? path_1.default.join(path_1.default.dirname(dataDir), exports.CHARTS_PROVIDER_ID, "enc-store");
+}
+/** The directory of a collection's cells; the whole store for ALL_COLLECTIONS. */
+function sharedCellsDir(dataDir, collection, api = sharedEncApi()) {
+    const root = sharedEncRoot(dataDir, api);
+    return collection === exports.ALL_COLLECTIONS ? root : path_1.default.join(root, collection);
+}
+/** `cfg` reading its cells from the charts provider's collection when it names one. */
+function withSharedCells(cfg, dataDir, api = sharedEncApi()) {
+    return cfg.chartsProviderEnc === undefined
+        ? cfg
+        : { ...cfg, cellsDir: sharedCellsDir(dataDir, cfg.chartsProviderEnc, api) };
+}
+/** One line naming the collections the charts provider shares, for the admin form. */
+function collectionsHint(api = sharedEncApi()) {
+    if (!api) {
+        return undefined;
+    }
+    let collections;
+    try {
+        collections = api.collections();
+    }
+    catch {
+        return undefined;
+    }
+    return collections.length === 0
+        ? "Charts Provider shares no ENC cells yet: download an ENC Charts set there."
+        : `Shared now: ${collections
+            .map((c) => `${c.id} (${c.kind === "chart-set" ? "chart set" : "converted chart"}, ${c.cellCount} cells)`)
+            .join(", ")}.`;
+}
+/**
+ * Why the charts provider's `collection` holds no cells to read, as it tells it; undefined
+ * when it is ready, or the provider cannot tell.
+ */
+function sharedCellsNote(collection, api = sharedEncApi()) {
+    if (!api) {
+        return undefined;
+    }
+    if (collection === exports.ALL_COLLECTIONS) {
+        return collectionsHint(api)?.startsWith("Charts Provider shares no")
+            ? "Charts Provider shares no ENC cells yet: download an ENC Charts set there"
+            : undefined;
+    }
+    let found;
+    try {
+        found = api.state?.(collection);
+    }
+    catch {
+        return undefined;
+    }
+    switch (found?.state) {
+        case "writing":
+            return `Charts Provider is writing the cells of ${collection}; the index is built once they are in place`;
+        case "pending":
+            return found.detail === "downloading"
+                ? `Charts Provider is downloading ${collection}; the index is built once its cells are shared`
+                : `${collection} is a Charts Provider chart set not downloaded yet: download it in its ENC Charts tab`;
+        case "absent":
+            return `Charts Provider shares no ${collection}: check ENC from Charts Provider`;
+        default:
+            return undefined;
+    }
+}
+/** `load` with the charts provider's word on why the collection in use has no cells. */
+function noteSharedCells(load, cfg, api = sharedEncApi()) {
+    const note = load.reason !== undefined && cfg.chartsProviderEnc !== undefined
+        ? sharedCellsNote(cfg.chartsProviderEnc, api)
+        : undefined;
+    return note === undefined ? load : { ...load, reason: `${load.reason ?? ""}; ${note}` };
+}
+/** Asks the charts provider for the cells around `bbox`; undefined when it cannot be asked. */
+function requestSharedArea(bbox, api = sharedEncApi()) {
+    try {
+        return api?.requestArea?.(bbox, "signalk-underkeel");
+    }
+    catch (err) {
+        return { accepted: false, started: false, reason: err.message };
+    }
+}
+/**
+ * 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.
+ */
+function watchSharedCells(collection, clock, onChange, opts = {}) {
+    const settleMs = opts.settleMs ?? 5_000;
+    const waitMs = opts.waitMs ?? 120_000;
+    const pollMs = opts.pollMs ?? 5_000;
+    const slowPollMs = opts.slowPollMs ?? 60_000;
+    const started = clock.now();
+    let unsubscribe;
+    let changedAt;
+    let timer;
+    let stopped = false;
+    let slow = false;
+    const stopTimer = () => {
+        if (timer !== undefined) {
+            clock.clearInterval(timer);
+            timer = undefined;
+        }
+    };
+    const changed = () => {
+        changedAt = clock.now();
+        timer ??= clock.setInterval(tick, pollMs);
+    };
+    const subscribe = (late) => {
+        const api = sharedEncApi(opts.scope);
+        if (!api) {
+            return false;
+        }
+        unsubscribe = api.onChange((id) => {
+            if (collection === exports.ALL_COLLECTIONS || id === collection) {
+                changed();
+            }
+        });
+        if (late) {
+            stopTimer();
+            changed();
+        }
+        return true;
+    };
+    function tick() {
+        if (stopped) {
+            return;
+        }
+        if (!unsubscribe && !subscribe(true)) {
+            if (!slow && clock.now() - started >= waitMs) {
+                slow = true;
+                stopTimer();
+                timer = clock.setInterval(tick, slowPollMs);
+            }
+            return;
+        }
+        if (changedAt !== undefined && clock.now() - changedAt >= settleMs) {
+            changedAt = undefined;
+            stopTimer();
+            onChange();
+            return;
+        }
+        if (unsubscribe && changedAt === undefined) {
+            stopTimer();
+        }
+    }
+    if (!subscribe(false)) {
+        timer = clock.setInterval(tick, pollMs);
+    }
+    return {
+        stop() {
+            stopped = true;
+            stopTimer();
+            unsubscribe?.();
+            unsubscribe = undefined;
+        }
+    };
+}

package/lib/spatial/build-source.js

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SOURCE_FILE = void 0;
+exports.writeSource = writeSource;
+exports.readSource = readSource;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const durable_file_1 = require("../foundation/durable-file");
+/** Where an index records the ENC source it was built from (`index-source.ts`). */
+exports.SOURCE_FILE = "source.json";
+function writeSource(staging, source) {
+    (0, durable_file_1.writeFileDurable)(path_1.default.join(staging, exports.SOURCE_FILE), JSON.stringify({ version: 1, source }));
+}
+/** The source the index in `dir` was built from; undefined when it records none. */
+function readSource(dir) {
+    try {
+        const json = JSON.parse(fs_1.default.readFileSync(path_1.default.join(dir, exports.SOURCE_FILE), "utf8"));
+        return json.version === 1 && typeof json.source === "string" ? json.source : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/lib/spatial/build-worker.js

@@ -28,6 +28,7 @@ const pyramid_regions_1 = require("./pyramid-regions");
 const store_1 = require("./store");
 const geo_1 = require("../foundation/geo");
 const build_box_1 = require("./build-box");
+const build_source_1 = require("./build-source");
 const build_progress_1 = require("./build-progress");
 const parsed_cells_1 = require("./parsed-cells");
 const region_jobs_1 = require("./region-jobs");
@@ -207,6 +208,9 @@ function stage(job, index) {
         if (job.box) {
             (0, build_box_1.writeBox)(staging, { ...job.box, leafZoom: job.leafZoom });
         }
+        if (job.source !== undefined) {
+            (0, build_source_1.writeSource)(staging, job.source);
+        }
         if (job.box && index.tiles) {
             const { minZoom, leafZoom } = index.pyramid;
             (0, tile_reuse_1.writeTiles)(staging, { bbox: job.box.bbox, minZoom, leafZoom, ...index.tiles });

package/lib/spatial/chart-index.js

@@ -78,8 +78,8 @@ function syncDirectory(dir) {
     }
 }
 /**
- * The files an index directory holds: these three, the build's reach and box
- * (`build-reuse.ts`, `build-box.ts`) beside them, and `hazards.json` of an
+ * The files an index directory holds: these three, the build's reach, box and
+ * source (`build-reuse.ts`, `build-box.ts`, `build-source.ts`) beside them, and `hazards.json` of an
  * index saved before `hazards.bin`, which a rebuild replaces.
  */
 const INDEX_FILES = new Set([
@@ -87,6 +87,7 @@ const INDEX_FILES = new Set([
     "hazards.json",
     "reach.json",
     "box.json",
+    "source.json",
     "tiles.json"
 ]);
 /** The first entry of directory `dir` that is not an index file. */
@@ -191,9 +192,18 @@ function commitChartIndex(dir, staging) {
         fs_1.default.rmSync(previous, { recursive: true, force: true });
     }
 }
-function saveChartIndex(dir, index) {
+/** Saves `index` in `dir`, `extra` adding files to the staged copy first. */
+function saveChartIndex(dir, index, extra) {
     dir = path_1.default.resolve(dir);
-    commitChartIndex(dir, stageChartIndex(dir, index));
+    const staging = stageChartIndex(dir, index);
+    try {
+        extra?.(staging);
+    }
+    catch (err) {
+        fs_1.default.rmSync(staging, { recursive: true, force: true });
+        throw err;
+    }
+    commitChartIndex(dir, staging);
 }
 function isCompleteIndex(dir) {
     return Object.values(FILES).every((f) => fs_1.default.existsSync(path_1.default.join(dir, f)));

package/lib/wfs-service.js

@@ -53,6 +53,8 @@ class WfsService {
     indexed;
     /** The box of the last index this service handed over in this run. */
     handed;
+    /** The box `onBox` is to be told of again, and when. */
+    again;
     /** The saved WFS cell was missing or unreadable at start: the box is downloaded again. */
     cellLost = false;
     busy = false;
@@ -263,6 +265,15 @@ class WfsService {
             this.ceilingKm = Math.max(min, Math.floor((radiusKm * 0.75) / box_sizing_1.STEP_KM) * box_sizing_1.STEP_KM);
         }
     }
+    announce(bbox, now) {
+        const ms = this.deps.onBox?.(bbox);
+        this.again = ms === undefined ? undefined : { bbox, at: now + ms };
+    }
+    announceAgain(now) {
+        if (this.again && now >= this.again.at) {
+            this.announce(this.again.bbox, now);
+        }
+    }
     /** Where the vessel will be when a refresh started now is handed over, kept inside the box. */
     centreAhead(pos, radiusKm, refreshMs) {
         const m = this.deps.motion();
@@ -275,6 +286,7 @@ class WfsService {
     async check() {
         const pos = this.deps.position();
         const now = this.deps.clock.now();
+        this.announceAgain(now);
         if (!pos || !this.due(pos, now) || this.refused(now)) {
             return;
         }
@@ -287,6 +299,7 @@ class WfsService {
         try {
             const centre = this.centreAhead(pos, radiusKm, run.estimateMs ?? this.refreshMs());
             const bbox = (0, wfs_1.boxAround)(centre, radiusKm);
+            this.announce(bbox, now);
             const config = this.deps.config;
             const { inBox, cellsDir } = this.deps;
             // With WFS depths alone in use an empty cells directory loses nothing.
@@ -309,6 +322,7 @@ class WfsService {
                     leafZoom: this.deps.leafZoom,
                     indexDir: this.deps.indexDir,
                     ...(this.deps.cacheDir === undefined ? {} : { cacheDir: this.deps.cacheDir }),
+                    source: this.deps.source,
                     ...(inBox ? {} : { changed: [this.cellDir] })
                 }
             }, controller.signal, (progress) => {

package/lib/wfs-wiring.js

@@ -3,12 +3,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.AREA_ASK_MAX_MS = exports.AREA_ASK_MIN_MS = void 0;
 exports.startBox = startBox;
+exports.areaRequests = areaRequests;
 exports.startWfs = startWfs;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const geo_1 = require("./foundation/geo");
 const index_loader_1 = require("./index-loader");
+const index_source_1 = require("./index-source");
+const shared_enc_1 = require("./shared-enc");
 const wfs_1 = require("./ingest/wfs");
 const livechart_service_1 = require("./livechart-service");
 const rebind_1 = require("./livechart/rebind");
@@ -79,6 +83,45 @@ function startBox(w) {
         ? startWfs(w, { radiusKm: boxRadiusKm }, "chart-box")
         : undefined;
 }
+/**
+ * What each new box tells the charts provider: asks for its cells with `chartsProviderArea`
+ * on, and only while the source is `*`, as they arrive in a chart set of their own.
+ */
+function areaRequests(config, app) {
+    return config.chartsProviderArea && config.chartsProviderEnc === shared_enc_1.ALL_COLLECTIONS
+        ? askForArea(app)
+        : undefined;
+}
+/** How soon, and how late, a box is asked about again: Charts Provider starting, or busy. */
+exports.AREA_ASK_MIN_MS = 60_000;
+exports.AREA_ASK_MAX_MS = 30 * 60_000;
+const ASK_STARTING_MS = 5 * 60_000;
+/**
+ * Asks the charts provider for each box's cells, logging its answer when it changes, and says
+ * when to ask again: when the provider says so, or is not running yet.
+ */
+function askForArea(app) {
+    let last;
+    return (bbox) => {
+        const answer = (0, shared_enc_1.requestSharedArea)(bbox);
+        const line = answer === undefined
+            ? "Charts Provider cannot be asked for the ENC around the vessel: it is not running, or too old"
+            : `Charts Provider, asked for the ENC around the vessel: ${answer.reason}`;
+        if (line !== last) {
+            last = line;
+            if (answer?.accepted === true) {
+                app.debug(line);
+            }
+            else {
+                app.error(line);
+            }
+        }
+        const ms = answer === undefined ? ASK_STARTING_MS : answer.retryAfterMs;
+        return typeof ms === "number" && Number.isFinite(ms)
+            ? Math.min(exports.AREA_ASK_MAX_MS, Math.max(exports.AREA_ASK_MIN_MS, ms))
+            : undefined;
+    };
+}
 function startWfs(w, config, dirName = "wfs") {
     const dir = path_1.default.join(w.app.getDataDirPath(), dirName);
     fs_1.default.mkdirSync(dir, { recursive: true });
@@ -88,6 +131,8 @@ function startWfs(w, config, dirName = "wfs") {
         indexDir: w.config.indexDir ?? path_1.default.join(w.app.getDataDirPath(), "index"),
         cacheDir: (0, index_loader_1.cellCacheDir)(w.app.getDataDirPath()),
         leafZoom: w.config.leafZoom,
+        source: (0, index_source_1.indexSource)(w.config),
+        onBox: areaRequests(w.config, w.app),
         cellsDir: w.config.cellsDir,
         inBox: w.config.boxRadiusKm > 0,
         index: () => w.state.load?.index,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-underkeel",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Under-keel clearance awareness for Signal K: look-ahead grounding risk, route checks and a living chart.",
   "main": "lib/index.js",
   "files": [