@rhizomatics/signalk-einklabel-plugin 1.3.0-beta2 → 1.3.0-beta4

package/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 First implementation of using new SignalK BLE Manager rather than directly using the `bluez` services. Off by default until longer term stability demonstrated.
 
+
 # 1.2.3
 
 - Improved example tide template for 2.9" Gicisky, and added blank and error templates

package/dist/devices/bleBackend.d.ts

@@ -12,7 +12,28 @@ export interface BleBackend {
     connectGatt(address: string, timeoutMs: number): Promise<GattConnection>;
     waitForManufacturerData(address: string, manufacturerId: number, timeoutMs: number): Promise<Buffer | undefined>;
 }
+/**
+ * Wraps a connected `GattConnection` so the session as a whole - not just the connect step - can't
+ * hang forever. Starts a single timer when the connection opens; if `disconnect()` hasn't been
+ * called (i.e. the caller's `paint()` hasn't finished, successfully or not) by the time it fires,
+ * treats the session as stuck: calls `forceClose` (which must tear down the connection and, for a
+ * shared backend, release any claim on it) and fails every call still outstanding or made afterwards.
+ * `Promise.race`ing each call against that same failure - rather than just refusing new calls once
+ * killed - is what actually unblocks a caller `await`ing a hung `write()`/`discoverServices()`:
+ * forcing the underlying connection closed doesn't guarantee the hung call's own promise ever
+ * settles, so the caller needs a second, independent way to move on.
+ */
+export declare function withSessionWatchdog(conn: GattConnection, timeoutMs: number, forceClose: () => Promise<void>): GattConnection;
 export declare function nodeBleBackend(): BleBackend;
+/**
+ * Waits for the BLE Manager to know about `address` before a GATT connect is attempted against it -
+ * mirrors `getOrDiscoverDevice` in `bleDiscovery.ts`, which gives `nodeBleBackend` the same guarantee
+ * against BlueZ directly. Without this, a specifically-addressed device that the manager hasn't seen
+ * yet (e.g. this plugin's own `scanOnStart` is off and no other BLE plugin happens to be scanning)
+ * would sit on `bleApi.connectGATT()` until that call's own `timeoutMs` gives up, rather than the
+ * plugin quietly rediscovering it the way the direct-BlueZ backend already does.
+ */
+export declare function ensureDeviceVisible(bleApi: BLEApi, pluginId: string, address: string, timeoutMs: number): Promise<void>;
 /**
  * `bleApi.connectGATT()` has no timeout of its own, same story as node-ble's `Device#connect()` (see
  * `connectWithTimeout` in `bleDiscovery.ts`) - races it against `timeoutMs`.

package/dist/devices/bleBackend.js

@@ -1,10 +1,81 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.withSessionWatchdog = withSessionWatchdog;
 exports.nodeBleBackend = nodeBleBackend;
+exports.ensureDeviceVisible = ensureDeviceVisible;
 exports.bleApiBackend = bleApiBackend;
+const pluginVersion_1 = require("../pluginVersion");
 const bleDiscovery_1 = require("./bleDiscovery");
 /** How long to wait for BlueZ to have (or acquire) a `Device` object for the target address before giving up - a separate budget from the connect step itself, matching both drivers' previous hardcoded constant. */
 const DEVICE_DISCOVERY_TIMEOUT_MS = 30000;
