@rhizomatics/signalk-einklabel-plugin 0.6.4 → 0.7.1

package/dist/render/formatters.js

@@ -8,7 +8,7 @@ const mathjs_1 = require("mathjs");
 /** Converts a base-SI value (always what SignalK paths deliver) to its metadata's preferred display unit and formats it with the unit's symbol, e.g. 3.42 -> "11.2ft". */
 function formatDisplayUnits(value, displayUnits, round) {
     const converted = displayUnits.formula ? Number((0, mathjs_1.evaluate)(displayUnits.formula, { value })) : value;
-    const decimals = round ?? (displayUnits.displayFormat?.includes('.') ? displayUnits.displayFormat.split('.')[1].length : 0);
+    const decimals = round ?? (displayUnits.displayFormat?.includes(".") ? displayUnits.displayFormat.split(".")[1].length : 0);
     const symbol = displayUnits.symbol ?? displayUnits.targetUnit;
     return `${converted.toFixed(decimals)}${symbol}`;
 }
@@ -37,10 +37,13 @@ function selfTimezone(context) {
  * binding (see `considerRepaint`).
  */
 function resolveLocalZoneAbbreviation(context) {
-    const part = new Intl.DateTimeFormat(undefined, { timeZone: selfTimezone(context), timeZoneName: 'short' })
+    const part = new Intl.DateTimeFormat(undefined, {
+        timeZone: selfTimezone(context),
+        timeZoneName: "short",
+    })
         .formatToParts(new Date())
-        .find((p) => p.type === 'timeZoneName');
-    return part?.value ?? '';
+        .find((p) => p.type === "timeZoneName");
+    return part?.value ?? "";
 }
 /**
  * A `resources`-sourced timestamp can arrive as either an ISO string (always true over HTTP, since
@@ -51,9 +54,9 @@ function resolveLocalZoneAbbreviation(context) {
  */
 function parseTimestamp(value) {
     if (value instanceof Date)
-        return luxon_1.DateTime.fromJSDate(value, { zone: 'utc' });
-    if (typeof value === 'string')
-        return luxon_1.DateTime.fromISO(value, { zone: 'utc' });
+        return luxon_1.DateTime.fromJSDate(value, { zone: "utc" });
+    if (typeof value === "string")
+        return luxon_1.DateTime.fromISO(value, { zone: "utc" });
     return undefined;
 }
 /**
@@ -63,51 +66,51 @@ function parseTimestamp(value) {
  */
 function formatLocalTime(value, context) {
     const dt = parseTimestamp(value)?.setZone(selfTimezone(context));
-    return dt?.isValid ? dt.toFormat('HH:mm') : '';
+    return dt?.isValid ? dt.toFormat("HH:mm") : "";
 }
 /** e.g. "27 Jun" - day of month (no leading zero) and abbreviated month name, in the local vessel's timezone. */
 function formatDayMonth(value, context) {
     const dt = parseTimestamp(value)?.setZone(selfTimezone(context));
-    return dt?.isValid ? dt.toFormat('d MMM') : '';
+    return dt?.isValid ? dt.toFormat("d MMM") : "";
 }
 /** e.g. "21 Jun 26 18:05" - day of month (no leading zero), abbreviated month, 2-digit year, and 24h time, in the local vessel's timezone. */
 function formatLocalDatetimeShort(value, context) {
     const dt = parseTimestamp(value)?.setZone(selfTimezone(context));
-    return dt?.isValid ? dt.toFormat('d MMM yy HH:mm') : '';
+    return dt?.isValid ? dt.toFormat("d MMM yy HH:mm") : "";
 }
 /**
  * IANA region names are ambiguous about DST (e.g. "Europe/London" is UTC+00:00 in winter, UTC+01:00
  * in summer); show the numeric offset actually in effect.
  */
 function formatUtcOffset(value) {
-    if (typeof value !== 'string' || !value)
-        return '';
+    if (typeof value !== "string" || !value)
+        return "";
     const dt = luxon_1.DateTime.now().setZone(value);
-    return dt.isValid ? `UTC${dt.toFormat('ZZ')}` : '';
+    return dt.isValid ? `UTC${dt.toFormat("ZZ")}` : "";
 }
 function formatPosition(value, round) {
     const position = value;
-    if (typeof position?.latitude !== 'number' || typeof position?.longitude !== 'number')
-        return '';
+    if (typeof position?.latitude !== "number" || typeof position?.longitude !== "number")
+        return "";
     const decimals = round ?? 4;
     const lat = Math.abs(position.latitude).toFixed(decimals);
     const lon = Math.abs(position.longitude).toFixed(decimals);
-    const latHemisphere = position.latitude >= 0 ? 'N' : 'S';
-    const lonHemisphere = position.longitude >= 0 ? 'E' : 'W';
+    const latHemisphere = position.latitude >= 0 ? "N" : "S";
+    const lonHemisphere = position.longitude >= 0 ? "E" : "W";
     return `${lat}°${latHemisphere} ${lon}°${lonHemisphere}`;
 }
 /** Applies a named `format=` formatter to a resolved binding value. */
 function applyFormat(name, value, context, round) {
     switch (name) {
-        case 'local_time':
+        case "local_time":
             return formatLocalTime(value, context);
-        case 'day_mon':
+        case "day_mon":
             return formatDayMonth(value, context);
-        case 'local_datetime_short':
+        case "local_datetime_short":
             return formatLocalDatetimeShort(value, context);
-        case 'utc_offset':
+        case "utc_offset":
             return formatUtcOffset(value);
-        case 'position':
+        case "position":
             return formatPosition(value, round);
         default:
             throw new Error(`unknown format "${name}"`);

package/dist/render/png.d.ts

@@ -1,3 +1,3 @@
-import { Bitmap } from './types';
+import { Bitmap } from "./types";
 /** Encodes a common Bitmap as PNG bytes, for previewing templates without a physical device. */
 export declare function bitmapToPng(bitmap: Bitmap): Buffer;

package/dist/render/svgRenderer.d.ts

@@ -1,4 +1,4 @@
-import { Bitmap, Renderer, TemplateContext } from './types';
+import { Bitmap, Renderer, TemplateContext } from "./types";
 /**
  * Renders an SVG+binding template to a common RGBA bitmap.
  *
@@ -17,12 +17,13 @@ import { Bitmap, Renderer, TemplateContext } from './types';
  * whole tree and rendered blank.
  *
  * Non-textual inclusion: an `<image>` element with a `<desc>` child works the same way, except the
- * resolved value picks one of a directory of `.svg` files (an `assets=` key, required, names that
- * directory - see `./assets.ts`) rather than substituting text, and the element is dropped entirely
- * (rather than showing an error placeholder) whenever the value is unavailable or doesn't map to a
- * file - e.g. a device without the `derived-data` plugin installed simply shows no moon-phase icon.
- * The matched file's contents are inlined as a `data:image/svg+xml;base64,...` URI so no filesystem
- * access happens at resvg-wasm's render step.
+ * resolved value picks one of a directory of `.svg` files (an `assets=` key, required, names an
+ * `assets/<name>` directory looked up under `templatesDir` first and `BUNDLED_TEMPLATES_DIR` otherwise
+ * - see `resolveAssetPath` in `./assets.ts`) rather than substituting text, and the element is dropped
+ * entirely (rather than showing an error placeholder) whenever the value is unavailable or doesn't map
+ * to a file - e.g. a device without the `derived-data` plugin installed simply shows no moon-phase
+ * icon. The matched file's contents are inlined as a `data:image/svg+xml;base64,...` URI so no
+ * filesystem access happens at resvg-wasm's render step.
  *
  * resvg-wasm cannot see the host's installed fonts (`loadSystemFonts`/`fontFiles`
  * are silently no-ops under plain Node) - it only renders text if given font
@@ -36,5 +37,5 @@ export declare class SvgRenderer implements Renderer {
     private fontBuffers?;
     constructor(fontPaths?: string[]);
     private loadFontBuffers;
-    render(svgTemplatePath: string, context: TemplateContext, width: number, height: number): Promise<Bitmap>;
+    render(svgTemplatePath: string, context: TemplateContext, width: number, height: number, templatesDir?: string, bundledTemplatesDir?: string): Promise<Bitmap>;
 }

package/dist/render/svgRenderer.js

@@ -2,15 +2,18 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SvgRenderer = void 0;
 const promises_1 = require("fs/promises");
+const path_1 = require("path");
 const xmldom_1 = require("@xmldom/xmldom");
 const resvg_wasm_1 = require("@resvg/resvg-wasm");
 const binding_1 = require("./binding");
 const assets_1 = require("./assets");
 const fonts_1 = require("./fonts");
+const pluginVersion_1 = require("../pluginVersion");
+const config_1 = require("../config");
 let wasmReady;
 function ensureWasmInitialized() {
     if (!wasmReady) {
-        wasmReady = (0, promises_1.readFile)(require.resolve('@resvg/resvg-wasm/index_bg.wasm')).then((buffer) => (0, resvg_wasm_1.initWasm)(buffer));
+        wasmReady = (0, promises_1.readFile)(require.resolve("@resvg/resvg-wasm/index_bg.wasm")).then((buffer) => (0, resvg_wasm_1.initWasm)(buffer));
     }
     return wasmReady;
 }
@@ -53,12 +56,13 @@ function expandGenericFontFamilies(svgSource) {
  * whole tree and rendered blank.
  *
  * Non-textual inclusion: an `<image>` element with a `<desc>` child works the same way, except the
- * resolved value picks one of a directory of `.svg` files (an `assets=` key, required, names that
- * directory - see `./assets.ts`) rather than substituting text, and the element is dropped entirely
- * (rather than showing an error placeholder) whenever the value is unavailable or doesn't map to a
- * file - e.g. a device without the `derived-data` plugin installed simply shows no moon-phase icon.
- * The matched file's contents are inlined as a `data:image/svg+xml;base64,...` URI so no filesystem
- * access happens at resvg-wasm's render step.
+ * resolved value picks one of a directory of `.svg` files (an `assets=` key, required, names an
+ * `assets/<name>` directory looked up under `templatesDir` first and `BUNDLED_TEMPLATES_DIR` otherwise
+ * - see `resolveAssetPath` in `./assets.ts`) rather than substituting text, and the element is dropped
+ * entirely (rather than showing an error placeholder) whenever the value is unavailable or doesn't map
+ * to a file - e.g. a device without the `derived-data` plugin installed simply shows no moon-phase
+ * icon. The matched file's contents are inlined as a `data:image/svg+xml;base64,...` URI so no
+ * filesystem access happens at resvg-wasm's render step.
  *
  * resvg-wasm cannot see the host's installed fonts (`loadSystemFonts`/`fontFiles`
  * are silently no-ops under plain Node) - it only renders text if given font
@@ -71,7 +75,7 @@ class SvgRenderer {
     constructor(fontPaths = fonts_1.DEFAULT_FONT_PATHS) {
         this.fontPaths = fontPaths;
         if (fontPaths.length === 0) {
-            throw new Error('SvgRenderer requires at least one font path - resvg-wasm cannot use host system fonts');
+            throw new Error("SvgRenderer requires at least one font path - resvg-wasm cannot use host system fonts");
         }
     }
     loadFontBuffers() {
@@ -80,73 +84,75 @@ class SvgRenderer {
         }
         return this.fontBuffers;
     }
-    async render(svgTemplatePath, context, width, height) {
+    async render(svgTemplatePath, context, width, height, templatesDir = (0, path_1.dirname)(svgTemplatePath), bundledTemplatesDir = config_1.BUNDLED_TEMPLATES_DIR) {
         const [, fontBuffers] = await Promise.all([ensureWasmInitialized(), this.loadFontBuffers()]);
-        const svgSource = expandGenericFontFamilies(await (0, promises_1.readFile)(svgTemplatePath, 'utf-8'));
-        const doc = new xmldom_1.DOMParser().parseFromString(svgSource, 'image/svg+xml');
-        const elements = doc.getElementsByTagName('text');
+        const svgSource = expandGenericFontFamilies(await (0, promises_1.readFile)(svgTemplatePath, "utf-8"));
+        const doc = new xmldom_1.DOMParser().parseFromString(svgSource, "image/svg+xml");
+        const elements = doc.getElementsByTagName("text");
         for (let i = 0; i < elements.length; i++) {
             const element = elements.item(i);
             if (!element)
                 continue;
-            const descElement = element.getElementsByTagName('desc').item(0);
+            const descElement = element.getElementsByTagName("desc").item(0);
             if (!descElement)
                 continue;
             // Scoped to this one element - a single bad/unavailable binding (e.g. a resource that hasn't
             // loaded yet) must not blank out every other field on the label, nor abort the whole repaint.
             try {
-                const binding = (0, binding_1.parseBinding)(descElement.textContent ?? '');
+                const binding = (0, binding_1.parseBinding)(descElement.textContent ?? "");
                 element.textContent = (0, binding_1.renderBinding)(binding, context);
             }
             catch (err) {
-                console.error(`field "${descElement.textContent}" failed to render: ${err.message}`);
-                element.textContent = 'ERROR';
+                console.error(`${pluginVersion_1.PLUGIN_NAME}: field "${descElement.textContent}" failed to render: ${err.message}`);
+                element.textContent = "ERROR";
             }
         }
         // Collected up front, rather than iterated live like the `<text>` loop above - some of these get
         // removed outright (see below), and removing from a live NodeList while iterating it by index would
         // skip whatever shifts into the removed slot.
         const imageElements = [];
-        const rawImageElements = doc.getElementsByTagName('image');
+        const rawImageElements = doc.getElementsByTagName("image");
         for (let i = 0; i < rawImageElements.length; i++) {
             const element = rawImageElements.item(i);
             if (element)
                 imageElements.push(element);
         }
         for (const element of imageElements) {
-            const descElement = element.getElementsByTagName('desc').item(0);
+            const descElement = element.getElementsByTagName("desc").item(0);
             if (!descElement)
                 continue;
             // Same one-field-at-a-time isolation as the `<text>` loop - and the same "no value" outcome
             // (here, dropping the element rather than blanking to 'ERROR' text) for a value that isn't
             // available at all as for one that doesn't map to any asset file, per the binding's contract.
             try {
-                const binding = (0, binding_1.parseBinding)(descElement.textContent ?? '');
+                const binding = (0, binding_1.parseBinding)(descElement.textContent ?? "");
                 if (!binding.assets) {
                     throw new Error('an <image> binding requires an "assets" key naming the directory to pick a file from');
                 }
                 const key = (0, assets_1.normalizeAssetKey)((0, binding_1.resolveBinding)(binding, context));
-                const assetPath = key && (0, assets_1.resolveAssetPath)(svgTemplatePath, binding.assets, key);
+                const assetPath = key && (0, assets_1.resolveAssetPath)(templatesDir, bundledTemplatesDir, binding.assets, key);
                 if (!assetPath) {
+                    const dirProblem = (0, assets_1.describeAssetsDirProblem)(templatesDir, bundledTemplatesDir, binding.assets);
                     console.error(key
-                        ? `image "${descElement.textContent}" has no asset file for value "${key}" in "${binding.assets}"`
-                        : `image "${descElement.textContent}" resolved to no usable value to pick an asset file with`);
+                        ? `${pluginVersion_1.PLUGIN_NAME}: image "${descElement.textContent}" has no asset file for value "${key}" in "${binding.assets}"`
+                        : `${pluginVersion_1.PLUGIN_NAME}: image "${descElement.textContent}" resolved to no usable value to pick an asset file with`);
+                    console.error(`${pluginVersion_1.PLUGIN_NAME}: ${dirProblem ?? `assets directory for "${binding.assets}" checked out fine - the miss is just this value's`}`);
                     element.parentNode?.removeChild(element);
                     continue;
                 }
-                const assetSource = await (0, promises_1.readFile)(assetPath, 'utf-8');
-                const dataUri = `data:image/svg+xml;base64,${Buffer.from(assetSource).toString('base64')}`;
-                const hrefAttr = element.getAttribute('href') !== null ? 'href' : 'xlink:href';
+                const assetSource = await (0, promises_1.readFile)(assetPath, "utf-8");
+                const dataUri = `data:image/svg+xml;base64,${Buffer.from(assetSource).toString("base64")}`;
+                const hrefAttr = element.getAttribute("href") !== null ? "href" : "xlink:href";
                 element.setAttribute(hrefAttr, dataUri);
             }
             catch (err) {
-                console.error(`image "${descElement.textContent}" failed to render: ${err.message}`);
+                console.error(`${pluginVersion_1.PLUGIN_NAME}: image "${descElement.textContent}" failed to render: ${err.message}`);
                 element.parentNode?.removeChild(element);
             }
         }
         const svgOutput = new xmldom_1.XMLSerializer().serializeToString(doc);
         const resvg = new resvg_wasm_1.Resvg(svgOutput, {
-            fitTo: { mode: 'width', value: width },
+            fitTo: { mode: "width", value: width },
             font: { fontBuffers },
         });
         const rendered = resvg.render();

package/dist/render/types.d.ts

@@ -22,5 +22,5 @@ export interface Bitmap {
  */
 export type TemplateContext = Record<string, unknown>;
 export interface Renderer {
-    render(svgTemplatePath: string, context: TemplateContext, width: number, height: number): Promise<Bitmap>;
+    render(svgTemplatePath: string, context: TemplateContext, width: number, height: number, templatesDir?: string, bundledTemplatesDir?: string): Promise<Bitmap>;
 }

package/dist/render/unwrapSignalkTree.d.ts

@@ -0,0 +1,15 @@
+/**
+ * SignalK's full data-model shape wraps every leaf as `{ value, $source, timestamp, ... }` rather
+ * than the bare value - true both over HTTP (`GET .../vessels/self`) and in-process
+ * (`app.getSelfPath`/`getPath` in the live plugin, see `repaintScheduler.ts` - despite that module's
+ * name, these do NOT already return bare values for a regular published path; only a handful of
+ * vessel-identity fields like `uuid` do). Recursively unwraps every such leaf so a `path=` binding
+ * resolves the same way regardless of which of the two ways the render context was assembled. Only
+ * applied to `signalk` fetches - `resources` responses have no such wrapper.
+ *
+ * Keys off `value` alone, not also requiring `timestamp`/`$source` - not every server includes both
+ * on every leaf, and a `value` key is otherwise meaningless on a SignalK data-model node (it isn't a
+ * regular vessel property name), so there's no real risk of unwrapping something that isn't this
+ * wrapper.
+ */
+export declare function unwrapSignalkTree(node: unknown): unknown;

package/dist/render/unwrapSignalkTree.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unwrapSignalkTree = unwrapSignalkTree;
+/**
+ * SignalK's full data-model shape wraps every leaf as `{ value, $source, timestamp, ... }` rather
+ * than the bare value - true both over HTTP (`GET .../vessels/self`) and in-process
+ * (`app.getSelfPath`/`getPath` in the live plugin, see `repaintScheduler.ts` - despite that module's
+ * name, these do NOT already return bare values for a regular published path; only a handful of
+ * vessel-identity fields like `uuid` do). Recursively unwraps every such leaf so a `path=` binding
+ * resolves the same way regardless of which of the two ways the render context was assembled. Only
+ * applied to `signalk` fetches - `resources` responses have no such wrapper.
+ *
+ * Keys off `value` alone, not also requiring `timestamp`/`$source` - not every server includes both
+ * on every leaf, and a `value` key is otherwise meaningless on a SignalK data-model node (it isn't a
+ * regular vessel property name), so there's no real risk of unwrapping something that isn't this
+ * wrapper.
+ */
+function unwrapSignalkTree(node) {
+    if (node === null || typeof node !== "object")
+        return node;
+    if (Array.isArray(node))
+        return node.map(unwrapSignalkTree);
+    const obj = node;
+    if ("value" in obj) {
+        return obj.value;
+    }
+    return Object.fromEntries(Object.entries(obj).map(([key, value]) => [key, unwrapSignalkTree(value)]));
+}

package/dist/repaintScheduler.d.ts

@@ -1,5 +1,5 @@
-import { ServerAPI } from '@signalk/server-api';
-import { PluginConfig } from './config';
+import { ServerAPI } from "@signalk/server-api";
+import { PluginConfig } from "./config";
 export interface RepaintScheduler {
     stop(): void;
 }

package/dist/repaintScheduler.js

@@ -10,6 +10,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 unwrapSignalkTree_1 = require("./render/unwrapSignalkTree");
 const unitCategories_1 = require("./unitCategories");
 const pathMeta_1 = require("./pathMeta");
 const resolveApiUrl_1 = require("./resolveApiUrl");
@@ -17,11 +18,11 @@ const pluginVersion_1 = require("./pluginVersion");
 const INTERVAL_POLL_MS = 60000;
 const SUBSCRIPTION_DEBOUNCE_MS = 2000;
 function statePath(app) {
-    return (0, path_1.join)(app.getDataDirPath(), 'repaint-state.json');
+    return (0, path_1.join)(app.getDataDirPath(), "repaint-state.json");
 }
 function loadState(app) {
     try {
-        return JSON.parse((0, fs_1.readFileSync)(statePath(app), 'utf-8'));
+        return JSON.parse((0, fs_1.readFileSync)(statePath(app), "utf-8"));
     }
     catch {
         return {};
@@ -33,24 +34,24 @@ function saveState(app, state) {
 /** Deterministic JSON serialisation (sorted keys) so re-ordered object keys don't change the hash. */
 function stableStringify(value) {
     if (Array.isArray(value)) {
-        return `[${value.map(stableStringify).join(',')}]`;
+        return `[${value.map(stableStringify).join(",")}]`;
     }
-    if (value !== null && typeof value === 'object') {
+    if (value !== null && typeof value === "object") {
         const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
-        return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(',')}}`;
+        return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
     }
     return JSON.stringify(value);
 }
 function hashContext(context) {
-    return (0, crypto_1.createHash)('sha1').update(stableStringify(context)).digest('hex');
+    return (0, crypto_1.createHash)("sha1").update(stableStringify(context)).digest("hex");
 }
 /** Merges `value` into `target` at the nested location described by a dotted SignalK path. */
 function setAtPath(target, path, value) {
-    const segments = path.split('.');
+    const segments = path.split(".");
     let node = target;
     for (const segment of segments.slice(0, -1)) {
         const next = node[segment];
-        node[segment] = typeof next === 'object' && next !== null ? next : {};
+        node[segment] = typeof next === "object" && next !== null ? next : {};
         node = node[segment];
     }
     node[segments[segments.length - 1]] = value;
@@ -58,32 +59,40 @@ function setAtPath(target, path, value) {
 /**
  * Reads live data for exactly what a template's own bindings ask for - no separate config declaring it.
  * `signalk`-sourced bindings are read directly (`self` via `getSelfPath`, anything else via `getPath`
- * against that literal SignalK context) - in-process, no URL needed. `resources`-sourced bindings go
- * through `app.resourcesApi`, in-process too. Per-path unit-conversion metadata (`pathMeta`, for
- * automatic conversion - see `renderBinding`) and an explicit `category=` binding's resolved
- * conversion both have no in-process equivalent (confirmed against the signalk-server source - that
- * resolution only happens in its REST layer), so both need `apiUrl` - fetching `pathMeta` is
- * best-effort (a missing/unreachable server just means no automatic conversion), but a `category=`
- * binding is a declared dependency, so a missing `apiUrl` is a hard error there.
+ * against that literal SignalK context) - in-process, no URL needed. Despite their names, neither
+ * already returns a bare value for a regular published path - both return the full data-model node
+ * (`{ path, value, context, source, $source, timestamp }`); only a handful of vessel-identity fields
+ * like `uuid` come back bare. `unwrapSignalkTree` strips that wrapper the same way it does for the
+ * CLI's HTTP-fetched equivalent (`assembleLiveContext` in `cli/liveContext.ts`), so a `path=` binding
+ * resolves to the same value either way - without it, `resolveBinding` would hand back the whole
+ * wrapper object instead of e.g. a plain string, breaking any binding that expects one (a `<image>`'s
+ * `assets=`, a `format=` formatter, etc). `resources`-sourced bindings go through `app.resourcesApi`,
+ * in-process too, with no such wrapper. Per-path unit-conversion metadata (`pathMeta`, for automatic
+ * conversion - see `renderBinding`) and an explicit `category=` binding's resolved conversion both
+ * have no in-process equivalent (confirmed against the signalk-server source - that resolution only
+ * happens in its REST layer), so both need `apiUrl` - fetching `pathMeta` is best-effort (a
+ * missing/unreachable server just means no automatic conversion), but a `category=` binding is a
+ * declared dependency, so a missing `apiUrl` is a hard error there.
  */
 async function assembleRawContext(app, apiUrl, bindings) {
     var _a;
     const signalk = {};
     const seenSignalk = new Set();
     for (const binding of bindings) {
-        if (binding.source !== 'signalk')
+        if (binding.source !== "signalk")
             continue;
         const key = `${binding.context} ${binding.path}`;
         if (seenSignalk.has(key))
             continue;
         seenSignalk.add(key);
-        const value = binding.context === 'self' ? app.getSelfPath(binding.path) : app.getPath(`${binding.context}.${binding.path}`);
+        const rawValue = binding.context === "self" ? app.getSelfPath(binding.path) : app.getPath(`${binding.context}.${binding.path}`);
+        const value = (0, unwrapSignalkTree_1.unwrapSignalkTree)(rawValue);
         const namespace = (signalk[_a = binding.context] ?? (signalk[_a] = {}));
         setAtPath(namespace, binding.path, value);
     }
     signalk.self ?? (signalk.self = {});
     const pathMeta = {};
-    const signalkContexts = new Set(bindings.filter((binding) => binding.source === 'signalk').map((binding) => binding.context));
+    const signalkContexts = new Set(bindings.filter((binding) => binding.source === "signalk").map((binding) => binding.context));
     if (apiUrl) {
         for (const ctx of signalkContexts) {
             try {
@@ -95,7 +104,7 @@ async function assembleRawContext(app, apiUrl, bindings) {
         }
     }
     const resources = {};
-    const resourceNames = new Set(bindings.filter((binding) => binding.source === 'resources').map((binding) => binding.resource));
+    const resourceNames = new Set(bindings.filter((binding) => binding.source === "resources").map((binding) => binding.resource));
     for (const name of resourceNames) {
         // `listResources`'s type only allows the standard SignalKResourceType union, but the underlying
         // Resources API (and a custom provider like signalk-tides, registered under the non-standard
@@ -105,7 +114,7 @@ async function assembleRawContext(app, apiUrl, bindings) {
     }
     const categoryNames = new Set(bindings.filter((binding) => binding.category).map((binding) => binding.category));
     if (categoryNames.size > 0 && !apiUrl) {
-        throw new Error(`binding references categor${categoryNames.size > 1 ? 'ies' : 'y'} "${[...categoryNames].join(', ')}" but no SignalK API base URL is configured`);
+        throw new Error(`binding references categor${categoryNames.size > 1 ? "ies" : "y"} "${[...categoryNames].join(", ")}" but no SignalK API base URL is configured`);
     }
     const categories = apiUrl ? await (0, unitCategories_1.fetchCategoryDisplayUnits)(apiUrl, categoryNames) : {};
     return { signalk, resources, pathMeta, categories };
@@ -126,8 +135,9 @@ async function considerRepaint(app, config, device, state, getApiUrl) {
         app.debug(`"${device.friendlyName}": no driver/metadata for device "${device.device}", skipping`);
         return;
     }
-    const templatePath = (0, config_1.resolveTemplatePath)((0, config_1.resolveTemplatesDir)(config.templatesDir), device.templateName);
-    const bindings = (0, binding_1.findBindings)((0, fs_1.readFileSync)(templatePath, 'utf-8'));
+    const templatesDir = (0, config_1.resolveTemplatesDir)(config.templatesDir);
+    const templatePath = (0, config_1.resolveTemplatePath)(templatesDir, device.templateName);
+    const bindings = (0, binding_1.findBindings)((0, fs_1.readFileSync)(templatePath, "utf-8"));
     const apiUrl = await getApiUrl().catch((err) => {
         app.debug(`"${device.friendlyName}": ${err.message}`);
         return undefined;
@@ -147,7 +157,7 @@ async function considerRepaint(app, config, device, state, getApiUrl) {
         },
     };
     const renderer = new svgRenderer_1.SvgRenderer();
-    const bitmap = await renderer.render(templatePath, renderContext, metadata.width, metadata.height - metadata.voffset);
+    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 paintDurationMs = 0;
     await (0, bleDiscovery_1.withRetries)(config.paintRetries, async (attempt) => {
@@ -170,7 +180,7 @@ function startRepaintScheduler(app, config) {
     const unsubscribes = [];
     const getApiUrl = (0, resolveApiUrl_1.createApiUrlResolver)(config.signalkApiUrl);
     const repaint = (device) => considerRepaint(app, config, device, state, getApiUrl).catch((err) => app.debug(`"${device.friendlyName}": repaint failed: ${err.message}`));
-    const intervalDevices = config.devices.filter((device) => device.repaintTrigger === 'interval');
+    const intervalDevices = config.devices.filter((device) => device.repaintTrigger === "interval");
     if (intervalDevices.length > 0) {
         const timer = setInterval(() => {
             const now = new Date();
@@ -178,14 +188,14 @@ function startRepaintScheduler(app, config) {
                 const hours = device.intervalHours ?? 1;
                 const minute = device.intervalMinute ?? 0;
                 if (now.getHours() % hours === 0 && now.getMinutes() === minute) {
-                    repaint(device);
+                    void repaint(device);
                 }
             }
         }, INTERVAL_POLL_MS);
         unsubscribes.push(() => clearInterval(timer));
     }
     for (const device of config.devices) {
-        if (device.repaintTrigger === 'subscription' && device.triggerPath) {
+        if (device.repaintTrigger === "subscription" && device.triggerPath) {
             const stream = app.streambundle.getSelfStream(device.triggerPath).debounce(SUBSCRIPTION_DEBOUNCE_MS);
             const unsub = stream.onValue(() => repaint(device));
             unsubscribes.push(unsub);
@@ -194,7 +204,7 @@ function startRepaintScheduler(app, config) {
     // Check every device once at startup - harmless given hash dedup, and covers newly-added
     // devices or a forceRepaint left set from before a restart.
     for (const device of config.devices) {
-        repaint(device);
+        void repaint(device);
     }
     return {
         stop() {

package/dist/resolveApiUrl.js

@@ -18,9 +18,9 @@ const httpJson_1 = require("./httpJson");
  * entirely by install method: a bare `npm install` defaults to 3000; container/systemd installs
  * commonly default to 80, or 443 if TLS-terminated locally.
  */
-exports.SIGNALK_API_URL_OPTIONS = ['http://localhost:3000', 'http://localhost', 'https://localhost'];
+exports.SIGNALK_API_URL_OPTIONS = ["http://localhost:3000", "http://localhost", "https://localhost"];
 /** Cheap, always-required (for `category=` resolution) and read-only, so safe to use as a connectivity+access probe. */
-const PROBE_PATH = '/signalk/v1/unitpreferences/categories';
+const PROBE_PATH = "/signalk/v1/unitpreferences/categories";
 async function probe(url) {
     try {
         await (0, httpJson_1.fetchJson)(`${url}${PROBE_PATH}`);
@@ -44,7 +44,7 @@ async function resolveSignalkApiUrl(configuredUrl) {
     }
     throw new Error(configuredUrl
         ? `configured SignalK API base URL "${configuredUrl}" did not respond to ${PROBE_PATH} - check the port, and that anonymous read access is enabled`
-        : `could not reach this server's API on any of ${exports.SIGNALK_API_URL_OPTIONS.join(', ')} - it may be on a different port, or anonymous read access may not be enabled`);
+        : `could not reach this server's API on any of ${exports.SIGNALK_API_URL_OPTIONS.join(", ")} - it may be on a different port, or anonymous read access may not be enabled`);
 }
 /**
  * Memoizes a successful resolution only - a failure (server not ready yet, anonymous access

package/dist/unitCategories.d.ts

@@ -1,4 +1,4 @@
-import { DisplayUnits } from './render/formatters';
+import { DisplayUnits } from "./render/formatters";
 /**
  * Resolves `category=` bindings (e.g. `category=depth` on a `source=resources` value with no per-path
  * metadata of its own to auto-convert from) against this server's unit-preferences setup.

package/dist/unitCategories.js

@@ -2,9 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchCategoryDisplayUnits = fetchCategoryDisplayUnits;
 const httpJson_1 = require("./httpJson");
-const CATEGORIES_PATH = '/signalk/v1/unitpreferences/categories';
-const ACTIVE_PRESET_PATH = '/signalk/v1/unitpreferences/active';
-const DEFINITIONS_PATH = '/signalk/v1/unitpreferences/definitions';
+const CATEGORIES_PATH = "/signalk/v1/unitpreferences/categories";
+const ACTIVE_PRESET_PATH = "/signalk/v1/unitpreferences/active";
+const DEFINITIONS_PATH = "/signalk/v1/unitpreferences/definitions";
 /**
  * Resolves `category=` bindings (e.g. `category=depth` on a `source=resources` value with no per-path
  * metadata of its own to auto-convert from) against this server's unit-preferences setup.