@rhizomatics/signalk-einklabel-plugin 0.10.1 → 1.0.0

package/dist/render/templateProviders.d.ts

@@ -0,0 +1,58 @@
+import { Colour } from "../devices/types";
+import { Binding } from "./binding";
+import { Bitmap, TemplateContext } from "./types";
+/**
+ * Everything a `TemplateProvider` needs to render one device's repaint - the same
+ * signalk/resources/pathMeta/categories/meta context an ordinary SVG template's `<desc>` bindings
+ * resolve against (specifically, whatever `describeBindings` asked for), plus `context.label` (see
+ * `buildLabelContext` in `./binding.ts`), already built by `considerRepaint` (`../repaintScheduler.ts`)
+ * exactly as it would be for any other device. A `TemplateProvider` never gets direct `ServerAPI`
+ * access itself - like `SvgRenderer`, it only ever sees this already-assembled context.
+ */
+export interface TemplateRenderRequest {
+    /** The exact string picked from the "Template" dropdown, e.g. `"forecast (GenAI)"` - see `TemplateProvider.listTemplates`. */
+    templateName: string;
+    context: TemplateContext;
+    width: number;
+    height: number;
+    colours: Colour[];
+}
+/**
+ * Public extension point for a package that wants to offer an alternative way to produce a device's
+ * content, alongside hand-authored SVG templates - e.g. `@rhizomatics/signalk-einklabel-genai-plugin`
+ * generating content from an LLM prompt. Mirrors `VendorDriver`/`registerDriver`
+ * (`../devices/registry.ts`): an extension declares this package as a regular `dependency` (**not** a
+ * `peerDependency` - see `registerVendorDriver`'s own doc comment in `../index.ts` for why) plus
+ * `"signalk": { "requires": [...] }` in its own package.json, calls `esl.registerTemplateProvider(...)`
+ * from its own SignalK plugin's `start()`, and its entries show up in the same "Template" dropdown as
+ * ordinary `.svg` files, distinguished only by `suffix`.
+ */
+export interface TemplateProvider {
+    /** Appended to every one of this provider's entries in the "Template" dropdown, e.g. `"(GenAI)"`. */
+    suffix: string;
+    /**
+     * Every template name this provider currently offers, already including `suffix` (e.g.
+     * `["forecast (GenAI)"]`) - called fresh each time the config schema is built, so newly added/removed
+     * entries show up without a plugin restart.
+     */
+    listTemplates(): string[];
+    /**
+     * The `signalk`/`resources` bindings one of `listTemplates()`'s entries needs (e.g. a prompt
+     * referencing `{design.length.overall}`) - `considerRepaint` fetches these the same way it would an
+     * SVG template's own `<desc>` bindings, *before* calling `render()`, so `request.context` arrives
+     * already populated. A `TemplateProvider` has no other way to get live SignalK data into its own
+     * render, since it never receives `ServerAPI` directly.
+     */
+    describeBindings(templateName: string): Binding[];
+    /**
+     * Renders one of `listTemplates()`'s exact strings. Rejecting routes the repaint through the same
+     * bundled fallback-warning template any other render failure gets (see `RENDER_FALLBACK_TEMPLATE_NAME`,
+     * `../config.ts`, and `considerRepaint`) - never leaving the previous, possibly now-wrong, content on
+     * screen unmarked.
+     */
+    render(request: TemplateRenderRequest): Promise<Bitmap>;
+}
+export declare function registerTemplateProvider(provider: TemplateProvider): void;
+export declare function allTemplateProviders(): TemplateProvider[];
+/** The registered provider (if any) whose `listTemplates()` currently offers `templateName`. */
+export declare function findTemplateProvider(templateName: string): TemplateProvider | undefined;