+/**
+ * Bounds the whole post-connect GATT session (service discovery, every read/write/notification a
+ * driver's `paint()` makes until it calls `disconnect()`), not just the connect step above - unlike
+ * `connectWithTimeout`/`bleApiBackend`'s connect race, neither backend's underlying `write()` or
+ * `discoverServices()` has any timeout of its own, so a hang there (plausible against a flaky real
+ * device) would otherwise sit forever with the connection, and any BLE Manager GATT claim, held open
+ * - see `withSessionWatchdog`. Generous relative to any single driver operation's own timeout (e.g.
+ * gicisky's 15s per-chunk ack) since it has to cover a whole multi-chunk image transfer, not one step
+ * of it; it's a last-resort backstop, not a normal-path budget.
+ */
+const GATT_SESSION_WATCHDOG_MS = 5 * 60000;
+/**
+ * Wraps a connected `GattConnection` so the session as a whole - not just the connect step - can't
+ * hang forever. Starts a single timer when the connection opens; if `disconnect()` hasn't been
+ * called (i.e. the caller's `paint()` hasn't finished, successfully or not) by the time it fires,
+ * treats the session as stuck: calls `forceClose` (which must tear down the connection and, for a
+ * shared backend, release any claim on it) and fails every call still outstanding or made afterwards.
+ * `Promise.race`ing each call against that same failure - rather than just refusing new calls once
+ * killed - is what actually unblocks a caller `await`ing a hung `write()`/`discoverServices()`:
+ * forcing the underlying connection closed doesn't guarantee the hung call's own promise ever
+ * settles, so the caller needs a second, independent way to move on.
+ */
+function withSessionWatchdog(conn, timeoutMs, forceClose) {
+    let killedError;
+    let resolveKilled;
+    const killed = new Promise((resolve) => {
+        resolveKilled = resolve;
+    });
+    let settled = false;
+    // `unref()` so this backstop timer never itself keeps the process alive (e.g. the CLI's `paint`
+    // command exiting naturally once its work is done) - it only ever needs to fire while something
+    // else is already keeping the event loop running anyway.
+    const timer = setTimeout(() => {
+        if (settled)
+            return;
+        killedError = new Error(`GATT session watchdog fired after ${timeoutMs}ms with no completion - forcing disconnect`);
+        console.error(`${pluginVersion_1.PLUGIN_NAME}: ${killedError.message}`);
+        resolveKilled(killedError);
+        void forceClose().catch(() => { });
+    }, timeoutMs).unref();
+    function guard(op) {
+        if (killedError)
+            return Promise.reject(killedError);
+        const result = op();
+        result.catch(() => { }); // observed here too, so losing the race below never surfaces as an unhandled rejection
+        return Promise.race([result, killed.then((err) => Promise.reject(err))]);
+    }
+    return {
+        read: (serviceUuid, charUuid) => guard(() => conn.read(serviceUuid, charUuid)),
+        write: (serviceUuid, charUuid, data, withResponse) => guard(() => conn.write(serviceUuid, charUuid, data, withResponse)),
+        startNotifications: (serviceUuid, charUuid, callback) => guard(() => conn.startNotifications(serviceUuid, charUuid, callback)),
+        stopNotifications: (serviceUuid, charUuid) => guard(() => conn.stopNotifications(serviceUuid, charUuid)),
+        discoverServices: () => guard(() => conn.discoverServices()),
+        onDisconnect: conn.onDisconnect.bind(conn),
+        get connected() {
+            return conn.connected;
+        },
+        async disconnect() {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (killedError)
+                return; // already forced closed by the watchdog above
+            await conn.disconnect();
+        },
+    };
+}
 function nodeBleBackend() {
     return {
         async connectGatt(address, timeoutMs) {
@@ -14,7 +85,14 @@ function nodeBleBackend() {
                 const device = await (0, bleDiscovery_1.getOrDiscoverDevice)(adapter, address, DEVICE_DISCOVERY_TIMEOUT_MS);
                 await (0, bleDiscovery_1.connectWithTimeout)(device, timeoutMs);
                 const conn = (0, bleDiscovery_1.openNodeBleGattConnection)(device);
-                return {
+                let destroyed = false;
+                const destroyOnce = () => {
+                    if (destroyed)
+                        return;
+                    destroyed = true;
+                    destroy();
+                };
+                const gatt = {
                     read: conn.read.bind(conn),
                     write: conn.write.bind(conn),
                     startNotifications: conn.startNotifications.bind(conn),
@@ -25,10 +103,22 @@ function nodeBleBackend() {
                         return conn.connected;
                     },
                     async disconnect() {
-                        await conn.disconnect();
-                        destroy();
+                        try {
+                            await conn.disconnect();
+                        }
+                        finally {
+                            destroyOnce();
+                        }
                     },
                 };
+                return withSessionWatchdog(gatt, GATT_SESSION_WATCHDOG_MS, async () => {
+                    // `device.disconnect()` can hang for the same underlying reason the operations
+                    // `withSessionWatchdog` already guards can (see its doc comment) - race it briefly rather
+                    // than awaiting it unbounded here too, but tear down the D-Bus connection either way so
+                    // those resources don't leak even if BlueZ's disconnect itself never completes.
+                    await Promise.race([gatt.disconnect(), (0, bleDiscovery_1.sleep)(5000)]);
+                    destroyOnce();
+                });
             }
             catch (err) {
                 destroy();
@@ -48,6 +138,35 @@ function nodeBleBackend() {
         },
     };
 }
+/**
+ * Waits for the BLE Manager to know about `address` before a GATT connect is attempted against it -
+ * mirrors `getOrDiscoverDevice` in `bleDiscovery.ts`, which gives `nodeBleBackend` the same guarantee
+ * against BlueZ directly. Without this, a specifically-addressed device that the manager hasn't seen
+ * yet (e.g. this plugin's own `scanOnStart` is off and no other BLE plugin happens to be scanning)
+ * would sit on `bleApi.connectGATT()` until that call's own `timeoutMs` gives up, rather than the
+ * plugin quietly rediscovering it the way the direct-BlueZ backend already does.
+ */
+async function ensureDeviceVisible(bleApi, pluginId, address, timeoutMs) {
+    const known = await bleApi.getDevice(address).catch(() => null);
+    if (known)
+        return;
+    const seen = await new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            unsubscribe();
+            resolve(false);
+        }, timeoutMs);
+        const unsubscribe = bleApi.onAdvertisement(pluginId, (adv) => {
+            if (adv.mac !== address)
+                return;
+            clearTimeout(timer);
+            unsubscribe();
+            resolve(true);
+        });
+    });
+    if (!seen) {
+        throw new Error(`device ${address} isn't visible to the SignalK BLE Manager yet (out of range, asleep, or never seen) after waiting ${timeoutMs}ms`);
+    }
+}
 /**
  * `bleApi.connectGATT()` has no timeout of its own, same story as node-ble's `Device#connect()` (see
  * `connectWithTimeout` in `bleDiscovery.ts`) - races it against `timeoutMs`.
@@ -60,6 +179,7 @@ function bleApiBackend(bleApi, pluginId) {
             // "already claimed" until the server restarts - see signalk-bluetti-plugin's BleManagerDevice
             // for the same defensive call. A no-op if we don't currently hold the claim.
             await bleApi.releaseGATTDevice(address, pluginId).catch(() => { });
+            await ensureDeviceVisible(bleApi, pluginId, address, DEVICE_DISCOVERY_TIMEOUT_MS);
             const connecting = bleApi.connectGATT(address, pluginId);
             let timedOut = false;
             const conn = await Promise.race([connecting, (0, bleDiscovery_1.sleep)(timeoutMs).then(() => void (timedOut = true))]);
@@ -78,13 +198,26 @@ function bleApiBackend(bleApi, pluginId) {
                     .then(() => connecting.then((c) => c.disconnect()).catch(() => { }));
                 throw new Error(`connecting to device timed out after ${timeoutMs}ms`);
             }
-            return conn;
+            return withSessionWatchdog(conn, GATT_SESSION_WATCHDOG_MS, async () => {
+                // Belt-and-suspenders, matching the timeout-cleanup above: `releaseGATTDevice` is the
+                // authoritative claim release, `disconnect()` a secondary teardown of this specific handle -
+                // do both regardless of which (if either) itself hangs or rejects.
+                await Promise.allSettled([bleApi.releaseGATTDevice(address, pluginId), conn.disconnect()]);
+            });
         },
         async waitForManufacturerData(address, manufacturerId, timeoutMs) {
             // Unlike node-ble's `device.getManufacturerData()`, there's no cached-instant-read path here -
             // `BLEDeviceInfo` (from `getDevices()`/`getDevice()`) carries mac/name/rssi/seenBy but not
             // manufacturer data (see `BLEDeviceInfoSchema` in `@signalk/server-api`'s `ble-schemas.ts`) -
             // only the streamed `BLEAdvertisement` does. So this always actively waits on the stream.
+            //
+            // Same defensive release as `connectGatt`, and just as necessary here: a device the BLE Manager
+            // still thinks *we* hold a GATT claim on (e.g. from a crash/reload mid-paint, before this call
+            // 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.
+            await bleApi.releaseGATTDevice(address, pluginId).catch(() => { });
             return new Promise((resolve) => {
                 const timer = setTimeout(() => {
                     unsubscribe();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizomatics/signalk-einklabel-plugin",
-  "version": "1.3.0-beta2",
+  "version": "1.3.0-beta4",
   "description": "Display SignalK data on eInk Electronic Shelf Labels, includes working examples for tide clock and watch schedule.",
   "keywords": [
     "ble",

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