@rhizomatics/signalk-einklabel-plugin 0.10.0 → 1.0.0

package/dist/render/llmPrompt.d.ts

@@ -0,0 +1,86 @@
+import { PluginConfig } from "../config";
+import { Colour } from "../devices/types";
+import { Binding } from "./binding";
+import { TemplateContext } from "./types";
+/** Facts about one physical label a prompt's `source=label,path=...` placeholders can reference - see `buildLabelContext`. */
+export interface LabelMeta {
+    manufacturer: string;
+    /** The physical panel's own size label, e.g. `'3.7"'` - `DeviceMetadata.label` verbatim, see `../devices/types.ts`. */
+    label: string;
+    width: number;
+    height: number;
+    colours: Colour[];
+    description?: string;
+    position?: {
+        latitude: number;
+        longitude: number;
+    };
+}
+/**
+ * Builds the `context.label` object a prompt/target-guidance fragment addresses via
+ * `source=label,path=...` bindings (e.g. `{source=label,path=width}`, or the bare-path shorthand
+ * `{width}` is *not* supported here deliberately - see `./binding.ts`'s `parseBinding`, every `{...}`
+ * placeholder is a real binding, so a `label` path always needs the explicit `source=label,path=`
+ * form to disambiguate it from a `signalk` self path). `colours`/`fonts` are left as arrays (each
+ * colour entry pre-annotated with its hex code, e.g. `"black (#000000)"`) rather than joined into a
+ * single string, so a prompt author can either use them bare (renders as JSON, e.g. for a model that
+ * parses structured hints) or add `format=csv` (see `./formatters.ts`) for a plain comma-separated list.
+ */
+export declare function buildLabelContext(meta: LabelMeta): Record<string, unknown>;
+/**
+ * Every binding referenced across one or more prompt fragments - every `{...}` placeholder, deduplicated
+ * across all of `texts` combined, parsed exactly the way a template's `<desc>` binding is
+ * (`parseBinding`, see `./binding.ts`), so a bare path (`{design.length}`, `source=signalk,context=self`
+ * shorthand), the full binding grammar (`{source=signalk,path=navigation.position,format=position}`),
+ * and a `source=label,path=...` binding all work uniformly. Pass the result to `assembleRawContext`
+ * (repaintScheduler.ts) exactly as a template's own bindings are - it fetches the `signalk`/
+ * `resources`-sourced ones and silently ignores `label`/`einklabel`-sourced ones, which resolve directly
+ * against `context.label`/`context.meta` instead (built by the caller, not fetched).
+ *
+ * A placeholder that isn't valid binding grammar (e.g. a typo like `{source=taheight}`) is silently
+ * skipped here rather than thrown - the same per-field isolation `SvgRenderer` gives a bad `<desc>`
+ * binding, so one malformed placeholder doesn't take down the whole prompt. `substitutePlaceholders`
+ * hits the identical parse error at substitution time and turns it into "???" for just that field.
+ */
+export declare function findPromptBindings(...texts: string[]): Binding[];
+/**
+ * Substitutes every `{...}` placeholder in `text` with its resolved binding value against `context`
+ * (built by `assembleRawContext` plus `context.label` from `buildLabelContext` - see
+ * `findPromptBindings`). Mirrors `renderBinding`'s per-field isolation, but substitutes "???" for
+ * anything that resolves to no value at all (missing path, invalid binding grammar) rather than "" -
+ * prose with a silently-blank word reads as a fact ("for the sailor of a m vessel"), not as a gap the
+ * reader would notice. Two things override that "???": a binding that resolves successfully to a
+ * legitimately empty string (e.g. an unset `{source=label,path=description}`) is left as empty, since
+ * that's a real answer, not a miss; and a binding with an explicit `default=` (see `./binding.ts`) uses
+ * that default instead, since the prompt author has already said what a missing value should read as.
+ */
+export declare function substitutePlaceholders(text: string, context: TemplateContext): string;
+/**
+ * Strips everything outside the first `<svg`...last `</svg>` span - a chat model asked for "only raw
+ * SVG markup" still often wraps it in a markdown code fence or adds a sentence of commentary either
+ * side, despite the target-guidance fragment telling it not to.
+ */
+export declare function extractSvg(raw: string): string;
+export type LlmSettings = Pick<PluginConfig, "llmProvider" | "llmApiKey" | "llmModel" | "llmBaseUrl"> & {
+    llmTimeoutSeconds?: number;
+};
+/**
+ * `ai` and every `@ai-sdk/*` provider package are `optionalDependencies` (see package.json), not plain
+ * `dependencies` - most installs (every device using `renderMode: "svg-template"` only) never touch an
+ * LLM at all, so they shouldn't have to pull in this whole gateway stack, and an install that fails to
+ * fetch one of these (network hiccup, `npm install --omit=optional`, an unsupported platform) must not
+ * break BLE painting/templates, which have nothing to do with it. That means every reference to one of
+ * these packages has to be a `require()` reached only when a `renderMode: "llm-prompt"` device actually
+ * calls `callLlm` - a top-level `import` would be resolved eagerly the moment this module loads (which
+ * is every plugin start, via `repaintScheduler.ts`), throwing before any config is even read. Types are
+ * still fully checked via `typeof import(...)` below, which - unlike a value `import` - is erased
+ * entirely at compile time and leaves no runtime trace for `tsc` to eagerly require.
+ */
+export declare function loadOptional<M>(moduleName: string): M;
+/**
+ * Calls the configured LLM gateway with `prompt`, returning its raw text response - not yet extracted/
+ * validated as SVG, see `extractSvg`. This is the first network call in the codebase that needs its own
+ * timeout (`fetchJson` in `../httpJson.ts` has none - every existing call is to the local SignalK
+ * server's own REST API).
+ */
+export declare function callLlm(settings: LlmSettings, prompt: string): Promise<string>;

