@rhizomatics/signalk-einklabel-plugin 0.4.0 → 0.4.1

package/dist/devices/zhsunyco/protocol.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Wolink ESL GATT service ("WOLINKBLEESL2020") and characteristic UUIDs, transcribed
+ * from the reference driver (examples/device_driver/zhunyco/wolink_ble.py).
+ */
+export declare const WOLINK_SERVICE_UUID = "30323032-4c53-4545-4c42-4b4e494c4f57";
+/** BLE manufacturer ID Zhsunyco/Wolink devices advertise under. */
+export declare const ZHSUNYCO_MANUFACTURER_ID = 48042;
+export declare const WOLINK_CHARACTERISTIC_UUIDS: {
+    readonly data: "31323032-4c53-4545-4c42-4b4e494c4f57";
+    readonly config: "32323032-4c53-4545-4c42-4b4e494c4f57";
+    readonly authenticate: "33323032-4c53-4545-4c42-4b4e494c4f57";
+    readonly status: "34323032-4c53-4545-4c42-4b4e494c4f57";
+    readonly battery: "35323032-4c53-4545-4c42-4b4e494c4f57";
+};
+export declare const COMMAND: {
+    readonly uploadBlock: 42240;
+    readonly refreshUncompressed: 42241;
+};
+export interface AdvertisedDeviceInfo {
+    pid: number;
+    appVersion: string;
+    hwVersion: string;
+}
+/** Decodes the 8-byte header shared by the advertising mirror and config characteristic. */
+export declare function decodeAdvertisedInfo(data: Buffer): AdvertisedDeviceInfo | undefined;
+export declare function decodeBatteryMv(data: Buffer): number;
+export declare function decodeStatus(data: Buffer): {
+    busy: boolean;
+    errorCode: number;
+};
+/** Builds the 6-byte command header: 2-byte LE command word + 4-byte LE offset/length. */
+export declare function commandHeader(command: number, offsetOrLength?: number): Buffer;
+/**
+ * Stock BLE auth key shared by Wolink ESL devices out of the box (same bytes as the
+ * reference driver's `BLE_SECRET_KEY`). Used as a fallback when a device hasn't been
+ * given its own key via the plugin config.
+ */
+export declare const DEFAULT_BLE_AUTH: number[];
+/** Resolves the configured per-device hex key, falling back to `DEFAULT_BLE_AUTH`. */
+export declare function resolveAesKey(aesKeyHex?: string): Buffer;
+/**
+ * Encrypts the device's auth challenge with the AES-128 key (CBC, zero IV).
+ *
+ * The reference driver PKCS7-pads the challenge before encrypting and keeps only the
+ * first ciphertext block. Since CBC's first output block depends only on the IV and the
+ * plaintext's first block, that's equivalent to encrypting the (already block-sized)
+ * challenge directly with padding disabled — so we skip the pad-then-truncate round trip.
+ */
+export declare function authResponse(challenge: Buffer, key: Buffer): Buffer;

