@rhizomatics/signalk-einklabel-plugin 1.3.0-beta9 → 1.3.0

package/dist/devices/bleBackend.js

@@ -73,7 +73,16 @@ function withSessionWatchdog(conn, timeoutMs, forceClose) {
             clearTimeout(timer);
             if (killedError)
                 return; // already forced closed by the watchdog above
-            await conn.disconnect();
+            // The watchdog is off from here, so the disconnect needs its own limit: a disconnect that never
+            // finishes (e.g. over a Bluetooth link that's already gone) would otherwise hang the caller - and
+            // hide whatever error it was cleaning up after - with the connection and any claim still held.
+            try {
+                await (0, bleDiscovery_1.withDeadline)(conn.disconnect(), CLEANUP_TIMEOUT_MS, "disconnecting");
+            }
+            catch (err) {
+                console.error(`${pluginVersion_1.PLUGIN_NAME}: ${err.message} - forcing the connection closed`);
+                await forceClose().catch(() => { });
+            }
         },
     };
 }
@@ -168,6 +177,17 @@ async function ensureDeviceVisible(bleApi, pluginId, address, timeoutMs) {
         throw new Error(`device ${address} isn't visible to the SignalK BLE Manager yet (out of range, asleep, or never seen) after waiting ${timeoutMs}ms`);
     }
 }
+/**
+ * Upper bound on each BLE Manager release/disconnect call this plugin waits on. Neither has a timeout
+ * of its own, and a release has to disconnect the device, which can wait on a Bluetooth link that's
+ * already gone - left unbounded, one stuck release wedges every later paint behind it (see
+ * `exclusiveBleManagerAccess`).
+ */
+const CLEANUP_TIMEOUT_MS = 10000;
+/** Waits for a cleanup call for at most `CLEANUP_TIMEOUT_MS`, ignoring its outcome - cleanup is best-effort. */
+async function boundedCleanup(...calls) {
+    await (0, bleDiscovery_1.withDeadline)(Promise.allSettled(calls), CLEANUP_TIMEOUT_MS, "BLE Manager cleanup").catch((err) => console.error(`${pluginVersion_1.PLUGIN_NAME}: ${err.message} - carrying on`));
+}
 /** Upper bound on how long a timed-out `bleApi.connectGATT()` is given to settle server-side before a retry - see `bleApiBackend`. */
 const CONNECT_SETTLE_GRACE_MS = 30000;
 let bleManagerQueue = Promise.resolve();
@@ -194,7 +214,7 @@ function bleApiBackend(bleApi, pluginId) {
             // registered under our own pluginId, which would otherwise block this connect with
             // "already claimed" until the server restarts - see signalk-bluetti-plugin's BleManagerDevice
             // for the same defensive call. A no-op if we don't currently hold the claim.
-            await bleApi.releaseGATTDevice(address, pluginId).catch(() => { });
+            await boundedCleanup(bleApi.releaseGATTDevice(address, pluginId));
             await ensureDeviceVisible(bleApi, pluginId, address, DEVICE_DISCOVERY_TIMEOUT_MS);
             const connecting = bleApi.connectGATT(address, pluginId);
             let timedOut = false;
@@ -210,7 +230,7 @@ function bleApiBackend(bleApi, pluginId) {
                 // disconnect again. The release is awaited (only the late disconnect is left in the
                 // background) so a caller retrying straight away - `withRetries` - can't race it with a new
                 // `connectGATT()` and get rejected with "has a GATT claim in progress" for its trouble.
-                await bleApi.releaseGATTDevice(address, pluginId).catch(() => { });
+                await boundedCleanup(bleApi.releaseGATTDevice(address, pluginId));
                 // ...except a claim still *connecting* isn't in the server's claim table yet, only its pending
                 // set, which `releaseGATTDevice` doesn't touch - so while the server's own connect is still in
                 // flight, a retry's `connectGATT()` is rejected outright with "has a GATT claim in progress".
@@ -220,18 +240,35 @@ function bleApiBackend(bleApi, pluginId) {
                     (0, bleDiscovery_1.sleep)(Math.min(timeoutMs, CONNECT_SETTLE_GRACE_MS)).then(() => undefined),
                 ]);
                 if (late) {
-                    await Promise.allSettled([bleApi.releaseGATTDevice(address, pluginId), late.disconnect()]);
+                    await boundedCleanup(bleApi.releaseGATTDevice(address, pluginId), late.disconnect());
                 }
                 else {
                     void connecting.then((c) => c.disconnect()).catch(() => { });
                 }
                 throw new Error(`connecting to device timed out after ${timeoutMs}ms`);
             }
