@rhizomatics/signalk-einklabel-plugin 1.3.1 → 1.3.2

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+# 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/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/plugin.js

@@ -104,14 +104,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/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
@@ -559,7 +568,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 +577,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/docs/bluetooth.md

@@ -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.
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizomatics/signalk-einklabel-plugin",
-  "version": "1.3.1",
+  "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,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);
-    }
-}