@rhizomatics/signalk-einklabel-plugin 1.3.0-beta8 → 1.3.0

package/dist/devices/zhsunyco/index.js

@@ -7,10 +7,14 @@ const pluginVersion_1 = require("../../pluginVersion");
 const metadata_1 = require("./metadata");
 const encode_1 = require("./encode");
 const reframe_1 = require("../../render/reframe");
+const mirror_1 = require("../../render/mirror");
+const compression_1 = require("./compression");
 const protocol_1 = require("./protocol");
 /** node-ble has no MTU API; this matches the reference driver's mtu(247)-9 default. */
 const UPLOAD_CHUNK_SIZE = 238;
 const CHUNK_WRITE_DELAY_MS = 20;
+/** With nothing acknowledging each write, pace them further apart so the label isn't sent data faster than it can take it. */
+const UNACKNOWLEDGED_CHUNK_WRITE_DELAY_MS = 50;
 const AUTH_SETTLE_DELAY_MS = 500;
 const STATUS_WAIT_TIMEOUT_MS = 60000;
 /** Bounds `readDeviceDetails`' whole connect+read attempt during a scan - see its doc comment. */
@@ -48,10 +52,13 @@ class ZhsunycoDriver {
     }
     async paint(bitmap, config) {
         const aesKey = (0, protocol_1.resolveAesKey)(config.aesKey);
+        const log = config.log ?? (() => { });
         const backend = config.gattBackend ?? (0, bleBackend_1.nodeBleBackend)();
+        log("connecting");
         const conn = await backend.connectGatt(config.address, config.connectTimeoutMs ?? DEFAULT_PAINT_CONNECT_TIMEOUT_MS);
+        log("connected");
         try {
-            const info = (0, protocol_1.decodeAdvertisedInfo)(await conn.read(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.config));
+            const info = (0, protocol_1.decodeAdvertisedInfo)(await readConfig(conn, log));
             if (!info) {
                 throw new Error("zhsunyco device did not return valid config data");
             }
@@ -77,23 +84,35 @@ class ZhsunycoDriver {
                 const challenge = await conn.read(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.authenticate);
                 await conn.write(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.authenticate, (0, protocol_1.authResponse)(challenge, aesKey), false);
                 await (0, bleDiscovery_1.sleep)(AUTH_SETTLE_DELAY_MS);
-                const framed = (0, reframe_1.reframeBitmap)(bitmap, metadata.width, metadata.height - metadata.voffset, config.reframe ?? "crop");
+                log("authenticated");
+                const framed = (0, mirror_1.mirrorBitmap)((0, reframe_1.reframeBitmap)(bitmap, metadata.width, metadata.height - metadata.voffset, config.reframe ?? "crop"), config.mirror ?? "none");
                 const pixelData = (0, encode_1.encodeBitmap)(framed, metadata);
-                for (let offset = 0; offset < pixelData.length; offset += UPLOAD_CHUNK_SIZE) {
-                    const chunk = pixelData.subarray(offset, offset + UPLOAD_CHUNK_SIZE);
-                    await conn.write(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.data, Buffer.concat([(0, protocol_1.commandHeader)(protocol_1.COMMAND.uploadBlock, offset), chunk]), true);
-                    await (0, bleDiscovery_1.sleep)(CHUNK_WRITE_DELAY_MS);
+                const compress = config.compress ?? true;
+                // Upload offsets and the refresh length both count bytes of whatever's actually sent - the
+                // compressed payload when compressing, not the raw buffer it inflates back to.
+                const payload = compress ? (0, compression_1.compressWolinkBlocks)(pixelData) : pixelData;
+                const acknowledged = !config.writeWithoutResponse;
+                log(`uploading ${payload.length} bytes${compress ? ` (compressed from ${pixelData.length})` : ""} in ` +
+                    `${Math.ceil(payload.length / UPLOAD_CHUNK_SIZE)} ${acknowledged ? "acknowledged" : "unacknowledged"} writes`);
+                for (let offset = 0; offset < payload.length; offset += UPLOAD_CHUNK_SIZE) {
+                    const chunk = payload.subarray(offset, offset + UPLOAD_CHUNK_SIZE);
+                    await conn.write(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.data, Buffer.concat([(0, protocol_1.commandHeader)(protocol_1.COMMAND.uploadBlock, offset), chunk]), acknowledged);
+                    await (0, bleDiscovery_1.sleep)(acknowledged ? CHUNK_WRITE_DELAY_MS : UNACKNOWLEDGED_CHUNK_WRITE_DELAY_MS);
                 }
-                await conn.write(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.data, (0, protocol_1.commandHeader)(protocol_1.COMMAND.refreshUncompressed, pixelData.length), true);
+                await conn.write(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.data, (0, protocol_1.commandHeader)(compress ? protocol_1.COMMAND.refreshCompressed : protocol_1.COMMAND.refreshUncompressed, payload.length), acknowledged);
+                log("refresh sent, waiting for the label to finish");
                 // `Promise.race` can't cancel its loser, so once `statusReceived` settles (the common case)
                 // this timer would otherwise sit alive for the rest of its 60s regardless - see the identical
                 // reasoning on `readDeviceDetails`'s own race, below.
                 let statusTimer;
                 const statusTimeout = new Promise((resolve) => {
-                    statusTimer = setTimeout(resolve, STATUS_WAIT_TIMEOUT_MS);
+                    statusTimer = setTimeout(() => resolve("timeout"), STATUS_WAIT_TIMEOUT_MS);
                 });
                 try {
-                    await Promise.race([statusReceived, statusTimeout]);
+                    const outcome = await Promise.race([statusReceived, statusTimeout]);
+                    log(outcome === "timeout"
+                        ? `no reply from the label within ${STATUS_WAIT_TIMEOUT_MS}ms - assuming it painted`
+                        : "label reported the paint complete");
                 }
                 finally {
                     clearTimeout(statusTimer);
@@ -109,6 +128,22 @@ class ZhsunycoDriver {
     }
 }
 exports.ZhsunycoDriver = ZhsunycoDriver;
+/**
+ * The first read of a paint. If the label's service isn't there at all (seen as node-ble's "Service not
+ * available" behind the BLE Manager), logs which services the connection does report - the difference
+ * between BlueZ not having discovered the label's services yet and it seeing a different set entirely.
+ */
+async function readConfig(conn, log) {
+    try {
+        return await conn.read(protocol_1.WOLINK_SERVICE_UUID, protocol_1.WOLINK_CHARACTERISTIC_UUIDS.config);
+    }
+    catch (err) {
+        const services = await conn.discoverServices().catch((discoverErr) => `could not list them: ${discoverErr.message}`);
+        const listed = Array.isArray(services) ? services.map((service) => service.uuid).join(", ") || "none" : services;
+        log(`reading the label's config failed (${err.message}) - services visible on this connection: ${listed}`);
+        throw err;
+    }
+}
 /**
  * Battery level needs a connection regardless, so reuse it to also fill in the PID/hwVersion
  * when the advertisement didn't carry decodable manufacturer data - a scan matched purely by name

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

@@ -15,6 +15,8 @@ export declare const WOLINK_CHARACTERISTIC_UUIDS: {
 export declare const COMMAND: {
     readonly uploadBlock: 42240;
     readonly refreshUncompressed: 42241;
+    /** Refresh after uploading a `compressWolinkBlocks` payload rather than the raw buffer. */
+    readonly refreshCompressed: 42242;
 };
 export interface AdvertisedDeviceInfo {
     pid: number;

package/dist/devices/zhsunyco/protocol.js

@@ -25,6 +25,8 @@ exports.WOLINK_CHARACTERISTIC_UUIDS = {
 exports.COMMAND = {
     uploadBlock: 0xa500,
     refreshUncompressed: 0xa501,
+    /** Refresh after uploading a `compressWolinkBlocks` payload rather than the raw buffer. */
+    refreshCompressed: 0xa502,
 };
 /** Decodes the 8-byte header shared by the advertising mirror and config characteristic. */
 function decodeAdvertisedInfo(data) {

package/dist/docs/templateReference.d.ts

@@ -0,0 +1,18 @@
+/** The reference block for one bundled template name, e.g. `tides` (a family) or `tide.svg`. */
+export declare function templateReference(templateName: string, templatesDir?: string): string;
+/** Every bundled template name a user can pick - plain `.svg` files and family directories, not dot-prefixed internals. */
+export declare function bundledTemplateNames(templatesDir?: string): string[];
+/** A one-row-per-template summary, linking each to the example page whose reference block covers it. */
+export declare function templatesSummary(pagesByTemplate: Map<string, string>, templatesDir?: string): string;
+/**
+ * Regenerates every marked block under `examplesDir`, returning each file's current and regenerated
+ * content. `templates-summary` blocks link to whichever page holds a template's `template-reference`
+ * block, so all pages are scanned for those first.
+ */
+export declare function regenerateExampleDocs(examplesDir: string, templatesDir?: string): {
+    path: string;
+    current: string;
+    updated: string;
+    stale: boolean;
+}[];
+export declare const EXAMPLES_DOCS_DIR: string;

package/dist/docs/templateReference.js

@@ -0,0 +1,207 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXAMPLES_DOCS_DIR = void 0;
+exports.templateReference = templateReference;
+exports.bundledTemplateNames = bundledTemplateNames;
+exports.templatesSummary = templatesSummary;
+exports.regenerateExampleDocs = regenerateExampleDocs;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const binding_1 = require("../render/binding");
+const config_1 = require("../config");
+const zhsunyco_1 = require("../devices/zhsunyco");
+const gicisky_1 = require("../devices/gicisky");
+/**
+ * Generates the "Template reference" blocks in the docs' example pages from the bundled templates
+ * themselves - sizes, aspect ratios, colours, which supported labels each size fits, and the data
+ * fields each one reads - so that reference can't drift from the templates it describes. Blocks sit
+ * between `<!-- BEGIN GENERATED: <kind> [<template>] -->` and `<!-- END GENERATED -->` markers in
+ * hand-written pages; everything outside them is left alone. Run `npm run docs:templates` to update,
+ * and `templateReference.test.ts` fails when a block is stale.
+ */
+const TEMPLATE_SOURCE_URL = "https://github.com/rhizomatics/signalk-einklabel-plugin/blob/main/templates";
+const MARKER = /<!-- BEGIN GENERATED: ([\w-]+)(?: ([^\s>]+))? -->[\s\S]*?<!-- END GENERATED -->/g;
+const COLOUR_LETTER = { black: "B", white: "W", red: "R", yellow: "Y" };
+function supportedLabels() {
+    return [new zhsunyco_1.ZhsunycoDriver(), new gicisky_1.GiciskyDriver()].flatMap((driver) => driver.supportedDevices());
+}
+/** Every file a bundled template name covers - one for a plain `.svg`, one per variant for a family directory. */
+function templateFiles(templatesDir, templateName) {
+    const path = (0, path_1.join)(templatesDir, templateName);
+    if (!(0, fs_1.existsSync)(path)) {
+        throw new Error(`template "${templateName}" not found in ${templatesDir}`);
+    }
+    const read = (relativePath, colours) => {
+        const source = (0, fs_1.readFileSync)((0, path_1.join)(templatesDir, relativePath), "utf-8");
+        return { path: relativePath, ...(0, binding_1.readTemplateDimensions)(source), colours, bindings: (0, binding_1.findBindings)(source) };
+    };
+    if ((0, fs_1.statSync)(path).isDirectory()) {
+        return (0, config_1.listTemplateVariants)(path)
+            .sort((a, b) => b.width - a.width || b.height - a.height)
+            .map((variant) => read(`${templateName}/${variant.fileName}`, variant.colours));
+    }
+    return [read(templateName)];
+}
+function variantName(file) {
+    return file.path
+        .split("/")
+        .pop()
+        .replace(/\.svg$/, "");
+}
+function aspectRatio(width, height) {
+    return `${(width / height).toFixed(2)} : 1`;
+}
+function matchingLabels(file, labels) {
+    const matches = labels
+        .filter((label) => label.width === file.width && label.height - label.voffset === file.height)
+        .map((label) => {
+        const colours = label.colours.map((colour) => COLOUR_LETTER[colour]).join("");
+        // Some models' own label already names their colours (e.g. Gicisky's `2.9" BWR`).
+        const name = label.label.includes(colours) ? label.label : `${label.label} ${colours}`;
+        return `${label.manufacturer ?? ""} ${name}`.trim();
+    });
+    return matches.length > 0 ? [...new Set(matches)].join(", ") : "none exactly - see [Reframing](../templates.md#reframing)";
+}
+function describeSource(binding) {
+    switch (binding.source) {
+        case "signalk":
+            return binding.context === "self" ? "Signal K path" : `Signal K path (${binding.context})`;
+        case "resources":
+            return `\`${binding.resource}\` resource${binding.provider ? ` (provider \`${binding.provider}\`)` : ""}`;
+        case "einklabel":
+            return "Plugin";
+        case "label":
+            return "Label details";
+    }
+}
+function describeOptions(binding) {
+    return [
+        binding.assets && `image from \`${binding.assets}\``,
+        binding.format && `format \`${binding.format}\``,
+        binding.category && `category \`${binding.category}\``,
+        binding.round !== undefined && `round ${binding.round}`,
+        binding.default !== undefined && `default \`${binding.default}\``,
+    ].filter((option) => Boolean(option));
+}
+/** A table row per distinct field - array indexes collapsed, so `extremes[0].time` and `extremes[2].time` are one row. */
+function fieldsTable(files) {
+    const rows = new Map();
+    for (const file of files) {
+        for (const binding of file.bindings) {
+            const source = describeSource(binding);
+            const path = binding.path.replace(/\[\d+\]/g, "[n]");
+            const key = `${source}\u0000${path}`;
+            const row = rows.get(key) ?? { source, path, options: new Set(), usedIn: new Set() };
+            describeOptions(binding).forEach((option) => row.options.add(option));
+            row.usedIn.add(variantName(file));
+            rows.set(key, row);
+        }
+    }
+    const showUsedIn = files.length > 1;
+    const header = showUsedIn ? "| Source | Path | Options | Used in |\n|---|---|---|---|" : "| Source | Path | Options |\n|---|---|---|";
+    const sorted = [...rows.values()].sort((a, b) => a.source.localeCompare(b.source) || a.path.localeCompare(b.path));
+    const lines = sorted.map((row) => {
+        const usedIn = row.usedIn.size === files.length ? "all" : [...row.usedIn].join(", ");
+        const cells = [row.source, `\`${row.path}\``, [...row.options].join(", ") || "-", ...(showUsedIn ? [usedIn] : [])];
+        return `| ${cells.join(" | ")} |`;
+    });
+    return [header, ...lines].join("\n");
+}
+/** The reference block for one bundled template name, e.g. `tides` (a family) or `tide.svg`. */
+function templateReference(templateName, templatesDir = config_1.BUNDLED_TEMPLATES_DIR) {
+    const files = templateFiles(templatesDir, templateName);
+    const labels = supportedLabels();
+    const sizes = files.map((file) => {
+        const size = file.width && file.height ? `${file.width} × ${file.height}` : "-";
+        const ratio = file.width && file.height ? aspectRatio(file.width, file.height) : "-";
+        const colours = file.colours?.join(", ") ?? "-";
+        return `| [\`${file.path}\`](${TEMPLATE_SOURCE_URL}/${file.path}) | ${size} | ${ratio} | ${colours} | ${matchingLabels(file, labels)} |`;
+    });
+    return [
+        `**Template:** \`${templateName}\``,
+        "",
+        "| File | Size (px) | Aspect ratio | Colours | Fits these labels exactly |",
+        "|---|---|---|---|---|",
+        ...sizes,
+        "",
+        "**Data used**",
+        "",
+        fieldsTable(files),
+    ].join("\n");
+}
+/** Every bundled template name a user can pick - plain `.svg` files and family directories, not dot-prefixed internals. */
+function bundledTemplateNames(templatesDir = config_1.BUNDLED_TEMPLATES_DIR) {
+    return [...(0, config_1.listTemplateFamilies)(templatesDir), ...(0, config_1.listSvgFiles)(templatesDir)].sort();
+}
+/** A one-row-per-template summary, linking each to the example page whose reference block covers it. */
+function templatesSummary(pagesByTemplate, templatesDir = config_1.BUNDLED_TEMPLATES_DIR) {
+    const rows = bundledTemplateNames(templatesDir).map((name) => {
+        const files = templateFiles(templatesDir, name);
+        const sizes = files.map((file) => (file.width && file.height ? `${file.width}×${file.height}` : "?")).join(", ");
+        // Only what has to come from outside the plugin - its own and the label's details are always there.
+        const external = files
+            .flatMap((file) => file.bindings)
+            .filter((binding) => binding.source === "signalk" || binding.source === "resources");
+        const resources = external.filter((binding) => binding.source === "resources").map(describeSource);
+        const paths = external.filter((binding) => binding.source === "signalk").map((binding) => `\`${binding.path}\``);
+        const sources = [...new Set(resources), ...(paths.length > 0 ? [`Signal K ${[...new Set(paths)].sort().join(", ")}`] : [])];
+        const page = pagesByTemplate.get(name);
+        return `| ${page ? `[\`${name}\`](${page})` : `\`${name}\``} | ${sizes} | ${sources.join(", ") || "-"} |`;
+    });
+    return ["| Template | Sizes | Data needed |", "|---|---|---|", ...rows].join("\n");
+}
+function markdownFiles(dir) {
+    return (0, fs_1.readdirSync)(dir, { withFileTypes: true }).flatMap((entry) => {
+        const path = (0, path_1.join)(dir, entry.name);
+        if (entry.isDirectory())
+            return markdownFiles(path);
+        return entry.name.endsWith(".md") ? [path] : [];
+    });
+}
+/**
+ * Regenerates every marked block under `examplesDir`, returning each file's current and regenerated
+ * content. `templates-summary` blocks link to whichever page holds a template's `template-reference`
+ * block, so all pages are scanned for those first.
+ */
+function regenerateExampleDocs(examplesDir, templatesDir = config_1.BUNDLED_TEMPLATES_DIR) {
+    const pages = markdownFiles(examplesDir).map((path) => ({ path, current: (0, fs_1.readFileSync)(path, "utf-8") }));
+    const pagesByTemplate = new Map();
+    for (const page of pages) {
+        for (const match of page.current.matchAll(MARKER)) {
+            if (match[1] === "template-reference" && match[2]) {
+                pagesByTemplate.set(match[2], page.path.slice(examplesDir.length + 1));
+            }
+        }
+    }
+    return pages.map((page) => {
+        const updated = page.current.replace(MARKER, (_block, kind, arg) => {
+            const body = kind === "template-reference" && arg
+                ? templateReference(arg, templatesDir)
+                : kind === "templates-summary"
+                    ? templatesSummary(pagesByTemplate, templatesDir)
+                    : undefined;
+            if (body === undefined)
+                throw new Error(`${page.path}: unknown generated block "${kind}${arg ? ` ${arg}` : ""}"`);
+            return `<!-- BEGIN GENERATED: ${kind}${arg ? ` ${arg}` : ""} -->\n<!-- Generated from the bundled templates by \`npm run docs:templates\` - do not edit by hand. -->\n\n${body}\n\n<!-- END GENERATED -->`;
+        });
+        return { ...page, updated, stale: ignoringTableAlignment(updated) !== ignoringTableAlignment(page.current) };
+    });
+}
+/**
+ * The formatter (`oxfmt`, run by `npm run docs:templates` after this) pads Markdown table columns to
+ * line up, which this generator doesn't - so compare with that padding stripped, or a freshly
+ * formatted page would always look stale.
+ */
+function ignoringTableAlignment(markdown) {
+    return markdown
+        .split("\n")
+        .map((line) => (line.startsWith("|") ? line.replace(/\s*\|\s*/g, "|").replace(/-{3,}/g, "---") : line))
+        .join("\n");
+}
+exports.EXAMPLES_DOCS_DIR = (0, path_1.join)(__dirname, "..", "..", "docs", "examples");
+if (require.main === module) {
+    const changed = regenerateExampleDocs(exports.EXAMPLES_DOCS_DIR).filter((page) => page.stale);
+    for (const page of changed)
+        (0, fs_1.writeFileSync)(page.path, page.updated);
+    console.log(changed.length > 0 ? `updated ${changed.map((page) => page.path).join(", ")}` : "template docs already up to date");
+}

package/dist/email/emailSender.d.ts

@@ -0,0 +1,27 @@
+import { EmailConfig } from "../config";
+import { Bitmap } from "../render/types";
+import { FieldRow } from "../render/fieldsTable";
+/** Either the SVG template's field-by-field table (`buildFieldsTable`), a `TemplateProvider`'s own rendered-content text (`describeContent`), or neither (a provider offered no `describeContent`). */
+export type EmailContentBody = {
+    kind: "table";
+    rows: FieldRow[];
+} | {
+    kind: "text";
+    text: string;
+} | {
+    kind: "none";
+};
+export interface LabelEmailContent {
+    friendlyName: string;
+    description?: string;
+    bitmap: Bitmap;
+    body: EmailContentBody;
+}
+/**
+ * Renders and sends one device's repaint as an email - a PNG attachment (also shown inline via a `cid`
+ * reference), the same field-by-field table `esl-cli fields` shows for a hand-authored SVG template (or
+ * a `TemplateProvider`'s own rendered-content text for something like a GenAI prompt - see `body`), and a
+ * link back to the docs site. Called from `considerRepaint` (`../repaintScheduler.ts`) whenever a
+ * device's `emailTo` is set and its render succeeds.
+ */
+export declare function sendLabelEmail(emailConfig: EmailConfig, to: string, content: LabelEmailContent): Promise<void>;

package/dist/email/emailSender.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendLabelEmail = sendLabelEmail;
+const nodemailer_1 = __importDefault(require("nodemailer"));
+const png_1 = require("../render/png");
+const DOCS_URL = "https://rhizomatics.github.io/signalk-einklabel-plugin/";
+function escapeHtml(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function bodyHtml(body) {
+    if (body.kind === "table") {
+        if (body.rows.length === 0)
+            return "";
+        const rows = body.rows
+            .map((row) => `<tr><td>${escapeHtml(row.id)}</td><td>${escapeHtml(row.spec)}</td><td>${escapeHtml(row.value)}</td></tr>`)
+            .join("");
+        return ('<table border="1" cellpadding="4" cellspacing="0" style="border-collapse:collapse;font-family:monospace;font-size:13px">' +
+            `<thead><tr><th>id</th><th>spec</th><th>value</th></tr></thead><tbody>${rows}</tbody></table>`);
+    }
+    if (body.kind === "text") {
+        return `<pre style="white-space:pre-wrap;font-family:monospace;font-size:13px">${escapeHtml(body.text)}</pre>`;
+    }
+    return "";
+}
+/**
+ * Renders and sends one device's repaint as an email - a PNG attachment (also shown inline via a `cid`
+ * reference), the same field-by-field table `esl-cli fields` shows for a hand-authored SVG template (or
+ * a `TemplateProvider`'s own rendered-content text for something like a GenAI prompt - see `body`), and a
+ * link back to the docs site. Called from `considerRepaint` (`../repaintScheduler.ts`) whenever a
+ * device's `emailTo` is set and its render succeeds.
+ */
+async function sendLabelEmail(emailConfig, to, content) {
+    const transporter = nodemailer_1.default.createTransport({
+        host: emailConfig.smtpHost,
+        port: emailConfig.smtpPort,
+        secure: emailConfig.smtpSecure,
+        auth: emailConfig.smtpUser ? { user: emailConfig.smtpUser, pass: emailConfig.smtpPassword } : undefined,
+    });
+    const png = (0, png_1.bitmapToPng)(content.bitmap);
+    const html = [
+        '<div style="font-family:sans-serif">',
+        `<h2>${escapeHtml(content.friendlyName)}</h2>`,
+        content.description ? `<p>${escapeHtml(content.description)}</p>` : "",
+        `<p><img src="cid:label-image" alt="${escapeHtml(content.friendlyName)}" style="border:1px solid #ccc" /></p>`,
+        bodyHtml(content.body),
+        `<p><a href="${DOCS_URL}">${DOCS_URL}</a></p>`,
+        "</div>",
+    ].join("\n");
+    await transporter.sendMail({
+        from: emailConfig.fromAddress,
+        to,
+        subject: `eInk Label: ${content.friendlyName}`,
+        html,
+        attachments: [
+            {
+                filename: "label.png",
+                content: png,
+                contentType: "image/png",
+                cid: "label-image",
+            },
+        ],
+    });
+}

package/dist/plugin.js

@@ -56,10 +56,10 @@ function createPlugin(app) {
         start(config) {
             const pluginConfig = {
                 ...(0, config_1.defaultConfig)(),
-                ...config,
+                ...(0, config_1.migrateConfig)(config).config,
             };
             app.debug(`starting with ${pluginConfig.devices.length} configured device(s)`);
-            (0, config_1.healNestedConfig)(app);
+            (0, config_1.healStoredConfig)(app);
             stopped = false;
             const useBleApi = pluginConfig.useBleApi && bleApiAvailable;
             if (pluginConfig.useBleApi && !bleApiAvailable) {

package/dist/render/fieldsTable.d.ts

@@ -0,0 +1,15 @@
+import { TemplateContext } from "./types";
+export interface FieldRow {
+    id: string;
+    spec: string;
+    value: string;
+}
+/**
+ * Synchronous counterpart to the CLI's `fields` command (`../cli/index.ts`) - same three columns (id,
+ * spec, resolved value), but resolved against a single already-assembled `context` rather than
+ * re-fetching per binding, since a caller like `considerRepaint` (`../repaintScheduler.ts`) already has
+ * the full context its render used. Only meaningful for a hand-authored SVG template - a
+ * `TemplateProvider`-backed template (e.g. GenAI) has no `<desc>` bindings to walk; see
+ * `TemplateProvider.describeContent` (`./templateProviders.ts`) for that case's own text summary instead.
+ */
+export declare function buildFieldsTable(svgSource: string, context: TemplateContext, templatesDir: string, bundledTemplatesDir: string): FieldRow[];

package/dist/render/fieldsTable.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFieldsTable = buildFieldsTable;
+const path_1 = require("path");
+const xmldom_1 = require("@xmldom/xmldom");
+const assets_1 = require("./assets");
+const binding_1 = require("./binding");
+function resolveFieldValue(tag, desc, context, templatesDir, bundledTemplatesDir) {
+    try {
+        const binding = (0, binding_1.parseBinding)(desc);
+        if (tag !== "image") {
+            return (0, binding_1.renderBinding)(binding, context);
+        }
+        if (!binding.assets) {
+            return 'ERROR: an <image> binding requires an "assets" key';
+        }
+        const key = (0, assets_1.normalizeAssetKey)((0, binding_1.resolveBinding)(binding, context));
+        if (!key)
+            return "(no usable value - image would be omitted)";
+        const assetPath = (0, assets_1.resolveAssetPath)(templatesDir, bundledTemplatesDir, binding.assets, key);
+        return assetPath ? `"${key}" -> ${(0, path_1.basename)(assetPath)}` : `"${key}" -> no matching asset file (image would be omitted)`;
+    }
+    catch (err) {
+        return `ERROR: ${err.message}`;
+    }
+}
+/**
+ * Synchronous counterpart to the CLI's `fields` command (`../cli/index.ts`) - same three columns (id,
+ * spec, resolved value), but resolved against a single already-assembled `context` rather than
+ * re-fetching per binding, since a caller like `considerRepaint` (`../repaintScheduler.ts`) already has
+ * the full context its render used. Only meaningful for a hand-authored SVG template - a
+ * `TemplateProvider`-backed template (e.g. GenAI) has no `<desc>` bindings to walk; see
+ * `TemplateProvider.describeContent` (`./templateProviders.ts`) for that case's own text summary instead.
+ */
+function buildFieldsTable(svgSource, context, templatesDir, bundledTemplatesDir) {
+    const doc = new xmldom_1.DOMParser().parseFromString(svgSource, "image/svg+xml");
+    const rows = [];
+    for (const tag of ["text", "image"]) {
+        const elements = doc.getElementsByTagName(tag);
+        for (let i = 0; i < elements.length; i++) {
+            const element = elements.item(i);
+            if (!element)
+                continue;
+            const id = element.getAttribute("id") ?? `${tag}#${i}`;
+            const desc = element.getElementsByTagName("desc").item(0);
+            if (!desc?.textContent)
+                continue;
+            rows.push({ id, spec: desc.textContent, value: resolveFieldValue(tag, desc.textContent, context, templatesDir, bundledTemplatesDir) });
+        }
+    }
+    return rows;
+}

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>;