package/dist/render/llmPrompt.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildLabelContext = buildLabelContext;
+exports.findPromptBindings = findPromptBindings;
+exports.substitutePlaceholders = substitutePlaceholders;
+exports.extractSvg = extractSvg;
+exports.loadOptional = loadOptional;
+exports.callLlm = callLlm;
+const binding_1 = require("./binding");
+const formatters_1 = require("./formatters");
+const COLOUR_HEX = { black: "#000000", white: "#FFFFFF", red: "#FF0000", yellow: "#FFFF00" };
+/** The only `font-family` values `SvgRenderer` is guaranteed to render - see `expandGenericFontFamilies` in `./svgRenderer.ts`. */
+const SAFE_FONT_FAMILIES = ["serif", "sans-serif", "monospace"];
+/**
+ * Builds the `context.label` object a prompt/target-guidance fragment addresses via
+ * `source=label,path=...` bindings (e.g. `{source=label,path=width}`, or the bare-path shorthand
+ * `{width}` is *not* supported here deliberately - see `./binding.ts`'s `parseBinding`, every `{...}`
+ * placeholder is a real binding, so a `label` path always needs the explicit `source=label,path=`
+ * form to disambiguate it from a `signalk` self path). `colours`/`fonts` are left as arrays (each
+ * colour entry pre-annotated with its hex code, e.g. `"black (#000000)"`) rather than joined into a
+ * single string, so a prompt author can either use them bare (renders as JSON, e.g. for a model that
+ * parses structured hints) or add `format=csv` (see `./formatters.ts`) for a plain comma-separated list.
+ */
+function buildLabelContext(meta) {
+    return {
+        manufacturer: meta.manufacturer,
+        label: meta.label,
+        width: meta.width,
+        height: meta.height,
+        colours: meta.colours.map((colour) => `${colour} (${COLOUR_HEX[colour]})`),
+        fonts: SAFE_FONT_FAMILIES,
+        description: meta.description ?? "",
+        position: meta.position ? (0, formatters_1.applyFormat)("position", meta.position, {}, 3) : undefined,
+    };
+}
+/**
+ * Every binding referenced across one or more prompt fragments - every `{...}` placeholder, deduplicated
+ * across all of `texts` combined, parsed exactly the way a template's `<desc>` binding is
+ * (`parseBinding`, see `./binding.ts`), so a bare path (`{design.length}`, `source=signalk,context=self`
+ * shorthand), the full binding grammar (`{source=signalk,path=navigation.position,format=position}`),
+ * and a `source=label,path=...` binding all work uniformly. Pass the result to `assembleRawContext`
+ * (repaintScheduler.ts) exactly as a template's own bindings are - it fetches the `signalk`/
+ * `resources`-sourced ones and silently ignores `label`/`einklabel`-sourced ones, which resolve directly
+ * against `context.label`/`context.meta` instead (built by the caller, not fetched).
+ *
+ * A placeholder that isn't valid binding grammar (e.g. a typo like `{source=taheight}`) is silently
+ * skipped here rather than thrown - the same per-field isolation `SvgRenderer` gives a bad `<desc>`
+ * binding, so one malformed placeholder doesn't take down the whole prompt. `substitutePlaceholders`
+ * hits the identical parse error at substitution time and turns it into "???" for just that field.
+ */
+function findPromptBindings(...texts) {
+    const seen = new Set();
+    const bindings = [];
+    for (const text of texts) {
+        for (const match of text.matchAll(/\{([^{}]+)\}/g)) {
+            const key = match[1].trim();
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            try {
+                bindings.push((0, binding_1.parseBinding)(key));
+            }
+            catch {
+                // see doc comment above - left for `substitutePlaceholders` to turn into "???"
+            }
+        }
+    }
+    return bindings;
+}
+/**
+ * Substitutes every `{...}` placeholder in `text` with its resolved binding value against `context`
+ * (built by `assembleRawContext` plus `context.label` from `buildLabelContext` - see
+ * `findPromptBindings`). Mirrors `renderBinding`'s per-field isolation, but substitutes "???" for
+ * anything that resolves to no value at all (missing path, invalid binding grammar) rather than "" -
+ * prose with a silently-blank word reads as a fact ("for the sailor of a m vessel"), not as a gap the
+ * reader would notice. Two things override that "???": a binding that resolves successfully to a
+ * legitimately empty string (e.g. an unset `{source=label,path=description}`) is left as empty, since
+ * that's a real answer, not a miss; and a binding with an explicit `default=` (see `./binding.ts`) uses
+ * that default instead, since the prompt author has already said what a missing value should read as.
+ */
+function substitutePlaceholders(text, context) {
+    return text.replace(/\{([^{}]+)\}/g, (_match, raw) => {
+        const key = raw.trim();
+        try {
+            const binding = (0, binding_1.parseBinding)(key);
+            const value = (0, binding_1.resolveBinding)(binding, context);
+            if ((value === undefined || value === null) && binding.default === undefined)
+                return "???";
+            return (0, binding_1.renderBinding)(binding, context);
+        }
+        catch {
+            return "???";
+        }
+    });
+}
+/**
+ * Strips everything outside the first `<svg`...last `</svg>` span - a chat model asked for "only raw
+ * SVG markup" still often wraps it in a markdown code fence or adds a sentence of commentary either
+ * side, despite the target-guidance fragment telling it not to.
+ */
+function extractSvg(raw) {
+    const start = raw.indexOf("<svg");
+    const end = raw.lastIndexOf("</svg>");
+    if (start === -1 || end === -1 || end < start) {
+        throw new Error('LLM response did not contain a "<svg>...</svg>" document');
+    }
+    return raw.slice(start, end + "</svg>".length);
+}
+/**
+ * `ai` and every `@ai-sdk/*` provider package are `optionalDependencies` (see package.json), not plain
+ * `dependencies` - most installs (every device using `renderMode: "svg-template"` only) never touch an
+ * LLM at all, so they shouldn't have to pull in this whole gateway stack, and an install that fails to
+ * fetch one of these (network hiccup, `npm install --omit=optional`, an unsupported platform) must not
+ * break BLE painting/templates, which have nothing to do with it. That means every reference to one of
+ * these packages has to be a `require()` reached only when a `renderMode: "llm-prompt"` device actually
+ * calls `callLlm` - a top-level `import` would be resolved eagerly the moment this module loads (which
+ * is every plugin start, via `repaintScheduler.ts`), throwing before any config is even read. Types are
+ * still fully checked via `typeof import(...)` below, which - unlike a value `import` - is erased
+ * entirely at compile time and leaves no runtime trace for `tsc` to eagerly require.
+ */
+function loadOptional(moduleName) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return require(moduleName);
+    }
+    catch (err) {
+        throw new Error(`LLM provider support needs the optional dependency "${moduleName}", which isn't installed - run "npm install ${moduleName}" (${err.message})`);
+    }
+}
+/** Ollama's own default local listen address - see the `"ollama"` case in `resolveModel` below. */
+const DEFAULT_OLLAMA_BASE_URL = "http://localhost:11434/v1";
+/**
+ * Resolves `settings` to a Vercel AI SDK model handle. `"ollama"` and `"local"` both go through the
+ * generic `@ai-sdk/openai-compatible` provider (Ollama/LM Studio/vLLM all expose an OpenAI-compatible
+ * endpoint, and none of them has - or needs - its own dedicated `@ai-sdk/*` package): `"ollama"`
+ * defaults `llmBaseUrl` to Ollama's own standard local address so it works with no further config
+ * (override it only if Ollama is running elsewhere, e.g. on the SignalK server's own host reached over
+ * the network); `"local"` is for anything else OpenAI-compatible, where there's no sensible universal
+ * default, so `llmBaseUrl` is required.
+ */
+function resolveModel(settings) {
+    const model = settings.llmModel;
+    if (!model) {
+        throw new Error("no LLM model configured (PluginConfig.llmModel)");
+    }
+    switch (settings.llmProvider ?? "openai") {
+        case "anthropic": {
+            const { createAnthropic } = loadOptional("@ai-sdk/anthropic");
+            return createAnthropic({ apiKey: settings.llmApiKey })(model);
+        }
+        case "google": {
+            const { createGoogleGenerativeAI } = loadOptional("@ai-sdk/google");
+            return createGoogleGenerativeAI({ apiKey: settings.llmApiKey })(model);
+        }
+        case "xai": {
+            const { createXai } = loadOptional("@ai-sdk/xai");
+            return createXai({ apiKey: settings.llmApiKey })(model);
+        }
+        case "ollama": {
+            const { createOpenAICompatible } = loadOptional("@ai-sdk/openai-compatible");
+            return createOpenAICompatible({
+                name: "ollama",
+                baseURL: settings.llmBaseUrl || DEFAULT_OLLAMA_BASE_URL,
+                apiKey: settings.llmApiKey,
+            })(model);
+        }
+        case "local": {
+            if (!settings.llmBaseUrl) {
+                throw new Error('llmBaseUrl is required when llmProvider is "local"');
+            }
+            const { createOpenAICompatible } = loadOptional("@ai-sdk/openai-compatible");
+            return createOpenAICompatible({ name: "local", baseURL: settings.llmBaseUrl, apiKey: settings.llmApiKey })(model);
+        }
+        case "openai":
+        default: {
+            const { createOpenAI } = loadOptional("@ai-sdk/openai");
+            return createOpenAI({ apiKey: settings.llmApiKey })(model);
+        }
+    }
+}
+/**
+ * Calls the configured LLM gateway with `prompt`, returning its raw text response - not yet extracted/
+ * validated as SVG, see `extractSvg`. This is the first network call in the codebase that needs its own
+ * timeout (`fetchJson` in `../httpJson.ts` has none - every existing call is to the local SignalK
+ * server's own REST API).
+ */
+async function callLlm(settings, prompt) {
+    const model = resolveModel(settings);
+    const { generateText } = loadOptional("ai");
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), (settings.llmTimeoutSeconds ?? 30) * 1000);
+    try {
+        const { text } = await generateText({ model, prompt, abortSignal: controller.signal });
+        return text;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

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,21 +1,21 @@
 {
   "name": "@rhizomatics/signalk-einklabel-plugin",
-  "version": "0.10.0",
-  "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",
     "eink",
     "esl",
     "instrument",
-    "watch-schedule",
     "signalk",
     "signalk-category-hardware",
     "signalk-category-instruments",
     "signalk-node-server-plugin",
-    "tides"
+    "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"
   },
@@ -83,6 +83,11 @@
       "docs/assets/screenshots/example_watch_schedule.png",
       "docs/assets/screenshots/plugin_config.png",
       "docs/assets/screenshots/label_config.png"
+    ],
+    "recommends": [
+      "signalk-watch-schedule",
+      "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>