@rhizomatics/signalk-einklabel-plugin 0.10.0 → 1.0.0

package/CHANGELOG.md

@@ -1,9 +1,28 @@
+# 1.0.0
+
+## Full Release
+
+- The `1.0.0` reflects that this plugin has been working in real environment for months, and has been refactored for better extensibility
+
+## Extension Support
+
+- Custom templates and CLI commands can now be provided by a different plugin
+- Initially this is to support `signalk-einklabel-genai-plugin` which can use a prompt to make an image using a GenAI service like Anthropic or local Ollama
+
 # 0.10.1
 
+- Test fixes
+- Moved blank templates to `.blank` directory and suppressed from drop down selection
+- Added recommendations for `signalk-tides` and `signalk-watch-schedule` plugins
+
+# 0.10.0
+
 ## Watch Schedule Example
+
 - New template to show current and next crew watch, using `signalk-watch-schedule` plugin
 
 ## CLI / Debugging
+
 - `fields` command now reports where text field definitions can't be interpreted
 - Epoch style timestamps now automatically handled as if proper date time for format options
 
@@ -21,8 +40,7 @@
 
 ## Fixes
 
-- Fix configuration JSON holding older versions of itself as subentries
-  and data changes
+- Fix configuration JSON holding older versions of itself as subentries and data changes
 - Fix most cases of scanned devices not appearing in device dropdown choice
 
 ## Improvements

package/README.md

