@rhizomatics/signalk-einklabel-plugin 1.3.1 → 1.3.3

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+# 1.3.3
+
+## 🔐 SSL
+
+- New "Allow self-signed certificates" setting, off by default. A SignalK server with SSL enabled redirects its http port to https, usually with a self-signed certificate, which the plugin previously rejected - so templates using the SignalK REST API (`category=` or a resource pinned with `provider=`) failed to render and the label showed the fallback warning. Turn the setting on for a server like this.
+
+## 🐛 Bug fixes
+
+- A render failure that paints the fallback warning on a label is now logged as an error, with its cause, rather than only in debug logging
+- When the SignalK API URL can't be reached, the logged error now gives the underlying reason for each address tried, e.g. a self-signed certificate, rather than only suggesting the port or anonymous access; a certificate failure points to the new setting
+
+## BLE Manager
+
+- The "Use the SignalK BLE Manager API" setting is now on by default. Servers without BLE Manager (before v2.31.0) fall back to direct BlueZ access, and existing configs that already saved the setting keep their value
+- Recent SignalK versions identify Zhsunyco labels by manufacturer, shown as "WOESL" in the BLE Manager device list
+
+# 1.3.2
+
+## 🐛 Bug fixes
+
+- On a SignalK server shutdown or admin UI restart (server v2.35.0+), the plugin now waits at most 5 seconds for a repaint in progress instead of 30, so it stops inside the server's shutdown deadline and the server can close the label's Bluetooth connection cleanly before exiting
+
+## 📚 Documentation
+
+- [Bluetooth](https://signalk-einklabel.rhizomatics.org.uk/bluetooth/) docs updated for the BLE Manager fixes in SignalK v2.34.0 and v2.35.0. v2.34.0 is now the practical minimum for BLE Manager, with v2.35.0 recommended. The BLE Manager setting stays off by default, since Zhsunyco labels not yet proven with it.
+
 # 1.3.1
 
 ## 🐛 Bug fixes

package/README.md

@@ -5,7 +5,7 @@
 [![SignalK Plugin CI](https://github.com/rhizomatics/signalk-einklabel-plugin/actions/workflows/signalk-ci.yml/badge.svg)](https://github.com/rhizomatics/signalk-einklabel-plugin/actions/workflows/signalk-ci.yml)
 [![code style: oxfmt](https://img.shields.io/badge/code_style-oxfmt-blue.svg)](https://github.com)
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/rhizomatics/signalk-einklabel-plugin/blob/main/LICENSE)
-[![boat tech directory](https://boat-tech-directory.rhizomatics.org.uk/images/badge.svg)](https://boat-tech-directory.rhizomatics.org.uk)
+[![boat tech directory](https://boat-tech-directory.rhizomatics.org.uk/images/badge.svg)](https://boat-tech-directory.rhizomatics.org.uk) [![managed by hq](https://raw.githubusercontent.com/rhizomatics/hq/main/assets/badge-managed-by-hq.svg)](https://github.com/rhizomatics/hq)
 
 A SignalK plugin to display data from SignalK paths, Resource APIs and plugins on Electronic Shelf Labels (ESL) over a Bluetooth Low Energy (BLE) connection using simple SVG templates, or optionally created from a crafted prompt by GenAI if the companion [`@rhizomatics/signalk-einklabel-genai-plugin`](https://github.com/rhizomatics/signalk-einklabel-genai-plugin) is installed. Supports ESLs from two of the major Chinese manufacturers, and requires **no firmware or hardware modifications**, switch on and go.
 

package/dist/config.d.ts

@@ -107,8 +107,9 @@ export interface PluginConfig {
     /**
      * Route BLE access through the SignalK server's BLE Manager API (`app.bleApi`, server >= 2.32.0)
      * instead of connecting to BlueZ directly, so this plugin shares the adapter with other BLE plugins
-     * instead of contending for it - see `bleBackend.ts`. Off by default, and only ever offered in the
-     * config schema when the running server actually has `app.bleApi` (see `configSchema` below).
+     * instead of contending for it - see `bleBackend.ts`. On by default; a server without `app.bleApi`
+     * falls back to direct BlueZ access (see `plugin.ts`), and the option is only ever offered in the
+     * config schema when the running server actually has it (see `configSchema` below).
      */
     useBleApi: boolean;
     /** How long to wait for a device to accept a BLE connection before giving up on a repaint attempt, in seconds. */
@@ -140,6 +141,11 @@ export interface PluginConfig {
      * anonymous read access - the plugin has no login flow.
      */
     signalkApiUrl?: string;
+    /**
+     * Accept a self-signed TLS certificate on the plugin's calls to `signalkApiUrl` - see
+     * `setAllowSelfSignedCertificates` in `./httpJson.ts`. Off by default, so certificates are verified.
+     */
+    allowSelfSignedCertificates: boolean;
     devices: DeviceConfig[];
 }
 /**

package/dist/config.js

@@ -99,10 +99,11 @@ function defaultConfig() {
         templatesDir: "",
         scanOnStart: false,
         scanDurationSeconds: 20,
-        useBleApi: false,
+        useBleApi: true,
         paintConnectTimeoutSeconds: 30,
         paintRetries: 3,
         settleSeconds: 120,
+        allowSelfSignedCertificates: false,
         devices: [],
     };
 }
@@ -115,6 +116,7 @@ const PLUGIN_CONFIG_KEYS = [
     "paintRetries",
     "settleSeconds",
     "signalkApiUrl",
+    "allowSelfSignedCertificates",
     "devices",
 ];
 /**
@@ -464,6 +466,13 @@ function configSchema(app, discovered = []) {
                 examples: resolveApiUrl_1.SIGNALK_API_URL_OPTIONS,
                 pattern: "^(\\s*|\\s*https?://\\S+\\s*)$",
             },
+            allowSelfSignedCertificates: {
+                type: "boolean",
+                title: "Allow self-signed certificates",
+                description: "Accept a self-signed certificate when calling the SignalK API above. Needed when the server has SSL enabled with its own " +
+                    "generated certificate - its http port then redirects to https, which otherwise fails certificate checks. Leave off unless needed.",
+                default: defaults.allowSelfSignedCertificates,
+            },
             devices: {
                 type: "array",
                 title: "Devices",

package/dist/devices/bleBackend.js

@@ -213,7 +213,9 @@ function bleApiBackend(bleApi, pluginId) {
             // A previous ungraceful stop (crash, plugin reload mid-paint) can leave a stale GATT claim
             // 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.
+            // for the same defensive call. A no-op if we don't currently hold the claim. Servers from 2.34.0
+            // release a stopped plugin's claims themselves (signalk-server#3093), so this only matters on
+            // older ones - kept for them.
             await boundedCleanup(bleApi.releaseGATTDevice(address, pluginId));
             await ensureDeviceVisible(bleApi, pluginId, address, DEVICE_DISCOVERY_TIMEOUT_MS);
             const connecting = bleApi.connectGATT(address, pluginId);
@@ -232,9 +234,12 @@ function bleApiBackend(bleApi, pluginId) {
                 // `connectGATT()` and get rejected with "has a GATT claim in progress" for its trouble.
                 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".
-                // Give that connect a bounded chance to settle first, so the retry gets a clean slate.
+                // set. Before 2.34.0 `releaseGATTDevice` didn't touch that at all; since then
+                // (signalk-server#3092) it marks the pending claim released, so the server closes the
+                // connection itself when it arrives - but the device stays reserved until the server's own
+                // connect returns (bounded at 60s since signalk-server#3082), and until then a retry's
+                // `connectGATT()` is rejected outright with "has a GATT claim in progress". Either way, give
+                // that connect a bounded chance to settle first, so the retry gets a clean slate.
                 const late = await Promise.race([
                     connecting.catch(() => undefined),
                     (0, bleDiscovery_1.sleep)(Math.min(timeoutMs, CONNECT_SETTLE_GRACE_MS)).then(() => undefined),
@@ -282,7 +287,7 @@ function bleApiBackend(bleApi, pluginId) {
             // ever reaches `connectGatt` below) stops advertising while claimed - which would otherwise wedge
             // 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.
+            // don't currently hold the claim; only needed before server 2.34.0, as in `connectGatt`.
             await boundedCleanup(bleApi.releaseGATTDevice(address, pluginId));
             return new Promise((resolve) => {
                 const timer = setTimeout(() => {

package/dist/httpJson.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Whether `fetchJson` accepts a self-signed (or otherwise unverifiable) TLS certificate. Off by default,
+ * so certificates are verified exactly as plain `fetch()` does. Set from the plugin's
+ * `allowSelfSignedCertificates` config on each start - a SignalK server with SSL enabled redirects its http
+ * port to https, usually with a self-signed certificate, which `fetch()` otherwise always rejects. Process-wide
+ * rather than per call, since every `fetchJson` call in the plugin goes to that one server's own API.
+ */
+export declare function setAllowSelfSignedCertificates(allowed: boolean): void;
 /**
  * Fetches and parses a JSON endpoint, with an error message that's actually actionable: which URL,
  * what HTTP status, and the response/underlying error detail - see `describeCause` for why plain

package/dist/httpJson.js

@@ -1,6 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.setAllowSelfSignedCertificates = setAllowSelfSignedCertificates;
 exports.fetchJson = fetchJson;
+const node_http_1 = require("node:http");
+const node_https_1 = require("node:https");
+/** How many redirects the self-signed path follows before giving up - `fetch()`'s own default is 20. */
+const MAX_REDIRECTS = 5;
+/** Per-request deadline on the self-signed path, which has none of `fetch()`'s built-in timeouts. */
+const REQUEST_TIMEOUT_MS = 30000;
+let allowSelfSigned = false;
+/**
+ * Whether `fetchJson` accepts a self-signed (or otherwise unverifiable) TLS certificate. Off by default,
+ * so certificates are verified exactly as plain `fetch()` does. Set from the plugin's
+ * `allowSelfSignedCertificates` config on each start - a SignalK server with SSL enabled redirects its http
+ * port to https, usually with a self-signed certificate, which `fetch()` otherwise always rejects. Process-wide
+ * rather than per call, since every `fetchJson` call in the plugin goes to that one server's own API.
+ */
+function setAllowSelfSignedCertificates(allowed) {
+    allowSelfSigned = allowed;
+}
 /**
  * Describes a network-level fetch failure's `error.cause` - Node's `fetch()` only ever throws a
  * generic `TypeError: fetch failed`, with the actually useful detail (e.g. ECONNREFUSED) nested in
@@ -23,6 +41,8 @@ function describeCause(cause) {
  * `fetch()` failures need unwrapping to be useful at all.
  */
 async function fetchJson(url) {
+    if (allowSelfSigned)
+        return fetchJsonAllowingSelfSigned(url);
     let response;
     try {
         response = await fetch(url);
@@ -30,7 +50,7 @@ async function fetchJson(url) {
     catch (err) {
         const cause = err.cause;
         const detail = cause !== undefined ? describeCause(cause) : err.message;
-        throw new Error(`fetch failed: ${url} - ${detail}`);
+        throw new Error(`fetch failed: ${url} - ${detail}${certificateHint(detail)}`);
     }
     if (!response.ok) {
         const body = await response.text().catch(() => "");
@@ -38,3 +58,60 @@ async function fetchJson(url) {
     }
     return response.json();
 }
+/** Points a certificate failure at the setting that fixes it, since the raw TLS error doesn't. */
+function certificateHint(detail) {
+    return /certificate|CERT_/i.test(detail)
+        ? ' - if this server uses a self-signed certificate, enable "Allow self-signed certificates" in the plugin config'
+        : "";
+}
+/**
+ * `fetchJson` over `node:http`/`node:https` with certificate verification off - built-in `fetch()` has no
+ * per-request way to skip it without the separate `undici` package. Follows redirects itself (the http to
+ * https redirect being the usual reason to need this at all), with the same error messages as `fetchJson`.
+ */
+async function fetchJsonAllowingSelfSigned(url) {
+    let current = url;
+    for (let redirects = 0;; redirects++) {
+        let response;
+        try {
+            response = await sendGet(current);
+        }
+        catch (err) {
+            throw new Error(`fetch failed: ${url} - ${describeCause(err)}`);
+        }
+        const status = response.statusCode ?? 0;
+        const location = response.headers.location;
+        if (status >= 300 && status < 400 && location) {
+            response.resume();
+            if (redirects >= MAX_REDIRECTS)
+                throw new Error(`fetch failed: ${url} - more than ${MAX_REDIRECTS} redirects`);
+            current = new URL(location, current).toString();
+            continue;
+        }
+        const body = await readBody(response).catch(() => "");
+        if (status < 200 || status >= 300) {
+            throw new Error(`fetch failed: ${url} (${status} ${response.statusMessage ?? ""})${body ? ` - ${body}` : ""}`);
+        }
+        return JSON.parse(body);
+    }
+}
+function sendGet(url) {
+    return new Promise((resolve, reject) => {
+        const target = new URL(url);
+        const headers = { accept: "application/json" };
+        const request = target.protocol === "https:"
+            ? (0, node_https_1.request)(target, { headers, rejectUnauthorized: false }, resolve)
+            : (0, node_http_1.request)(target, { headers }, resolve);
+        request.setTimeout(REQUEST_TIMEOUT_MS, () => request.destroy(new Error(`no response after ${REQUEST_TIMEOUT_MS / 1000}s`)));
+        request.on("error", reject);
+        request.end();
+    });
+}
+function readBody(response) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        response.on("data", (chunk) => chunks.push(chunk));
+        response.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+        response.on("error", reject);
+    });
+}

package/dist/index.d.ts

@@ -15,11 +15,12 @@ import type { Bitmap as BitmapType, TemplateContext as TemplateContextType } fro
  * `start()` (or at module load time). There's no scanning of installed packages -
  * registration is always an explicit call by the extension's own code.
  *
- * Declare this package as a regular `dependency` in the extension package (**not** a
- * `peerDependency` - the SignalK team's own guidance is that npm's peer-dependency resolution
- * interacts poorly with the server's plugin install layout), and declare the SignalK-level
- * relationship via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }` in the
- * extension's own package.json instead, so the App Store can install/report the dependency.
+ * Declare the relationship via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }`
+ * in the extension's own package.json, plus a `devDependency` for types/tests - **not** a regular
+ * `dependency` or `peerDependency`. The App Store installs required plugins flat in
+ * `~/.signalk/node_modules`, so the extension's `require` resolves the one copy the running plugin
+ * uses; a regular `dependency` can leave a nested copy with its own empty registry, and a
+ * `peerDependency` interacts poorly with the server's plugin install layout (SignalK's own guidance).
  */
 declare function plugin(app: ServerAPI): Plugin;
 declare namespace plugin {
@@ -30,7 +31,7 @@ declare namespace plugin {
      * Public extension point for a package offering an alternative to hand-authored SVG templates - e.g.
      * `@rhizomatics/signalk-einklabel-genai-plugin` generating content from an LLM prompt - see
      * `TemplateProvider`'s own doc comment (`./render/templateProviders.ts`) for the full contract. Same
-     * regular-`dependency`-plus-`signalk.requires` convention as `registerVendorDriver` above.
+     * `signalk.requires`-plus-`devDependency` convention as `registerVendorDriver` above.
      */
     const registerTemplateProvider: typeof registerTemplateProviderImpl;
     const getTemplateProvider: typeof findTemplateProviderImpl;

package/dist/index.js

@@ -12,11 +12,12 @@ const binding_1 = require("./render/binding");
  * `start()` (or at module load time). There's no scanning of installed packages -
  * registration is always an explicit call by the extension's own code.
  *
- * Declare this package as a regular `dependency` in the extension package (**not** a
- * `peerDependency` - the SignalK team's own guidance is that npm's peer-dependency resolution
- * interacts poorly with the server's plugin install layout), and declare the SignalK-level
- * relationship via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }` in the
- * extension's own package.json instead, so the App Store can install/report the dependency.
+ * Declare the relationship via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }`
+ * in the extension's own package.json, plus a `devDependency` for types/tests - **not** a regular
+ * `dependency` or `peerDependency`. The App Store installs required plugins flat in
+ * `~/.signalk/node_modules`, so the extension's `require` resolves the one copy the running plugin
+ * uses; a regular `dependency` can leave a nested copy with its own empty registry, and a
+ * `peerDependency` interacts poorly with the server's plugin install layout (SignalK's own guidance).
  */
 function plugin(app) {
     return (0, plugin_1.createPlugin)(app);
@@ -29,7 +30,7 @@ function plugin(app) {
      * Public extension point for a package offering an alternative to hand-authored SVG templates - e.g.
      * `@rhizomatics/signalk-einklabel-genai-plugin` generating content from an LLM prompt - see
      * `TemplateProvider`'s own doc comment (`./render/templateProviders.ts`) for the full contract. Same
-     * regular-`dependency`-plus-`signalk.requires` convention as `registerVendorDriver` above.
+     * `signalk.requires`-plus-`devDependency` convention as `registerVendorDriver` above.
      */
     plugin.registerTemplateProvider = templateProviders_1.registerTemplateProvider;
     plugin.getTemplateProvider = templateProviders_1.findTemplateProvider;

package/dist/plugin.js

@@ -10,6 +10,7 @@ const bleDiscovery_1 = require("./devices/bleDiscovery");
 const discoveredDevicesStore_1 = require("./devices/discoveredDevicesStore");
 const repaintScheduler_1 = require("./repaintScheduler");
 const pluginVersion_1 = require("./pluginVersion");
+const httpJson_1 = require("./httpJson");
 /** Mirrors signalk-bluetti-plugin's convention: scan briefly, report finds via plugin status for the user to copy-paste. */
 async function runStartupScan(app, durationSeconds, useBleApi) {
     const alreadyRunning = (0, discoveryCoordinator_1.scanInProgressSince)();
@@ -64,6 +65,7 @@ function createPlugin(app) {
             };
             app.debug(`starting with ${pluginConfig.devices.length} configured device(s)`);
             (0, config_1.healStoredConfig)(app);
+            (0, httpJson_1.setAllowSelfSignedCertificates)(pluginConfig.allowSelfSignedCertificates);
             const thisGeneration = ++generation;
             const isCurrent = () => thisGeneration === generation;
             const previousStop = stopping;
@@ -104,14 +106,18 @@ function createPlugin(app) {
         },
         // Returns a Promise, as the server asks of a stop() with async work: it resolves once a paint
         // already under way has finished (bounded by `STOP_DRAIN_TIMEOUT_MS`), so a config save mid-paint
-        // or a server shutdown doesn't leave that BLE session running behind the next start().
-        stop() {
+        // or a server shutdown doesn't leave that BLE session running behind the next start(). On a
+        // server shutdown (`reason`, passed by signalk-server 2.35.0+) the wait is cut to
+        // `SHUTDOWN_DRAIN_TIMEOUT_MS` to fit the server's own shutdown deadline - see its doc comment.
+        // `reason` is typed loosely so this still compiles against server-api versions before 2.35.0.
+        stop(options) {
             generation++;
             const stoppingScheduler = scheduler;
             scheduler = undefined;
             stopDiscoveryListener?.();
             stopDiscoveryListener = undefined;
-            stopping = (stoppingScheduler?.stop() ?? Promise.resolve()).then(() => app.debug("stopped"));
+            const drainTimeoutMs = options?.reason === "shutdown" ? repaintScheduler_1.SHUTDOWN_DRAIN_TIMEOUT_MS : repaintScheduler_1.STOP_DRAIN_TIMEOUT_MS;
+            stopping = (stoppingScheduler?.stop(drainTimeoutMs) ?? Promise.resolve()).then(() => app.debug(options?.reason ? `stopped (${options.reason})` : "stopped"));
             return stopping;
         },
     };

package/dist/render/templateProviders.d.ts

@@ -21,9 +21,9 @@ export interface TemplateRenderRequest {
  * Public extension point for a package that wants to offer an alternative way to produce a device's
  * content, alongside hand-authored SVG templates - e.g. `@rhizomatics/signalk-einklabel-genai-plugin`
  * generating content from an LLM prompt. Mirrors `VendorDriver`/`registerDriver`
- * (`../devices/registry.ts`): an extension declares this package as a regular `dependency` (**not** a
- * `peerDependency` - see `registerVendorDriver`'s own doc comment in `../index.ts` for why) plus
- * `"signalk": { "requires": [...] }` in its own package.json, calls `esl.registerTemplateProvider(...)`
+ * (`../devices/registry.ts`): an extension declares this package via `"signalk": { "requires": [...] }`
+ * plus a `devDependency` (**not** a regular `dependency` or `peerDependency` - see
+ * `registerVendorDriver`'s own doc comment in `../index.ts` for why), calls `esl.registerTemplateProvider(...)`
  * from its own SignalK plugin's `start()`, and its entries show up in the same "Template" dropdown as
  * ordinary `.svg` files, distinguished only by `suffix`.
  */

package/dist/repaintScheduler.d.ts

@@ -7,12 +7,21 @@ import { PluginConfig } from "./config";
  * stuck; such a paint is still ended by its own connect timeout and `PAINT_ATTEMPT_BACKSTOP_MS`.
  */
 export declare const STOP_DRAIN_TIMEOUT_MS = 30000;
+/**
+ * The drain limit for a server shutdown (signalk-server 2.35.0+ passes `stop()` a `reason`), in place
+ * of `STOP_DRAIN_TIMEOUT_MS`. The server gives all plugins' `stop()`s 6s together before it moves on,
+ * and exits at 8s - so a 30s drain would be cut off anyway, mid-transfer. Resolving inside that
+ * window instead lets the server's own release of this plugin's BLE Manager claims (signalk-server
+ * #3093, run once `stop()` returns) close the connection before the process exits. Since 2.35.0 the
+ * admin UI's Restart button goes through the same shutdown path; a config save doesn't.
+ */
+export declare const SHUTDOWN_DRAIN_TIMEOUT_MS = 5000;
 export interface RepaintScheduler {
     /**
      * Stops every trigger, lets no new paint or retry start, and resolves once any paint already in
-     * progress finishes - or after `STOP_DRAIN_TIMEOUT_MS`, whichever comes first.
+     * progress finishes - or after `drainTimeoutMs` (default `STOP_DRAIN_TIMEOUT_MS`), whichever comes first.
      */
-    stop(): Promise<void>;
+    stop(drainTimeoutMs?: number): Promise<void>;
 }
 /**
  * The most recent wall-clock instant at or before `now` that an `interval`-triggered device's own

package/dist/repaintScheduler.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.STOP_DRAIN_TIMEOUT_MS = void 0;
+exports.SHUTDOWN_DRAIN_TIMEOUT_MS = exports.STOP_DRAIN_TIMEOUT_MS = void 0;
 exports.mostRecentScheduledSlot = mostRecentScheduledSlot;
 exports.oneAtATimePerKey = oneAtATimePerKey;
 exports.startRepaintScheduler = startRepaintScheduler;
@@ -41,6 +41,15 @@ const PAINT_ATTEMPT_BACKSTOP_MS = 7 * 60000;
  * stuck; such a paint is still ended by its own connect timeout and `PAINT_ATTEMPT_BACKSTOP_MS`.
  */
 exports.STOP_DRAIN_TIMEOUT_MS = 30000;
+/**
+ * The drain limit for a server shutdown (signalk-server 2.35.0+ passes `stop()` a `reason`), in place
+ * of `STOP_DRAIN_TIMEOUT_MS`. The server gives all plugins' `stop()`s 6s together before it moves on,
+ * and exits at 8s - so a 30s drain would be cut off anyway, mid-transfer. Resolving inside that
+ * window instead lets the server's own release of this plugin's BLE Manager claims (signalk-server
+ * #3093, run once `stop()` returns) close the connection before the process exits. Since 2.35.0 the
+ * admin UI's Restart button goes through the same shutdown path; a config save doesn't.
+ */
+exports.SHUTDOWN_DRAIN_TIMEOUT_MS = 5000;
 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
@@ -169,7 +178,7 @@ async function assembleRawContext(app, apiUrl, bindings) {
             // REST API's own `?provider=` query param doesn't have this bug (it queries only that provider),
             // so a pinned binding goes over HTTP instead of the in-process API to actually get what it asked for.
             if (!apiUrl) {
-                throw new Error(`binding pins resource "${binding.resource}" to provider "${binding.provider}" but no SignalK API base URL is configured`);
+                throw new Error(`binding pins resource "${binding.resource}" to provider "${binding.provider}" but the SignalK API base URL could not be resolved (see the earlier error)`);
             }
             resources[key] = await (0, httpJson_1.fetchJson)(`${apiUrl}${RESOURCES_API_PATH}/${binding.resource}?provider=${encodeURIComponent(binding.provider)}`);
         }
@@ -184,7 +193,7 @@ async function assembleRawContext(app, apiUrl, bindings) {
     }
     const categoryNames = new Set(bindings.filter((binding) => binding.category).map((binding) => binding.category));
     if (categoryNames.size > 0 && !apiUrl) {
-        throw new Error(`binding references categor${categoryNames.size > 1 ? "ies" : "y"} "${[...categoryNames].join(", ")}" but no SignalK API base URL is configured`);
+        throw new Error(`binding references categor${categoryNames.size > 1 ? "ies" : "y"} "${[...categoryNames].join(", ")}" but the SignalK API base URL could not be resolved (see the earlier error)`);
     }
     const categories = apiUrl ? await (0, unitCategories_1.fetchCategoryDisplayUnits)(apiUrl, categoryNames) : {};
     return { signalk, resources, pathMeta, categories };
@@ -276,6 +285,7 @@ async function considerRepaint(app, config, device, target, state, getApiUrl, is
     let dataHash = "";
     let paintDurationMs = 0;
     let repaintReason = "render failed";
+    let renderError = "";
     // Built up front, outside the try below, so the fallback warning render gets it too - it's all local
     // facts (no network or template involved), so there's nothing here that can fail a render.
     const rawPosition = (0, unwrapSignalkTree_1.unwrapSignalkTree)(app.getSelfPath("navigation.position"));
@@ -295,7 +305,9 @@ async function considerRepaint(app, config, device, target, state, getApiUrl, is
     });
     try {
         const apiUrl = await getApiUrl().catch((err) => {
-            app.debug(`${label}: ${err.message}`);
+            // An error, not debug - templates that need the API (pinned resources, `category=`) fail to render
+            // without it, and this is the only place the underlying reason is reported.
+            app.error(`${label}: ${err.message}`);
             return undefined;
         });
         let bindings = [];
@@ -366,7 +378,10 @@ async function considerRepaint(app, config, device, target, state, getApiUrl, is
                         : "data changed";
     }
     catch (err) {
-        app.debug(`${label}: render failed (${err.message}) - showing fallback warning`);
+        // An error, not debug - the label shows only a generic warning, so the server log is the one place
+        // the actual cause is visible, and it must be there without the plugin's debug logging enabled.
+        renderError = err.message;
+        app.error(`${label}: render failed (${renderError}) - showing fallback warning`);
         const fallbackPath = (0, config_1.resolveTemplatePath)(templatesDir, config_1.RENDER_FALLBACK_TEMPLATE_NAME, {
             width: metadata.width,
             height: metadata.height,
@@ -417,7 +432,9 @@ async function considerRepaint(app, config, device, target, state, getApiUrl, is
         state[stateKey] = { templateHash, dataHash, repaintedAt: Date.now() };
         saveState(app, state);
     }
-    app.debug(succeeded ? `${label}: repainted (${repaintReason}, paint took ${paintDurationMs}ms)` : `${label}: repainted fallback warning`);
+    app.debug(succeeded
+        ? `${label}: repainted (${repaintReason}, paint took ${paintDurationMs}ms)`
+        : `${label}: repainted fallback warning (render failed: ${renderError})`);
 }
 function oneAtATimePerKey(keyOf, run, onBusy = () => { }) {
     const inProgress = new Map();
@@ -559,7 +576,7 @@ function startRepaintScheduler(app, config) {
     }, settleMs);
     unsubscribes.push(() => clearTimeout(startupCheckTimer));
     return {
-        async stop() {
+        async stop(drainTimeoutMs = exports.STOP_DRAIN_TIMEOUT_MS) {
             stopping = true;
             for (const unsubscribe of unsubscribes)
                 unsubscribe();
@@ -568,12 +585,12 @@ function startRepaintScheduler(app, config) {
             const drained = await Promise.race([
                 repaint.idle().then(() => true),
                 new Promise((resolve) => {
-                    timer = setTimeout(() => resolve(false), exports.STOP_DRAIN_TIMEOUT_MS);
+                    timer = setTimeout(() => resolve(false), drainTimeoutMs);
                 }),
             ]);
             clearTimeout(timer);
             if (!drained) {
-                app.debug(`a repaint was still running ${exports.STOP_DRAIN_TIMEOUT_MS / 1000}s after stop - not waiting any longer`);
+                app.debug(`a repaint was still running ${drainTimeoutMs / 1000}s after stop - not waiting any longer`);
             }
         },
     };

package/dist/resolveApiUrl.js

@@ -21,13 +21,14 @@ const httpJson_1 = require("./httpJson");
 exports.SIGNALK_API_URL_OPTIONS = ["http://localhost:3000", "http://localhost", "https://localhost"];
 /** Cheap, always-required (for `category=` resolution) and read-only, so safe to use as a connectivity+access probe. */
 const PROBE_PATH = "/signalk/v1/unitpreferences/categories";
+/** Resolves to `undefined` when `url` answers the probe, or to the failure's message when it doesn't. */
 async function probe(url) {
     try {
         await (0, httpJson_1.fetchJson)(`${url}${PROBE_PATH}`);
-        return true;
+        return undefined;
     }
-    catch {
-        return false;
+    catch (err) {
+        return err.message;
     }
 }
 /**
@@ -41,13 +42,19 @@ async function resolveSignalkApiUrl(configuredUrl) {
     // otherwise double up with the leading slash of every API path appended to it.
     configuredUrl = configuredUrl?.trim().replace(/\/+$/, "") || undefined;
     const candidates = configuredUrl ? [configuredUrl] : exports.SIGNALK_API_URL_OPTIONS;
+    // Kept so the error says *why* each candidate failed - e.g. an http URL redirected to https with a
+    // self-signed certificate, which otherwise looks identical to a wrong port.
+    const failures = [];
     for (const url of candidates) {
-        if (await probe(url))
+        const failure = await probe(url);
+        if (failure === undefined)
             return url;
+        failures.push(failure);
     }
-    throw new Error(configuredUrl
+    throw new Error((configuredUrl
         ? `configured SignalK API base URL "${configuredUrl}" did not respond to ${PROBE_PATH} - check the port, and that anonymous read access is enabled`
-        : `could not reach this server's API on any of ${exports.SIGNALK_API_URL_OPTIONS.join(", ")} - it may be on a different port, or anonymous read access may not be enabled`);
+        : `could not reach this server's API on any of ${exports.SIGNALK_API_URL_OPTIONS.join(", ")} - it may be on a different port, or anonymous read access may not be enabled`) +
+        ` (${failures.join("; ")})`);
 }
 /**
  * Memoizes a successful resolution only - a failure (server not ready yet, anonymous access

package/docs/bluetooth.md

@@ -6,11 +6,11 @@ Bluetooth can be used in of three ways by a plugin:
 
 - Direct access to dongle (usually `hci0` device). Not recommended
 - Access via `bluez` and `dbus` services. Better but not ideal
-- Using the BLE Manager added to SignalK in 2026. Recommended with caveats.
-  - "Use the SignalK BLE Manager API" setting is enabled, the adapter and its lifecycle are managed by the SignalK server, under its own Bluetooth admin settings, once for every BLE-consuming plugin.
+- Using the BLE Manager added to SignalK in 2026. Recommended, and the default for this plugin.
+  - With the "Use the SignalK BLE Manager API" setting enabled (the default), the adapter and its lifecycle are managed by the SignalK server, under its own Bluetooth admin settings, once for every BLE-consuming plugin.
   - Under the hood, this uses `bluez` and `dbus` however manages them so that plugins are controlled in how they can impact each other
   - It also has a very useful GUI for seeing all scanned devices, and all GATT claims (GATT being the protocol for directly connecting to BLE devices).
-  - This is still new and settling down, so not yet the default for this plugin
+  - On a server without BLE Manager (before v2.31.0) the plugin falls back to direct `bluez` access
 
 The advice here is general to Bluetooth on Linux, whichever way its being used.
 
@@ -32,15 +32,19 @@ SignalK BLE Manager also supports BLE Gateways, which could be an MQTT topic or
 
 ## BLE Manager Readiness
 
-v2.31.0 is the minumum version of SignalK possible for BLE Manager. Several fixes went in to v2.33.0 so this is the practical minimum version for using the plugin.
+v2.31.0 is the minimum version of SignalK possible for BLE Manager. v2.34.0 is the practical minimum for using it with this plugin, and v2.35.0 is recommended.
 
-Gicisky labels have been painted successfully using BLE Manager, however Zhsunyco have some different interactions that are waiting other fixes.
+Gicisky labels have been painted successfully using BLE Manager. Zhsunyco labels needed three server fixes, all released in v2.34.0:
 
 - [PR#3082](https://github.com/SignalK/signalk-server/pull/3082) - hung connections locking up device
 - [PR#3088](https://github.com/SignalK/signalk-server/pull/3088) - Support plain GATT write requests
 - [PR#3089](https://github.com/SignalK/signalk-server/pull/3089) - Pause scanning while GATT operation in progress
 
-There's a workaround for **PR#3088** available in the _Advanced Options_, and **PR#3082** isn't a problem if operations don't fail, however **PR#3089** is a blocker for using Zhsunyco labels - they'll fail with a `0x0e` error code.
+BLE Manager is now the default. If a label misbehaves through it, turn off "Use the SignalK BLE Manager API" to go back to direct BlueZ access.
+
+v2.34.0 also releases a plugin's Bluetooth connections when the plugin stops ([PR#3093](https://github.com/SignalK/signalk-server/pull/3093)). v2.35.0 stops plugins cleanly when the server shuts down or is restarted from the admin UI ([PR#3194](https://github.com/SignalK/signalk-server/pull/3194)). On a shutdown this plugin only waits 5 seconds for a label part way through a repaint, rather than the usual 30, so that it finishes inside the server's shutdown deadline.
+
+With BLE Manager, scanning pauses while any plugin is connecting to a Bluetooth device, for up to 60 seconds. If another plugin's device keeps failing to connect, a label may not be seen in time for a repaint, which then fails and is retried.
 
 ## Weak Signal
 
@@ -64,9 +68,12 @@ Sometime Bluetooth adapters, and/or the Linux services that use them, can get in
 
 ## Zhsunyco Labels and the BLE Manager
 
-With the "Use the SignalK BLE Manager API" setting on, Zhsunyco labels can connect and authenticate, then fail as soon as the image upload starts, with `Operation failed with ATT error: 0x0e` in the log. SignalK's BLE Manager (2.33 and earlier) sends every write that waits for an acknowledgement as a Bluetooth "reliable" write, which these labels don't support.
+> [!NOTE]
+> ZhSunyCo labels may show as manufacturer label`WOESL`, or as a `WL` prefixed device name, on the BLE Manager.
+
+With the "Use the SignalK BLE Manager API" setting on, Zhsunyco labels can connect and authenticate, then fail as soon as the image upload starts, with `Operation failed with ATT error: 0x0e` in the log. SignalK's BLE Manager (2.33 and earlier) sends every write that waits for an acknowledgement as a Bluetooth "reliable" write, which these labels don't support. This was fixed in SignalK v2.34.0, so upgrading is the first thing to try.
 
-Either:
+On 2.33 and earlier, either:
 
 - turn on _Send image without waiting for each write (Zhsunyco)_ in the label's _Advanced settings_ - the image is sent with a small gap between writes instead, and the label still confirms once the whole image has arrived; or
 - switch the BLE Manager setting off, if no other plugins need to share Bluetooth with this one.

package/docs/design/spec.md

@@ -9,11 +9,11 @@ A SignalK plugin, in TypeScript, that renders selected SignalK data to BLE eInk
 - Pluggable vendor support
   - Built-in drivers for Zhsunyco and Gicisky BLE labels (`src/devices/zhsunyco/`, `src/devices/gicisky/`), registered by `plugin.ts` at startup
   - Each driver has a metadata table of the models it supports, keyed by PID, with `hwVersion` used where a vendor reuses a PID across panel sizes. Each entry gives the label, width, height, vertical offset and colours. `esl-cli vendors` lists them
-  - Additional vendors are added by a separate npm package implementing `VendorDriver` and calling the exported `registerVendorDriver` explicitly - no scanning of installed packages. In the SignalK runtime the extension calls it from its own plugin `start()`; the CLI loads it via `esl-cli --require <module>`. Extension packages declare this package as a regular `dependency`, not a `peerDependency` (SignalK's guidance is that npm's peer-dependency resolution interacts poorly with the server's plugin install layout), and declare the SignalK-level relationship via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }` - see [Extending](../extending.md)
+  - Additional vendors are added by a separate npm package implementing `VendorDriver` and calling the exported `registerVendorDriver` explicitly - no scanning of installed packages. In the SignalK runtime the extension calls it from its own plugin `start()`; the CLI loads it via `esl-cli --require <module>`. Extension packages declare the relationship only via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }` (plus a `devDependency` for types/tests), not as a regular `dependency` or `peerDependency` - the App Store installs it flat in `~/.signalk/node_modules`, so `require` resolves the single running copy - see [Extending](../extending.md)
   - The config schema's device and template options are read live from the registries when the schema is built, so a newly-registered extension shows up the next time the config panel is opened
 - Bluetooth access, either direct or shared
   - Direct BlueZ access over D-Bus via `node-ble` (the default). The plugin waits, with backoff, for a local adapter before scanning or painting, to cover the boot-time race where the plugin starts before BlueZ is ready
-  - The SignalK BLE Manager API (`app.bleApi`, server >= 2.32.0), opted into with `useBleApi`, so the plugin shares the adapter with other BLE plugins. Only offered in the config schema when the running server has it. Paints through BLE Manager are serialised so only one label holds a GATT connection at a time
+  - The SignalK BLE Manager API (`app.bleApi`, server >= 2.32.0), used by default (`useBleApi`, falling back to direct BlueZ access on older servers), so the plugin shares the adapter with other BLE plugins. Only offered in the config schema when the running server has it. Paints through BLE Manager are serialised so only one label holds a GATT connection at a time
 - Device discovery
   - One shared discovery path across all registered drivers (`discoveryCoordinator.ts`): each advertisement is read once and offered to each driver's `matchesAdvertisement`; only a matching driver's `identifyDevice` runs, which may open a GATT connection when the advertisement alone doesn't identify the model
   - A scan already in progress is joined rather than a second one started, since neither backend can run two discovery sessions at once
@@ -42,6 +42,7 @@ A SignalK plugin, in TypeScript, that renders selected SignalK data to BLE eInk
   - An `<image>` element with a `<desc>` binding and an `assets=<name>` key picks one `.svg` from an asset directory (`.assets/<name>/`, user templates directory first, then bundled) by the resolved value, e.g. the bundled `lunar_phases` icons for `environment.moon.phaseName`. The element is dropped when the value is missing or has no matching file
 - SignalK API base URL
   - `signalkApiUrl` is optional. Left unset, `resolveSignalkApiUrl` (`src/resolveApiUrl.ts`) probes `http://localhost:3000`, `http://localhost` and `https://localhost`, in that order, at the first repaint and caches whichever responds. Always the loopback address, since the plugin runs on the same host as the server. Setting it explicitly skips probing but is still verified
+  - `allowSelfSignedCertificates` (off by default) makes `fetchJson` (`src/httpJson.ts`) accept a self-signed certificate on these API calls, using `node:https` with verification off and following redirects itself. A server with SSL enabled redirects its http port to https, usually with its own generated certificate, which plain `fetch()` rejects. With it off, a certificate failure's error names the setting. A failure to resolve the URL is logged as an error, with each candidate's underlying cause
   - It errors clearly if nothing responds (wrong port) or every probe is rejected (anonymous read access not enabled) - these endpoints need anonymous read access, since the plugin has no login flow. A failed resolution is retried on the next repaint rather than cached
   - Path metadata is best-effort (no server just means raw values); a `category=` or `provider=` binding without a reachable server fails the render
 - Repainting

package/docs/extending.md

@@ -20,7 +20,7 @@ Additional vendors and devices can be added by a separate npm package that imple
 
 - `import esl from '@rhizomatics/signalk-einklabel-plugin'; esl.registerVendorDriver(myDriver)`
 - In the SignalK runtime, call this from the extension's own plugin `start()`. In the CLI, load the extension with `esl-cli --require <module> <command>`.
-- Declare this package as a regular npm `dependency` in the extension package - **not** a `peerDependency`, per SignalK's own guidance that npm's peer-dependency resolution interacts poorly with the server's plugin install layout - and declare the SignalK-level relationship via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }` in the extension's own `package.json` instead, so the App Store can install/report it.
+- Don't list this package in the extension's `dependencies` or `peerDependencies` - declare the relationship via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }` in the extension's own `package.json` instead, and add it as a `devDependency` for types and tests. The App Store installs required plugins flat in `~/.signalk/node_modules`, so the extension's `require` still resolves at runtime - and always to the one copy the running plugin uses. A regular `dependency` can leave a separate nested copy under the extension (e.g. on a version mismatch), with its own empty registry, so the registration silently goes nowhere; a `peerDependency` interacts poorly with the server's plugin install layout, per SignalK's own guidance.
 
 ## Template Providers
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizomatics/signalk-einklabel-plugin",
-  "version": "1.3.1",
+  "version": "1.3.3",
   "description": "Display SignalK data on eInk Electronic Shelf Labels, includes working examples for tide clock and watch schedule.",
   "keywords": [
     "ble",
@@ -76,8 +76,8 @@
     "@types/luxon": "^3.7.5",
     "@types/node": "^26.6.0",
     "@types/pngjs": "^6.0.5",
-    "oxfmt": "^0.74.0",
-    "oxlint": "^1.85.0",
+    "oxfmt": "^0.75.0",
+    "oxlint": "^1.89.0",
     "oxlint-tsgolint": "^7.0.2001",
     "ts-node": "^10.9.2",
     "typescript": "^5.5.0"

package/dist/email/emailSender.d.ts

@@ -1,27 +0,0 @@
-import { EmailConfig } from "../config";
-import { Bitmap } from "../render/types";
-import { FieldRow } from "../render/fieldsTable";
-/** Either the SVG template's field-by-field table (`buildFieldsTable`), a `TemplateProvider`'s own rendered-content text (`describeContent`), or neither (a provider offered no `describeContent`). */
-export type EmailContentBody = {
-    kind: "table";
-    rows: FieldRow[];
-} | {
-    kind: "text";
-    text: string;
-} | {
-    kind: "none";
-};
-export interface LabelEmailContent {
-    friendlyName: string;
-    description?: string;
-    bitmap: Bitmap;
-    body: EmailContentBody;
-}
-/**
- * Renders and sends one device's repaint as an email - a PNG attachment (also shown inline via a `cid`
- * reference), the same field-by-field table `esl-cli fields` shows for a hand-authored SVG template (or
- * a `TemplateProvider`'s own rendered-content text for something like a GenAI prompt - see `body`), and a
- * link back to the docs site. Called from `considerRepaint` (`../repaintScheduler.ts`) whenever a
- * device's `emailTo` is set and its render succeeds.
- */
-export declare function sendLabelEmail(emailConfig: EmailConfig, to: string, content: LabelEmailContent): Promise<void>;

package/dist/email/emailSender.js

@@ -1,66 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.sendLabelEmail = sendLabelEmail;
-const nodemailer_1 = __importDefault(require("nodemailer"));
-const png_1 = require("../render/png");
-const DOCS_URL = "https://rhizomatics.github.io/signalk-einklabel-plugin/";
-function escapeHtml(text) {
-    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
-}
-function bodyHtml(body) {
-    if (body.kind === "table") {
-        if (body.rows.length === 0)
-            return "";
-        const rows = body.rows
-            .map((row) => `<tr><td>${escapeHtml(row.id)}</td><td>${escapeHtml(row.spec)}</td><td>${escapeHtml(row.value)}</td></tr>`)
-            .join("");
-        return ('<table border="1" cellpadding="4" cellspacing="0" style="border-collapse:collapse;font-family:monospace;font-size:13px">' +
-            `<thead><tr><th>id</th><th>spec</th><th>value</th></tr></thead><tbody>${rows}</tbody></table>`);
-    }
-    if (body.kind === "text") {
-        return `<pre style="white-space:pre-wrap;font-family:monospace;font-size:13px">${escapeHtml(body.text)}</pre>`;
-    }
-    return "";
-}
-/**
- * Renders and sends one device's repaint as an email - a PNG attachment (also shown inline via a `cid`
- * reference), the same field-by-field table `esl-cli fields` shows for a hand-authored SVG template (or
- * a `TemplateProvider`'s own rendered-content text for something like a GenAI prompt - see `body`), and a
- * link back to the docs site. Called from `considerRepaint` (`../repaintScheduler.ts`) whenever a
- * device's `emailTo` is set and its render succeeds.
- */
-async function sendLabelEmail(emailConfig, to, content) {
-    const transporter = nodemailer_1.default.createTransport({
-        host: emailConfig.smtpHost,
-        port: emailConfig.smtpPort,
-        secure: emailConfig.smtpSecure,
-        auth: emailConfig.smtpUser ? { user: emailConfig.smtpUser, pass: emailConfig.smtpPassword } : undefined,
-    });
-    const png = (0, png_1.bitmapToPng)(content.bitmap);
-    const html = [
-        '<div style="font-family:sans-serif">',
-        `<h2>${escapeHtml(content.friendlyName)}</h2>`,
-        content.description ? `<p>${escapeHtml(content.description)}</p>` : "",
-        `<p><img src="cid:label-image" alt="${escapeHtml(content.friendlyName)}" style="border:1px solid #ccc" /></p>`,
-        bodyHtml(content.body),
-        `<p><a href="${DOCS_URL}">${DOCS_URL}</a></p>`,
-        "</div>",
-    ].join("\n");
-    await transporter.sendMail({
-        from: emailConfig.fromAddress,
-        to,
-        subject: `eInk Label: ${content.friendlyName}`,
-        html,
-        attachments: [
-            {
-                filename: "label.png",
-                content: png,
-                contentType: "image/png",
-                cid: "label-image",
-            },
-        ],
-    });
-}

package/dist/render/fieldsTable.d.ts

@@ -1,15 +0,0 @@
-import { TemplateContext } from "./types";
-export interface FieldRow {
-    id: string;
-    spec: string;
-    value: string;
-}
-/**
- * Synchronous counterpart to the CLI's `fields` command (`../cli/index.ts`) - same three columns (id,
- * spec, resolved value), but resolved against a single already-assembled `context` rather than
- * re-fetching per binding, since a caller like `considerRepaint` (`../repaintScheduler.ts`) already has
- * the full context its render used. Only meaningful for a hand-authored SVG template - a
- * `TemplateProvider`-backed template (e.g. GenAI) has no `<desc>` bindings to walk; see
- * `TemplateProvider.describeContent` (`./templateProviders.ts`) for that case's own text summary instead.
- */
-export declare function buildFieldsTable(svgSource: string, context: TemplateContext, templatesDir: string, bundledTemplatesDir: string): FieldRow[];

package/dist/render/fieldsTable.js

@@ -1,52 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildFieldsTable = buildFieldsTable;
-const path_1 = require("path");
-const xmldom_1 = require("@xmldom/xmldom");
-const assets_1 = require("./assets");
-const binding_1 = require("./binding");
-function resolveFieldValue(tag, desc, context, templatesDir, bundledTemplatesDir) {
-    try {
-        const binding = (0, binding_1.parseBinding)(desc);
-        if (tag !== "image") {
-            return (0, binding_1.renderBinding)(binding, context);
-        }
-        if (!binding.assets) {
-            return 'ERROR: an <image> binding requires an "assets" key';
-        }
-        const key = (0, assets_1.normalizeAssetKey)((0, binding_1.resolveBinding)(binding, context));
-        if (!key)
-            return "(no usable value - image would be omitted)";
-        const assetPath = (0, assets_1.resolveAssetPath)(templatesDir, bundledTemplatesDir, binding.assets, key);
-        return assetPath ? `"${key}" -> ${(0, path_1.basename)(assetPath)}` : `"${key}" -> no matching asset file (image would be omitted)`;
-    }
-    catch (err) {
-        return `ERROR: ${err.message}`;
-    }
-}
-/**
- * Synchronous counterpart to the CLI's `fields` command (`../cli/index.ts`) - same three columns (id,
- * spec, resolved value), but resolved against a single already-assembled `context` rather than
- * re-fetching per binding, since a caller like `considerRepaint` (`../repaintScheduler.ts`) already has
- * the full context its render used. Only meaningful for a hand-authored SVG template - a
- * `TemplateProvider`-backed template (e.g. GenAI) has no `<desc>` bindings to walk; see
- * `TemplateProvider.describeContent` (`./templateProviders.ts`) for that case's own text summary instead.
- */
-function buildFieldsTable(svgSource, context, templatesDir, bundledTemplatesDir) {
-    const doc = new xmldom_1.DOMParser().parseFromString(svgSource, "image/svg+xml");
-    const rows = [];
-    for (const tag of ["text", "image"]) {
-        const elements = doc.getElementsByTagName(tag);
-        for (let i = 0; i < elements.length; i++) {
-            const element = elements.item(i);
-            if (!element)
-                continue;
-            const id = element.getAttribute("id") ?? `${tag}#${i}`;
-            const desc = element.getElementsByTagName("desc").item(0);
-            if (!desc?.textContent)
-                continue;
-            rows.push({ id, spec: desc.textContent, value: resolveFieldValue(tag, desc.textContent, context, templatesDir, bundledTemplatesDir) });
-        }
-    }
-    return rows;
-}

package/dist/render/llmPrompt.d.ts

@@ -1,86 +0,0 @@
-import { PluginConfig } from "../config";
-import { Colour } from "../devices/types";
-import { Binding } from "./binding";
-import { TemplateContext } from "./types";
-/** Facts about one physical label a prompt's `source=label,path=...` placeholders can reference - see `buildLabelContext`. */
-export interface LabelMeta {
-    manufacturer: string;
-    /** The physical panel's own size label, e.g. `'3.7"'` - `DeviceMetadata.label` verbatim, see `../devices/types.ts`. */
-    label: string;
-    width: number;
-    height: number;
-    colours: Colour[];
-    description?: string;
-    position?: {
-        latitude: number;
-        longitude: number;
-    };
-}
-/**
- * Builds the `context.label` object a prompt/target-guidance fragment addresses via
- * `source=label,path=...` bindings (e.g. `{source=label,path=width}`, or the bare-path shorthand
- * `{width}` is *not* supported here deliberately - see `./binding.ts`'s `parseBinding`, every `{...}`
- * placeholder is a real binding, so a `label` path always needs the explicit `source=label,path=`
- * form to disambiguate it from a `signalk` self path). `colours`/`fonts` are left as arrays (each
- * colour entry pre-annotated with its hex code, e.g. `"black (#000000)"`) rather than joined into a
- * single string, so a prompt author can either use them bare (renders as JSON, e.g. for a model that
- * parses structured hints) or add `format=csv` (see `./formatters.ts`) for a plain comma-separated list.
- */
-export declare function buildLabelContext(meta: LabelMeta): Record<string, unknown>;
-/**
- * Every binding referenced across one or more prompt fragments - every `{...}` placeholder, deduplicated
- * across all of `texts` combined, parsed exactly the way a template's `<desc>` binding is
- * (`parseBinding`, see `./binding.ts`), so a bare path (`{design.length}`, `source=signalk,context=self`
- * shorthand), the full binding grammar (`{source=signalk,path=navigation.position,format=position}`),
- * and a `source=label,path=...` binding all work uniformly. Pass the result to `assembleRawContext`
- * (repaintScheduler.ts) exactly as a template's own bindings are - it fetches the `signalk`/
- * `resources`-sourced ones and silently ignores `label`/`einklabel`-sourced ones, which resolve directly
- * against `context.label`/`context.meta` instead (built by the caller, not fetched).
- *
- * A placeholder that isn't valid binding grammar (e.g. a typo like `{source=taheight}`) is silently
- * skipped here rather than thrown - the same per-field isolation `SvgRenderer` gives a bad `<desc>`
- * binding, so one malformed placeholder doesn't take down the whole prompt. `substitutePlaceholders`
- * hits the identical parse error at substitution time and turns it into "???" for just that field.
- */
-export declare function findPromptBindings(...texts: string[]): Binding[];
-/**
- * Substitutes every `{...}` placeholder in `text` with its resolved binding value against `context`
- * (built by `assembleRawContext` plus `context.label` from `buildLabelContext` - see
- * `findPromptBindings`). Mirrors `renderBinding`'s per-field isolation, but substitutes "???" for
- * anything that resolves to no value at all (missing path, invalid binding grammar) rather than "" -
- * prose with a silently-blank word reads as a fact ("for the sailor of a m vessel"), not as a gap the
- * reader would notice. Two things override that "???": a binding that resolves successfully to a
- * legitimately empty string (e.g. an unset `{source=label,path=description}`) is left as empty, since
- * that's a real answer, not a miss; and a binding with an explicit `default=` (see `./binding.ts`) uses
- * that default instead, since the prompt author has already said what a missing value should read as.
- */
-export declare function substitutePlaceholders(text: string, context: TemplateContext): string;
-/**
- * Strips everything outside the first `<svg`...last `</svg>` span - a chat model asked for "only raw
- * SVG markup" still often wraps it in a markdown code fence or adds a sentence of commentary either
- * side, despite the target-guidance fragment telling it not to.
- */
-export declare function extractSvg(raw: string): string;
-export type LlmSettings = Pick<PluginConfig, "llmProvider" | "llmApiKey" | "llmModel" | "llmBaseUrl"> & {
-    llmTimeoutSeconds?: number;
-};
-/**
- * `ai` and every `@ai-sdk/*` provider package are `optionalDependencies` (see package.json), not plain
- * `dependencies` - most installs (every device using `renderMode: "svg-template"` only) never touch an
- * LLM at all, so they shouldn't have to pull in this whole gateway stack, and an install that fails to
- * fetch one of these (network hiccup, `npm install --omit=optional`, an unsupported platform) must not
- * break BLE painting/templates, which have nothing to do with it. That means every reference to one of
- * these packages has to be a `require()` reached only when a `renderMode: "llm-prompt"` device actually
- * calls `callLlm` - a top-level `import` would be resolved eagerly the moment this module loads (which
- * is every plugin start, via `repaintScheduler.ts`), throwing before any config is even read. Types are
- * still fully checked via `typeof import(...)` below, which - unlike a value `import` - is erased
- * entirely at compile time and leaves no runtime trace for `tsc` to eagerly require.
- */
-export declare function loadOptional<M>(moduleName: string): M;
-/**
- * Calls the configured LLM gateway with `prompt`, returning its raw text response - not yet extracted/
- * validated as SVG, see `extractSvg`. This is the first network call in the codebase that needs its own
- * timeout (`fetchJson` in `../httpJson.ts` has none - every existing call is to the local SignalK
- * server's own REST API).
- */
-export declare function callLlm(settings: LlmSettings, prompt: string): Promise<string>;

package/dist/render/llmPrompt.js

@@ -1,199 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildLabelContext = buildLabelContext;
-exports.findPromptBindings = findPromptBindings;
-exports.substitutePlaceholders = substitutePlaceholders;
-exports.extractSvg = extractSvg;
-exports.loadOptional = loadOptional;
-exports.callLlm = callLlm;
-const binding_1 = require("./binding");
-const formatters_1 = require("./formatters");
-const COLOUR_HEX = { black: "#000000", white: "#FFFFFF", red: "#FF0000", yellow: "#FFFF00" };
-/** The only `font-family` values `SvgRenderer` is guaranteed to render - see `expandGenericFontFamilies` in `./svgRenderer.ts`. */
-const SAFE_FONT_FAMILIES = ["serif", "sans-serif", "monospace"];
-/**
- * Builds the `context.label` object a prompt/target-guidance fragment addresses via
- * `source=label,path=...` bindings (e.g. `{source=label,path=width}`, or the bare-path shorthand
- * `{width}` is *not* supported here deliberately - see `./binding.ts`'s `parseBinding`, every `{...}`
- * placeholder is a real binding, so a `label` path always needs the explicit `source=label,path=`
- * form to disambiguate it from a `signalk` self path). `colours`/`fonts` are left as arrays (each
- * colour entry pre-annotated with its hex code, e.g. `"black (#000000)"`) rather than joined into a
- * single string, so a prompt author can either use them bare (renders as JSON, e.g. for a model that
- * parses structured hints) or add `format=csv` (see `./formatters.ts`) for a plain comma-separated list.
- */
-function buildLabelContext(meta) {
-    return {
-        manufacturer: meta.manufacturer,
-        label: meta.label,
-        width: meta.width,
-        height: meta.height,
-        colours: meta.colours.map((colour) => `${colour} (${COLOUR_HEX[colour]})`),
-        fonts: SAFE_FONT_FAMILIES,
-        description: meta.description ?? "",
-        position: meta.position ? (0, formatters_1.applyFormat)("position", meta.position, {}, 3) : undefined,
-    };
-}
-/**
- * Every binding referenced across one or more prompt fragments - every `{...}` placeholder, deduplicated
- * across all of `texts` combined, parsed exactly the way a template's `<desc>` binding is
- * (`parseBinding`, see `./binding.ts`), so a bare path (`{design.length}`, `source=signalk,context=self`
- * shorthand), the full binding grammar (`{source=signalk,path=navigation.position,format=position}`),
- * and a `source=label,path=...` binding all work uniformly. Pass the result to `assembleRawContext`
- * (repaintScheduler.ts) exactly as a template's own bindings are - it fetches the `signalk`/
- * `resources`-sourced ones and silently ignores `label`/`einklabel`-sourced ones, which resolve directly
- * against `context.label`/`context.meta` instead (built by the caller, not fetched).
- *
- * A placeholder that isn't valid binding grammar (e.g. a typo like `{source=taheight}`) is silently
- * skipped here rather than thrown - the same per-field isolation `SvgRenderer` gives a bad `<desc>`
- * binding, so one malformed placeholder doesn't take down the whole prompt. `substitutePlaceholders`
- * hits the identical parse error at substitution time and turns it into "???" for just that field.
- */
-function findPromptBindings(...texts) {
-    const seen = new Set();
-    const bindings = [];
-    for (const text of texts) {
-        for (const match of text.matchAll(/\{([^{}]+)\}/g)) {
-            const key = match[1].trim();
-            if (seen.has(key))
-                continue;
-            seen.add(key);
-            try {
-                bindings.push((0, binding_1.parseBinding)(key));
-            }
-            catch {
-                // see doc comment above - left for `substitutePlaceholders` to turn into "???"
-            }
-        }
-    }
-    return bindings;
-}
-/**
- * Substitutes every `{...}` placeholder in `text` with its resolved binding value against `context`
- * (built by `assembleRawContext` plus `context.label` from `buildLabelContext` - see
- * `findPromptBindings`). Mirrors `renderBinding`'s per-field isolation, but substitutes "???" for
- * anything that resolves to no value at all (missing path, invalid binding grammar) rather than "" -
- * prose with a silently-blank word reads as a fact ("for the sailor of a m vessel"), not as a gap the
- * reader would notice. Two things override that "???": a binding that resolves successfully to a
- * legitimately empty string (e.g. an unset `{source=label,path=description}`) is left as empty, since
- * that's a real answer, not a miss; and a binding with an explicit `default=` (see `./binding.ts`) uses
- * that default instead, since the prompt author has already said what a missing value should read as.
- */
-function substitutePlaceholders(text, context) {
-    return text.replace(/\{([^{}]+)\}/g, (_match, raw) => {
-        const key = raw.trim();
-        try {
-            const binding = (0, binding_1.parseBinding)(key);
-            const value = (0, binding_1.resolveBinding)(binding, context);
-            if ((value === undefined || value === null) && binding.default === undefined)
-                return "???";
-            return (0, binding_1.renderBinding)(binding, context);
-        }
-        catch {
-            return "???";
-        }
-    });
-}
-/**
- * Strips everything outside the first `<svg`...last `</svg>` span - a chat model asked for "only raw
- * SVG markup" still often wraps it in a markdown code fence or adds a sentence of commentary either
- * side, despite the target-guidance fragment telling it not to.
- */
-function extractSvg(raw) {
-    const start = raw.indexOf("<svg");
-    const end = raw.lastIndexOf("</svg>");
-    if (start === -1 || end === -1 || end < start) {
-        throw new Error('LLM response did not contain a "<svg>...</svg>" document');
-    }
-    return raw.slice(start, end + "</svg>".length);
-}
-/**
- * `ai` and every `@ai-sdk/*` provider package are `optionalDependencies` (see package.json), not plain
- * `dependencies` - most installs (every device using `renderMode: "svg-template"` only) never touch an
- * LLM at all, so they shouldn't have to pull in this whole gateway stack, and an install that fails to
- * fetch one of these (network hiccup, `npm install --omit=optional`, an unsupported platform) must not
- * break BLE painting/templates, which have nothing to do with it. That means every reference to one of
- * these packages has to be a `require()` reached only when a `renderMode: "llm-prompt"` device actually
- * calls `callLlm` - a top-level `import` would be resolved eagerly the moment this module loads (which
- * is every plugin start, via `repaintScheduler.ts`), throwing before any config is even read. Types are
- * still fully checked via `typeof import(...)` below, which - unlike a value `import` - is erased
- * entirely at compile time and leaves no runtime trace for `tsc` to eagerly require.
- */
-function loadOptional(moduleName) {
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-require-imports
-        return require(moduleName);
-    }
-    catch (err) {
-        throw new Error(`LLM provider support needs the optional dependency "${moduleName}", which isn't installed - run "npm install ${moduleName}" (${err.message})`);
-    }
-}
-/** Ollama's own default local listen address - see the `"ollama"` case in `resolveModel` below. */
-const DEFAULT_OLLAMA_BASE_URL = "http://localhost:11434/v1";
-/**
- * Resolves `settings` to a Vercel AI SDK model handle. `"ollama"` and `"local"` both go through the
- * generic `@ai-sdk/openai-compatible` provider (Ollama/LM Studio/vLLM all expose an OpenAI-compatible
- * endpoint, and none of them has - or needs - its own dedicated `@ai-sdk/*` package): `"ollama"`
- * defaults `llmBaseUrl` to Ollama's own standard local address so it works with no further config
- * (override it only if Ollama is running elsewhere, e.g. on the SignalK server's own host reached over
- * the network); `"local"` is for anything else OpenAI-compatible, where there's no sensible universal
- * default, so `llmBaseUrl` is required.
- */
-function resolveModel(settings) {
-    const model = settings.llmModel;
-    if (!model) {
-        throw new Error("no LLM model configured (PluginConfig.llmModel)");
-    }
-    switch (settings.llmProvider ?? "openai") {
-        case "anthropic": {
-            const { createAnthropic } = loadOptional("@ai-sdk/anthropic");
-            return createAnthropic({ apiKey: settings.llmApiKey })(model);
-        }
-        case "google": {
-            const { createGoogleGenerativeAI } = loadOptional("@ai-sdk/google");
-            return createGoogleGenerativeAI({ apiKey: settings.llmApiKey })(model);
-        }
-        case "xai": {
-            const { createXai } = loadOptional("@ai-sdk/xai");
-            return createXai({ apiKey: settings.llmApiKey })(model);
-        }
-        case "ollama": {
-            const { createOpenAICompatible } = loadOptional("@ai-sdk/openai-compatible");
-            return createOpenAICompatible({
-                name: "ollama",
-                baseURL: settings.llmBaseUrl || DEFAULT_OLLAMA_BASE_URL,
-                apiKey: settings.llmApiKey,
-            })(model);
-        }
-        case "local": {
-            if (!settings.llmBaseUrl) {
-                throw new Error('llmBaseUrl is required when llmProvider is "local"');
-            }
-            const { createOpenAICompatible } = loadOptional("@ai-sdk/openai-compatible");
-            return createOpenAICompatible({ name: "local", baseURL: settings.llmBaseUrl, apiKey: settings.llmApiKey })(model);
-        }
-        case "openai":
-        default: {
-            const { createOpenAI } = loadOptional("@ai-sdk/openai");
-            return createOpenAI({ apiKey: settings.llmApiKey })(model);
-        }
-    }
-}
-/**
- * Calls the configured LLM gateway with `prompt`, returning its raw text response - not yet extracted/
- * validated as SVG, see `extractSvg`. This is the first network call in the codebase that needs its own
- * timeout (`fetchJson` in `../httpJson.ts` has none - every existing call is to the local SignalK
- * server's own REST API).
- */
-async function callLlm(settings, prompt) {
-    const model = resolveModel(settings);
-    const { generateText } = loadOptional("ai");
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), (settings.llmTimeoutSeconds ?? 30) * 1000);
-    try {
-        const { text } = await generateText({ model, prompt, abortSignal: controller.signal });
-        return text;
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}