package/dist/devices/zhsunyco/protocol.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BLE_AUTH = exports.COMMAND = exports.WOLINK_CHARACTERISTIC_UUIDS = exports.ZHSUNYCO_MANUFACTURER_ID = exports.WOLINK_SERVICE_UUID = void 0;
+exports.decodeAdvertisedInfo = decodeAdvertisedInfo;
+exports.decodeBatteryMv = decodeBatteryMv;
+exports.decodeStatus = decodeStatus;
+exports.commandHeader = commandHeader;
+exports.resolveAesKey = resolveAesKey;
+exports.authResponse = authResponse;
+const crypto_1 = require("crypto");
+/**
+ * Wolink ESL GATT service ("WOLINKBLEESL2020") and characteristic UUIDs, transcribed
+ * from the reference driver (examples/device_driver/zhunyco/wolink_ble.py).
+ */
+exports.WOLINK_SERVICE_UUID = '30323032-4c53-4545-4c42-4b4e494c4f57';
+/** BLE manufacturer ID Zhsunyco/Wolink devices advertise under. */
+exports.ZHSUNYCO_MANUFACTURER_ID = 0xbbaa;
+exports.WOLINK_CHARACTERISTIC_UUIDS = {
+    data: '31323032-4c53-4545-4c42-4b4e494c4f57',
+    config: '32323032-4c53-4545-4c42-4b4e494c4f57',
+    authenticate: '33323032-4c53-4545-4c42-4b4e494c4f57',
+    status: '34323032-4c53-4545-4c42-4b4e494c4f57',
+    battery: '35323032-4c53-4545-4c42-4b4e494c4f57',
+};
+exports.COMMAND = {
+    uploadBlock: 0xa500,
+    refreshUncompressed: 0xa501,
+};
+/** Decodes the 8-byte header shared by the advertising mirror and config characteristic. */
+function decodeAdvertisedInfo(data) {
+    if (data.length < 8) {
+        return undefined;
+    }
+    return {
+        pid: data.readUInt16BE(2),
+        appVersion: data.readUInt16BE(4).toString(16).padStart(4, '0'),
+        hwVersion: data.readUInt16BE(6).toString(16).padStart(4, '0'),
+    };
+}
+function decodeBatteryMv(data) {
+    return data.readUInt16BE(data.length - 2);
+}
+function decodeStatus(data) {
+    return { busy: data[0] === 0xff, errorCode: data[1] };
+}
+/** Builds the 6-byte command header: 2-byte LE command word + 4-byte LE offset/length. */
+function commandHeader(command, offsetOrLength = 0) {
+    const header = Buffer.alloc(6);
+    header.writeUInt16LE(command, 0);
+    header.writeUInt32LE(offsetOrLength, 2);
+    return header;
+}
+const AES_KEY_LENGTH = 16;
+const AES_CHALLENGE_LENGTH = 16;
+/**
+ * Stock BLE auth key shared by Wolink ESL devices out of the box (same bytes as the
+ * reference driver's `BLE_SECRET_KEY`). Used as a fallback when a device hasn't been
+ * given its own key via the plugin config.
+ */
+exports.DEFAULT_BLE_AUTH = [
+    155, 96, 159, 40, 188, 73, 226, 87,
+    41, 189, 123, 141, 242, 43, 68, 32,
+];
+/** Resolves the configured per-device hex key, falling back to `DEFAULT_BLE_AUTH`. */
+function resolveAesKey(aesKeyHex) {
+    return aesKeyHex ? Buffer.from(aesKeyHex, 'hex') : Buffer.from(exports.DEFAULT_BLE_AUTH);
+}
+/**
+ * Encrypts the device's auth challenge with the AES-128 key (CBC, zero IV).
+ *
+ * The reference driver PKCS7-pads the challenge before encrypting and keeps only the
+ * first ciphertext block. Since CBC's first output block depends only on the IV and the
+ * plaintext's first block, that's equivalent to encrypting the (already block-sized)
+ * challenge directly with padding disabled — so we skip the pad-then-truncate round trip.
+ */
+function authResponse(challenge, key) {
+    if (key.length !== AES_KEY_LENGTH) {
+        throw new Error(`zhsunyco AES key must be ${AES_KEY_LENGTH} bytes (${AES_KEY_LENGTH * 2} hex chars), got ${key.length}`);
+    }
+    if (challenge.length !== AES_CHALLENGE_LENGTH) {
+        throw new Error(`zhsunyco auth challenge expected ${AES_CHALLENGE_LENGTH} bytes, got ${challenge.length}`);
+    }
+    const cipher = (0, crypto_1.createCipheriv)('aes-128-cbc', key, Buffer.alloc(16));
+    cipher.setAutoPadding(false);
+    return Buffer.concat([cipher.update(challenge), cipher.final()]);
+}

package/dist/httpJson.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Fetches and parses a JSON endpoint, with an error message that's actually actionable: which URL,
+ * what HTTP status, and the response/underlying error detail - see `describeCause` for why plain
+ * `fetch()` failures need unwrapping to be useful at all.
+ */
+export declare function fetchJson(url: string): Promise<unknown>;