package/dist/render/templateProviders.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTemplateProvider = registerTemplateProvider;
+exports.allTemplateProviders = allTemplateProviders;
+exports.findTemplateProvider = findTemplateProvider;
+const providers = [];
+function registerTemplateProvider(provider) {
+    providers.push(provider);
+}
+function allTemplateProviders() {
+    return providers;
+}
+/** The registered provider (if any) whose `listTemplates()` currently offers `templateName`. */
+function findTemplateProvider(templateName) {
+    return providers.find((provider) => provider.listTemplates().includes(templateName));
+}

package/dist/repaintScheduler.js

@@ -13,6 +13,7 @@ const registry_1 = require("./devices/registry");
 const svgRenderer_1 = require("./render/svgRenderer");
 const binding_1 = require("./render/binding");
 const formatters_1 = require("./render/formatters");
+const templateProviders_1 = require("./render/templateProviders");
 const unwrapSignalkTree_1 = require("./render/unwrapSignalkTree");
 const unitCategories_1 = require("./unitCategories");
 const pathMeta_1 = require("./pathMeta");
@@ -217,55 +218,132 @@ async function resolveTargets(app, config, device) {
     }
     return [target];
 }
+/**
+ * Renders and paints one device. `device.templateName` is resolved two ways: first against the
+ * `TemplateProvider` registry (`./render/templateProviders.ts`) - an extension like
+ * `signalk-einklabel-genai-plugin` contributing e.g. `"forecast (GenAI)"` - and only if no provider
+ * matches, as an ordinary `.svg` file/family (`resolveTemplatePath`), exactly as before this registry
+ * existed. Either way, the resolved content is rendered and pushed through the same paint step.
+ *
+ * `context.label` (`buildLabelContext`, `./render/binding.ts`) is now built for *every* device, not
+ * just provider-rendered ones - a plain SVG template can use `source=label,path=width` etc too. Its
+ * `position` is pre-rounded there, so folding it into every device's dedup hash below doesn't
+ * reintroduce GPS-jitter-driven repaints for a template that never even references it.
+ *
+ * On any failure - a broken hand-authored template, a missing template file, or a `TemplateProvider`'s
+ * `render()` rejecting (e.g. an LLM call failing) - pushes the bundled `RENDER_FALLBACK_TEMPLATE_NAME`
+ * warning instead, and deliberately does *not* persist a success hash: content that can't be generated
+ * must never leave the previous, possibly now-wrong, content on screen unmarked (e.g. a stale weather
+ * prompt showing "gentle breezes" through an actual storm), and not persisting a hash means the very
+ * next scheduled tick retries for real rather than being suppressed by dedup.
+ */
 async function considerRepaint(app, config, device, target, state, getApiUrl) {
     const { address, metadata, driver } = target;
     const label = `"${device.friendlyName}" [${address}]`;
+    if (!device.templateName) {
+        app.debug(`${label}: no template configured, skipping`);
+        return;
+    }
+    const width = metadata.width;
+    const height = metadata.height - metadata.voffset;
+    const provider = (0, templateProviders_1.findTemplateProvider)(device.templateName);
     const templatesDir = (0, config_1.resolveTemplatesDir)(config.templatesDir);
-    const templatePath = (0, config_1.resolveTemplatePath)(templatesDir, device.templateName, {
-        width: metadata.width,
-        height: metadata.height,
-        colours: metadata.colours,
-    });
-    const templateMtimeMs = (0, fs_1.statSync)(templatePath).mtimeMs;
-    const bindings = (0, binding_1.findBindings)((0, fs_1.readFileSync)(templatePath, "utf-8"));
-    const apiUrl = await getApiUrl().catch((err) => {
-        app.debug(`${label}: ${err.message}`);
-        return undefined;
-    });
-    const rawContext = await assembleRawContext(app, apiUrl, bindings);
-    const templateHash = hashTemplate(templateMtimeMs);
-    // Hashed from `rawContext`, not `renderContext` below - `meta.repainted` (and the rest of `meta`)
-    // is only added after this point, deliberately, so a template merely *displaying* the repaint
-    // timestamp doesn't perpetually invalidate its own dedup and force a repaint every check. A full
-    // paint flashes the whole panel several times, and there's no confirmed partial-refresh path on
-    // these devices - so a bound value simply being unchanged is worth trusting over any staleness in
-    // a displayed clock.
-    const dataHash = hashData(rawContext);
     const stateKey = stateKeyFor(device.friendlyName, address);
     const previous = state[stateKey];
-    const templateChanged = previous?.templateHash !== templateHash;
-    const dataChanged = previous?.dataHash !== dataHash;
-    // The devices are battery-constrained, so a repaint is skipped whenever neither the template nor
-    // the bound data has changed since the last successful paint - regardless of what triggered this
-    // check (interval or subscription) or whether it's a regular scheduled tick vs. the deferred
-    // startup catch-up (see `startupCheckTimer`). `forceRepaint` is the explicit, one-shot override
-    // for "repaint anyway".
-    if (!templateChanged && !dataChanged && !device.forceRepaint) {
-        app.debug(`${label}: data unchanged, skipping repaint`);
-        return;
-    }
-    const renderContext = {
-        ...rawContext,
-        meta: {
-            repainted: new Date().toISOString(),
-            local_zone: (0, formatters_1.resolveLocalZoneAbbreviation)(rawContext),
-            plugin_version: pluginVersion_1.PLUGIN_VERSION,
-        },
-    };
     const renderer = new svgRenderer_1.SvgRenderer();
-    const bitmap = await renderer.render(templatePath, renderContext, metadata.width, metadata.height - metadata.voffset, templatesDir, config_1.BUNDLED_TEMPLATES_DIR);
-    const connectTimeoutMs = config.paintConnectTimeoutSeconds * 1000;
+    let bitmap;
+    let succeeded = false;
+    let templateHash = "";
+    let dataHash = "";
     let paintDurationMs = 0;
+    let repaintReason = "render failed";
+    try {
+        const apiUrl = await getApiUrl().catch((err) => {
+            app.debug(`${label}: ${err.message}`);
+            return undefined;
+        });
+        let bindings = [];
+        let templatePath = "";
+        if (provider) {
+            templateHash = (0, crypto_1.createHash)("sha1").update(device.templateName).digest("hex");
+            bindings = provider.describeBindings(device.templateName);
+        }
+        else {
+            templatePath = (0, config_1.resolveTemplatePath)(templatesDir, device.templateName, {
+                width: metadata.width,
+                height: metadata.height,
+                colours: metadata.colours,
+            });
+            templateHash = hashTemplate((0, fs_1.statSync)(templatePath).mtimeMs);
+            bindings = (0, binding_1.findBindings)((0, fs_1.readFileSync)(templatePath, "utf-8"));
+        }
+        const rawContext = await assembleRawContext(app, apiUrl, bindings);
+        const rawPosition = (0, unwrapSignalkTree_1.unwrapSignalkTree)(app.getSelfPath("navigation.position"));
+        const position = typeof rawPosition?.latitude === "number" && typeof rawPosition?.longitude === "number"
+            ? { latitude: rawPosition.latitude, longitude: rawPosition.longitude }
+            : undefined;
+        const labelContext = (0, binding_1.buildLabelContext)({
+            // Falls back to the driver's own internal vendor key (e.g. "zhsunyco") when a device model has no
+            // explicit `manufacturer` of its own - see `DeviceMetadata.manufacturer`'s doc comment.
+            manufacturer: metadata.manufacturer ?? target.vendor,
+            label: metadata.label,
+            width,
+            height,
+            colours: metadata.colours,
+            description: device.description,
+            position,
+        });
+        // Hashed before `meta` is merged in below, deliberately, so a template merely *displaying* the
+        // repaint timestamp doesn't perpetually invalidate its own dedup and force a repaint every check. A
+        // full paint flashes the whole panel several times, and there's no confirmed partial-refresh path
+        // on these devices - so a bound value simply being unchanged is worth trusting over any staleness
+        // in a displayed clock.
+        dataHash = hashData({ ...rawContext, label: labelContext });
+        const templateChanged = previous?.templateHash !== templateHash;
+        const dataChanged = previous?.dataHash !== dataHash;
+        // A provider-rendered template always attempts a fresh render when triggered, bypassing dedup
+        // entirely - core can't know whether the provider's output would differ, and "fresh content each
+        // scheduled tick" (e.g. a regenerated forecast) is the whole point of one - which is exactly why a
+        // provider-backed device should use `repaintTrigger: "interval"`, not `subscription`, for
+        // cost/battery reasons (each repaint may be a paid API call on the provider's side).
+        if (!provider && !templateChanged && !dataChanged && !device.forceRepaint) {
+            app.debug(`${label}: data unchanged, skipping repaint`);
+            return;
+        }
+        const renderContext = {
+            ...rawContext,
+            label: labelContext,
+            meta: {
+                repainted: new Date().toISOString(),
+                local_zone: (0, formatters_1.resolveLocalZoneAbbreviation)(rawContext),
+                plugin_version: pluginVersion_1.PLUGIN_VERSION,
+                description: device.description ?? "",
+            },
+        };
+        bitmap = provider
+            ? await provider.render({ templateName: device.templateName, context: renderContext, width, height, colours: metadata.colours })
+            : await renderer.render(templatePath, renderContext, width, height, templatesDir, config_1.BUNDLED_TEMPLATES_DIR);
+        succeeded = true;
+        repaintReason = device.forceRepaint
+            ? "forced"
+            : provider
+                ? "provider-rendered"
+                : templateChanged && dataChanged
+                    ? "template and data changed"
+                    : templateChanged
+                        ? "template changed"
+                        : "data changed";
+    }
+    catch (err) {
+        app.debug(`${label}: render failed (${err.message}) - showing fallback warning`);
+        const fallbackPath = (0, config_1.resolveTemplatePath)(templatesDir, config_1.RENDER_FALLBACK_TEMPLATE_NAME, {
+            width: metadata.width,
+            height: metadata.height,
+            colours: metadata.colours,
+        });
+        bitmap = await renderer.render(fallbackPath, { meta: { repainted: new Date().toISOString(), plugin_version: pluginVersion_1.PLUGIN_VERSION, description: device.description ?? "" } }, width, height, templatesDir, config_1.BUNDLED_TEMPLATES_DIR);
+    }
+    const connectTimeoutMs = config.paintConnectTimeoutSeconds * 1000;
     await (0, bleDiscovery_1.withRetries)(config.paintRetries, async (attempt) => {
         if (attempt > 1) {
             app.debug(`${label}: attempting paint ${attempt}/${config.paintRetries}`);
@@ -275,16 +353,13 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
         paintDurationMs = Date.now() - startedAt;
     });
     (0, discoveredDevicesStore_1.touchDiscoveredDevice)(app, { address, vendor: target.vendor, pid: target.pid, hwVersion: target.hwVersion, metadata });
-    state[stateKey] = { templateHash, dataHash, repaintedAt: Date.now() };
-    saveState(app, state);
-    const reason = device.forceRepaint
-        ? "forced"
-        : templateChanged && dataChanged
-            ? "template and data changed"
-            : templateChanged
-                ? "template changed"
-                : "data changed";
-    app.debug(`${label}: repainted (${reason}, paint took ${paintDurationMs}ms)`);
+    // Only a successful render counts as "repainted" for dedup/catch-up purposes - a failure must not be
+    // recorded here (see this function's doc comment on why).
+    if (succeeded) {
+        state[stateKey] = { templateHash, dataHash, repaintedAt: Date.now() };
+        saveState(app, state);
+    }
+    app.debug(succeeded ? `${label}: repainted (${repaintReason}, paint took ${paintDurationMs}ms)` : `${label}: repainted fallback warning`);
 }
 function startRepaintScheduler(app, config) {
     const state = loadState(app);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rhizomatics/signalk-einklabel-plugin",
-  "version": "0.10.1",
-  "description": "Display SignalK data on eInk Electronic Shelf Labels",
+  "version": "1.0.0",
+  "description": "Display SignalK data on eInk Electronic Shelf Labels, includes working examples for tide clock and watch schedule.",
   "keywords": [
     "ble",
     "display",
@@ -15,7 +15,7 @@
     "tides",
     "watch-schedule"
   ],
-  "homepage": "https://github.com/rhizomatics/signalk-einklabel-plugin#readme",
+  "homepage": "https://rhizomatics.github.io/signalk-einklabel-plugin/",
   "bugs": {
     "url": "https://github.com/rhizomatics/signalk-einklabel-plugin/issues"
   },
@@ -66,9 +66,9 @@
     "@types/luxon": "^3.7.1",
     "@types/node": "^20.14.0",
     "@types/pngjs": "^6.0.5",
-    "oxfmt": "^0.56.0",
-    "oxlint": "^1.71.0",
-    "oxlint-tsgolint": "^0.23.0",
+    "oxfmt": "^0.59.0",
+    "oxlint": "^1.74.0",
+    "oxlint-tsgolint": "^7.0.0",
     "ts-node": "^10.9.2",
     "typescript": "^5.5.0"
   },
@@ -86,7 +86,8 @@
     ],
     "recommends": [
       "signalk-watch-schedule",
-      "signalk-tides"
+      "signalk-tides",
+      "@rhizomatics/signalk-einklabel-genai-plugin"
     ]
   }
 }

