@rhizomatics/signalk-einklabel-plugin 0.10.1 → 1.2.0

package/dist/render/binding.js

@@ -3,12 +3,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseBinding = parseBinding;
 exports.resourceContextKey = resourceContextKey;
 exports.findBindings = findBindings;
+exports.readTemplateDimensions = readTemplateDimensions;
 exports.resolveBinding = resolveBinding;
 exports.renderBinding = renderBinding;
+exports.buildLabelContext = buildLabelContext;
+exports.findTextBindings = findTextBindings;
+exports.substituteTextBindings = substituteTextBindings;
 const xmldom_1 = require("@xmldom/xmldom");
 const formatters_1 = require("./formatters");
-const SOURCES = ["signalk", "resources", "einklabel"];
-const KNOWN_KEYS = new Set(["source", "context", "resource", "provider", "path", "format", "category", "round", "assets"]);
+const SOURCES = ["signalk", "resources", "einklabel", "label"];
+const KNOWN_KEYS = new Set(["source", "context", "resource", "provider", "path", "format", "category", "round", "assets", "default"]);
 /**
  * Parses a `<desc>` element's text content into a `Binding`, e.g.
  * `source=resources,resource=tides,path=extremes[0].level,category=depth,round=2` or, using the
@@ -62,6 +66,7 @@ function parseBinding(desc) {
         category: fields.category,
         round: fields.round !== undefined ? Number(fields.round) : undefined,
         assets: fields.assets,
+        default: fields.default,
     };
 }
 /**
@@ -95,6 +100,26 @@ function findBindings(svgSource) {
     }
     return bindings;
 }
+/**
+ * Reads the root `<svg>` element's declared `width`/`height` (falling back to the 3rd/4th `viewBox`
+ * numbers when either attribute is missing) - lets a caller default a render size to what the template
+ * itself was authored for, e.g. the CLI's -w/--width and --height options.
+ */
+function readTemplateDimensions(svgSource) {
+    const doc = new xmldom_1.DOMParser().parseFromString(svgSource, "image/svg+xml");
+    const svg = doc.getElementsByTagName("svg").item(0);
+    if (!svg)
+        return {};
+    const viewBox = svg.getAttribute("viewBox")?.trim().split(/\s+/).map(Number);
+    const viewBoxWidth = viewBox?.length === 4 && Number.isFinite(viewBox[2]) ? viewBox[2] : undefined;
+    const viewBoxHeight = viewBox?.length === 4 && Number.isFinite(viewBox[3]) ? viewBox[3] : undefined;
+    const width = parseFloat(svg.getAttribute("width") ?? "");
+    const height = parseFloat(svg.getAttribute("height") ?? "");
+    return {
+        width: Number.isFinite(width) ? width : viewBoxWidth,
+        height: Number.isFinite(height) ? height : viewBoxHeight,
+    };
+}
 /** Supports both `a.[0].b` and `a[0].b` array index notation, matching `setAtPath` in repaintScheduler.ts. */
 function getAtPath(obj, path) {
     const segments = path
@@ -126,6 +151,13 @@ function resolveBinding(binding, context) {
         }
         return getAtPath(meta, binding.path);
     }
+    if (binding.source === "label") {
+        const label = context.label;
+        if (label === undefined) {
+            throw new Error('binding references source "label" but no "label" is present in the render context');
+        }
+        return getAtPath(label, binding.path);
+    }
     const resources = context.resources;
     const resourceKey = resourceContextKey(binding);
     const resource = resources?.[resourceKey];