package/dist/httpJson.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchJson = fetchJson;
+/**
+ * Describes a network-level fetch failure's `error.cause` - Node's `fetch()` only ever throws a
+ * generic `TypeError: fetch failed`, with the actually useful detail (e.g. ECONNREFUSED) nested in
+ * `.cause`, and a multi-address connection attempt (e.g. trying both IPv6 and IPv4 for "localhost")
+ * surfaces as an `AggregateError` whose own `.message` is empty - the real detail is in `.errors`.
+ */
+function describeCause(cause) {
+    const errors = cause.errors;
+    if (Array.isArray(errors)) {
+        return errors.map(describeCause).join('; ');
+    }
+    if (cause instanceof Error) {
+        return cause.message || cause.code || cause.toString();
+    }
+    return String(cause);
+}
+/**
+ * Fetches and parses a JSON endpoint, with an error message that's actually actionable: which URL,
+ * what HTTP status, and the response/underlying error detail - see `describeCause` for why plain
+ * `fetch()` failures need unwrapping to be useful at all.
+ */
+async function fetchJson(url) {
+    let response;
+    try {
+        response = await fetch(url);
+    }
+    catch (err) {
+        const cause = err.cause;
+        const detail = cause !== undefined ? describeCause(cause) : err.message;
+        throw new Error(`fetch failed: ${url} - ${detail}`);
+    }
+    if (!response.ok) {
+        const body = await response.text().catch(() => '');
+        throw new Error(`fetch failed: ${url} (${response.status} ${response.statusText})${body ? ` - ${body}` : ''}`);
+    }
+    return response.json();
+}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import { ServerAPI, Plugin } from '@signalk/server-api';
+import { registerDriver, getDriver, allDrivers } from './devices/registry';
+import type { VendorDriver as VendorDriverType, DeviceMetadata as DeviceMetadataType, DiscoveredDevice as DiscoveredDeviceType, VendorDeviceConfig as VendorDeviceConfigType, Colour as ColourType } from './devices/types';
+/**
+ * Public extension point for vendor packages. A package that adds support for a new
+ * ESL vendor (e.g. `signalk-esl-shoplabelcorp-plugin`) imports this module and calls
+ * `plugin.registerDriver(new ShopLabelCorpDriver())` from its own SignalK plugin's
+ * `start()` (or at module load time). There's no scanning of installed packages -
+ * registration is always an explicit call by the extension's own code.
+ *
+ * Declare this package as a `peerDependency` (not a regular dependency) in the
+ * extension package, so npm resolves a single shared copy - otherwise the extension
+ * would register into a different registry instance than the one this plugin reads from.
+ */
+declare function plugin(app: ServerAPI): Plugin;
+declare namespace plugin {
+    const registerVendorDriver: typeof registerDriver;
+    const getVendorDriver: typeof getDriver;
+    const allVendorDrivers: typeof allDrivers;
+    type VendorDriver = VendorDriverType;
+    type DeviceMetadata = DeviceMetadataType;
+    type DiscoveredDevice = DiscoveredDeviceType;
+    type VendorDeviceConfig = VendorDeviceConfigType;
+    type Colour = ColourType;
+}
+export = plugin;

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+const plugin_1 = require("./plugin");
+const registry_1 = require("./devices/registry");
+/**
+ * Public extension point for vendor packages. A package that adds support for a new
+ * ESL vendor (e.g. `signalk-esl-shoplabelcorp-plugin`) imports this module and calls
+ * `plugin.registerDriver(new ShopLabelCorpDriver())` from its own SignalK plugin's
+ * `start()` (or at module load time). There's no scanning of installed packages -
+ * registration is always an explicit call by the extension's own code.
+ *
+ * Declare this package as a `peerDependency` (not a regular dependency) in the
+ * extension package, so npm resolves a single shared copy - otherwise the extension
+ * would register into a different registry instance than the one this plugin reads from.
+ */
+function plugin(app) {
+    return (0, plugin_1.createPlugin)(app);
+}
+(function (plugin) {
+    plugin.registerVendorDriver = registry_1.registerDriver;
+    plugin.getVendorDriver = registry_1.getDriver;
+    plugin.allVendorDrivers = registry_1.allDrivers;
+})(plugin || (plugin = {}));
+module.exports = plugin;

package/dist/pathMeta.d.ts