package/templates/.error/250x128-BWRY.svg

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg width="250" height="128" viewBox="0 0 250 128" xmlns="http://www.w3.org/2000/svg">
+  <rect x="0" y="0" width="250" height="128" fill="white" />
+  <polygon points="45,18 12,96 78,96" fill="red" stroke="black" stroke-width="3" stroke-linejoin="round" />
+  <rect x="41" y="46" width="8" height="26" fill="black" />
+  <circle cx="45" cy="84" r="5" fill="black" />
+  <text x="92" y="46" font-size="22" font-family="sans-serif" font-weight="bold" fill="black">CONTENT</text>
+  <text x="92" y="72" font-size="22" font-family="sans-serif" font-weight="bold" fill="black">UNAVAILABLE</text>
+  <text x="92" y="92" font-size="12" font-family="sans-serif" fill="black">Check manually</text>
+  <text id="last_attempt" x="92" y="112" font-size="10" font-family="monospace" fill="black"
+    ><desc>source=einklabel,path=repainted,format=local_datetime_short</desc>last attempt: --</text>
+</svg>

package/templates/.error/416x240-BWRY.svg

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg width="416" height="240" viewBox="0 0 416 240" xmlns="http://www.w3.org/2000/svg">
+  <rect x="0" y="0" width="416" height="240" fill="white" />
+  <polygon points="80,40 18,168 142,168" fill="red" stroke="black" stroke-width="5" stroke-linejoin="round" />
+  <rect x="75" y="85" width="12" height="48" fill="black" />
+  <circle cx="81" cy="150" r="7" fill="black" />
+  <text x="168" y="90" font-size="34" font-family="sans-serif" font-weight="bold" fill="black">CONTENT</text>
+  <text x="168" y="132" font-size="34" font-family="sans-serif" font-weight="bold" fill="black">UNAVAILABLE</text>
+  <text x="168" y="165" font-size="18" font-family="sans-serif" fill="black">Check manually</text>
+  <text id="last_attempt" x="168" y="205" font-size="16" font-family="monospace" fill="black"
+    ><desc>source=einklabel,path=repainted,format=local_datetime_short</desc>last attempt: --</text>
+</svg>