@@ -7,9 +7,9 @@
 [![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)
 
-    Fully working but limited vendor/product support and requires Linux for device access.
+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.
 
-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.
+![Companionway Tidal Clock](docs/assets/images/real_tidal_clock.jpg)
 
 ## What is an ESL?
 
@@ -27,13 +27,13 @@ Most of requirements below are to make SignalK work with Bluetooth Low Energy, w
 
 1. A SignalK server, **running Linux**
 
-- MacOS and Windows aren't supported by the [BLE interface layer](https://www.npmjs.com/package/@naugehyde/node-ble), however can be used for template development and
+- MacOS and Windows aren't supported by the [BLE interface layer](https://www.npmjs.com/package/@naugehyde/node-ble), however they can be used for template development and
   debugging (everything except `scan` and `paint`)
 
 2. A Bluetooth adapter, that can handle BLE (Bluetooth Low Energy).
 
 - Bluetooth adapters for Linux can be tricky, TP-Link UB400 and Asus USB-BT500 are two well-known and available ones
-- Some Raspberry Pi models come with suitable Bluetooth it built-in
+- Some Raspberry Pi models come with suitable Bluetooth built in
 - Don't worry about the very latest Bluetooth versions, 4.0 is minimum for BLE, 5.0 is nice
 - Home Assistant is massively more popular than SignalK, and often also run on Raspberry Pi and similar, so good source of advice
 
@@ -44,14 +44,14 @@ Most of requirements below are to make SignalK work with Bluetooth Low Energy, w
 
 4. One or more supported Electronic Shelf Labels
 
-- The label used for testing this is the [ZhunyCo 3.7" BRWY](https://www.aliexpress.com/item/1005010050104435.html)
+- The label used for testing this is the [Zhsunyco 3.7" BWRY](https://www.aliexpress.com/item/1005010050104435.html)
 
 5. Correct time zone set on server if local time is to be shown on display
 
 - See [FAQ](#faq-timezone)
 - If not set, everything will work, but you may see the wrong zone or not have daylight savings applied
 
-Once you have all of that, it may be worth also installing [signalk-victron-ble](https://github.com/stefanor/signalk-victron-ble),[signalk-ruuvitag-plugin](https://github.com/vokkim/signalk-ruuvitag-plugin) or [bt-sensors-plugin](https://github.com/naugehyde/bt-sensors-plugin-sk) to pull in data from other sensors and equipment.
+Once you have all of that, it may be worth also installing [signalk-victron-ble](https://github.com/stefanor/signalk-victron-ble), [signalk-ruuvitag-plugin](https://github.com/vokkim/signalk-ruuvitag-plugin) or [bt-sensors-plugin](https://github.com/naugehyde/bt-sensors-plugin-sk) to pull in data from other sensors and equipment.
 
 ## Installation
 
@@ -89,7 +89,7 @@ A _tides_ provider plugin for the Resources API installed and enabled, currently
 
 The [tides](https://github.com/rhizomatics/signalk-einklabel-plugin/blob/main/templates/tides/) templates can be customized to run with any tide provider, a specific one, or switch to other APIs or SignalK data paths.
 
-- In the template it uses a SVG description like `source=resources,resource=tides,provider=tides,path=extremes[0].time,format=local_time` to get the first tide time, ensures its the preferred `signalk-tides` provider and makes it a simple local time rather than a UTC date time.
+- In the template it uses a SVG description like `source=resources,resource=tides,provider=tides,path=extremes[0].time,format=local_time` to get the first tide time, ensures it's the preferred `signalk-tides` provider and makes it a simple local time rather than a UTC date-time.
 
 To show the lunar phase, the `environment.moon.phaseName` path is required, which can
 be easily achieved by installing and configuring the `derived-data` plugin.
@@ -107,29 +107,30 @@ Template available as 416x240-BWRY for 3.7" ESLs.
 
 ## Setting up a Label
 
-Enable the plugin, and use the large **+** sign to add a label, which open up these fields.
+Enable the plugin, and use the large **+** sign to add a label, which opens up these fields.
 
 ![Label Config](docs/assets/screenshots/label_config.png)
 
 - _Friendly Name_ - Give the label any name (word or phrase) you like, for example 'Tide Clock'
-- _Device_ - Unless you have multiple labels, don't bother with pre-scanning or selecting a specifig device, instead pick **"All discovered devices"** and it will paint any compatible labels it finds. If you want to pick a specific device, you'll need to wait for a device scan to complete.
-- _Template_ - Choose a built in template, or one you've added to the local templates directory
+- _Device_ - Unless you have multiple labels, don't bother with pre-scanning or selecting a specific device, instead pick **"All discovered devices"** and it will paint any compatible labels it finds. If you want to pick a specific device, you'll need to wait for a device scan to complete.
+- _Template_ - Choose a built-in template, one you've added to the local templates directory, or - if a companion plugin like [`@rhizomatics/signalk-einklabel-genai-plugin`](#genai-rendering) is installed - one of its own contributed entries (shown with a suffix, e.g. "forecast (GenAI)")
+- _Location/description_ - Optional free-text notes on where this label is physically mounted/viewed from, e.g. "chart table, viewed from ~1m in poor light" - available to any template as `source=einklabel,path=description` or `source=label,path=description`
 - _Repaint Trigger_- Do you want this to repaint every few hours (at a chosen minutes past hour), or when a SignalK path changes?
-  - If its a SignalK path, enter it next, for example `environment.tide.state`
-  - If its time based, enter how many hours between repaints, for example 00:00/08:00/16:00 for an 8h schedule, and if you want a specific number of minutes after the hour.
+  - If it's a SignalK path, enter it next, for example `environment.tide.state`
+  - If it's time based, enter how many hours between repaints, for example 00:00/08:00/16:00 for an 8h schedule, and if you want a specific number of minutes after the hour.
 
 There are also two more advanced options, which can usually be ignored.
 
 - _BLE AES key_ - Only needed if the default key doesn't work and you have a better alternative, otherwise ignore
 - _Force Repaint_ - Next time the label is due to be painted, update even if the data or template hasn't changed (this flag will automatically be cleared after this.)
 
-When the plugin starts, it will automatically re-paint the label if its new, or the last timed slot was missed and the data has changed.
+When the plugin starts, it will automatically re-paint the label if it's new, or the last timed slot was missed and the data has changed.
 
 ### Scanning for Devices
 
 Since these are ultra-low power devices, they don't respond instantly to either identify themselves or accept a new image. By default, both scanning and painting have time-outs to wait for a response, which can be altered in the plugin configuration or CLI argument.
 
-One other quirk is that some devices respond with a different name at different times, for example the genric `WOESL` sometimes and model specific `WL17500C74` other times. However, the MAC address, e.g. `66:66:17:50:0D:2B` is constant, and this is what's tracked by the plugin.
+One other quirk is that some devices respond with a different name at different times, for example the generic `WOESL` sometimes and model specific `WL17500C74` other times. However, the MAC address, e.g. `66:66:17:50:0D:2B` is constant, and this is what's tracked by the plugin.
 
 The plugin can optionally re-scan whenever it starts up (off by default), although this isn't essential once a label has been configured. Devices found by any scan are remembered across restarts - see the FAQ below.
 
@@ -207,6 +208,8 @@ Note that for dates and times, the server timezone must be set correctly, for ex
 
 Additionally, `round=n` can be used to round to limited decimal places.
 
+`default=<value>` substitutes `<value>` whenever the resolved value is missing (e.g. an unpublished path), instead of falling through to an empty string - useful anywhere a blank would be misread as a real answer. `default=` with nothing after the `=` still counts as set, deliberately defaulting to an empty string rather than leaving the fallback behaviour unchanged.
+
 These can all be combined as in `source=resources,resource=tides,provider=tides,path=extremes[2].level,category=depth,round=2`
 
 ### Non-Textual Fields (Images)
@@ -231,6 +234,16 @@ Three font types are loaded by default, use the generic font family, or exact fo
 - `sans-serif` - `Roboto`
 - `monospace` - `Roboto Mono`
 
+## GenAI Rendering
+
+As an alternative to hand-designed SVG templates, a device's content can be generated by an LLM instead - this is provided entirely by a separate companion plugin, [`@rhizomatics/signalk-einklabel-genai-plugin`](https://github.com/rhizomatics/signalk-einklabel-genai-plugin), not by this core plugin. The base plugin (BLE painting, SVG templates) has nothing to do with any LLM SDK or API key, so installing it never pulls in GenAI dependencies unless you also explicitly install and enable the companion plugin - the split is deliberate, for anyone on a small/constrained install or who'd simply rather not have any GenAI code in their install at all.
+
+Once the companion plugin is installed and enabled, its own config screen handles provider/model/API-key selection (OpenAI, Anthropic, Google, xAI, DeepSeek, Moonshot AI, Ollama, or any other OpenAI-compatible endpoint), and its prompts show up as ordinary entries in this plugin's "Template" dropdown, suffixed (e.g. "forecast (GenAI)") - pick one exactly like you'd pick a `.svg` file. Under the hood it's a `TemplateProvider` (see [Extending](#extending) below) - the same extension mechanism a new vendor's hardware driver uses - so from this plugin's point of view it's just another way `templateName` gets resolved to an image.
+
+If the LLM call fails (network/API error, exhausted retries) or its response isn't renderable, this core plugin pushes its own bundled warning template instead of leaving the previous, possibly now-wrong, content on screen - so a stale weather prompt never quietly shows yesterday's forecast through today's storm. This is a generic safety net, not GenAI-specific: the exact same fallback covers a broken hand-authored template failing to render at all. The next scheduled repaint retries automatically. Since each repaint may call a (usually paid) LLM API, a GenAI-backed device should use Repaint Trigger `interval`, not `subscription`.
+
+See the companion plugin's own README for installing it, writing prompts, and its `esl-cli prompt`/`generate` commands for testing prompts without a device.
+
 ## Architecture
 
 The primary things managed and provided by the plugin are:
@@ -257,7 +270,9 @@ See also the commands useful for debugging under [Developing Templates]
 - `render` - transform an SVG template and data into a PNG
 - `paint` - render an SVG template and data to a selected ESL
 
-The width, height, vertical offset and colour palette for the device is taken from the internal register of devices, however can be overridden on the command line. This could be used to help you choose what size of label to buy, or to get an unsupported label working.
+The width, height, vertical offset and colour palette for the device are taken from the internal register of devices, however can be overridden on the command line. This could be used to help you choose what size of label to buy, or to get an unsupported label working.
+
+`esl-cli` can also be extended with new subcommands by a `-r/--require`'d package - see [Extending](#extending) below - which is how [`@rhizomatics/signalk-einklabel-genai-plugin`](#genai-rendering) adds its own `prompt`/`generate` commands for testing prompts without a device.
 
 ( The CLI can also be run from a checked out module, or by opening a terminal shell at `~/.signalk/node_modules/@rhizomatics/signalk-einklabel-plugin`, as `npx esl-cli command --args` )
 
@@ -278,7 +293,13 @@ Additional vendors and devices can be added by a separate npm package that imple
 
 - `import esl from '@rhizomatics/signalk-einklabel-plugin'; esl.registerVendorDriver(myDriver)`
 - In the SignalK runtime, call this from the extension's own plugin `start()`. In the CLI, load the extension with `esl-cli --require <module> <command>`.
-- Declare this package as a `peerDependency` (not a regular dependency) in the extension package, so npm resolves a single shared copy of the registry.
+- Declare this package as a regular npm `dependency` in the extension package - **not** a `peerDependency`, per SignalK's own guidance that npm's peer-dependency resolution interacts poorly with the server's plugin install layout - and declare the SignalK-level relationship via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }` in the extension's own `package.json` instead, so the App Store can install/report it.
+
+### 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`](#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.
+
+`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.
 
 ### Developing Templates
 
@@ -351,7 +372,7 @@ For example, `npx esl-cli fields -t templates/tide.svg -e examples` will show al
 
 ### I can't see my device as a choice on the drop-down list after scan
 
-SignalK plugins lack ability to self-update after something like a scan, so first time round you may have to close the config and reload it to see this. Subsequently the plugin will remember all scanned devices, and only drop previously seen ones if it goes 24 hours without a positive scan or with failed paint attempts.
+SignalK plugins lack the ability to self-update after something like a scan, so first time round you may have to close the config and reload it to see this. Subsequently the plugin will remember all scanned devices, and only drop previously seen ones if it goes 24 hours without a positive scan or with failed paint attempts.
 
 Easiest way to solve this is to choose 'All Discovered Devices' in the device configuration, and it will paint any compatible devices it finds on future scans.
 
@@ -359,12 +380,12 @@ Easiest way to solve this is to choose 'All Discovered Devices' in the device co
 
 If the plugin repaints a display at server startup, then the plugin that provides the data may not have started ( or in the case of `derived-data` the plugin that the plugin depends on! ) and unlike Home Assistant, there's no good way of sequencing the start of plugins.
 
-Use the _settle_ time, to impose a minimum wait between the eInk Label plugin being initialized, and it attempting to paint any displays, and increase this value if its still missing data.
+Use the _settle_ time, to impose a minimum wait between the eInk Label plugin being initialized, and it attempting to paint any displays, and increase this value if it's still missing data.
 
 ### Times are showing incorrectly {#faq-timezone}
 
 If times are in the wrong timezone, or don't have daylight savings applied correctly,
-then check that the server itself (at the Linux level, not SignalK, which doesn't know)is configured for your timezone, assuming of course that you're a coastal sailor. Use `raspi-config` on a Raspberry Pi, or `timedatectl` on a Linux server.
+then check that the server itself (at the Linux level, not SignalK, which doesn't know) is configured for your timezone, assuming of course that you're a coastal sailor. Use `raspi-config` on a Raspberry Pi, or `timedatectl` on a Linux server.
 
 If you're a global cruiser, then use something like [signalk-set-gps-timezone](https://github.com/hoeken/signalk-set-gps-timezone) to set the value in the operating system.
 
@@ -374,16 +395,47 @@ Try a BLE proxy device, ESP32 is popular for this.
 
 ### Can't edit the text contents of SVG template in VSCode
 
-If you have an SVG viewer extension, this wll show the image rather than allowing editing of text. To solve, right click on the file in VSCode _Explorer_ view and choose to edit with _Text Editor_.
+If you have an SVG viewer extension, this will show the image rather than allowing editing of text. To solve, right click on the file in VSCode _Explorer_ view and choose to edit with _Text Editor_.
 
 ### Description is set in InkScape but doesn't render
 
 Check if the text boxes are normal text or flowed text, and correct to normal text.
 
-## Other ESL and General eInk Resources
+### My label just shows "CONTENT UNAVAILABLE"
+
+That's the bundled fallback warning, not necessarily an error in this plugin - it means the most recent repaint failed, whatever produced the content (a broken hand-authored template, or a `TemplateProvider` extension like [`@rhizomatics/signalk-einklabel-genai-plugin`](#genai-rendering) - e.g. its LLM call failing on no network/API access, an invalid API key, or a response that wasn't a renderable SVG, after using up its configured retries). Check the SignalK server logs (debug logging on for this plugin) for the specific error, and if it's a GenAI device, check that plugin's own provider/API key/model settings. This plugin deliberately never leaves old content on screen when a repaint fails - it retries automatically at the next scheduled interval.
+
+### SignalK starts before the Bluetooth daemon — does the plugin need `bluetoothd` running at boot?
+
+The plugin retries BLE adapter initialisation with backoff (starting at 2s, capping at 30s) if `bluetoothd`/D-Bus isn't up yet when the plugin starts, so a slow-starting Bluetooth stack on boot will no longer strand it — it keeps retrying until the adapter appears rather than failing once and giving up. You'll see `BLE adapter not ready … — retrying in Ns …` in the SignalK logs in the meantime.
+
+That said, it's cleaner to fix the boot ordering at the systemd level so the plugin finds the adapter ready on its first attempt. If SignalK runs as a systemd service (`systemctl status signalk`) and its unit file has no `[Unit]` section (check with `systemctl cat signalk`), add one:
+
+```bash
+sudo systemctl edit signalk.service
+```
+
+This opens an override file — add:
+
+```ini
+[Unit]
+After=bluetooth.target
+Wants=bluetooth.target
+```
+
+Save and exit, then:
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl restart signalk
+```
+
+This tells systemd to start `bluetoothd` first and wait for it before starting SignalK, rather than relying on both racing to start in parallel at boot.
+
+## Other ESL and General eInk Resources
 
 - [Open ePaper Link](https://openepaperlink.de) - Alternative open source firmware to flash onto eInk shelf labels, with Home Assistant integration.
-- [zhsynyco-esl](https://github.com/roxburghm/zhsunyco-esl) - Python interface
+- [zhsunyco-esl](https://github.com/roxburghm/zhsunyco-esl) - Python interface
 - [WoLink](https://github.com/NickWaterton/Wolink) - Python interface and protocol analysis
 - [e-ink dashboard for Signal K](https://github.com/meri-imperiumi/dashboard) - Waveshare display based multi instrument display.
 - [eInk Dashboard Modern SK](https://github.com/VladimirKalachikhin/e-inkDashboardModernSK) - SignalK dashboard for non-ESL eInk display.

package/dist/cli/index.d.ts

@@ -1,2 +1,14 @@
 #!/usr/bin/env node
-export {};
+import { Command } from "commander";
+import { Colour } from "../devices/types";
+import { Binding } from "../render/binding";
+import { TemplateContext } from "../render/types";
+/** Tried in order when -u/--url is omitted (and -e/--example-data isn't given) - first one that answers wins. */
+export declare const DEFAULT_SIGNALK_URLS: string[];
+export declare function parseColours(code: string): Colour[];
+/** Shared by every command that takes -u/--url and -e/--example-data - -e wins when both are present; when neither is given, probes DEFAULT_SIGNALK_URLS for a default. */
+export declare function assembleContext(opts: {
+    url?: string;
+    exampleData?: string;
+}, bindings: Binding[]): Promise<TemplateContext>;
+export declare const program: Command;

package/dist/cli/index.js

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.program = exports.DEFAULT_SIGNALK_URLS = void 0;
+exports.parseColours = parseColours;
+exports.assembleContext = assembleContext;
 const promises_1 = require("fs/promises");
 const path_1 = require("path");
 const commander_1 = require("commander");
@@ -19,7 +22,7 @@ const log_1 = require("./log");
 (0, registry_1.registerDriver)(new zhsunyco_1.ZhsunycoDriver());
 const VENDOR_IDENTIFY_TIMEOUT_MS = 30000;
 /** Tried in order when -u/--url is omitted (and -e/--example-data isn't given) - first one that answers wins. */
-const DEFAULT_SIGNALK_URLS = ["http://localhost", "http://localhost:3000", "https://localhost"];
+exports.DEFAULT_SIGNALK_URLS = ["http://localhost", "http://localhost:3000", "https://localhost"];
 const COLOUR_CODES = {
     BW: ["black", "white"],
     BWR: ["black", "white", "red"],
@@ -34,7 +37,7 @@ function parseColours(code) {
 }
 /** Probes DEFAULT_SIGNALK_URLS in order and returns the first that answers a plain GET - used when -u/--url is omitted. */
 async function resolveDefaultUrl() {
-    for (const candidate of DEFAULT_SIGNALK_URLS) {
+    for (const candidate of exports.DEFAULT_SIGNALK_URLS) {
         try {
             (0, log_1.logDebug)(`probing ${candidate} as a default SignalK server`);
             await (0, httpJson_1.fetchJson)(`${candidate}/signalk`);
@@ -44,7 +47,7 @@ async function resolveDefaultUrl() {
             (0, log_1.logDebug)(`${candidate} did not answer: ${err.message}`);
         }
     }
-    throw new Error(`no -u/--url given and none of ${DEFAULT_SIGNALK_URLS.join(", ")} answered - specify the server explicitly with -u/--url`);
+    throw new Error(`no -u/--url given and none of ${exports.DEFAULT_SIGNALK_URLS.join(", ")} answered - specify the server explicitly with -u/--url`);
 }
 /** Shared by every command that takes -u/--url and -e/--example-data - -e wins when both are present; when neither is given, probes DEFAULT_SIGNALK_URLS for a default. */
 async function assembleContext(opts, bindings) {
@@ -73,21 +76,49 @@ async function identifyVendor(address) {
         destroy();
     }
 }
-const program = new commander_1.Command();
-program.name("esl-cli").description("Local CLI for testing ESL device scan and paint without a SignalK server");
-program.option("-r, --require <module>", "require a module before running, e.g. an npm package that registers a vendor driver (repeatable)", 
-// Commander's own typings declare `previous` as always `string[]`, but at runtime it's actually
-// `undefined` on the first invocation when no default is passed to `.option()` - the `| undefined`
-// here keeps that true and makes the `= []` fallback meaningful rather than dead code.
-(value, previous = []) => [...previous, value]);
-program.option("-l, --log-level <level>", "log verbosity: info or debug (e.g. trace which URLs are fetched)", "info");
-program.hook("preAction", () => {
-    (0, log_1.setLogLevel)(program.opts().logLevel);
-    for (const mod of program.opts().require ?? []) {
-        require(mod);
+/**
+ * Values passed via `-r`/`--require` (repeatable, `--require=value` form included), read directly from
+ * `process.argv` rather than through commander - see the doc comment below on why.
+ */
+function scanRequireModules(argv) {
+    const modules = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "-r" || arg === "--require") {
+            if (argv[i + 1])
+                modules.push(argv[i + 1]);
+        }
+        else if (arg.startsWith("--require=")) {
+            modules.push(arg.slice("--require=".length));
+        }
     }
+    return modules;
+}
+// `program` is created (and exported) before anything is `require()`'d below, and before any built-in
+// `.command(...)` is defined - a `-r`'d extension module commonly `require()`s this same compiled file
+// (e.g. `require(".../dist/cli/index.js")`) to get at `program`/`assembleContext`/etc; since that's a
+// circular require back into the module currently being loaded, Node hands it back this module's
+// *exports object as it exists so far*, not the finished one - so `program` has to already be assigned
+// by this point, or the extension would see it as `undefined`.
+exports.program = new commander_1.Command();
+exports.program.name("esl-cli").description("Local CLI for testing ESL device scan and paint without a SignalK server");
+exports.program.option("-r, --require <module>", "require a module before running, e.g. an npm package that registers a vendor driver/template provider or contributes its own subcommands (repeatable) - loaded before any command is parsed", (value, previous = []) => [...previous, value]);
+exports.program.option("-l, --log-level <level>", "log verbosity: info or debug (e.g. trace which URLs are fetched)", "info");
+exports.program.hook("preAction", () => {
+    (0, log_1.setLogLevel)(exports.program.opts().logLevel);
 });
-program
+// Loaded here - after `program` exists (see above) but before any built-in `.command(...)` is defined,
+// and well before `.parseAsync()` at the bottom of this file - not in a commander `preAction` hook (as
+// this used to work), which only runs *after* commander has already resolved which command was invoked
+// and parsed its arguments. That timing is fine for a `-r`'d module that only registers a vendor driver
+// or template provider (an already-defined command's own action merely consults those registries when
+// it runs), but too late for one to contribute a brand-new *subcommand* (e.g. a companion plugin adding
+// its own `prompt`/`generate`) to this same invocation - by the time `preAction` fires, commander has
+// already decided there's no such command.
+for (const mod of scanRequireModules(process.argv)) {
+    require(mod);
+}
+exports.program
     .command("vendors")
     .description("List supported vendors and the device models each has confirmed metadata for")
     .action(() => {
@@ -114,7 +145,7 @@ program
     printRow(header);
     rows.forEach(printRow);
 });
-program
+exports.program
     .command("scan")
     .description("Scan for supported BLE ESL devices across all registered vendor drivers")
     .option("-d, --duration <seconds>", "scan duration in seconds", "10")
@@ -161,14 +192,14 @@ program
     printRow(header);
     rows.forEach(printRow);
 });
-program
+exports.program
     .command("paint")
     .description("Render a template against a live SignalK server and send it to a device")
     .option("-v, --vendor <vendor>", "vendor driver to use - if omitted, inferred from the device's advertised name")
     .requiredOption("-a, --address <address>", "BLE address of the device")
     .requiredOption("-t, --template <path>", "path to SVG template")
     .option("-u, --url <url>", "SignalK server base URL - resolves the template's source=signalk/resources bindings - if omitted, tries each of " +
-    DEFAULT_SIGNALK_URLS.join(", ") +
+    exports.DEFAULT_SIGNALK_URLS.join(", ") +
     " in turn")
     .option("-e, --example-data <dir>", "load vessels/resources from local example JSON files in <dir> (e.g. ./examples) instead of a live SignalK server - alternative to -u")
     .option("-k, --aes-key <hex>", "AES-128 key for device authentication, as 32 hex characters - defaults to the vendor's stock key if omitted")
@@ -211,13 +242,13 @@ program
     });
     console.log(`painted ${opts.address} (${bitmap.width}x${bitmap.height}) ${opts.colours}`);
 });
-program
+exports.program
     .command("render")
     .description("Render a template against a live SignalK server and write a PNG, without needing a device")
     .requiredOption("-t, --template <path>", "path to SVG template")
     .requiredOption("-o, --output <path>", "output PNG path")
     .option("-u, --url <url>", "SignalK server base URL - resolves the template's source=signalk/resources bindings - if omitted, tries each of " +
-    DEFAULT_SIGNALK_URLS.join(", ") +
+    exports.DEFAULT_SIGNALK_URLS.join(", ") +
     " in turn")
     .option("-e, --example-data <dir>", "load vessels/resources from local example JSON files in <dir> (e.g. ./examples) instead of a live SignalK server - alternative to -u")
     .option("-w, --width <px>", "render width", "416")
@@ -233,12 +264,12 @@ program
     await (0, promises_1.writeFile)(opts.output, (0, png_1.bitmapToPng)(bitmap));
     console.log(`wrote ${opts.output} (${bitmap.width}x${bitmap.height})`);
 });
-program
+exports.program
     .command("fields")
     .description("List every <desc> binding in a template by element id, with its source spec and resolved value")
     .requiredOption("-t, --template <path>", "path to SVG template")
     .option("-u, --url <url>", "SignalK server base URL - resolves the template's source=signalk/resources bindings - if omitted, tries each of " +
-    DEFAULT_SIGNALK_URLS.join(", ") +
+    exports.DEFAULT_SIGNALK_URLS.join(", ") +
     " in turn")
     .option("-e, --example-data <dir>", "load vessels/resources from local example JSON files in <dir> (e.g. ./examples) instead of a live SignalK server - alternative to -u")
     .action(async (opts) => {
@@ -296,12 +327,12 @@ program
     printRow(header);
     table.forEach(printRow);
 });
-program
+exports.program
     .command("field")
     .description("Resolve a single binding spec directly against a live SignalK server, with no template")
     .argument("<spec>", 'binding spec, e.g. "source=resources,resource=tides,path=station.name" or a bare SignalK path')
     .option("-u, --url <url>", "SignalK server base URL - resolves the spec's source=signalk/resources binding - if omitted, tries each of " +
-    DEFAULT_SIGNALK_URLS.join(", ") +
+    exports.DEFAULT_SIGNALK_URLS.join(", ") +
     " in turn")
     .option("-e, --example-data <dir>", "load vessels/resources from local example JSON files in <dir> (e.g. ./examples) instead of a live SignalK server - alternative to -u")
     .action(async (spec, opts) => {
@@ -309,7 +340,7 @@ program
     const context = await assembleContext(opts, [binding]);
     console.log((0, binding_1.renderBinding)(binding, context));
 });
-program.parseAsync(process.argv).catch((err) => {
+exports.program.parseAsync(process.argv).catch((err) => {
     console.error(err.message);
     process.exitCode = 1;
 });

package/dist/config.d.ts

@@ -17,6 +17,14 @@ export interface DeviceConfig {
      * live BLE read) and the BLE address, or the special value `ALL_DEVICES` (see above).
      */
     device: string;
+    /**
+     * Free-text notes about where this label is physically mounted/viewed from, e.g. "chart table,
+     * viewed from ~1m in poor light" - purely descriptive. Available to any template via
+     * `source=einklabel,path=description` or `source=label,path=description` (see `buildLabelContext` in
+     * `./render/binding.ts`) if it wants it - e.g. useful to a `TemplateProvider` extension (see
+     * `./render/templateProviders.ts`) tailoring content to where the label actually sits.
+     */
+    description?: string;
     /** Per-device override; if omitted, the vendor driver may fall back to a stock/manufacturer-default key. */
     aesKey?: string;
     /**
@@ -25,8 +33,13 @@ export interface DeviceConfig {
      * (e.g. `templates/tides/416x240-BWRY.svg`) - `pickBestVariant` then picks whichever file inside it
      * best matches this entry's actual device(s), so one `DeviceConfig` (and one `ALL_DEVICES` entry in
      * particular) works across different panel sizes without the user picking a file for each.
+     *
+     * Can also name an entry a registered `TemplateProvider` offers (see `./render/templateProviders.ts`)
+     * instead of a file - e.g. `signalk-einklabel-genai-plugin` contributing `"forecast (GenAI)"` -
+     * `considerRepaint` (`./repaintScheduler.ts`) checks the provider registry before falling back to
+     * resolving this as a file path.
      */
-    templateName: string;
+    templateName?: string;
     repaintTrigger: "subscription" | "interval";
     /** SignalK path to subscribe to when `repaintTrigger` is `subscription` - a repaint is considered on every delta. */
     triggerPath?: string;
@@ -93,6 +106,18 @@ export interface PluginConfig {
  * `templates/.assets/lunar_phases`) just to keep a binding the override never touched working.
  */
 export declare const BUNDLED_TEMPLATES_DIR: string;
+/**
+ * Bundled template family pushed instead of a device's real content whenever a repaint fails - a broken
+ * hand-authored template, or a registered `TemplateProvider`'s `render()` rejecting (e.g.
+ * `@rhizomatics/signalk-einklabel-genai-plugin`'s LLM call failing) - see `considerRepaint` in
+ * `./repaintScheduler.ts`. Generic on purpose: it has no idea *why* the render failed, only that it
+ * did, and that the previous, possibly now-wrong, content must never be left on screen unmarked.
+ *
+ * Dot-prefixed like `.assets`/`.blank` so `listTemplateFamilies` excludes it from the "Template"
+ * dropdown - it's an internal fallback mechanism, not something a user should ever pick as a device's
+ * own template.
+ */
+export declare const RENDER_FALLBACK_TEMPLATE_NAME = ".error";
 export declare function defaultConfig(): PluginConfig;
 export declare function readCurrentConfig(app: ServerAPI): Partial<PluginConfig>;
 /**
@@ -106,12 +131,7 @@ export declare function readCurrentConfig(app: ServerAPI): Partial<PluginConfig>
  * flattened even if nothing ever triggers that path.
  */
 export declare function healNestedConfig(app: ServerAPI): void;
-/**
- * Resolves the user-facing `templatesDir` setting to an actual directory, mirroring
- * signalk-parquet's `outputDirectory` convention: empty means the default location, a relative
- * path is resolved against `~/.signalk` (where SignalK itself stores its config by default), and
- * an absolute path is used as-is.
- */
+/** See `resolveDir` - `templatesDir`'s own resolution. */
 export declare function resolveTemplatesDir(templatesDir: string | undefined): string;
 export declare function parseDevice(device: string): {
     vendor: string;