@@ -0,0 +1,16 @@
+import { DisplayUnits } from './render/formatters';
+export interface PathMetadata {
+    units?: string;
+    description?: string;
+    displayUnits?: DisplayUnits;
+}
+/**
+ * Fetches all of a vessel's per-path metadata in one request - `GET .../vessels/<context>/meta` returns
+ * a flat `{ "<dotted.path>": { units, description, displayUnits? }, ... }` map, with `displayUnits`
+ * already fully resolved (category/targetUnit/formula/symbol) server-side. That resolution
+ * (`enhanceMetadataResponse` in signalk-server's `src/interfaces/rest.js`) has no in-process equivalent
+ * reachable via the plugin API (confirmed against the signalk-server source - `app.getMetadata` is
+ * bound directly to the unenhanced `@signalk/path-metadata` package), so both the live plugin
+ * (repaintScheduler.ts) and the CLI (cli/liveContext.ts) fetch it the same way, over HTTP.
+ */
+export declare function fetchPathMeta(apiUrl: string, context: string): Promise<Record<string, PathMetadata>>;

package/dist/pathMeta.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchPathMeta = fetchPathMeta;
+const httpJson_1 = require("./httpJson");
+/** `self` -> `vessels/self`, `vessels.urn:mrn:imo:mmsi:1` -> `vessels/urn:mrn:imo:mmsi:1` - matches the REST path for that context's whole-vessel metadata. */
+function metaContextPath(context) {
+    return context === 'self' ? 'vessels/self' : context.replace(/\./g, '/');
+}
+/**
+ * Fetches all of a vessel's per-path metadata in one request - `GET .../vessels/<context>/meta` returns
+ * a flat `{ "<dotted.path>": { units, description, displayUnits? }, ... }` map, with `displayUnits`
+ * already fully resolved (category/targetUnit/formula/symbol) server-side. That resolution
+ * (`enhanceMetadataResponse` in signalk-server's `src/interfaces/rest.js`) has no in-process equivalent
+ * reachable via the plugin API (confirmed against the signalk-server source - `app.getMetadata` is
+ * bound directly to the unenhanced `@signalk/path-metadata` package), so both the live plugin
+ * (repaintScheduler.ts) and the CLI (cli/liveContext.ts) fetch it the same way, over HTTP.
+ */
+async function fetchPathMeta(apiUrl, context) {
+    const url = `${apiUrl}/signalk/v1/api/${metaContextPath(context)}/meta`;
+    return (await (0, httpJson_1.fetchJson)(url));
+}

package/dist/plugin.d.ts

@@ -0,0 +1,2 @@
+import { Plugin, ServerAPI } from '@signalk/server-api';
+export declare function createPlugin(app: ServerAPI): Plugin;