@@ -166,6 +198,8 @@ function resolveCategoryDisplayUnits(binding, context) {
  * the CLI's `field`/`fields` commands show the same thing a real render would.
  *
  * Precedence for a numeric value:
+ * 0. A missing value (`undefined`/`null`, e.g. an unpublished path) with an explicit `default=` given -
+ *    that default, verbatim, bypassing every step below (there's nothing to format).
  * 1. An explicit named `format=` (anything other than `raw`) - `local_time`/`utc_offset`/`position`.
  * 2. An explicit `category=` - for values with no path metadata of their own, e.g. a `source=resources`
  *    value.
@@ -173,10 +207,13 @@ function resolveCategoryDisplayUnits(binding, context) {
  *    `context.pathMeta`) by default - `format=raw` opts out of this step only.
  * 4. Falls through to `round=` (`toFixed`), `JSON.stringify` for an unformatted object/array value
  *    (e.g. a path that resolved to a whole sub-tree rather than a leaf) instead of the useless
- *    `String(value)` -> `"[object Object]"`, else `String`.
+ *    `String(value)` -> `"[object Object]"`, else `String`. A missing value with no `default=` given
+ *    still falls through to the pre-existing "" here, unchanged from before `default=` existed.
  */
 function renderBinding(binding, context) {
     const value = resolveBinding(binding, context);
+    if ((value === null || value === undefined) && binding.default !== undefined)
+        return binding.default;
     if (binding.format && binding.format !== "raw")
         return (0, formatters_1.applyFormat)(binding.format, value, context, binding.round);
     if (typeof value === "number") {
@@ -194,3 +231,98 @@ function renderBinding(binding, context) {
         return JSON.stringify(value);
     return String(value);
 }
+const COLOUR_HEX = { black: "#000000", white: "#FFFFFF", red: "#FF0000", yellow: "#FFFF00" };
+/** The only `font-family` values `SvgRenderer` is guaranteed to render - see `expandGenericFontFamilies` in `./svgRenderer.ts`. */
+const SAFE_FONT_FAMILIES = ["serif", "sans-serif", "monospace"];
+/**
+ * Builds the `context.label` object a `source=label,path=...` binding addresses (e.g.
+ * `{source=label,path=width}` in free text, or a `<desc>source=label,path=width</desc>` in an SVG
+ * template - every `{...}`/`<desc>` placeholder is a real binding, so a `label` path always needs the
+ * explicit `source=label,path=` form to disambiguate it from a `signalk` self path). `colours`/`fonts`
+ * are left as arrays (each colour entry pre-annotated with its hex code, e.g. `"black (#000000)"`)
+ * rather than joined into a single string, so a caller can either use them bare (renders as JSON) or add
+ * `format=csv` (see `./formatters.ts`) for a plain comma-separated list. `position`, if given, is rounded
+ * to ~2 decimal places (~1.1km) - fine-grained enough to be meaningfully "for here", coarse enough that
+ * ordinary GPS jitter at anchor doesn't change it tick to tick, which matters because `considerRepaint`
+ * (`../repaintScheduler.ts`) folds this whole object into every device's dedup hash - full-precision
+ * jitter here would otherwise force a repaint (and, for a provider-rendered template, a fresh paid API
+ * call) far more often than the underlying position has actually meaningfully changed.
+ */
+function buildLabelContext(meta) {
+    const position = meta.position && {
+        latitude: Math.round(meta.position.latitude * 100) / 100,
+        longitude: Math.round(meta.position.longitude * 100) / 100,
+    };
+    return {
+        manufacturer: meta.manufacturer,
+        label: meta.label,
+        width: meta.width,
+        height: meta.height,
+        colours: meta.colours.map((colour) => `${colour} (${COLOUR_HEX[colour]})`),
+        fonts: SAFE_FONT_FAMILIES,
+        description: meta.description ?? "",
+        position: position ? (0, formatters_1.applyFormat)("position", position, {}, 2) : undefined,
+    };
+}
+function placeholderContents(text) {
+    return [...new Set([...text.matchAll(/\{([^{}]+)\}/g)].map((match) => match[1].trim()))];
+}
+/**
+ * Every binding referenced across one or more free-text fragments - every `{...}` placeholder,
+ * deduplicated across all of `texts` combined, parsed exactly the way a template's `<desc>` binding is
+ * (`parseBinding` above), so a bare path (`{design.length}`, `source=signalk,context=self` shorthand),
+ * the full binding grammar (`{source=signalk,path=navigation.position,format=position}`), and a
+ * `source=label,path=...` binding all work uniformly. Pass the result to `assembleRawContext`
+ * (`../repaintScheduler.ts`) exactly as a template's own bindings are - it fetches the `signalk`/
+ * `resources`-sourced ones and silently ignores `label`/`einklabel`-sourced ones, which resolve directly
+ * against `context.label`/`context.meta` instead (built by the caller, not fetched).
+ *
+ * A placeholder that isn't valid binding grammar (e.g. a typo like `{source=taheight}`) is silently
+ * skipped here rather than thrown - the same per-field isolation `SvgRenderer` gives a bad `<desc>`
+ * binding, so one malformed placeholder doesn't take down the whole text. `substituteTextBindings` hits
+ * the identical parse error at substitution time and turns it into "???" for just that field.
+ */
+function findTextBindings(...texts) {
+    const seen = new Set();
+    const bindings = [];
+    for (const text of texts) {
+        for (const key of placeholderContents(text)) {
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            try {
+                bindings.push(parseBinding(key));
+            }
+            catch {
+                // see doc comment above - left for `substituteTextBindings` to turn into "???"
+            }
+        }
+    }
+    return bindings;
+}
+/**
+ * Substitutes every `{...}` placeholder in `text` with its resolved binding value against `context`
+ * (built by `assembleRawContext` plus `context.label` from `buildLabelContext` - see
+ * `findTextBindings`). Mirrors `renderBinding`'s per-field isolation, but substitutes "???" for anything
+ * that resolves to no value at all (missing path, invalid binding grammar) rather than "" - prose with a
+ * silently-blank word reads as a fact ("for the sailor of a m vessel"), not as a gap the reader would
+ * notice. Two things override that "???": a binding that resolves successfully to a legitimately empty
+ * string (e.g. an unset `{source=label,path=description}`) is left as empty, since that's a real answer,
+ * not a miss; and a binding with an explicit `default=` uses that default instead, since the caller has
+ * already said what a missing value should read as.
+ */
+function substituteTextBindings(text, context) {
+    return text.replace(/\{([^{}]+)\}/g, (_match, raw) => {
+        const key = raw.trim();
+        try {
+            const binding = parseBinding(key);
+            const value = resolveBinding(binding, context);
+            if ((value === undefined || value === null) && binding.default === undefined)
+                return "???";
+            return renderBinding(binding, context);
+        }
+        catch {
+            return "???";
+        }
+    });
+}

package/dist/render/formatters.js

@@ -101,6 +101,22 @@ function formatPosition(value, round) {
     const lonHemisphere = position.longitude >= 0 ? "E" : "W";
     return `${lat}°${latHemisphere} ${lon}°${lonHemisphere}`;
 }
+/**
+ * A resolved value that's an array (e.g. `source=label,path=colours` - see `../render/llmPrompt.ts`'s
+ * `buildLabelContext`) joined into a plain comma-separated list, e.g. `["black","white"]` ->
+ * `"black, white"`. A non-array value falls through to the same null/object/scalar handling
+ * `renderBinding` uses for its own generic fallback, so `format=csv` is harmless on an ordinary
+ * scalar binding too.
+ */
+function formatCsv(value) {
+    if (Array.isArray(value))
+        return value.map((entry) => String(entry)).join(", ");
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "object")
+        return JSON.stringify(value);
+    return String(value);
+}
 /** Applies a named `format=` formatter to a resolved binding value. */
 function applyFormat(name, value, context, round) {
     switch (name) {
@@ -114,6 +130,8 @@ function applyFormat(name, value, context, round) {
             return formatUtcOffset(value);
         case "position":
             return formatPosition(value, round);
+        case "csv":
+            return formatCsv(value);
         default:
             throw new Error(`unknown format "${name}"`);
     }

package/dist/render/reframe.d.ts

@@ -0,0 +1,12 @@
+import { Bitmap } from "./types";
+/**
+ * How a rendered bitmap is fitted onto a device's actual panel size when the two don't match -
+ * `"fixed"` (the default, and the only behaviour before this existed) makes no change, leaving each
+ * vendor driver's own exact-size check in `encodeBitmap` to reject the mismatch; `"scale"` scales
+ * the source onto the target dimensions independently per axis (not preserving aspect ratio);
+ * `"crop"` keeps source pixels 1:1, placing them from the top-left and either truncating whatever
+ * doesn't fit (source bigger than target) or leaving the extra target space blank (source smaller).
+ */
+export type ReframeMode = "fixed" | "scale" | "crop";
+/** Applies `mode` to fit `bitmap` onto a `targetWidth`x`targetHeight` panel - a no-op whenever the size already matches, regardless of mode. */
+export declare function reframeBitmap(bitmap: Bitmap, targetWidth: number, targetHeight: number, mode: ReframeMode): Bitmap;

package/dist/render/reframe.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reframeBitmap = reframeBitmap;
+/** Nearest-neighbour, not bilinear: the vendor colour quantisers threshold each pixel independently into a small fixed palette (see `nearestColour`/`classifyColour`), so blended edge pixels from interpolation would just be re-thresholded arbitrarily rather than improving the result. */
+function scaleBitmap(bitmap, targetWidth, targetHeight) {
+    const data = new Uint8Array(targetWidth * targetHeight * 4);
+    for (let y = 0; y < targetHeight; y++) {
+        const srcY = Math.min(bitmap.height - 1, Math.floor((y * bitmap.height) / targetHeight));
+        for (let x = 0; x < targetWidth; x++) {
+            const srcX = Math.min(bitmap.width - 1, Math.floor((x * bitmap.width) / targetWidth));
+            const srcOffset = (srcY * bitmap.width + srcX) * 4;
+            const dstOffset = (y * targetWidth + x) * 4;
+            data.set(bitmap.data.subarray(srcOffset, srcOffset + 4), dstOffset);
+        }
+    }
+    return { width: targetWidth, height: targetHeight, data };
+}
+/** Opaque white (matches an untouched label's own background) rather than transparent black, since the vendor colour quantisers treat a fully-transparent pixel the same as an opaque black one. */
+function cropBitmap(bitmap, targetWidth, targetHeight) {
+    const data = new Uint8Array(targetWidth * targetHeight * 4).fill(255);
+    const copyWidth = Math.min(bitmap.width, targetWidth);
+    const copyHeight = Math.min(bitmap.height, targetHeight);
+    for (let y = 0; y < copyHeight; y++) {
+        const srcOffset = y * bitmap.width * 4;
+        const dstOffset = y * targetWidth * 4;
+        data.set(bitmap.data.subarray(srcOffset, srcOffset + copyWidth * 4), dstOffset);
+    }
+    return { width: targetWidth, height: targetHeight, data };
+}
+/** Applies `mode` to fit `bitmap` onto a `targetWidth`x`targetHeight` panel - a no-op whenever the size already matches, regardless of mode. */
+function reframeBitmap(bitmap, targetWidth, targetHeight, mode) {
+    if (mode === "fixed" || (bitmap.width === targetWidth && bitmap.height === targetHeight)) {
+        return bitmap;
+    }
+    return mode === "scale" ? scaleBitmap(bitmap, targetWidth, targetHeight) : cropBitmap(bitmap, targetWidth, targetHeight);
+}

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.2.0",
+  "description": "Display SignalK data on eInk Electronic Shelf Labels, includes working examples for tide clock and watch schedule.",
   "keywords": [
     "ble",
     "display",
@@ -9,13 +9,15 @@
     "esl",
     "instrument",
     "signalk",
+    "zhsunyco",
+    "gicisky",
     "signalk-category-hardware",
     "signalk-category-instruments",
     "signalk-node-server-plugin",
     "tides",
     "watch-schedule"
   ],
-  "homepage": "https://github.com/rhizomatics/signalk-einklabel-plugin#readme",
+  "homepage": "https://signalk-einklabel.rhizomatics.org.uk/",
   "bugs": {
     "url": "https://github.com/rhizomatics/signalk-einklabel-plugin/issues"
   },
@@ -49,26 +51,26 @@
     "lint": "oxlint"
   },
   "dependencies": {
-    "@fontsource/roboto": "^5.2.10",
-    "@fontsource/roboto-mono": "^5.2.9",
-    "@fontsource/roboto-serif": "^5.2.9",
+    "@fontsource/roboto": "^5.3.0",
+    "@fontsource/roboto-mono": "^5.3.0",
+    "@fontsource/roboto-serif": "^5.3.0",
     "@naugehyde/node-ble": "^1.13.5",
     "@resvg/resvg-wasm": "^2.6.2",
     "@xmldom/xmldom": "^0.9.10",
-    "commander": "^12.1.0",
+    "commander": "^15.0.0",
     "form-data": "^4.0.6",
     "luxon": "^3.7.2",
     "mathjs": "^15.2.0",
     "pngjs": "^7.0.0"
   },
   "devDependencies": {
-    "@signalk/server-api": "^2.28.0",
+    "@signalk/server-api": "^2.31.0",
     "@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.66.0",
+    "oxlint": "^1.81.0",
+    "oxlint-tsgolint": "^7.0.2001",
     "ts-node": "^10.9.2",
     "typescript": "^5.5.0"
   },
@@ -86,7 +88,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>