@rhizomatics/signalk-einklabel-plugin 1.3.0 → 1.3.2

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+# 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
+
+- Stopping the plugin mid-paint (saving its config, disabling it, or shutting down the server) now waits up to 30 seconds for that paint to finish, and starts no new paint or retry, so the restarted plugin no longer connects while the old Bluetooth session is still open
+
+## 📚 Documentation
+
+- Docs site made friendlier to AI coding agents: an [llms.txt](https://signalk-einklabel.rhizomatics.org.uk/llms.txt) index plus the whole documentation as Markdown in `llms-full.txt` and `llms-small.txt`, and every page available as Markdown by replacing its trailing `/` with `.md` (e.g. [getting-started.md](https://signalk-einklabel.rhizomatics.org.uk/getting-started.md))
+
 # 1.3.0
 
 ## BLE Manager

package/README.md

@@ -3,10 +3,9 @@
 [![npm version](https://img.shields.io/npm/v/@rhizomatics/signalk-einklabel-plugin.svg)](https://www.npmjs.com/package/@rhizomatics/signalk-einklabel-plugin)
 [![npm downloads](https://img.shields.io/npm/dm/@rhizomatics/signalk-einklabel-plugin.svg)](https://www.npmjs.com/package/@rhizomatics/signalk-einklabel-plugin)
 [![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)
-[![codecov](https://img.shields.io/codecov/c/github/rhizomatics/signalk-einklabel-plugin)](https://codecov.io/gh/rhizomatics/signalk-einklabel-plugin)
 [![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/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/devices/bleDiscovery.d.ts

@@ -45,9 +45,15 @@ export declare function forEachAdvertisedDevice(adapter: Adapter, fn: (advertise
  * 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 }?: {
+/**
+ * Runs `fn` up to `attempts` times, `delayMs` apart, rethrowing the last error if every attempt fails.
+ * `shouldStop` is checked after each failed attempt and again after the pause, so a plugin `stop()`
+ * ends the retry loop instead of opening a fresh BLE session behind the next `start()`.
+ */
+export declare function withRetries<T>(attempts: number, fn: (attempt: number) => Promise<T>, { delayMs, onError, shouldStop, }?: {
     delayMs?: number;
     onError?: (err: unknown, attempt: number) => void;
+    shouldStop?: () => boolean;
 }): Promise<T>;
 /**
  * Opens exactly one BLE discovery window and one D-Bus/BlueZ session, then hands the adapter to

package/dist/devices/bleDiscovery.js

@@ -92,7 +92,12 @@ async function withDeadline(promise, ms, what) {
         clearTimeout(timer);
     }
 }
-async function withRetries(attempts, fn, { delayMs = 0, onError } = {}) {
+/**
+ * Runs `fn` up to `attempts` times, `delayMs` apart, rethrowing the last error if every attempt fails.
+ * `shouldStop` is checked after each failed attempt and again after the pause, so a plugin `stop()`
+ * ends the retry loop instead of opening a fresh BLE session behind the next `start()`.
+ */
+async function withRetries(attempts, fn, { delayMs = 0, onError, shouldStop = () => false, } = {}) {
     const total = Math.max(1, attempts);
     let lastErr;
     for (let attempt = 1; attempt <= total; attempt++) {
@@ -102,9 +107,11 @@ async function withRetries(attempts, fn, { delayMs = 0, onError } = {}) {
         catch (err) {
             lastErr = err;
             onError?.(err, attempt);
-            if (attempt < total && delayMs > 0) {
+            if (attempt < total && delayMs > 0 && !shouldStop()) {
                 await sleep(delayMs);
             }
+            if (shouldStop())
+                break;
         }
     }
     throw lastErr;

package/dist/plugin.js

@@ -43,7 +43,11 @@ function createPlugin(app) {
     const bleApiAvailable = !!app.bleApi;
     let scheduler;
     let stopDiscoveryListener;
-    let stopped = false;
+    // Bumped by every start() and stop(), so a start() whose plugin has since been stopped (or
+    // restarted) can tell it's stale - a plain `stopped` flag would be reset by the next start().
+    let generation = 0;
+    // The last stop()'s drain of any in-flight repaint; start() waits on it before touching BLE.
+    let stopping = Promise.resolve();
     const plugin = {
         id: "signalk-einklabel-plugin",
         name: "eInk ESL (Electronic Shelf Label)",
@@ -60,14 +64,19 @@ function createPlugin(app) {
             };
             app.debug(`starting with ${pluginConfig.devices.length} configured device(s)`);
             (0, config_1.healStoredConfig)(app);
-            stopped = false;
+            const thisGeneration = ++generation;
+            const isCurrent = () => thisGeneration === generation;
+            const previousStop = stopping;
             const useBleApi = pluginConfig.useBleApi && bleApiAvailable;
             if (pluginConfig.useBleApi && !bleApiAvailable) {
                 app.debug("useBleApi is enabled but this SignalK server has no BLE Manager API (requires >= 2.32.0) - falling back to direct BlueZ access");
             }
             app.debug(useBleApi ? "using the SignalK BLE Manager API for Bluetooth access" : "using direct BlueZ access for Bluetooth");
-            const start = () => {
-                if (stopped)
+            const start = async () => {
+                // A server that doesn't await stop()'s Promise (or calls start() first) would otherwise have
+                // this connect while the previous session's paint is still running.
+                await previousStop;
+                if (!isCurrent())
                     return;
                 if (pluginConfig.scanOnStart) {
                     void runStartupScan(app, pluginConfig.scanDurationSeconds, useBleApi);
@@ -83,23 +92,31 @@ function createPlugin(app) {
                 // The server/provider governs its own local-adapter readiness once BLE Manager mode owns
                 // `hci0` (or has none at all, behind a remote gateway) - waiting on a *local* BlueZ adapter
                 // here would be waiting on something this mode may never even need.
-                start();
+                void start();
             }
             else {
                 // Waits (with backoff, indefinitely on Linux) for a BLE adapter before the startup scan or
                 // the repaint scheduler touch BLE at all - see `waitForAdapter`'s doc comment on the
-                // boot-time race this covers. `stopped` is checked again inside `start()`, not just passed
+                // boot-time race this covers. `isCurrent` is checked again inside `start()`, not just passed
                 // as `cancelled`, since the wait can also resolve `true` on its own right as `stop()` runs.
-                void (0, bleDiscovery_1.waitForAdapter)((message) => app.debug(message), () => stopped).then(start);
+                void (0, bleDiscovery_1.waitForAdapter)((message) => app.debug(message), () => !isCurrent()).then(start);
             }
         },
-        stop() {
-            stopped = true;
-            scheduler?.stop();
+        // 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(). 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;
-            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;
         },
     };
     return plugin;

package/dist/render/assets.js

@@ -19,7 +19,8 @@ function normalizeAssetKey(value) {
         .trim()
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, "_")
-        .replace(/^_+|_+$/g, "");
+        // runs are already collapsed to a single `_` above, so one at each end is all there can be
+        .replace(/^_|_$/g, "");
     return normalized || undefined;
 }
 /**

package/dist/render/templateProviders.d.ts

@@ -51,6 +51,13 @@ export interface TemplateProvider {
      * screen unmarked.
      */
     render(request: TemplateRenderRequest): Promise<Bitmap>;
+    /**
+     * Optional, debug only: a human-readable description of what `render()` will be given for this
+     * request (e.g. a GenAI provider's prompt with every placeholder substituted) - `considerRepaint`
+     * writes it to `app.debug` just before calling `render()`, standing in for the `<desc>` bindings an
+     * SVG template's debug output would otherwise show. Throwing only skips that debug line, never the render.
+     */
+    describeContent?(request: TemplateRenderRequest): string;
 }
 export declare function registerTemplateProvider(provider: TemplateProvider): void;
 export declare function allTemplateProviders(): TemplateProvider[];

package/dist/repaintScheduler.d.ts

@@ -1,7 +1,27 @@
 import { ServerAPI } from "@signalk/server-api";
 import { PluginConfig } from "./config";
+/**
+ * How long `stop()` waits for a paint already in progress before resolving anyway. Long enough for a
+ * normal transfer to finish (so a config save mid-paint doesn't have the next `start()` connect while
+ * the old BLE session is still open), short enough not to hold up server shutdown on a label that's
+ * 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 {
-    stop(): void;
+    /**
+     * Stops every trigger, lets no new paint or retry start, and resolves once any paint already in
+     * progress finishes - or after `drainTimeoutMs` (default `STOP_DRAIN_TIMEOUT_MS`), whichever comes first.
+     */
+    stop(drainTimeoutMs?: number): Promise<void>;
 }
 /**
  * The most recent wall-clock instant at or before `now` that an `interval`-triggered device's own
@@ -19,6 +39,15 @@ export declare function mostRecentScheduledSlot(now: Date, intervalHours: number
  * but only if it succeeded (`run` resolved `true`). For repaints: newer data still gets shown promptly,
  * but a label that's failing isn't hammered with a fresh round of retries straight after the last
  * one gave up - the next scheduled trigger tries again instead.
+ *
+ * `close()` makes every later call a no-op and drops pending follow-ups; `idle()` resolves once no
+ * `run` is in progress. Together they let the scheduler's `stop()` wait for a paint already under way
+ * without starting another.
  */
-export declare function oneAtATimePerKey<T>(keyOf: (arg: T) => string, run: (arg: T) => Promise<boolean>, onBusy?: (arg: T) => void): (arg: T) => Promise<void>;
+export interface OneAtATimePerKey<T> {
+    (arg: T): Promise<void>;
+    close(): void;
+    idle(): Promise<void>;
+}
+export declare function oneAtATimePerKey<T>(keyOf: (arg: T) => string, run: (arg: T) => Promise<boolean>, onBusy?: (arg: T) => void): OneAtATimePerKey<T>;
 export declare function startRepaintScheduler(app: ServerAPI, config: PluginConfig): RepaintScheduler;

package/dist/repaintScheduler.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHUTDOWN_DRAIN_TIMEOUT_MS = exports.STOP_DRAIN_TIMEOUT_MS = void 0;
 exports.mostRecentScheduledSlot = mostRecentScheduledSlot;
 exports.oneAtATimePerKey = oneAtATimePerKey;
 exports.startRepaintScheduler = startRepaintScheduler;
@@ -33,6 +34,22 @@ const PAINT_RETRY_DELAY_MS = 5000;
  * the longest being the 5-minute GATT session watchdog in `bleBackend.ts`.
  */
 const PAINT_ATTEMPT_BACKSTOP_MS = 7 * 60000;
+/**
+ * How long `stop()` waits for a paint already in progress before resolving anyway. Long enough for a
+ * normal transfer to finish (so a config save mid-paint doesn't have the next `start()` connect while
+ * the old BLE session is still open), short enough not to hold up server shutdown on a label that's
+ * 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
@@ -248,7 +265,7 @@ async function resolveTargets(app, config, device) {
  * prompt showing "gentle breezes" through an actual storm), and not persisting a hash means the very
  * next scheduled tick retries for real rather than being suppressed by dedup.
  */
-async function considerRepaint(app, config, device, target, state, getApiUrl) {
+async function considerRepaint(app, config, device, target, state, getApiUrl, isStopping = () => false) {
     const { address, metadata, driver } = target;
     const label = `"${device.friendlyName}" [${address}]`;
     if (!device.templateName) {
@@ -334,8 +351,17 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
                 description: device.description ?? "",
             },
         };
+        const providerRequest = { templateName: device.templateName, context: renderContext, width, height, colours: metadata.colours };
+        if (provider?.describeContent) {
+            try {
+                app.debug(`${label}: provider content:\n${provider.describeContent(providerRequest)}`);
+            }
+            catch (err) {
+                app.debug(`${label}: describeContent failed (${err.message})`);
+            }
+        }
         bitmap = provider
-            ? await provider.render({ templateName: device.templateName, context: renderContext, width, height, colours: metadata.colours })
+            ? await provider.render(providerRequest)
             : await renderer.render(templatePath, renderContext, width, height, templatesDir, config_1.BUNDLED_TEMPLATES_DIR);
         succeeded = true;
         repaintReason = device.advanced?.forceRepaint
@@ -363,28 +389,35 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
     const connectTimeoutMs = (device.advanced?.paintConnectTimeoutSeconds ?? config.paintConnectTimeoutSeconds) * 1000;
     const gattBackend = config.useBleApi && app.bleApi ? (0, bleBackend_1.bleApiBackend)(app.bleApi, pluginVersion_1.PLUGIN_NAME) : undefined;
     const attempts = Math.max(1, device.advanced?.paintRetries ?? config.paintRetries);
-    const paintWithRetries = () => (0, bleDiscovery_1.withRetries)(attempts, async (attempt) => {
-        app.debug(`${label}: attempting paint ${attempt}/${attempts}`);
-        const startedAt = Date.now();
-        const paint = driver.paint(bitmap, {
-            address,
-            pid: target.pid,
-            aesKey: device.advanced?.aesKey,
-            connectTimeoutMs,
-            reframe: device.advanced?.reframe,
-            mirror: device.advanced?.mirror,
-            compress: device.advanced?.compress,
-            compressionFormat: device.advanced?.compressionFormat,
-            writeWithoutResponse: device.advanced?.writeWithoutResponse,
-            gattBackend,
-            log: (message) => app.debug(`${label}: ${message}`),
+    const paintWithRetries = () => {
+        // Rendering (or waiting for `exclusiveBleManagerAccess`) can outlast a `stop()` - don't open a
+        // BLE session for a plugin that's already stopping.
+        if (isStopping())
+            throw new Error("plugin stopping - paint skipped");
+        return (0, bleDiscovery_1.withRetries)(attempts, async (attempt) => {
+            app.debug(`${label}: attempting paint ${attempt}/${attempts}`);
+            const startedAt = Date.now();
+            const paint = driver.paint(bitmap, {
+                address,
+                pid: target.pid,
+                aesKey: device.advanced?.aesKey,
+                connectTimeoutMs,
+                reframe: device.advanced?.reframe,
+                mirror: device.advanced?.mirror,
+                compress: device.advanced?.compress,
+                compressionFormat: device.advanced?.compressionFormat,
+                writeWithoutResponse: device.advanced?.writeWithoutResponse,
+                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,
+            onError: (err, attempt) => app.debug(`${label}: paint attempt ${attempt}/${attempts} failed: ${err.message}`),
+            shouldStop: isStopping,
         });
-        await (0, bleDiscovery_1.withDeadline)(paint, connectTimeoutMs + PAINT_ATTEMPT_BACKSTOP_MS, `paint attempt ${attempt}/${attempts}`);
-        paintDurationMs = Date.now() - startedAt;
-    }, {
-        delayMs: PAINT_RETRY_DELAY_MS,
-        onError: (err, attempt) => app.debug(`${label}: paint attempt ${attempt}/${attempts} failed: ${err.message}`),
-    });
+    };
     await (gattBackend ? (0, bleBackend_1.exclusiveBleManagerAccess)(paintWithRetries) : paintWithRetries());
     (0, discoveredDevicesStore_1.touchDiscoveredDevice)(app, { address, vendor: target.vendor, pid: target.pid, hwVersion: target.hwVersion, metadata });
     // Only a successful render counts as "repainted" for dedup/catch-up purposes - a failure must not be
@@ -395,27 +428,24 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
     }
     app.debug(succeeded ? `${label}: repainted (${repaintReason}, paint took ${paintDurationMs}ms)` : `${label}: repainted fallback warning`);
 }
-/**
- * Wraps `run` so only one call per key is in progress at a time. A call made while that key is busy
- * is folded into a single follow-up (with the latest arguments), run once the current one finishes -
- * but only if it succeeded (`run` resolved `true`). For repaints: newer data still gets shown promptly,
- * but a label that's failing isn't hammered with a fresh round of retries straight after the last
- * one gave up - the next scheduled trigger tries again instead.
- */
 function oneAtATimePerKey(keyOf, run, onBusy = () => { }) {
-    const inProgress = new Set();
+    const inProgress = new Map();
     const followUps = new Map();
+    let closed = false;
     const call = async (arg) => {
+        if (closed)
+            return;
         const key = keyOf(arg);
         if (inProgress.has(key)) {
             followUps.set(key, arg);
             onBusy(arg);
             return;
         }
-        inProgress.add(key);
+        const running = run(arg);
+        inProgress.set(key, running);
         let succeeded = false;
         try {
-            succeeded = await run(arg);
+            succeeded = await running;
         }
         finally {
             inProgress.delete(key);
@@ -426,12 +456,25 @@ function oneAtATimePerKey(keyOf, run, onBusy = () => { }) {
             await call(followUp);
         }
     };
-    return call;
+    return Object.assign(call, {
+        close() {
+            closed = true;
+            followUps.clear();
+        },
+        async idle() {
+            // A follow-up can start as an earlier run settles (unless closed), so loop until nothing is left.
+            while (inProgress.size > 0) {
+                await Promise.allSettled(inProgress.values());
+            }
+        },
+    });
 }
 function startRepaintScheduler(app, config) {
     const state = loadState(app);
     const unsubscribes = [];
     const getApiUrl = (0, resolveApiUrl_1.createApiUrlResolver)(config.signalkApiUrl);
+    let stopping = false;
+    const isStopping = () => stopping;
     // The first minute or two of a SignalK server's life is a chaos of plugin dependency sequencing -
     // a repaint attempted before other plugins (e.g. derived-data) have published the data a template
     // needs renders with missing/wrong values, and hash dedup (see `considerRepaint`) then means it
@@ -451,7 +494,7 @@ function startRepaintScheduler(app, config) {
         if (targets.length === 0) {
             return false;
         }
-        const results = await Promise.allSettled(targets.map((target) => considerRepaint(app, config, device, target, state, getApiUrl)));
+        const results = await Promise.allSettled(targets.map((target) => considerRepaint(app, config, device, target, state, getApiUrl, isStopping)));
         results.forEach((result, i) => {
             if (result.status === "rejected") {
                 app.debug(`"${device.friendlyName}" [${targets[i].address}]: repaint failed: ${result.reason.message}`);
@@ -525,9 +568,22 @@ function startRepaintScheduler(app, config) {
     }, settleMs);
     unsubscribes.push(() => clearTimeout(startupCheckTimer));
     return {
-        stop() {
+        async stop(drainTimeoutMs = exports.STOP_DRAIN_TIMEOUT_MS) {
+            stopping = true;
             for (const unsubscribe of unsubscribes)
                 unsubscribe();
+            repaint.close();
+            let timer;
+            const drained = await Promise.race([
+                repaint.idle().then(() => true),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(false), drainTimeoutMs);
+                }),
+            ]);
+            clearTimeout(timer);
+            if (!drained) {
+                app.debug(`a repaint was still running ${drainTimeoutMs / 1000}s after stop - not waiting any longer`);
+            }
         },
     };
 }

package/docs/bluetooth.md

@@ -30,17 +30,21 @@ First step is having a Bluetooth Low Energy (BLE) compatible bluetooth adapter a
 
 SignalK BLE Manager also supports BLE Gateways, which could be an MQTT topic or an ESP-32 device. The [espos-ble-gateway](https://github.com/dirkwa/espos-ble-gateway) can be used with a cheap ESP32 device (see the list of supported hardware), which allows positioning of the gateway closer to devices, or having multiple gateways on a big boat.
 
-## BLE Manager Readiness
+## 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.
+Zhsunyco labels still have problems through BLE Manager even with these fixes, so the BLE Manager setting stays off by default for now. Direct BlueZ access remains the reliable choice for them.
+
+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,9 @@ 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.
+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.
@@ -160,3 +164,32 @@ Following file created at /etc/tlp.d/99-bt500-no-autosuspend.conf
 ```
 USB_DENYLIST="0b05:190e"
 ```
+
+## Bluetooth Jargon Buster
+
+Bluetooth comes with a lot of acronyms. Here's what the ones on this page mean, without needing to be a computer person.
+
+When the plugin paints a label, the request goes down a chain: the plugin asks **BlueZ** over **D-Bus**, BlueZ gives orders to the Bluetooth dongle over **HCI**, and the dongle's radio talks to the label using **BLE**, reading and writing the label's **GATT** services. A **gateway** or **proxy** simply moves the radio end of that chain somewhere else on the boat.
+
+- **BLE (Bluetooth Low Energy)** - the kind of Bluetooth made for small battery-powered gadgets like labels, sensors and battery monitors.
+  - It's different from the "classic" Bluetooth used by headphones and speakers, and doesn't have the usual pairing process.
+  - BLE devices talk in short bursts and sleep in between, which is how a label runs for years on a coin cell.
+  - They regularly broadcast short "advertisements" saying who they are, and the server picks these up by _scanning_.
+  - BLE needs an adapter supporting Bluetooth 4.0 or later.
+- **HCI (Host Controller Interface)** - the standard set of commands a computer uses to give orders to a Bluetooth radio chip, such as "start scanning" or "connect to this device".
+  - Linux names each Bluetooth adapter after it, so `hci0` is the first adapter, `hci1` the second, and so on.
+  - A plugin using the adapter "directly" is sending HCI commands itself, works fine if there's only one Bluetooth app on the server.
+- **BlueZ** - the standard Bluetooth software on Linux.
+  - It runs quietly in the background as a service called `bluetoothd`, takes charge of the adapter, keeps a list of the devices it has heard, and handles connecting to them.
+  - Its a sane alternative to multiple Linux programs all trying to grab the limited resources of the Bluetooth adapter and stomping over each other. It does at a Linux level what BLE Manager does for SignalK - a single point of ownership and control over a contested resource.
+- **D-Bus** - the messaging system that programs on a Linux computer use to talk to each other.
+  - It's how the plugin, or SignalK's BLE Manager, asks BlueZ to scan or connect.
+  - If you know NMEA 2000, it's a similar idea: one shared backbone that everything plugs into and exchanges messages over, rather than a separate cable between every pair of devices.
+- **GATT (Generic Attribute Profile)** - how a BLE device organises what it offers once you're connected to it.
+  - The device has _services_, each a group of related features, and each service has _characteristics_, individual values you can read, write or be told about when they change.
+  - Painting a label means connecting, finding its image service, and writing the picture into the right characteristic a piece at a time.
+  - The "GATT claims" shown in SignalK's BLE Manager are simply which plugin has booked which device for a connection, so that two plugins don't try to talk to it at once.
+- **Gateway** - a separate small device, often a cheap ESP32 board, with its own Bluetooth radio, which listens for and talks to BLE devices near it and relays everything to SignalK over the boat's network.
+  - It's effectively fitting a remote antenna closer to where it's needed: useful when a label is too far from the server, or on a big boat that needs more than one. SignalK's BLE Manager can use gateways alongside, or instead of, a local adapter.
+- **Proxy** - much the same idea as a gateway: a device that does the Bluetooth radio work on the server's behalf, somewhere with a better signal.
+  - Different software uses different names for it. Home Assistant users, for example, will know ESP32 "Bluetooth proxies".

package/docs/design/roadmap.md

@@ -0,0 +1,9 @@
+# Design Plans
+
+## Label Support
+
+- More vendors, and more labels for existing vendors
+- Ability for people to plug-in vendor support for themselves or as published plugins
+- A model override in the plugin config, so a discovered device whose PID isn't in its driver's table yet can be repainted (the CLI's `paint --colours` already does this)
+- Neaps or springs status (e.g. "Springs +1", "Neaps -2") on the tide template, pending upstream signalk-tides support
+- Alternatives to SVG templates, perhaps [imagespec](https://pypi.org/project/imagespec/) or [signalk-hmi-designer](https://github.com/dirkwa/signalk-hmi-designer)

package/docs/design/spec.md

@@ -0,0 +1,59 @@
+# Design Specification
+
+A SignalK plugin, in TypeScript, that renders selected SignalK data to BLE eInk Electronic Shelf Labels (ESLs). This page describes the plugin as it is built. Plans and ideas not yet built are in the [roadmap](roadmap.md).
+
+# Features
+
+- Native TypeScript, Node 20 compatible (runs on armv7, e.g. a Cerbo GX)
+- Bundled templates for a tide clock and a watch schedule, rendered from any SignalK data, Resources API resource or label fact a template binds to
+- 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)
+  - 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
+- 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
+  - With direct BlueZ access, scanning happens in bounded windows: an optional startup scan (`scanOnStart`, off by default, `scanDurationSeconds` long), an on-demand scan when an "All discovered devices" entry has nothing discovered yet, or `esl-cli scan`. With BLE Manager, the plugin listens to its advertisement stream for as long as the plugin runs, and only identifies new addresses
+  - Discovered devices are persisted in the plugin data directory, keyed by BLE address, and kept for 24 hours after last being seen; a successful paint counts as being seen. The startup scan reports what it found in the plugin status line
+  - The device picker lists any device a driver identified as its vendor, even if the PID isn't in that driver's metadata table yet (labelled "vendor unrecognised PID 0x.... (address)"), so it can be reported. Such a device can't be repainted from the plugin, since there's no width/height to render with; `esl-cli paint` can paint one by supplying the model facts on the command line
+- Device configuration
+  - Each device entry has a friendly name, a combined "Device" choice, an optional location/description, a template and a repaint trigger, with less common settings grouped under "Advanced settings"
+  - The "Device" value is `"<vendor>:<pid>[:<hwVersion>]@<address>"`, picked from recently discovered devices, so width/height/colours are known from config alone and never need a live BLE read or a rescan after a restart. The special value `ALL` ("All discovered devices") paints the same template and trigger to every currently-known device instead, resolved at repaint time
+  - Advanced settings: reframe (`crop` by default, `scale`, or `fixed` to fail on a size mismatch), compress upload (on by default), mirror (`none`, `horizontal`, `vertical`, `both`), Gicisky wire format (`auto` or experimental `chunked`), Zhsunyco write-without-response, force repaint, Zhsunyco AES key (falls back to a default key), and per-device overrides of the plugin-wide paint connect timeout and retry count
+  - Config saved before advanced settings were grouped, or nested by an older save bug, is rewritten into the current shape at plugin start (`healStoredConfig`)
+- Templates
+  - SVG files, rendered to bitmaps with resvg-wasm (`src/render/svgRenderer.ts`). A user templates directory (`templatesDir`: empty for `~/.signalk/einklabel/templates`, relative to `~/.signalk`, or absolute) is scanned alongside the bundled `templates/` directory; a user template with the same name as a bundled one takes priority. There is no upload UI
+  - A template is either a single `.svg` file or a _template family_: a directory of variants named `<width>x<height>-<colours>.svg` (e.g. `tides/416x240-BWRY.svg`). The best variant for each device is picked at repaint time: exact size and colours, then exact size, then the nearest width with the closest aspect ratio. Dot-prefixed directories (`.assets`, `.blank`, `.error`) are never offered as templates
+  - Each template can be assigned to one or more devices. There is no separate data config; a template's own bindings declare what data it needs, re-read from the template on every repaint
+  - Text uses the bundled serif, sans-serif and monospace fonts (resvg-wasm can't see system fonts); the generic CSS family names are rewritten to the bundled fonts' exact names
+- Bindings
+  - A dynamic `<text>` element carries a flat `key=value,key=value` binding in a `<desc>` child, not a templating engine - e.g. `source=resources,resource=tides,path=extremes[0].time,format=local_time`. `source`/`context` default to `signalk`/`self`, a bare path with no `=` is shorthand for `path=...`, and array indices use bracket notation. The element's own text is a placeholder for laying out the template in an editor. See `src/render/binding.ts` for the grammar
+  - Keys: `source`, `context`, `resource`, `provider`, `path`, `format`, `category`, `round`, `assets`, `default`. An unknown key is an error; `default=` replaces a missing value
+  - `source=signalk` (default): `context=self` reads via `getSelfPath`; any other `context` is read via `getPath` against that literal SignalK context, exactly as shown in the Data Browser (e.g. `vessels.urn:mrn:imo:mmsi:232345678`)
+  - `source=resources`: `resource=<name>` reads any Resources API resource type (`tides`, `waypoints`, ...) via `app.resourcesApi.listResources` in-process. `provider=<plugin id>` pins it to one resource provider; a pinned binding goes over the REST API instead, since the in-process call ignores the provider id (signalk-server 2.30.0)
+  - `source=label`: facts about the physical label - `manufacturer`, `label`, `width`, `height`, `colours`, `fonts`, `description`, and `position` (rounded to about 1km so GPS jitter doesn't force repaints)
+  - `source=einklabel`: plugin-injected values - `repainted` (repaint time), `local_zone` (timezone abbreviation) and `plugin_version`
+  - `format=` names a formatter from `src/render/formatters.ts`: `local_time`, `day_mon`, `local_datetime_short`, `utc_offset`, `position`, `csv`. Times use the vessel's `environment.time.timezoneRegion` when published, otherwise the host's timezone - never a tide station's own `timezone` field
+  - A `signalk`-sourced numeric value converts to its path's preferred display unit by default, via `GET {signalkApiUrl}/signalk/v1/api/vessels/<context>/meta` (there's no in-process equivalent); `format=raw` opts out. A value with no path of its own (e.g. resource-sourced) can take an explicit `category=<name>` (e.g. `category=depth`), resolved from `{signalkApiUrl}/signalk/v1/unitpreferences/...` client-side (`src/unitCategories.ts`). `round=` sets decimal places
+  - 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
+  - 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
+  - Each device picks one repaint trigger: a change on a SignalK path (`subscription`, debounced by 2 seconds, ignoring transient null/missing values), or a fixed interval (every N hours at a configurable minute past the hour, checked by one shared one-minute timer rather than one per device)
+  - Every trigger waits for a settle window after plugin start (`settleSeconds`, default 120), so a template isn't rendered before other plugins (e.g. derived-data) have published its data. After that window each device is checked once; an interval device already painted for its current slot skips this catch-up
+  - Before repainting, the template's mtime and the assembled data (bindings plus label facts, before plugin-injected values like the repaint time are added) are hashed and compared against the last successful paint, persisted in the plugin data directory per device entry and BLE address (`friendlyName:address`). If both are unchanged the repaint is skipped, to save the label's battery and avoid a full-panel flash. A template provider's output always repaints, since the plugin can't know whether it would differ
+  - "Force repaint" bypasses the unchanged-data skip for one repaint, then clears itself once every target device has painted successfully
+  - Only one repaint per device entry runs at a time; a trigger arriving mid-repaint queues one follow-up, run only if the current repaint succeeded
+  - A paint is retried up to `paintRetries` times (default 3, 5 seconds apart), each attempt bounded by `paintConnectTimeoutSeconds` (default 30) plus a backstop deadline
+  - Stopping the plugin (a config save, disable, or server shutdown) stops every trigger, drops queued follow-ups and retries, and skips a paint that hasn't connected yet. `stop()` returns a Promise that resolves once a paint already under way has finished, waiting at most 30 seconds, and the next `start()` also waits for it, so two BLE sessions don't overlap
+  - If rendering fails (a broken template, a missing file, or a template provider's `render()` rejecting), the bundled `.error` warning template is painted instead, so stale content is never left on screen unmarked. No success hash is saved, so the next trigger retries
+- Template providers
+  - An extension package can offer content generated another way, alongside SVG templates, via `registerTemplateProvider` - e.g. `@rhizomatics/signalk-einklabel-genai-plugin` generating content from an LLM prompt. Its entries appear in the same "Template" dropdown, marked by the provider's `suffix`. See [Extending](../extending.md) and `src/render/templateProviders.ts`
+- `esl-cli`, a local CLI for scanning, painting and testing templates outside the SignalK plugin
+  - `vendors`, `scan`, `paint` (with the same image options as the plugin, plus `--colours`/`--width`/`--height`/`--voffset` model facts for hardware not yet in a driver's table), `render` (template to PNG), `fields` (every binding in a template with its resolved value) and `field` (one binding spec). Bindings resolve against a live SignalK server over HTTP, or against local example JSON (`-e examples`). Extensions can add subcommands via `--require`. See [Command Line Interface](../cli.md)

package/docs/extending.md

@@ -24,9 +24,9 @@ Additional vendors and devices can be added by a separate npm package that imple
 
 ## Template Providers
 
-An alternative way to produce a device's content, alongside hand-authored SVG templates, can be added the same way - `esl.registerTemplateProvider({ suffix, listTemplates, render })`, from a separate package's own plugin `start()` (or `esl-cli --require <module>`). This is what [`@rhizomatics/signalk-einklabel-genai-plugin`](templates.md#genai-rendering) is: `listTemplates()` returns the entries it currently offers (already including its own `suffix`, e.g. `"forecast (GenAI)"`) for the "Template" dropdown, and `render(request)` - given the same signalk/resources/label context any SVG template's bindings get - returns a `Bitmap`, exactly as `SvgRenderer.render()` would. Rejecting from `render()` routes the repaint through this plugin's own generic fallback-warning template, the same as a broken hand-authored template failing to render.
+An alternative way to produce a device's content, alongside hand-authored SVG templates, can be added the same way - `esl.registerTemplateProvider({ suffix, listTemplates, render })`, from a separate package's own plugin `start()` (or `esl-cli --require <module>`). This is what [`@rhizomatics/signalk-einklabel-genai-plugin`](templates.md#genai-rendering) is: `listTemplates()` returns the entries it currently offers (already including its own `suffix`, e.g. `"forecast (GenAI)"`) for the "Template" dropdown, and `render(request)` - given the same signalk/resources/label context any SVG template's bindings get - returns a `Bitmap`, exactly as `new esl.Renderer().render()` would for an SVG template. Rejecting from `render()` routes the repaint through this plugin's own generic fallback-warning template, the same as a broken hand-authored template failing to render. An optional `describeContent(request)` returns a human-readable description of what `render()` will be given (the GenAI plugin returns its fully-substituted LLM prompt); when present, it's logged to the plugin's debug output just before each `render()`, standing in for the `<desc>` bindings an SVG template's debug output would show.
 
-`esl.SvgRenderer`, `esl.buildLabel`, `esl.findBindingsInText`, and `esl.substituteBindingsInText` are also exported for a `TemplateProvider` extension to reuse - e.g. to resolve its own `{...}`-style placeholders against the request's context, or to rasterize whatever SVG it produces into the `Bitmap` its `render()` must return.
+`esl.Renderer` (the SVG renderer), `esl.bitmapToPng`, `esl.buildLabel`, `esl.findBindingsInText`, and `esl.substituteBindingsInText` are also exported for a `TemplateProvider` extension to reuse - e.g. to resolve its own `{...}`-style placeholders against the request's context, or to rasterize whatever SVG it produces into the `Bitmap` its `render()` must return.
 
 ## CLI Commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizomatics/signalk-einklabel-plugin",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Display SignalK data on eInk Electronic Shelf Labels, includes working examples for tide clock and watch schedule.",
   "keywords": [
     "ble",
@@ -76,14 +76,15 @@
     "@types/luxon": "^3.7.5",
     "@types/node": "^26.6.0",
     "@types/pngjs": "^6.0.5",
-    "oxfmt": "^0.70.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"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22",
+    "signalk-server": ">=2.25.0"
   },
   "signalk": {
     "displayName": "eInk Label Displays",

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);
-    }
-}