package/dist/plugin.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPlugin = createPlugin;
+const config_1 = require("./config");
+const registry_1 = require("./devices/registry");
+const zhsunyco_1 = require("./devices/zhsunyco");
+const bleDiscovery_1 = require("./devices/bleDiscovery");
+const repaintScheduler_1 = require("./repaintScheduler");
+/** Mirrors signalk-bluetti-plugin's convention: scan briefly, report finds via plugin status for the user to copy-paste. */
+async function runStartupScan(app, discovered, durationSeconds) {
+    app.setPluginStatus(`Scanning for ESL devices for ${durationSeconds}s...`);
+    const startedAt = Date.now();
+    let scanError;
+    const drivers = (0, registry_1.allDrivers)();
+    try {
+        await (0, bleDiscovery_1.withDiscovery)(durationSeconds * 1000, async (adapter) => {
+            await (0, bleDiscovery_1.forEachAdvertisedDevice)(adapter, async ({ device, address, name, manufacturerId, manufacturerData }) => {
+                const driver = drivers.find((candidate) => candidate.matchesAdvertisement(name, manufacturerId));
+                if (!driver) {
+                    return;
+                }
+                const found = await driver.identifyDevice(device, address, name, manufacturerId, manufacturerData).catch((err) => {
+                    scanError = `${driver.vendor} scan failed: ${err.message}`;
+                    app.debug(`${scanError}\n${err.stack ?? ''}`);
+                    return undefined;
+                });
+                if (!found) {
+                    return;
+                }
+                discovered.push(found);
+                const pid = found.pid !== undefined ? `0x${found.pid.toString(16).padStart(4, '0')}` : 'unknown';
+                app.debug(`discovered ${driver.vendor} device "${found.name ?? ''}" [${found.address}] pid=${pid}`);
+            });
+        });
+    }
+    catch (err) {
+        // Without this, an error thrown anywhere in the discovery window (e.g. BlueZ dropping the
+        // D-Bus connection) skips every line below, leaving the admin UI stuck on "Scanning..."
+        // forever even though `discovered` may already hold devices found before the failure.
+        scanError = `scan failed: ${err.message}`;
+        app.debug(`${scanError}\n${err.stack ?? ''}`);
+    }
+    // Surfaces the real cause in the admin UI (instead of only the debug log) - a scan that
+    // ends in well under its configured duration is almost always this, not "no devices nearby".
+    app.setPluginError(scanError ?? '');
+    const elapsedSeconds = ((Date.now() - startedAt) / 1000).toFixed(1);
+    if (discovered.length === 0) {
+        app.setPluginStatus(`Scan complete - no ESL devices found nearby after ${elapsedSeconds} seconds.`);
+        return;
+    }
+    const summary = discovered.map((device) => `${device.name ?? device.vendor} [${device.address}]`).join(', ');
+    app.setPluginStatus(`Scan complete - found ${discovered.length} device(s) in ${elapsedSeconds}s: ${summary} - pick one from a device's "Device" field below`);
+}
+function createPlugin(app) {
+    (0, registry_1.registerDriver)(new zhsunyco_1.ZhsunycoDriver());
+    let scheduler;
+    const lastDiscovered = [];
+    // node-ble/BlueZ has no scan-cancellation API, so a scan started by a previous start()
+    // keeps running its full duration even after stop() - tracking it here stops a quick
+    // disable/re-enable from opening a second concurrent D-Bus/BlueZ session, which was
+    // making the new scan fail (and report "no devices found") almost immediately.
+    let scanInProgress;
+    let scanStartedAt;
+    const plugin = {
+        id: 'signalk-einklabel-plugin',
+        name: 'eInk ESL (Electronic Shelf Label)',
+        description: 'Renders selected SignalK data to BLE eInk Electronic Shelf Labels',
+        schema: () => (0, config_1.configSchema)(app, lastDiscovered),
+        uiSchema: () => (0, config_1.configUiSchema)(),
+        start(config) {
+            const pluginConfig = { ...(0, config_1.defaultConfig)(), ...config };
+            app.debug(`starting with ${pluginConfig.devices.length} configured device(s)`);
+            if (pluginConfig.scanOnStart) {
+                if (scanInProgress) {
+                    const elapsedSeconds = ((Date.now() - (scanStartedAt ?? Date.now())) / 1000).toFixed(0);
+                    app.debug(`a scan from before this restart is still running (${elapsedSeconds}s) - skipping a new one to avoid a second concurrent BLE session`);
+                    app.setPluginStatus(`Skipped startup scan - a scan from before this restart is still finishing (running ${elapsedSeconds}s) and will update the "Device" picker below once it does.`);
+                }
+                else {
+                    lastDiscovered.length = 0;
+                    scanStartedAt = Date.now();
+                    const scan = runStartupScan(app, lastDiscovered, pluginConfig.scanDurationSeconds).catch((err) => app.debug(`startup scan failed: ${err.message}`));
+                    scanInProgress = scan;
+                    scan.finally(() => {
+                        scanInProgress = undefined;
+                        scanStartedAt = undefined;
+                    });
+                }
+            }
+            scheduler = (0, repaintScheduler_1.startRepaintScheduler)(app, pluginConfig);
+        },
+        stop() {
+            scheduler?.stop();
+            scheduler = undefined;
+            app.debug('stopped');
+        },
+    };
+    return plugin;
+}

package/dist/render/binding.d.ts

