@rhizomatics/signalk-einklabel-plugin 1.3.0-beta12 → 1.3.0-beta14

package/dist/config.js

@@ -7,6 +7,9 @@ exports.readCurrentConfig = readCurrentConfig;
 exports.healStoredConfig = healStoredConfig;
 exports.resolveTemplatesDir = resolveTemplatesDir;
 exports.parseDevice = parseDevice;
+exports.listSvgFiles = listSvgFiles;
+exports.listTemplateVariants = listTemplateVariants;
+exports.listTemplateFamilies = listTemplateFamilies;
 exports.resolveTemplatePath = resolveTemplatePath;
 exports.configSchema = configSchema;
 exports.configUiSchema = configUiSchema;
@@ -362,9 +365,9 @@ function withEnum(schema, values, names) {
 }
 /** The plugin's documentation site - its sections' anchors are the README's own headings (see `site/scripts/sync-readme.mjs`). */
 const DOCS_URL = "https://signalk-einklabel.rhizomatics.org.uk/";
-/** A Markdown link to a docs section, for a field description rendered with `ui:enableMarkdownInDescription` (see `configUiSchema`). */
-function docsLink(anchor, text = "More in the docs") {
-    return `[${text}](${DOCS_URL}#${anchor})`;
+/** A Markdown link to a docs page (and optional section, e.g. `templates/#reframing`), for a field description rendered with `ui:enableMarkdownInDescription` (see `configUiSchema`). */
+function docsLink(page, text = "More in the docs") {
+    return `[${text}](${DOCS_URL}${page})`;
 }
 /**
  * An enum-like string field whose options show explanatory labels rather than their raw stored values
@@ -481,12 +484,12 @@ function configSchema(app, discovered = []) {
                             title: "Location/description (optional)",
                             description: 'Free-text notes about where this label is physically mounted/viewed from, e.g. "chart table, viewed from ~1m ' +
                                 'in poor light" - available to any template as `source=label,path=description`. ' +
-                                docsLink("label-details"),
+                                docsLink("templates/#label-details"),
                         },
                         templateName: withEnum({
                             type: "string",
                             title: "Template",
-                            description: `A bundled template, or one from your templates directory. ${docsLink("templating")}`,
+                            description: `A bundled template, or one from your templates directory. ${docsLink("examples/")}`,
                         }, templateNameOptions(resolveTemplatesDir(current.templatesDir))),
                         repaintTrigger: choiceField("Repaint trigger", [
                             ["subscription", "When a SignalK path changes"],
@@ -501,11 +504,11 @@ function configSchema(app, discovered = []) {
                                     ["crop", "Crop - place at the top-left, cutting off anything too big or leaving the rest blank"],
                                     ["scale", "Scale - stretch to fit exactly (may distort)"],
                                     ["fixed", "Fixed - fail the repaint rather than show an off-size image"],
-                                ], { description: docsLink("reframing"), default: "crop" }),
+                                ], { description: docsLink("templates/#reframing"), default: "crop" }),
                                 compress: {
                                     type: "boolean",
                                     title: 'Compress upload (Zhsunyco, Gicisky 7.5"/10.2")',
-                                    description: `Sends far less data over BLE, so repaints are quicker. Turn off if a label stops updating. ${docsLink("other-image-options")}`,
+                                    description: `Sends far less data over BLE, so repaints are quicker. Turn off if a label stops updating. ${docsLink("templates/#other-image-options")}`,
                                     default: true,
                                 },
                                 mirror: choiceField("Mirror", [
@@ -514,7 +517,7 @@ function configSchema(app, discovered = []) {
                                     ["vertical", "Flip top to bottom"],
                                     ["both", "Rotate 180° - for a label mounted upside down"],
                                 ], {
-                                    description: `Only needed if the image shows up mirrored or upside down on the label. ${docsLink("other-image-options")}`,
+                                    description: `Only needed if the image shows up mirrored or upside down on the label. ${docsLink("templates/#other-image-options")}`,
                                     default: "none",
                                 }),
                                 compressionFormat: choiceField("Wire format (Gicisky, experimental)", [
@@ -524,7 +527,7 @@ function configSchema(app, discovered = []) {
                                         'Chunked - send compressed like the 7.5"/10.2" panels, e.g. to speed up a 4.2" BWR (untested on current firmware)',
                                     ],
                                 ], {
-                                    description: `Chunked needs Compress upload on. Switch back to Auto if the label stops updating. ${docsLink("other-image-options")}`,
+                                    description: `Chunked needs Compress upload on. Switch back to Auto if the label stops updating. ${docsLink("templates/#other-image-options")}`,
                                     default: "auto",
                                 }),
                                 forceRepaint: {
@@ -616,7 +619,7 @@ function configUiSchema() {
                     "advanced",
                 ],
                 friendlyName: { "ui:placeholder": "e.g. Tide clock" },
-                description: { "ui:widget": "textarea", "ui:placeholder": "e.g. chart table, viewed from about 1m in poor light", ...MARKDOWN },
+                description: { "ui:widget": "textarea", "ui:placeholder": "e.g. at companionway", ...MARKDOWN },
                 templateName: MARKDOWN,
                 repaintTrigger: { "ui:widget": "radio" },
                 triggerPath: { "ui:placeholder": "e.g. environment.tide.state" },

package/dist/devices/bleBackend.js

@@ -168,6 +168,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 +205,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 +221,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,7 +231,7 @@ 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(() => { });
@@ -231,7 +242,7 @@ function bleApiBackend(bleApi, pluginId) {
                 // 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 +257,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,11 @@ export interface VendorDeviceConfig {
     compress?: boolean;
     /** Overrides the model's own wire format - see `CompressionFormat`. Defaults to `"auto"`. */
     compressionFormat?: CompressionFormat;
+    /**
+     * 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

@@ -50,8 +50,11 @@ 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));
             if (!info) {
@@ -79,27 +82,34 @@ 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;
+                log(`uploading ${payload.length} bytes${compress ? ` (compressed from ${pixelData.length})` : ""} in ` +
+                    `${Math.ceil(payload.length / UPLOAD_CHUNK_SIZE)} 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, (0, protocol_1.commandHeader)(compress ? protocol_1.COMMAND.refreshCompressed : protocol_1.COMMAND.refreshUncompressed, payload.length), true);
+                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);

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/repaintScheduler.js

@@ -25,6 +25,13 @@ const INTERVAL_POLL_MS = 60000;
 const SUBSCRIPTION_DEBOUNCE_MS = 2000;
 /** Pause between paint attempts - see `withRetries`' `delayMs`. */
 const PAINT_RETRY_DELAY_MS = 5000;
+/**
+ * Last-resort limit on one paint attempt, on top of its connect timeout - so an attempt stuck on
+ * anything, anywhere, still fails and gets retried instead of blocking this label (and, via
+ * `exclusiveBleManagerAccess`, every other label) forever. Longer than every inner limit it backs up,
+ * the longest being the 5-minute GATT session watchdog in `bleBackend.ts`.
+ */
+const PAINT_ATTEMPT_BACKSTOP_MS = 7 * 60000;
 const RESOURCES_API_PATH = "/signalk/v2/api/resources";
 /**
  * The most recent wall-clock instant at or before `now` that an `interval`-triggered device's own
@@ -358,7 +365,7 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
     const paintWithRetries = () => (0, bleDiscovery_1.withRetries)(attempts, async (attempt) => {
         app.debug(`${label}: attempting paint ${attempt}/${attempts}`);
         const startedAt = Date.now();
-        await driver.paint(bitmap, {
+        const paint = driver.paint(bitmap, {
             address,
             pid: target.pid,
             aesKey: device.advanced?.aesKey,
@@ -368,7 +375,9 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
             compress: device.advanced?.compress,
             compressionFormat: device.advanced?.compressionFormat,
             gattBackend,
+            log: (message) => app.debug(`${label}: ${message}`),
         });
+        await (0, bleDiscovery_1.withDeadline)(paint, connectTimeoutMs + PAINT_ATTEMPT_BACKSTOP_MS, `paint attempt ${attempt}/${attempts}`);
         paintDurationMs = Date.now() - startedAt;
     }, {
         delayMs: PAINT_RETRY_DELAY_MS,