@rhizomatics/signalk-einklabel-plugin 0.10.1 → 1.0.0

package/CHANGELOG.md

@@ -1,3 +1,14 @@
+# 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

package/README.md

@@ -7,7 +7,7 @@
 [![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)
 
-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.
+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.
 
 ![Companionway Tidal Clock](docs/assets/images/real_tidal_clock.jpg)
 
@@ -113,7 +113,8 @@ Enable the plugin, and use the large **+** sign to add a label, which opens up t
 
 - _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 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, or one you've added to the local templates directory
+- _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 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.
@@ -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:
@@ -259,6 +272,8 @@ See also the commands useful for debugging under [Developing Templates]
 
 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` )
 
 ### Scans from CLI
@@ -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
 
@@ -380,7 +401,38 @@ If you have an SVG viewer extension, this will show the image rather than allowi
 
 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.
 - [zhsunyco-esl](https://github.com/roxburghm/zhsunyco-esl) - Python interface

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;

package/dist/config.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BUNDLED_TEMPLATES_DIR = exports.ALL_DEVICES = void 0;
+exports.RENDER_FALLBACK_TEMPLATE_NAME = exports.BUNDLED_TEMPLATES_DIR = exports.ALL_DEVICES = void 0;
 exports.defaultConfig = defaultConfig;
 exports.readCurrentConfig = readCurrentConfig;
 exports.healNestedConfig = healNestedConfig;
@@ -12,6 +12,7 @@ exports.configUiSchema = configUiSchema;
 const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
+const templateProviders_1 = require("./render/templateProviders");
 const resolveApiUrl_1 = require("./resolveApiUrl");
 /**
  * Special `device` value meaning "every currently-known discovered device" instead of one specific
@@ -31,6 +32,18 @@ exports.ALL_DEVICES = "ALL";
  * `templates/.assets/lunar_phases`) just to keep a binding the override never touched working.
  */
 exports.BUNDLED_TEMPLATES_DIR = (0, path_1.join)(__dirname, "..", "templates");
+/**
+ * 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.
+ */
+exports.RENDER_FALLBACK_TEMPLATE_NAME = ".error";
 const SIGNALK_HOME_DIR = (0, path_1.join)((0, os_1.homedir)(), ".signalk");
 const DEFAULT_TEMPLATES_DIR = (0, path_1.join)(SIGNALK_HOME_DIR, "einklabel", "templates");
 function defaultConfig() {
@@ -117,18 +130,21 @@ function healNestedConfig(app) {
     });
 }
 /**
- * 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.
+ * Resolves a user-facing `<x>Dir` setting to an actual directory, mirroring signalk-parquet's
+ * `outputDirectory` convention: empty means `defaultDir`, a relative path is resolved against
+ * `~/.signalk` (where SignalK itself stores its config by default), and an absolute path is used as-is.
  */
-function resolveTemplatesDir(templatesDir) {
-    const trimmed = templatesDir?.trim();
+function resolveDir(dir, defaultDir) {
+    const trimmed = dir?.trim();
     if (!trimmed) {
-        return DEFAULT_TEMPLATES_DIR;
+        return defaultDir;
     }
     return (0, path_1.isAbsolute)(trimmed) ? trimmed : (0, path_1.join)(SIGNALK_HOME_DIR, trimmed);
 }
+/** See `resolveDir` - `templatesDir`'s own resolution. */
+function resolveTemplatesDir(templatesDir) {
+    return resolveDir(templatesDir, DEFAULT_TEMPLATES_DIR);
+}
 /**
  * Enum for the combined "device" field, built from recently scanned devices - including ones a
  * driver identified as its vendor but whose PID isn't in its metadata table yet (clearly labelled,
@@ -219,11 +235,18 @@ function listTemplateFamilies(dir) {
         .filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && listTemplateVariants((0, path_1.join)(dir, entry.name)).length > 0)
         .map((entry) => entry.name);
 }
-/** Local templates (files or template-family directories) take priority over a same-named bundled one; both show up as options. */
+/**
+ * Local templates (files or template-family directories) take priority over a same-named bundled one;
+ * both show up as options, followed by every registered `TemplateProvider`'s own entries (e.g.
+ * `signalk-einklabel-genai-plugin` contributing `"forecast (GenAI)"` - see `./render/templateProviders.ts`)
+ * - so a provider-backed "template" is picked from this exact same dropdown, distinguished only by its
+ * `suffix`, with no separate render-mode field at all.
+ */
 function templateNameOptions(templatesDir) {
     const local = [...listSvgFiles(templatesDir), ...listTemplateFamilies(templatesDir)];
     const bundled = [...listSvgFiles(exports.BUNDLED_TEMPLATES_DIR), ...listTemplateFamilies(exports.BUNDLED_TEMPLATES_DIR)].filter((name) => !local.includes(name));
-    return [...local, ...bundled];
+    const provided = (0, templateProviders_1.allTemplateProviders)().flatMap((provider) => provider.listTemplates());
+    return [...local, ...bundled, ...provided];
 }
 function sameColours(a, b) {
     if (a.length !== b.length)
@@ -350,6 +373,12 @@ function configSchema(app, discovered = []) {
                                 'address, or "All discovered devices" to paint this same template/trigger to every device the plugin currently ' +
                                 "knows about - simplest for a single label, and also covers several identical labels without listing each one.",
                         }, deviceValues, deviceLabels),
+                        description: {
+                            type: "string",
+                            title: "Location/description (optional)",
+                            description: 'Free-text notes about 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.',
+                        },
                         templateName: withEnum({ type: "string", title: "Template" }, templateNameOptions(resolveTemplatesDir(current.templatesDir))),
                         repaintTrigger: {
                             type: "string",
@@ -392,6 +421,7 @@ function configUiSchema() {
     return {
         devices: {
             items: {
+                description: { "ui:widget": "textarea" },
                 repaintTrigger: { "ui:widget": "radio" },
             },
         },

package/dist/devices/types.d.ts

@@ -13,6 +13,14 @@ export interface DeviceMetadata {
      * that should be treated as the default/fallback for that PID.
      */
     hwVersion?: string;
+    /**
+     * Real-world brand name (e.g. "Zhsunyco") - distinct from `VendorDriver.vendor` (e.g. also
+     * "zhsunyco"), which is this codebase's internal BLE-protocol driver key rather than a name meant
+     * for display. Optional since a CLI/config `DeviceModelOverride` for unsupported hardware has no
+     * table entry to source it from - `considerLlmPromptRepaint` (repaintScheduler.ts) falls back to
+     * the driver's own `vendor` key when unset, for a `source=label,path=manufacturer` prompt binding.
+     */
+    manufacturer?: string;
     label: string;
     width: number;
     height: number;

package/dist/devices/zhsunyco/metadata.js

@@ -22,6 +22,7 @@ exports.ZHSUNYCO_PID_METADATA = void 0;
 exports.ZHSUNYCO_PID_METADATA = [
     {
         pid: 0x0008,
+        manufacturer: "Zhsunyco",
         label: '1.54"',
         width: 200,
         height: 200,
@@ -30,6 +31,7 @@ exports.ZHSUNYCO_PID_METADATA = [
     },
     {
         pid: 0x000a,
+        manufacturer: "Zhsunyco",
         label: '2.13"',
         width: 250,
         height: 128,
@@ -38,6 +40,7 @@ exports.ZHSUNYCO_PID_METADATA = [
     },
     {
         pid: 0x000e,
+        manufacturer: "Zhsunyco",
         label: '3.7"',
         width: 416,
         height: 240,
@@ -47,6 +50,7 @@ exports.ZHSUNYCO_PID_METADATA = [
     {
         pid: 0x000e,
         hwVersion: "0103",
+        manufacturer: "Zhsunyco",
         label: '2.13"',
         width: 250,
         height: 128,
@@ -56,6 +60,7 @@ exports.ZHSUNYCO_PID_METADATA = [
     {
         pid: 0x000e,
         hwVersion: "0201",
+        manufacturer: "Zhsunyco",
         label: '3.5"',
         width: 384,
         height: 184,
@@ -65,6 +70,7 @@ exports.ZHSUNYCO_PID_METADATA = [
     {
         pid: 0x000e,
         hwVersion: "0203",
+        manufacturer: "Zhsunyco",
         label: '7.5"',
         width: 800,
         height: 480,
@@ -73,6 +79,7 @@ exports.ZHSUNYCO_PID_METADATA = [
     },
     {
         pid: 0x0012,
+        manufacturer: "Zhsunyco",
         label: '2.9"',
         width: 296,
         height: 128,
@@ -81,6 +88,7 @@ exports.ZHSUNYCO_PID_METADATA = [
     },
     {
         pid: 0x0016,
+        manufacturer: "Zhsunyco",
         label: '4.2"',
         width: 400,
         height: 300,
@@ -89,6 +97,7 @@ exports.ZHSUNYCO_PID_METADATA = [
     },
     {
         pid: 0x001a,
+        manufacturer: "Zhsunyco",
         label: '5.8"',
         width: 648,
         height: 480,

package/dist/index.d.ts

@@ -1,6 +1,13 @@
 import { ServerAPI, Plugin } from "@signalk/server-api";
 import { registerDriver, getDriver, allDrivers } from "./devices/registry";
+import { registerTemplateProvider as registerTemplateProviderImpl, findTemplateProvider as findTemplateProviderImpl, allTemplateProviders as allTemplateProvidersImpl } from "./render/templateProviders";
+import { SvgRenderer } from "./render/svgRenderer";
+import { bitmapToPng as bitmapToPngImpl } from "./render/png";
+import { buildLabelContext, findTextBindings, substituteTextBindings } from "./render/binding";
 import type { VendorDriver as VendorDriverType, DeviceMetadata as DeviceMetadataType, DiscoveredDevice as DiscoveredDeviceType, VendorDeviceConfig as VendorDeviceConfigType, Colour as ColourType } from "./devices/types";
+import type { TemplateProvider as TemplateProviderType, TemplateRenderRequest as TemplateRenderRequestType } from "./render/templateProviders";
+import type { LabelMeta as LabelMetaType } from "./render/binding";
+import type { Bitmap as BitmapType, TemplateContext as TemplateContextType } from "./render/types";
 /**
  * Public extension point for vendor packages. A package that adds support for a new
  * ESL vendor (e.g. `signalk-esl-shoplabelcorp-plugin`) imports this module and calls
@@ -8,19 +15,45 @@ import type { VendorDriver as VendorDriverType, DeviceMetadata as DeviceMetadata
  * `start()` (or at module load time). There's no scanning of installed packages -
  * registration is always an explicit call by the extension's own code.
  *
- * Declare this package as a `peerDependency` (not a regular dependency) in the
- * extension package, so npm resolves a single shared copy - otherwise the extension
- * would register into a different registry instance than the one this plugin reads from.
+ * Declare this package as a regular `dependency` in the extension package (**not** a
+ * `peerDependency` - the SignalK team's own guidance is that npm's peer-dependency resolution
+ * interacts poorly with the server's plugin install layout), and declare the SignalK-level
+ * relationship via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }` in the
+ * extension's own package.json instead, so the App Store can install/report the dependency.
  */
 declare function plugin(app: ServerAPI): Plugin;
 declare namespace plugin {
     const registerVendorDriver: typeof registerDriver;
     const getVendorDriver: typeof getDriver;
     const allVendorDrivers: typeof allDrivers;
+    /**
+     * Public extension point for a package offering an alternative to hand-authored SVG templates - e.g.
+     * `@rhizomatics/signalk-einklabel-genai-plugin` generating content from an LLM prompt - see
+     * `TemplateProvider`'s own doc comment (`./render/templateProviders.ts`) for the full contract. Same
+     * regular-`dependency`-plus-`signalk.requires` convention as `registerVendorDriver` above.
+     */
+    const registerTemplateProvider: typeof registerTemplateProviderImpl;
+    const getTemplateProvider: typeof findTemplateProviderImpl;
+    const allTemplateProviders: typeof allTemplateProvidersImpl;
+    /** Rasterizes an SVG string to a `Bitmap` - a template provider needs this to turn whatever SVG it produces (e.g. an LLM's response) into paintable pixels, exactly as a bundled template is rendered. */
+    const Renderer: typeof SvgRenderer;
+    /** Encodes a `Bitmap` as PNG bytes - useful for a CLI extension writing a preview file, same as the core plugin's own `render`/`generate` commands. */
+    const bitmapToPng: typeof bitmapToPngImpl;
+    /** Facts about one physical label (`source=label,path=...` bindings resolve against these) - see `./render/binding.ts`. */
+    const buildLabel: typeof buildLabelContext;
+    /** Every `{...}` placeholder referenced across one or more text fragments, parsed as bindings - see `./render/binding.ts`. */
+    const findBindingsInText: typeof findTextBindings;
+    /** Substitutes every `{...}` placeholder in `text` with its resolved binding value - see `./render/binding.ts`. */
+    const substituteBindingsInText: typeof substituteTextBindings;
     type VendorDriver = VendorDriverType;
     type DeviceMetadata = DeviceMetadataType;
     type DiscoveredDevice = DiscoveredDeviceType;
     type VendorDeviceConfig = VendorDeviceConfigType;
     type Colour = ColourType;
+    type TemplateProvider = TemplateProviderType;
+    type TemplateRenderRequest = TemplateRenderRequestType;
+    type LabelMeta = LabelMetaType;
+    type Bitmap = BitmapType;
+    type TemplateContext = TemplateContextType;
 }
 export = plugin;