@@ -0,0 +1,54 @@
+import { TemplateContext } from './types';
+declare const SOURCES: readonly ["signalk", "resources", "einklabel"];
+type Source = (typeof SOURCES)[number];
+/**
+ * Parsed form of a `<desc>`'s `key=value,key=value` content - see `parseBinding` for the grammar.
+ */
+export interface Binding {
+    source: Source;
+    /** `'self'` (default) or any other literal SignalK context as shown in the Data Browser, e.g. `vessels.urn:mrn:imo:mmsi:232345678`. */
+    context: string;
+    /** Required when `source === 'resources'` - the Resources API resource type, e.g. `tides`, `waypoints`. */
+    resource?: string;
+    /** For `source === 'einklabel'`, a dotted path into the plugin's own injected `meta` (e.g. `repainted`), rather than into vessel/resource data. */
+    path: string;
+    /** A named formatter (see `./formatters.ts`), or `'raw'` to suppress automatic unit conversion (see `renderBinding`). */
+    format?: string;
+    /** Explicit unit-preferences category (e.g. `depth`, `speed`, `temperature`) for a numeric value with no path metadata of its own, e.g. a `source=resources` value - see `../unitCategories.ts`. */
+    category?: string;
+    round?: number;
+}
+/**
+ * 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
+ * defaults (`source=signalk,context=self`), plain `path=navigation.speedOverGround` (auto-converts via
+ * that path's own metadata - see `renderBinding`). A bare path with no `key=value` pairs at all, e.g.
+ * `environment.forecast.description`, is shorthand for `path=environment.forecast.description`
+ * (source/context still default to signalk/self) - SignalK paths never contain `=`, so its absence
+ * unambiguously signals this shorthand.
+ */
+export declare function parseBinding(desc: string): Binding;
+/**
+ * Parses every `<text>` element's `<desc>` binding out of raw SVG source - lets a caller discover what
+ * data a template needs before fetching anything, with no separate config declaring it (see
+ * `assembleRawContext` in repaintScheduler.ts).
+ */
+export declare function findBindings(svgSource: string): Binding[];
+/** Resolves a parsed `Binding` against the render context assembled by `assembleRawContext`. */
+export declare function resolveBinding(binding: Binding, context: TemplateContext): unknown;
+/**
+ * Resolves a binding and renders it to text exactly as `SvgRenderer` does for a `<desc>` - shared so
+ * the CLI's `field`/`fields` commands show the same thing a real render would.
+ *
+ * Precedence for a numeric value:
+ * 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.
+ * 3. Otherwise, a `signalk`-sourced value auto-converts to its path's own preferred display unit (from
+ *    `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`.
+ */
+export declare function renderBinding(binding: Binding, context: TemplateContext): string;
+export {};

