@rhizomatics/signalk-einklabel-plugin 1.3.0-beta11 → 1.3.0-beta13

package/dist/config.d.ts

@@ -22,7 +22,7 @@ export interface DeviceConfig {
     /**
      * Free-text notes about where this label is physically mounted/viewed from, e.g. "chart table,
      * viewed from ~1m in poor light" - purely descriptive. Available to any template via
-     * `source=einklabel,path=description` or `source=label,path=description` (see `buildLabelContext` in
+     * `source=label,path=description` (see `buildLabelContext` in
      * `./render/binding.ts`) if it wants it - e.g. useful to a `TemplateProvider` extension (see
      * `./render/templateProviders.ts`) tailoring content to where the label actually sits.
      */
@@ -47,6 +47,10 @@ export interface DeviceConfig {
     intervalHours?: number;
     /** ...at this minute past the hour. */
     intervalMinute?: number;
+    /** Settings most labels never need, grouped so the admin UI shows them in their own "Advanced settings" box. */
+    advanced?: AdvancedDeviceSettings;
+}
+export interface AdvancedDeviceSettings {
     /**
      * How to fit the rendered image onto the device's actual panel size when it doesn't match (see
      * `ReframeMode`) - e.g. a template family with no variant sized for this particular label. Left
@@ -55,10 +59,6 @@ export interface DeviceConfig {
      * showing *something*, even off-size, beats a repaint that just fails outright.
      */
     reframe?: ReframeMode;
-    /** Settings most labels never need, grouped so the admin UI shows them in their own "Advanced settings" box. */
-    advanced?: AdvancedDeviceSettings;
-}
-export interface AdvancedDeviceSettings {
     /** Compress the upload (zhsunyco, and gicisky's chunked 7.5"/10.2" panels - ignored otherwise). Unset means on; turn off if a device fails to show compressed images. */
     compress?: boolean;
     /** Flip the image before sending - for a panel whose layout is mirrored, or one mounted upside down (`"both"`). Unset means `"none"`. */
@@ -187,6 +187,22 @@ export declare function parseDevice(device: string): {
     hwVersion?: string;
     address: string;
 } | undefined;
+export declare function listSvgFiles(dir: string): string[];
+export interface TemplateVariant {
+    fileName: string;
+    width: number;
+    height: number;
+    colours: Colour[];
+}
+export declare function listTemplateVariants(dir: string): TemplateVariant[];
+/**
+ * A directory only counts as a template-family option if it actually has at least one parseable
+ * variant file in it - otherwise it's something else entirely, e.g. `.assets`. Dot-prefixed
+ * directories (e.g. `.assets`, `.blank`) are always excluded, even if they happen to contain
+ * parseable variant files, since they're reserved for non-template-option use (asset bundles,
+ * work-in-progress templates not ready to appear in the dropdown, etc).
+ */
+export declare function listTemplateFamilies(dir: string): string[];
 /**
  * Resolves a template name to an actual file path - a local template overrides the bundled one of the
  * same name. `templateName` can also name a template-family *directory* (see `pickBestVariant`), in

package/dist/config.js

@@ -7,6 +7,9 @@ exports.readCurrentConfig = readCurrentConfig;
 exports.healStoredConfig = healStoredConfig;
 exports.resolveTemplatesDir = resolveTemplatesDir;
 exports.parseDevice = parseDevice;
+exports.listSvgFiles = listSvgFiles;
+exports.listTemplateVariants = listTemplateVariants;
+exports.listTemplateFamilies = listTemplateFamilies;
 exports.resolveTemplatePath = resolveTemplatePath;
 exports.configSchema = configSchema;
 exports.configUiSchema = configUiSchema;
@@ -29,6 +32,7 @@ exports.ALL_DEVICES = "ALL";
  * saved before they were grouped still has them there. See `migrateDeviceConfig`.
  */
 const ADVANCED_DEVICE_KEYS = [
+    "reframe",
     "compress",
     "mirror",
     "compressionFormat",
@@ -359,6 +363,12 @@ function withEnum(schema, values, names) {
         return schema;
     return names ? { ...schema, oneOf: values.map((value, i) => ({ const: value, title: names[i] ?? value })) } : { ...schema, enum: values };
 }
+/** The plugin's documentation site - its sections' anchors are the README's own headings (see `site/scripts/sync-readme.mjs`). */
+const DOCS_URL = "https://signalk-einklabel.rhizomatics.org.uk/";
+/** A Markdown link to a docs page (and optional section, e.g. `templates/#reframing`), for a field description rendered with `ui:enableMarkdownInDescription` (see `configUiSchema`). */
+function docsLink(page, text = "More in the docs") {
+    return `[${text}](${DOCS_URL}${page})`;
+}
 /**
  * An enum-like string field whose options show explanatory labels rather than their raw stored values
  * - `oneOf` with `const`/`title`, which RJSF 5 (the admin UI's form library) renders as each option's
@@ -447,8 +457,12 @@ function configSchema(app, discovered = []) {
             signalkApiUrl: {
                 type: "string",
                 title: "SignalK API base URL (leave blank to auto-detect)",
-                description: "Used for plugin access to SignalK REST APIs not yet integrated for direct plugin access. Left blank, the plugin probes the likely options at startup (3000, 80, 443 ) - only set this manually to skip probing. Anonymous read access is required.",
-                enum: ["", ...resolveApiUrl_1.SIGNALK_API_URL_OPTIONS],
+                description: "Used for plugin access to SignalK REST APIs not yet integrated for direct plugin access. Left blank, the plugin probes the likely options at startup (3000, 80, 443) - " +
+                    "only set this to skip probing, or for a server on another port or host, e.g. http://localhost:3001. Anonymous read access is required.",
+                // Free text with the probed options as suggestions - `examples` renders as the input's
+                // autocomplete list in the admin UI's form library (RJSF 5), where `enum` would forbid anything else.
+                examples: resolveApiUrl_1.SIGNALK_API_URL_OPTIONS,
+                pattern: "^(\\s*|\\s*https?://\\S+\\s*)$",
             },
             devices: {
                 type: "array",
@@ -469,43 +483,32 @@ function configSchema(app, discovered = []) {
                             type: "string",
                             title: "Location/description (optional)",
                             description: 'Free-text notes about where this label is physically mounted/viewed from, e.g. "chart table, viewed from ~1m ' +
-                                'in poor light" - available to any template as source=einklabel,path=description or source=label,path=description.',
+                                'in poor light" - available to any template as `source=label,path=description`. ' +
+                                docsLink("templates/#label-details"),
                         },
-                        templateName: withEnum({ type: "string", title: "Template" }, templateNameOptions(resolveTemplatesDir(current.templatesDir))),
+                        templateName: withEnum({
+                            type: "string",
+                            title: "Template",
+                            description: `A bundled template, or one from your templates directory. ${docsLink("examples/")}`,
+                        }, templateNameOptions(resolveTemplatesDir(current.templatesDir))),
                         repaintTrigger: choiceField("Repaint trigger", [
                             ["subscription", "When a SignalK path changes"],
                             ["interval", "On a timed schedule"],
                         ]),
-                        triggerPath: {
-                            type: "string",
-                            title: "Trigger SignalK path (if repaint trigger is subscription)",
-                        },
-                        intervalHours: {
-                            type: "number",
-                            title: "Repaint every N hours (if repaint trigger is interval)",
-                            minimum: 1,
-                        },
-                        intervalMinute: {
-                            type: "number",
-                            title: "Minutes past the hour (if repaint trigger is interval)",
-                            minimum: 0,
-                            maximum: 59,
-                            default: 0,
-                        },
-                        reframe: choiceField("If the render doesn't match the panel size", [
-                            ["crop", "Crop - place at the top-left, cutting off anything too big or leaving the rest blank"],
-                            ["scale", "Scale - stretch to fit exactly (may distort)"],
-                            ["fixed", "Fixed - fail the repaint rather than show an off-size image"],
-                        ], { default: "crop" }),
                         advanced: {
                             type: "object",
                             title: "Advanced settings",
                             description: "Most labels never need these.",
                             properties: {
+                                reframe: choiceField("If the render doesn't match the panel size", [
+                                    ["crop", "Crop - place at the top-left, cutting off anything too big or leaving the rest blank"],
+                                    ["scale", "Scale - stretch to fit exactly (may distort)"],
+                                    ["fixed", "Fixed - fail the repaint rather than show an off-size image"],
+                                ], { description: docsLink("templates/#reframing"), default: "crop" }),
                                 compress: {
                                     type: "boolean",
                                     title: 'Compress upload (Zhsunyco, Gicisky 7.5"/10.2")',
-                                    description: "Sends far less data over BLE, so repaints are quicker. Turn off if a label stops updating.",
+                                    description: `Sends far less data over BLE, so repaints are quicker. Turn off if a label stops updating. ${docsLink("templates/#other-image-options")}`,
                                     default: true,
                                 },
                                 mirror: choiceField("Mirror", [
@@ -513,14 +516,20 @@ function configSchema(app, discovered = []) {
                                     ["horizontal", "Flip left to right"],
                                     ["vertical", "Flip top to bottom"],
                                     ["both", "Rotate 180° - for a label mounted upside down"],
-                                ], { description: "Only needed if the image shows up mirrored or upside down on the label.", default: "none" }),
+                                ], {
+                                    description: `Only needed if the image shows up mirrored or upside down on the label. ${docsLink("templates/#other-image-options")}`,
+                                    default: "none",
+                                }),
                                 compressionFormat: choiceField("Wire format (Gicisky, experimental)", [
                                     ["auto", "Auto - the model's usual format"],
                                     [
                                         "chunked",
                                         'Chunked - send compressed like the 7.5"/10.2" panels, e.g. to speed up a 4.2" BWR (untested on current firmware)',
                                     ],
-                                ], { description: "Chunked needs Compress upload on. Switch back to Auto if the label stops updating.", default: "auto" }),
+                                ], {
+                                    description: `Chunked needs Compress upload on. Switch back to Auto if the label stops updating. ${docsLink("templates/#other-image-options")}`,
+                                    default: "auto",
+                                }),
                                 forceRepaint: {
                                     type: "boolean",
                                     title: "Force repaint",
@@ -529,7 +538,9 @@ function configSchema(app, discovered = []) {
                                 },
                                 aesKey: {
                                     type: "string",
-                                    title: "BLE AES key (vendor-specific; leave blank to use a default key)",
+                                    title: "BLE AES key (Zhsunyco)",
+                                    description: "32 hex characters. Leave blank to use the default key, which works for most labels.",
+                                    pattern: "^([0-9a-fA-F]{32})?$",
                                 },
                                 paintConnectTimeoutSeconds: {
                                     type: "number",
@@ -546,21 +557,78 @@ function configSchema(app, discovered = []) {
                             },
                         },
                     },
+                    // Shows only the fields for the chosen trigger. RJSF keeps a hidden field's value, so switching
+                    // trigger and back doesn't lose it - and the scheduler only reads the ones matching the trigger.
+                    dependencies: {
+                        repaintTrigger: {
+                            oneOf: [
+                                {
+                                    properties: {
+                                        repaintTrigger: { const: "subscription" },
+                                        triggerPath: {
+                                            type: "string",
+                                            title: "Trigger SignalK path",
+                                            description: "Repaints whenever this path's value changes.",
+                                        },
+                                    },
+                                },
+                                {
+                                    properties: {
+                                        repaintTrigger: { const: "interval" },
+                                        intervalHours: {
+                                            type: "number",
+                                            title: "Repaint every N hours",
+                                            minimum: 1,
+                                        },
+                                        intervalMinute: {
+                                            type: "number",
+                                            title: "Minutes past the hour",
+                                            minimum: 0,
+                                            maximum: 59,
+                                            default: 0,
+                                        },
+                                    },
+                                },
+                            ],
+                        },
+                    },
                 },
             },
         },
     };
 }
+/** Lets a field's `description` include Markdown - used for its `docsLink`. */
+const MARKDOWN = { "ui:enableMarkdownInDescription": true };
 function configUiSchema() {
     return {
+        signalkApiUrl: { "ui:placeholder": "Auto-detect, or e.g. http://localhost:3001" },
         devices: {
             items: {
-                description: { "ui:widget": "textarea" },
+                // Keeps the trigger's own fields (added by the schema's `dependencies`) next to it, rather than
+                // after every other field, and Advanced settings last.
+                "ui:order": [
+                    "friendlyName",
+                    "device",
+                    "description",
+                    "templateName",
+                    "repaintTrigger",
+                    "triggerPath",
+                    "intervalHours",
+                    "intervalMinute",
+                    "*",
+                    "advanced",
+                ],
+                friendlyName: { "ui:placeholder": "e.g. Tide clock" },
+                description: { "ui:widget": "textarea", "ui:placeholder": "e.g. at companionway", ...MARKDOWN },
+                templateName: MARKDOWN,
                 repaintTrigger: { "ui:widget": "radio" },
-                reframe: { "ui:widget": "radio" },
+                triggerPath: { "ui:placeholder": "e.g. environment.tide.state" },
                 advanced: {
-                    mirror: { "ui:widget": "radio" },
-                    compressionFormat: { "ui:widget": "radio" },
+                    reframe: { "ui:widget": "radio", ...MARKDOWN },
+                    compress: MARKDOWN,
+                    mirror: { "ui:widget": "radio", ...MARKDOWN },
+                    compressionFormat: { "ui:widget": "radio", ...MARKDOWN },
+                    aesKey: { "ui:placeholder": "e.g. 00112233445566778899aabbccddeeff" },
                 },
             },
         },

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/repaintScheduler.js

@@ -260,6 +260,23 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
     let dataHash = "";
     let paintDurationMs = 0;
     let repaintReason = "render failed";
+    // Built up front, outside the try below, so the fallback warning render gets it too - it's all local
+    // facts (no network or template involved), so there's nothing here that can fail a render.
+    const rawPosition = (0, unwrapSignalkTree_1.unwrapSignalkTree)(app.getSelfPath("navigation.position"));
+    const position = typeof rawPosition?.latitude === "number" && typeof rawPosition?.longitude === "number"
+        ? { latitude: rawPosition.latitude, longitude: rawPosition.longitude }
+        : undefined;
+    const labelContext = (0, binding_1.buildLabelContext)({
+        // Falls back to the driver's own internal vendor key (e.g. "zhsunyco") when a device model has no
+        // explicit `manufacturer` of its own - see `DeviceMetadata.manufacturer`'s doc comment.
+        manufacturer: metadata.manufacturer ?? target.vendor,
+        label: metadata.label,
+        width,
+        height,
+        colours: metadata.colours,
+        description: device.description,
+        position,
+    });
     try {
         const apiUrl = await getApiUrl().catch((err) => {
             app.debug(`${label}: ${err.message}`);
@@ -281,21 +298,6 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
             bindings = (0, binding_1.findBindings)((0, fs_1.readFileSync)(templatePath, "utf-8"));
         }
         const rawContext = await assembleRawContext(app, apiUrl, bindings);
-        const rawPosition = (0, unwrapSignalkTree_1.unwrapSignalkTree)(app.getSelfPath("navigation.position"));
-        const position = typeof rawPosition?.latitude === "number" && typeof rawPosition?.longitude === "number"
-            ? { latitude: rawPosition.latitude, longitude: rawPosition.longitude }
-            : undefined;
-        const labelContext = (0, binding_1.buildLabelContext)({
-            // Falls back to the driver's own internal vendor key (e.g. "zhsunyco") when a device model has no
-            // explicit `manufacturer` of its own - see `DeviceMetadata.manufacturer`'s doc comment.
-            manufacturer: metadata.manufacturer ?? target.vendor,
-            label: metadata.label,
-            width,
-            height,
-            colours: metadata.colours,
-            description: device.description,
-            position,
-        });
         // Hashed before `meta` is merged in below, deliberately, so a template merely *displaying* the
         // repaint timestamp doesn't perpetually invalidate its own dedup and force a repaint every check. A
         // full paint flashes the whole panel several times, and there's no confirmed partial-refresh path
@@ -320,6 +322,7 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
                 repainted: new Date().toISOString(),
                 local_zone: (0, formatters_1.resolveLocalZoneAbbreviation)(rawContext),
                 plugin_version: pluginVersion_1.PLUGIN_VERSION,
+                // Undocumented legacy alias of `label.description` - kept so templates already using it keep working.
                 description: device.description ?? "",
             },
         };
@@ -344,7 +347,10 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
             height: metadata.height,
             colours: metadata.colours,
         });
-        bitmap = await renderer.render(fallbackPath, { meta: { repainted: new Date().toISOString(), plugin_version: pluginVersion_1.PLUGIN_VERSION, description: device.description ?? "" } }, width, height, templatesDir, config_1.BUNDLED_TEMPLATES_DIR);
+        bitmap = await renderer.render(fallbackPath, {
+            label: labelContext,
+            meta: { repainted: new Date().toISOString(), plugin_version: pluginVersion_1.PLUGIN_VERSION, description: device.description ?? "" },
+        }, width, height, templatesDir, config_1.BUNDLED_TEMPLATES_DIR);
     }
     const connectTimeoutMs = (device.advanced?.paintConnectTimeoutSeconds ?? config.paintConnectTimeoutSeconds) * 1000;
     const gattBackend = config.useBleApi && app.bleApi ? (0, bleBackend_1.bleApiBackend)(app.bleApi, pluginVersion_1.PLUGIN_NAME) : undefined;
@@ -357,7 +363,7 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
             pid: target.pid,
             aesKey: device.advanced?.aesKey,
             connectTimeoutMs,
-            reframe: device.reframe,
+            reframe: device.advanced?.reframe,
             mirror: device.advanced?.mirror,
             compress: device.advanced?.compress,
             compressionFormat: device.advanced?.compressionFormat,

package/dist/resolveApiUrl.js

@@ -37,6 +37,9 @@ async function probe(url) {
  * and uses the first that responds.
  */
 async function resolveSignalkApiUrl(configuredUrl) {
+    // Typed free-form in the config UI, so tolerate stray whitespace and a trailing slash, which would
+    // otherwise double up with the leading slash of every API path appended to it.
+    configuredUrl = configuredUrl?.trim().replace(/\/+$/, "") || undefined;
     const candidates = configuredUrl ? [configuredUrl] : exports.SIGNALK_API_URL_OPTIONS;
     for (const url of candidates) {
         if (await probe(url))