-            return withSessionWatchdog(conn, GATT_SESSION_WATCHDOG_MS, async () => {
+            // Disconnecting alone doesn't always drop the server's claim - it only clears that itself once it
+            // sees the link close, which a half-dead link may never report - so every disconnect releases the
+            // claim explicitly too, leaving the device free for the next paint (or another plugin).
+            const released = {
+                read: conn.read.bind(conn),
+                write: conn.write.bind(conn),
+                startNotifications: conn.startNotifications.bind(conn),
+                stopNotifications: conn.stopNotifications.bind(conn),
+                discoverServices: conn.discoverServices.bind(conn),
+                onDisconnect: conn.onDisconnect.bind(conn),
+                get connected() {
+                    return conn.connected;
+                },
+                async disconnect() {
+                    await Promise.allSettled([conn.disconnect(), bleApi.releaseGATTDevice(address, pluginId)]);
+                },
+            };
+            return withSessionWatchdog(released, GATT_SESSION_WATCHDOG_MS, async () => {
                 // Belt-and-suspenders, matching the timeout-cleanup above: `releaseGATTDevice` is the
                 // authoritative claim release, `disconnect()` a secondary teardown of this specific handle -
                 // do both regardless of which (if either) itself hangs or rejects.
-                await Promise.allSettled([bleApi.releaseGATTDevice(address, pluginId), conn.disconnect()]);
+                await boundedCleanup(bleApi.releaseGATTDevice(address, pluginId), conn.disconnect());
             });
         },
         async waitForManufacturerData(address, manufacturerId, timeoutMs) {
@@ -246,7 +283,7 @@ function bleApiBackend(bleApi, pluginId) {
             // this wait forever, since nothing else in this path ever calls `connectGatt` (and so never gets a
             // chance to release the stale claim) unless a fresh advertisement shows up first. A no-op if we
             // don't currently hold the claim.
-            await bleApi.releaseGATTDevice(address, pluginId).catch(() => { });
+            await boundedCleanup(bleApi.releaseGATTDevice(address, pluginId));
             return new Promise((resolve) => {
                 const timer = setTimeout(() => {
                     unsubscribe();

package/dist/devices/bleDiscovery.d.ts

@@ -40,6 +40,11 @@ export declare function forEachAdvertisedDevice(adapter: Adapter, fn: (advertise
  * last one that's eventually thrown - an early attempt's error is often the real cause, with later
  * ones just fallout from it.
  */
+/**
+ * Rejects with `${what} timed out after ${ms}ms` if `promise` hasn't settled by then. The underlying
+ * work can't be cancelled - this only lets the caller stop waiting for it.
+ */
+export declare function withDeadline<T>(promise: Promise<T>, ms: number, what: string): Promise<T>;
 export declare function withRetries<T>(attempts: number, fn: (attempt: number) => Promise<T>, { delayMs, onError }?: {
     delayMs?: number;
     onError?: (err: unknown, attempt: number) => void;

package/dist/devices/bleDiscovery.js

@@ -4,6 +4,7 @@ exports.sleep = sleep;
 exports.createBluetooth = createBluetooth;
 exports.getManufacturerId = getManufacturerId;
 exports.forEachAdvertisedDevice = forEachAdvertisedDevice;
+exports.withDeadline = withDeadline;
 exports.withRetries = withRetries;
 exports.withDiscovery = withDiscovery;
 exports.connectWithTimeout = connectWithTimeout;
@@ -74,6 +75,23 @@ async function forEachAdvertisedDevice(adapter, fn) {
  * last one that's eventually thrown - an early attempt's error is often the real cause, with later
  * ones just fallout from it.
  */
+/**
+ * Rejects with `${what} timed out after ${ms}ms` if `promise` hasn't settled by then. The underlying
+ * work can't be cancelled - this only lets the caller stop waiting for it.
+ */
+async function withDeadline(promise, ms, what) {
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${what} timed out after ${ms}ms`)), ms);
+    });
+    promise.catch(() => { }); // observed here too, so losing the race never surfaces as an unhandled rejection
+    try {
+        return await Promise.race([promise, deadline]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 async function withRetries(attempts, fn, { delayMs = 0, onError } = {}) {
     const total = Math.max(1, attempts);
     let lastErr;

package/dist/devices/gicisky/index.js

@@ -73,7 +73,10 @@ class GiciskyDriver {
         const layout = (0, layout_1.withCompressionFormat)((pid !== undefined && layout_1.GICISKY_PID_LAYOUT[pid]) || (0, layout_1.defaultLayoutFor)(metadata.colours), config.compressionFormat ?? "auto", metadata.colours);
         const framed = (0, mirror_1.mirrorBitmap)((0, reframe_1.reframeBitmap)(bitmap, metadata.width, metadata.height, config.reframe ?? "crop"), config.mirror ?? "none");
         const payload = (0, encode_1.encodeBitmap)(framed, metadata, layout, config.compress ?? true);
+        const log = config.log ?? (() => { });
+        log("connecting");
         const conn = await backend.connectGatt(config.address, config.connectTimeoutMs ?? DEFAULT_PAINT_CONNECT_TIMEOUT_MS);
+        log("connected");
         try {
             const { cmdServiceUuid, cmdUuid, imgServiceUuid, imgUuid } = await findCommandAndImageCharacteristics(conn);
             const ack = new AckChannel();
@@ -87,6 +90,7 @@ class GiciskyDriver {
                 if (!started?.ok) {
                     throw new Error(`gicisky device rejected start-image-transfer request: ${startImageAck.toString("hex")}`);
                 }
+                log(`uploading ${payload.length} bytes in ${Math.ceil(payload.length / chunkSize)} parts`);
                 let part = started.nextPart;
                 let lastPart = -1;
                 let repeats = 0;
@@ -115,6 +119,7 @@ class GiciskyDriver {
                     }
                     part = decoded.nextPart;
                 }
+                log("upload complete");
             }
             finally {
                 await conn.stopNotifications(cmdServiceUuid, cmdUuid).catch(() => { });

package/dist/devices/types.d.ts

@@ -83,6 +83,17 @@ export interface VendorDeviceConfig {
     compress?: boolean;
     /** Overrides the model's own wire format - see `CompressionFormat`. Defaults to `"auto"`. */
     compressionFormat?: CompressionFormat;
+    /**
+     * Send the image without waiting for each write to be acknowledged (zhsunyco; ignored otherwise).
+     * Works around SignalK's BLE Manager (2.33 and earlier) sending every acknowledged write as a
+     * "reliable" write, which zhsunyco labels reject with ATT error 0x0e. Defaults to `false`.
+     */
+    writeWithoutResponse?: boolean;
+    /**
+     * Receives one line per paint step (connecting, connected, uploading, ...), so a paint that stalls
+     * shows in the log where it stopped. Omitted means no step logging.
+     */
+    log?: (message: string) => void;
     /**
      * How `paint()` reaches the device's BLE hardware - omitted (always true for the CLI, which has no
      * `ServerAPI`/`app.bleApi` to source one from) means direct BlueZ access via a fresh

package/dist/devices/zhsunyco/index.js

@@ -13,6 +13,8 @@ const protocol_1 = require("./protocol");
 /** node-ble has no MTU API; this matches the reference driver's mtu(247)-9 default. */
 const UPLOAD_CHUNK_SIZE = 238;
 const CHUNK_WRITE_DELAY_MS = 20;
+/** With nothing acknowledging each write, pace them further apart so the label isn't sent data faster than it can take it. */
+const UNACKNOWLEDGED_CHUNK_WRITE_DELAY_MS = 50;
 const AUTH_SETTLE_DELAY_MS = 500;
 const STATUS_WAIT_TIMEOUT_MS = 60000;
 /** Bounds `readDeviceDetails`' whole connect+read attempt during a scan - see its doc comment. */
@@ -50,10 +52,13 @@ class ZhsunycoDriver {
     }
     async paint(bitmap, config) {
         const aesKey = (0, protocol_1.resolveAesKey)(config.aesKey);
+        const log = config.log ?? (() => { });
         const backend = config.gattBackend ?? (0, bleBackend_1.nodeBleBackend)();
+        log("connecting");
         const conn = await backend.connectGatt(config.address, config.connectTimeoutMs ?? DEFAULT_PAINT_CONNECT_TIMEOUT_MS);
+        log("connected");
         try {
-            const info = (0, protocol_1.decodeAdvertisedInfo)(await conn.read(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.config));
+            const info = (0, protocol_1.decodeAdvertisedInfo)(await readConfig(conn, log));
             if (!info) {
                 throw new Error("zhsunyco device did not return valid config data");
             }
@@ -79,27 +84,35 @@ class ZhsunycoDriver {
                 const challenge = await conn.read(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.authenticate);
                 await conn.write(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.authenticate, (0, protocol_1.authResponse)(challenge, aesKey), false);
                 await (0, bleDiscovery_1.sleep)(AUTH_SETTLE_DELAY_MS);
+                log("authenticated");
                 const framed = (0, mirror_1.mirrorBitmap)((0, reframe_1.reframeBitmap)(bitmap, metadata.width, metadata.height - metadata.voffset, config.reframe ?? "crop"), config.mirror ?? "none");
                 const pixelData = (0, encode_1.encodeBitmap)(framed, metadata);
                 const compress = config.compress ?? true;
                 // Upload offsets and the refresh length both count bytes of whatever's actually sent - the
                 // compressed payload when compressing, not the raw buffer it inflates back to.
                 const payload = compress ? (0, compression_1.compressWolinkBlocks)(pixelData) : pixelData;
+                const acknowledged = !config.writeWithoutResponse;
+                log(`uploading ${payload.length} bytes${compress ? ` (compressed from ${pixelData.length})` : ""} in ` +
+                    `${Math.ceil(payload.length / UPLOAD_CHUNK_SIZE)} ${acknowledged ? "acknowledged" : "unacknowledged"} writes`);
                 for (let offset = 0; offset < payload.length; offset += UPLOAD_CHUNK_SIZE) {
                     const chunk = payload.subarray(offset, offset + UPLOAD_CHUNK_SIZE);
-                    await conn.write(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.data, Buffer.concat([(0, protocol_1.commandHeader)(protocol_1.COMMAND.uploadBlock, offset), chunk]), true);
-                    await (0, bleDiscovery_1.sleep)(CHUNK_WRITE_DELAY_MS);
+                    await conn.write(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.data, Buffer.concat([(0, protocol_1.commandHeader)(protocol_1.COMMAND.uploadBlock, offset), chunk]), acknowledged);
+                    await (0, bleDiscovery_1.sleep)(acknowledged ? CHUNK_WRITE_DELAY_MS : UNACKNOWLEDGED_CHUNK_WRITE_DELAY_MS);
                 }
-                await conn.write(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.data, (0, protocol_1.commandHeader)(compress ? protocol_1.COMMAND.refreshCompressed : protocol_1.COMMAND.refreshUncompressed, payload.length), true);
+                await conn.write(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.data, (0, protocol_1.commandHeader)(compress ? protocol_1.COMMAND.refreshCompressed : protocol_1.COMMAND.refreshUncompressed, payload.length), acknowledged);
+                log("refresh sent, waiting for the label to finish");
                 // `Promise.race` can't cancel its loser, so once `statusReceived` settles (the common case)
                 // this timer would otherwise sit alive for the rest of its 60s regardless - see the identical
                 // reasoning on `readDeviceDetails`'s own race, below.
                 let statusTimer;
                 const statusTimeout = new Promise((resolve) => {
-                    statusTimer = setTimeout(resolve, STATUS_WAIT_TIMEOUT_MS);
+                    statusTimer = setTimeout(() => resolve("timeout"), STATUS_WAIT_TIMEOUT_MS);
                 });
                 try {
-                    await Promise.race([statusReceived, statusTimeout]);
+                    const outcome = await Promise.race([statusReceived, statusTimeout]);
+                    log(outcome === "timeout"
+                        ? `no reply from the label within ${STATUS_WAIT_TIMEOUT_MS}ms - assuming it painted`
+                        : "label reported the paint complete");
                 }
                 finally {
                     clearTimeout(statusTimer);
@@ -115,6 +128,22 @@ class ZhsunycoDriver {
     }
 }
 exports.ZhsunycoDriver = ZhsunycoDriver;
+/**
+ * The first read of a paint. If the label's service isn't there at all (seen as node-ble's "Service not
+ * available" behind the BLE Manager), logs which services the connection does report - the difference
+ * between BlueZ not having discovered the label's services yet and it seeing a different set entirely.
+ */
+async function readConfig(conn, log) {
+    try {
+        return await conn.read(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.config);
+    }
+    catch (err) {
+        const services = await conn.discoverServices().catch((discoverErr) => `could not list them: ${discoverErr.message}`);
+        const listed = Array.isArray(services) ? services.map((service) => service.uuid).join(", ") || "none" : services;
+        log(`reading the label's config failed (${err.message}) - services visible on this connection: ${listed}`);
+        throw err;
+    }
+}
 /**
  * Battery level needs a connection regardless, so reuse it to also fill in the PID/hwVersion
  * when the advertisement didn't carry decodable manufacturer data - a scan matched purely by name

package/dist/docs/templateReference.d.ts

@@ -0,0 +1,18 @@
+/** The reference block for one bundled template name, e.g. `tides` (a family) or `tide.svg`. */
+export declare function templateReference(templateName: string, templatesDir?: string): string;
+/** Every bundled template name a user can pick - plain `.svg` files and family directories, not dot-prefixed internals. */
+export declare function bundledTemplateNames(templatesDir?: string): string[];
+/** A one-row-per-template summary, linking each to the example page whose reference block covers it. */
+export declare function templatesSummary(pagesByTemplate: Map<string, string>, templatesDir?: string): string;
+/**
+ * Regenerates every marked block under `examplesDir`, returning each file's current and regenerated
+ * content. `templates-summary` blocks link to whichever page holds a template's `template-reference`
+ * block, so all pages are scanned for those first.
+ */
+export declare function regenerateExampleDocs(examplesDir: string, templatesDir?: string): {
+    path: string;
+    current: string;
+    updated: string;
+    stale: boolean;
+}[];
+export declare const EXAMPLES_DOCS_DIR: string;

package/dist/docs/templateReference.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXAMPLES_DOCS_DIR = void 0;
+exports.templateReference = templateReference;
+exports.bundledTemplateNames = bundledTemplateNames;
+exports.templatesSummary = templatesSummary;
+exports.regenerateExampleDocs = regenerateExampleDocs;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const binding_1 = require("../render/binding");
+const config_1 = require("../config");
+const zhsunyco_1 = require("../devices/zhsunyco");
+const gicisky_1 = require("../devices/gicisky");
+/**
+ * Generates the "Template reference" blocks in the docs' example pages from the bundled templates
+ * themselves - sizes, aspect ratios, colours, which supported labels each size fits, and the data
+ * fields each one reads - so that reference can't drift from the templates it describes. Blocks sit
+ * between `<!-- BEGIN GENERATED: <kind> [<template>] -->` and `<!-- END GENERATED -->` markers in
+ * hand-written pages; everything outside them is left alone. Run `npm run docs:templates` to update,
+ * and `templateReference.test.ts` fails when a block is stale.
+ */
+const TEMPLATE_SOURCE_URL = "https://github.com/rhizomatics/signalk-einklabel-plugin/blob/main/templates";
+const MARKER = /<!-- BEGIN GENERATED: ([\w-]+)(?: ([^\s>]+))? -->[\s\S]*?<!-- END GENERATED -->/g;
+const COLOUR_LETTER = { black: "B", white: "W", red: "R", yellow: "Y" };
+function supportedLabels() {
+    return [new zhsunyco_1.ZhsunycoDriver(), new gicisky_1.GiciskyDriver()].flatMap((driver) => driver.supportedDevices());
+}
+/** Every file a bundled template name covers - one for a plain `.svg`, one per variant for a family directory. */
+function templateFiles(templatesDir, templateName) {
+    const path = (0, path_1.join)(templatesDir, templateName);
+    if (!(0, fs_1.existsSync)(path)) {
+        throw new Error(`template "${templateName}" not found in ${templatesDir}`);
+    }
+    const read = (relativePath, colours) => {
+        const source = (0, fs_1.readFileSync)((0, path_1.join)(templatesDir, relativePath), "utf-8");
+        return { path: relativePath, ...(0, binding_1.readTemplateDimensions)(source), colours, bindings: (0, binding_1.findBindings)(source) };
+    };
+    if ((0, fs_1.statSync)(path).isDirectory()) {
+        return (0, config_1.listTemplateVariants)(path)
+            .sort((a, b) => b.width - a.width || b.height - a.height)
+            .map((variant) => read(`${templateName}/${variant.fileName}`, variant.colours));
+    }
+    return [read(templateName)];
+}
+function variantName(file) {
+    return file.path
+        .split("/")
+        .pop()
+        .replace(/\.svg$/, "");
+}
+function aspectRatio(width, height) {
+    return `${(width / height).toFixed(2)} : 1`;
+}
+function matchingLabels(file, labels) {
+    const matches = labels
+        .filter((label) => label.width === file.width && label.height - label.voffset === file.height)
+        .map((label) => {
+        const colours = label.colours.map((colour) => COLOUR_LETTER[colour]).join("");
+        // Some models' own label already names their colours (e.g. Gicisky's `2.9" BWR`).
+        const name = label.label.includes(colours) ? label.label : `${label.label} ${colours}`;
+        return `${label.manufacturer ?? ""} ${name}`.trim();
+    });
+    return matches.length > 0 ? [...new Set(matches)].join(", ") : "none exactly - see [Reframing](../templates.md#reframing)";
+}
+function describeSource(binding) {
+    switch (binding.source) {
+        case "signalk":
+            return binding.context === "self" ? "Signal K path" : `Signal K path (${binding.context})`;
+        case "resources":
+            return `\`${binding.resource}\` resource${binding.provider ? ` (provider \`${binding.provider}\`)` : ""}`;
+        case "einklabel":
+            return "Plugin";
+        case "label":
+            return "Label details";
+    }
+}
+function describeOptions(binding) {
+    return [
+        binding.assets && `image from \`${binding.assets}\``,
+        binding.format && `format \`${binding.format}\``,
+        binding.category && `category \`${binding.category}\``,
+        binding.round !== undefined && `round ${binding.round}`,
+        binding.default !== undefined && `default \`${binding.default}\``,
+    ].filter((option) => Boolean(option));
+}
+/** A table row per distinct field - array indexes collapsed, so `extremes[0].time` and `extremes[2].time` are one row. */
+function fieldsTable(files) {
+    const rows = new Map();
+    for (const file of files) {
+        for (const binding of file.bindings) {
+            const source = describeSource(binding);
+            const path = binding.path.replace(/\[\d+\]/g, "[n]");
+            const key = `${source}\u0000${path}`;
+            const row = rows.get(key) ?? { source, path, options: new Set(), usedIn: new Set() };
+            describeOptions(binding).forEach((option) => row.options.add(option));
+            row.usedIn.add(variantName(file));
+            rows.set(key, row);
+        }
+    }
+    const showUsedIn = files.length > 1;
+    const header = showUsedIn ? "| Source | Path | Options | Used in |\n|---|---|---|---|" : "| Source | Path | Options |\n|---|---|---|";
+    const sorted = [...rows.values()].sort((a, b) => a.source.localeCompare(b.source) || a.path.localeCompare(b.path));
+    const lines = sorted.map((row) => {
+        const usedIn = row.usedIn.size === files.length ? "all" : [...row.usedIn].join(", ");
+        const cells = [row.source, `\`${row.path}\``, [...row.options].join(", ") || "-", ...(showUsedIn ? [usedIn] : [])];
+        return `| ${cells.join(" | ")} |`;
+    });
+    return [header, ...lines].join("\n");
+}
+/** The reference block for one bundled template name, e.g. `tides` (a family) or `tide.svg`. */
+function templateReference(templateName, templatesDir = config_1.BUNDLED_TEMPLATES_DIR) {
+    const files = templateFiles(templatesDir, templateName);
+    const labels = supportedLabels();
+    const sizes = files.map((file) => {
+        const size = file.width && file.height ? `${file.width} × ${file.height}` : "-";
+        const ratio = file.width && file.height ? aspectRatio(file.width, file.height) : "-";
+        const colours = file.colours?.join(", ") ?? "-";
+        return `| [\`${file.path}\`](${TEMPLATE_SOURCE_URL}/${file.path}) | ${size} | ${ratio} | ${colours} | ${matchingLabels(file, labels)} |`;
+    });
+    return [
+        `**Template:** \`${templateName}\``,
+        "",
+        "| File | Size (px) | Aspect ratio | Colours | Fits these labels exactly |",
+        "|---|---|---|---|---|",
+        ...sizes,
+        "",
+        "**Data used**",
+        "",
+        fieldsTable(files),
+    ].join("\n");
+}
+/** Every bundled template name a user can pick - plain `.svg` files and family directories, not dot-prefixed internals. */
+function bundledTemplateNames(templatesDir = config_1.BUNDLED_TEMPLATES_DIR) {
+    return [...(0, config_1.listTemplateFamilies)(templatesDir), ...(0, config_1.listSvgFiles)(templatesDir)].sort();
+}
+/** A one-row-per-template summary, linking each to the example page whose reference block covers it. */
+function templatesSummary(pagesByTemplate, templatesDir = config_1.BUNDLED_TEMPLATES_DIR) {
+    const rows = bundledTemplateNames(templatesDir).map((name) => {
+        const files = templateFiles(templatesDir, name);
+        const sizes = files.map((file) => (file.width && file.height ? `${file.width}×${file.height}` : "?")).join(", ");
+        // Only what has to come from outside the plugin - its own and the label's details are always there.
+        const external = files
+            .flatMap((file) => file.bindings)
+            .filter((binding) => binding.source === "signalk" || binding.source === "resources");
+        const resources = external.filter((binding) => binding.source === "resources").map(describeSource);
+        const paths = external.filter((binding) => binding.source === "signalk").map((binding) => `\`${binding.path}\``);
+        const sources = [...new Set(resources), ...(paths.length > 0 ? [`Signal K ${[...new Set(paths)].sort().join(", ")}`] : [])];
+        const page = pagesByTemplate.get(name);
+        return `| ${page ? `[\`${name}\`](${page})` : `\`${name}\``} | ${sizes} | ${sources.join(", ") || "-"} |`;
+    });
+    return ["| Template | Sizes | Data needed |", "|---|---|---|", ...rows].join("\n");
+}
+function markdownFiles(dir) {
+    return (0, fs_1.readdirSync)(dir, { withFileTypes: true }).flatMap((entry) => {
+        const path = (0, path_1.join)(dir, entry.name);
+        if (entry.isDirectory())
+            return markdownFiles(path);
+        return entry.name.endsWith(".md") ? [path] : [];
+    });
+}
+/**
+ * Regenerates every marked block under `examplesDir`, returning each file's current and regenerated
+ * content. `templates-summary` blocks link to whichever page holds a template's `template-reference`
+ * block, so all pages are scanned for those first.
+ */
+function regenerateExampleDocs(examplesDir, templatesDir = config_1.BUNDLED_TEMPLATES_DIR) {
+    const pages = markdownFiles(examplesDir).map((path) => ({ path, current: (0, fs_1.readFileSync)(path, "utf-8") }));
+    const pagesByTemplate = new Map();
+    for (const page of pages) {
+        for (const match of page.current.matchAll(MARKER)) {
+            if (match[1] === "template-reference" && match[2]) {
+                pagesByTemplate.set(match[2], page.path.slice(examplesDir.length + 1));
+            }
+        }
+    }
+    return pages.map((page) => {
+        const updated = page.current.replace(MARKER, (_block, kind, arg) => {
+            const body = kind === "template-reference" && arg
+                ? templateReference(arg, templatesDir)
+                : kind === "templates-summary"
+                    ? templatesSummary(pagesByTemplate, templatesDir)
+                    : undefined;
+            if (body === undefined)
+                throw new Error(`${page.path}: unknown generated block "${kind}${arg ? ` ${arg}` : ""}"`);
+            return `<!-- BEGIN GENERATED: ${kind}${arg ? ` ${arg}` : ""} -->\n<!-- Generated from the bundled templates by \`npm run docs:templates\` - do not edit by hand. -->\n\n${body}\n\n<!-- END GENERATED -->`;
+        });
+        return { ...page, updated, stale: ignoringTableAlignment(updated) !== ignoringTableAlignment(page.current) };
+    });
+}
+/**
+ * The formatter (`oxfmt`, run by `npm run docs:templates` after this) pads Markdown table columns to
+ * line up, which this generator doesn't - so compare with that padding stripped, or a freshly
+ * formatted page would always look stale.
+ */
+function ignoringTableAlignment(markdown) {
+    return markdown
+        .split("\n")
+        .map((line) => (line.startsWith("|") ? line.replace(/\s*\|\s*/g, "|").replace(/-{3,}/g, "---") : line))
+        .join("\n");
+}
+exports.EXAMPLES_DOCS_DIR = (0, path_1.join)(__dirname, "..", "..", "docs", "examples");
+if (require.main === module) {
+    const changed = regenerateExampleDocs(exports.EXAMPLES_DOCS_DIR).filter((page) => page.stale);
+    for (const page of changed)
+        (0, fs_1.writeFileSync)(page.path, page.updated);
+    console.log(changed.length > 0 ? `updated ${changed.map((page) => page.path).join(", ")}` : "template docs already up to date");
+}

package/dist/plugin.js

@@ -56,10 +56,10 @@ function createPlugin(app) {
         start(config) {
             const pluginConfig = {
                 ...(0, config_1.defaultConfig)(),
-                ...config,
+                ...(0, config_1.migrateConfig)(config).config,
             };
             app.debug(`starting with ${pluginConfig.devices.length} configured device(s)`);
-            (0, config_1.healNestedConfig)(app);
+            (0, config_1.healStoredConfig)(app);
             stopped = false;
             const useBleApi = pluginConfig.useBleApi && bleApiAvailable;
             if (pluginConfig.useBleApi && !bleApiAvailable) {

package/dist/repaintScheduler.d.ts

@@ -13,4 +13,12 @@ export interface RepaintScheduler {
  * rather than waiting up to `intervalHours` for the next one).
  */
 export declare function mostRecentScheduledSlot(now: Date, intervalHours: number, intervalMinute: number): Date;
+/**
+ * Wraps `run` so only one call per key is in progress at a time. A call made while that key is busy
+ * is folded into a single follow-up (with the latest arguments), run once the current one finishes -
+ * but only if it succeeded (`run` resolved `true`). For repaints: newer data still gets shown promptly,
+ * but a label that's failing isn't hammered with a fresh round of retries straight after the last
+ * one gave up - the next scheduled trigger tries again instead.
+ */
+export declare function oneAtATimePerKey<T>(keyOf: (arg: T) => string, run: (arg: T) => Promise<boolean>, onBusy?: (arg: T) => void): (arg: T) => Promise<void>;
 export declare function startRepaintScheduler(app: ServerAPI, config: PluginConfig): RepaintScheduler;