package/dist/render/binding.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseBinding = parseBinding;
+exports.findBindings = findBindings;
+exports.resolveBinding = resolveBinding;
+exports.renderBinding = renderBinding;
+const xmldom_1 = require("@xmldom/xmldom");
+const formatters_1 = require("./formatters");
+const SOURCES = ['signalk', 'resources', 'einklabel'];
+const KNOWN_KEYS = new Set(['source', 'context', 'resource', 'path', 'format', 'category', 'round']);
+/**
+ * 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
+ * defaults (`source=signalk,context=self`), plain `path=navigation.speedOverGround` (auto-converts via
+ * that path's own metadata - see `renderBinding`). A bare path with no `key=value` pairs at all, e.g.
+ * `environment.forecast.description`, is shorthand for `path=environment.forecast.description`
+ * (source/context still default to signalk/self) - SignalK paths never contain `=`, so its absence
+ * unambiguously signals this shorthand.
+ */
+function parseBinding(desc) {
+    const trimmedDesc = desc.trim();
+    if (trimmedDesc && !trimmedDesc.includes('=')) {
+        return { source: 'signalk', context: 'self', path: trimmedDesc };
+    }
+    const fields = {};
+    for (const pair of desc.split(',')) {
+        const trimmed = pair.trim();
+        if (!trimmed)
+            continue;
+        const eq = trimmed.indexOf('=');
+        if (eq < 0) {
+            throw new Error(`invalid binding "${desc}" - expected "key=value" pairs, got "${trimmed}"`);
+        }
+        const key = trimmed.slice(0, eq).trim();
+        if (!KNOWN_KEYS.has(key)) {
+            throw new Error(`invalid binding "${desc}" - unknown key "${key}"`);
+        }
+        fields[key] = trimmed.slice(eq + 1).trim();
+    }
+    const source = (fields.source ?? 'signalk');
+    if (!SOURCES.includes(source)) {
+        throw new Error(`invalid binding "${desc}" - unknown source "${source}"`);
+    }
+    const context = fields.context ?? 'self';
+    if (source === 'resources' && !fields.resource) {
+        throw new Error(`invalid binding "${desc}" - source=resources requires a "resource" key`);
+    }
+    if (!fields.path) {
+        throw new Error(`invalid binding "${desc}" - missing required "path" key`);
+    }
+    return {
+        source,
+        context,
+        resource: fields.resource,
+        path: fields.path,
+        format: fields.format,
+        category: fields.category,
+        round: fields.round !== undefined ? Number(fields.round) : undefined,
+    };
+}
+/**
+ * Parses every `<text>` element's `<desc>` binding out of raw SVG source - lets a caller discover what
+ * data a template needs before fetching anything, with no separate config declaring it (see
+ * `assembleRawContext` in repaintScheduler.ts).
+ */
+function findBindings(svgSource) {
+    const doc = new xmldom_1.DOMParser().parseFromString(svgSource, 'image/svg+xml');
+    const elements = doc.getElementsByTagName('text');
+    const bindings = [];
+    for (let i = 0; i < elements.length; i++) {
+        const desc = elements.item(i)?.getElementsByTagName('desc').item(0);
+        if (desc?.textContent) {
+            bindings.push(parseBinding(desc.textContent));
+        }
+    }
+    return bindings;
+}
+/** Supports both `a.[0].b` and `a[0].b` array index notation, matching `setAtPath` in repaintScheduler.ts. */
+function getAtPath(obj, path) {
+    const segments = path
+        .replace(/\[(\d+)\]/g, '.$1')
+        .split('.')
+        .filter((segment) => segment.length > 0);
+    let node = obj;
+    for (const segment of segments) {
+        if (node === null || typeof node !== 'object')
+            return undefined;
+        node = node[segment];
+    }
+    return node;
+}
+/** Resolves a parsed `Binding` against the render context assembled by `assembleRawContext`. */
+function resolveBinding(binding, context) {
+    if (binding.source === 'signalk') {
+        const signalk = context.signalk;
+        const vessel = signalk?.[binding.context];
+        if (vessel === undefined) {
+            throw new Error(`binding references context "${binding.context}" which is not present in the render context`);
+        }
+        return getAtPath(vessel, binding.path);
+    }
+    if (binding.source === 'einklabel') {
+        const meta = context.meta;
+        if (meta === undefined) {
+            throw new Error('binding references source "einklabel" but no "meta" is present in the render context');
+        }
+        return getAtPath(meta, binding.path);
+    }
+    const resources = context.resources;
+    const resource = resources?.[binding.resource];
+    if (resource === undefined) {
+        throw new Error(`binding references resource "${binding.resource}" which is not present in the render context`);
+    }
+    return getAtPath(resource, binding.path);
+}
+/**
+ * Looks up a `signalk`-sourced binding's path in `context.pathMeta` - a flat `{ [context]:
+ * { [dottedPath]: { displayUnits } } }` map (see `../pathMeta.ts`), matching the flat shape
+ * `GET .../vessels/<context>/meta` itself returns, unlike `context.signalk`'s nested tree. Unlike
+ * `resolveBinding`, never throws - metadata is always best-effort (a `source=resources` binding, a
+ * path with no metadata, or a server unreachable at `signalkApiUrl` all resolve to "no metadata"
+ * rather than an error).
+ */
+function resolveDisplayUnits(binding, context) {
+    if (binding.source !== 'signalk')
+        return undefined;
+    const pathMeta = context.pathMeta;
+    return pathMeta?.[binding.context]?.[binding.path]?.displayUnits;
+}
+/**
+ * Looks up an explicit `category=` binding's resolved conversion info from `context.categories` (built
+ * by `fetchCategoryDisplayUnits` in `../unitCategories.ts`) - same throw-on-missing pattern as
+ * `resolveBinding`'s context/resource lookups, since naming a category is a declared dependency.
+ */
+function resolveCategoryDisplayUnits(binding, context) {
+    const categories = context.categories;
+    const displayUnits = categories?.[binding.category];
+    if (!displayUnits) {
+        throw new Error(`binding references category "${binding.category}" which is not present in the render context`);
+    }
+    return displayUnits;
+}
+/**
+ * Resolves a binding and renders it to text exactly as `SvgRenderer` does for a `<desc>` - shared so
+ * the CLI's `field`/`fields` commands show the same thing a real render would.
+ *
+ * Precedence for a numeric value:
+ * 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.
+ * 3. Otherwise, a `signalk`-sourced value auto-converts to its path's own preferred display unit (from
+ *    `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`.
+ */
+function renderBinding(binding, context) {
+    const value = resolveBinding(binding, context);
+    if (binding.format && binding.format !== 'raw')
+        return (0, formatters_1.applyFormat)(binding.format, value, context, binding.round);
+    if (typeof value === 'number') {
+        if (binding.category)
+            return (0, formatters_1.formatDisplayUnits)(value, resolveCategoryDisplayUnits(binding, context), binding.round);
+        const displayUnits = binding.format === 'raw' ? undefined : resolveDisplayUnits(binding, context);
+        if (displayUnits)
+            return (0, formatters_1.formatDisplayUnits)(value, displayUnits, binding.round);
+        if (binding.round !== undefined)
+            return value.toFixed(binding.round);
+    }
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'object')
+        return JSON.stringify(value);
+    return String(value);
+}

package/dist/render/fonts.d.ts

@@ -0,0 +1,9 @@
+/**
+ * One font per CSS generic family bucket (monospace/sans-serif/serif), bundled so rendering
+ * doesn't depend on the host having any fonts installed - resvg-wasm cannot see host fonts at
+ * all (see project memory). Must be .woff2 - resvg-wasm silently fails to render .woff.
+ * resvg auto-classifies each loaded font from its own metadata; there's no proven way to
+ * control which one wins if two loaded fonts share a generic bucket, so keep this to one per
+ * bucket rather than adding e.g. bold variants here.
+ */
+export declare const DEFAULT_FONT_PATHS: string[];

package/dist/render/fonts.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_FONT_PATHS = void 0;
+/**
+ * One font per CSS generic family bucket (monospace/sans-serif/serif), bundled so rendering
+ * doesn't depend on the host having any fonts installed - resvg-wasm cannot see host fonts at
+ * all (see project memory). Must be .woff2 - resvg-wasm silently fails to render .woff.
+ * resvg auto-classifies each loaded font from its own metadata; there's no proven way to
+ * control which one wins if two loaded fonts share a generic bucket, so keep this to one per
+ * bucket rather than adding e.g. bold variants here.
+ */
+exports.DEFAULT_FONT_PATHS = [
+    require.resolve('@fontsource/jetbrains-mono/files/jetbrains-mono-latin-400-normal.woff2'),
+    require.resolve('@fontsource/roboto/files/roboto-latin-400-normal.woff2'),
+    require.resolve('@fontsource/playfair-display/files/playfair-display-latin-400-normal.woff2'),
+];

package/dist/render/formatters.d.ts

@@ -0,0 +1,18 @@
+import { TemplateContext } from './types';
+/**
+ * Matches `displayUnits` on a path's own metadata (`app.getMetadata(path).displayUnits` in the live
+ * plugin, the `.../meta` tree over HTTP in the CLI) - SignalK's per-path unit-preference info, fully
+ * resolved (formula/symbol ready to use), unlike the global `/signalk/v1/unitpreferences/active`
+ * endpoint which only gives a bare `targetUnit` name with no conversion math at all.
+ */
+export interface DisplayUnits {
+    category: string;
+    targetUnit: string;
+    formula?: string;
+    symbol?: string;
+    displayFormat?: string;
+}
+/** 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". */
+export declare function formatDisplayUnits(value: number, displayUnits: DisplayUnits, round: number | undefined): string;
+/** Applies a named `format=` formatter to a resolved binding value. */
+export declare function applyFormat(name: string, value: unknown, context: TemplateContext, round: number | undefined): string;