@rhizomatics/signalk-einklabel-plugin 0.10.1 → 1.0.0

package/dist/index.js

@@ -1,6 +1,10 @@
 "use strict";
 const plugin_1 = require("./plugin");
 const registry_1 = require("./devices/registry");
+const templateProviders_1 = require("./render/templateProviders");
+const svgRenderer_1 = require("./render/svgRenderer");
+const png_1 = require("./render/png");
+const binding_1 = require("./render/binding");
 /**
  * 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
@@ -8,9 +12,11 @@ const registry_1 = require("./devices/registry");
  * `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 this package as a regular `dependency` in the extension package (**not** a
+ * `peerDependency` - the SignalK team's own guidance is that npm's peer-dependency resolution
+ * interacts poorly with the server's plugin install layout), and declare the SignalK-level
+ * relationship via `"signalk": { "requires": ["@rhizomatics/signalk-einklabel-plugin"] }` in the
+ * extension's own package.json instead, so the App Store can install/report the dependency.
  */
 function plugin(app) {
     return (0, plugin_1.createPlugin)(app);
@@ -19,5 +25,24 @@ function plugin(app) {
     plugin.registerVendorDriver = registry_1.registerDriver;
     plugin.getVendorDriver = registry_1.getDriver;
     plugin.allVendorDrivers = registry_1.allDrivers;
+    /**
+     * Public extension point for a package offering an alternative to hand-authored SVG templates - e.g.
+     * `@rhizomatics/signalk-einklabel-genai-plugin` generating content from an LLM prompt - see
+     * `TemplateProvider`'s own doc comment (`./render/templateProviders.ts`) for the full contract. Same
+     * regular-`dependency`-plus-`signalk.requires` convention as `registerVendorDriver` above.
+     */
+    plugin.registerTemplateProvider = templateProviders_1.registerTemplateProvider;
+    plugin.getTemplateProvider = templateProviders_1.findTemplateProvider;
+    plugin.allTemplateProviders = templateProviders_1.allTemplateProviders;
+    /** Rasterizes an SVG string to a `Bitmap` - a template provider needs this to turn whatever SVG it produces (e.g. an LLM's response) into paintable pixels, exactly as a bundled template is rendered. */
+    plugin.Renderer = svgRenderer_1.SvgRenderer;
+    /** Encodes a `Bitmap` as PNG bytes - useful for a CLI extension writing a preview file, same as the core plugin's own `render`/`generate` commands. */
+    plugin.bitmapToPng = png_1.bitmapToPng;
+    /** Facts about one physical label (`source=label,path=...` bindings resolve against these) - see `./render/binding.ts`. */
+    plugin.buildLabel = binding_1.buildLabelContext;
+    /** Every `{...}` placeholder referenced across one or more text fragments, parsed as bindings - see `./render/binding.ts`. */
+    plugin.findBindingsInText = binding_1.findTextBindings;
+    /** Substitutes every `{...}` placeholder in `text` with its resolved binding value - see `./render/binding.ts`. */
+    plugin.substituteBindingsInText = binding_1.substituteTextBindings;
 })(plugin || (plugin = {}));
 module.exports = plugin;

package/dist/render/binding.d.ts

@@ -1,5 +1,6 @@
+import { Colour } from "../devices/types";
 import { TemplateContext } from "./types";
-declare const SOURCES: readonly ["signalk", "resources", "einklabel"];
+declare const SOURCES: readonly ["signalk", "resources", "einklabel", "label"];
 type Source = (typeof SOURCES)[number];
 /**
  * Parsed form of a `<desc>`'s `key=value,key=value` content - see `parseBinding` for the grammar.
@@ -19,7 +20,12 @@ export interface Binding {
      * for). Set this to pin a template to one provider regardless of what else is installed.
      */
     provider?: string;
-    /** For `source === 'einklabel'`, a dotted path into the plugin's own injected `meta` (e.g. `repainted`), rather than into vessel/resource data. */
+    /**
+     * For `source === 'einklabel'`, a dotted path into the plugin's own injected `meta` (e.g. `repainted`);
+     * for `source === 'label'`, a dotted path into the physical label's own facts (`manufacturer`, `label`,
+     * `width`, `height`, `colours`, `fonts`, `description`, `position` - see `buildLabelContext` below)
+     * 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;
@@ -35,6 +41,14 @@ export interface Binding {
      * template doesn't also require duplicating its bundled asset sets.
      */
     assets?: string;
+    /**
+     * Substituted in place of the resolved value when that value is missing (`undefined`/`null`,
+     * e.g. an unpublished SignalK path) - see `renderBinding`. Distinct from an *unset* default (this
+     * field itself being `undefined`), which falls through to the pre-existing "" fallback - explicitly
+     * writing `default=` (an empty value) still counts as "given", so a binding can deliberately default
+     * to blank rather than to `substituteTextBindings`' own "???" below.
+     */
+    default?: string;
 }
 /**
  * Parses a `<desc>` element's text content into a `Binding`, e.g.
@@ -69,6 +83,8 @@ export declare function resolveBinding(binding: Binding, context: TemplateContex
  * the CLI's `field`/`fields` commands show the same thing a real render would.
  *
  * Precedence for a numeric value:
+ * 0. A missing value (`undefined`/`null`, e.g. an unpublished path) with an explicit `default=` given -
+ *    that default, verbatim, bypassing every step below (there's nothing to format).
  * 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.
@@ -76,7 +92,65 @@ export declare function resolveBinding(binding: Binding, context: TemplateContex
  *    `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`.
+ *    `String(value)` -> `"[object Object]"`, else `String`. A missing value with no `default=` given
+ *    still falls through to the pre-existing "" here, unchanged from before `default=` existed.
  */
 export declare function renderBinding(binding: Binding, context: TemplateContext): string;
+/** Facts about one physical label a `source=label,path=...` binding 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 `source=label,path=...` binding addresses (e.g.
+ * `{source=label,path=width}` in free text, or a `<desc>source=label,path=width</desc>` in an SVG
+ * template - every `{...}`/`<desc>` 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 caller can either use them bare (renders as JSON) or add
+ * `format=csv` (see `./formatters.ts`) for a plain comma-separated list. `position`, if given, is rounded
+ * to ~2 decimal places (~1.1km) - fine-grained enough to be meaningfully "for here", coarse enough that
+ * ordinary GPS jitter at anchor doesn't change it tick to tick, which matters because `considerRepaint`
+ * (`../repaintScheduler.ts`) folds this whole object into every device's dedup hash - full-precision
+ * jitter here would otherwise force a repaint (and, for a provider-rendered template, a fresh paid API
+ * call) far more often than the underlying position has actually meaningfully changed.
+ */
+export declare function buildLabelContext(meta: LabelMeta): Record<string, unknown>;
+/**
+ * Every binding referenced across one or more free-text fragments - every `{...}` placeholder,
+ * deduplicated across all of `texts` combined, parsed exactly the way a template's `<desc>` binding is
+ * (`parseBinding` above), 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 text. `substituteTextBindings` hits
+ * the identical parse error at substitution time and turns it into "???" for just that field.
+ */
+export declare function findTextBindings(...texts: string[]): Binding[];
+/**
+ * Substitutes every `{...}` placeholder in `text` with its resolved binding value against `context`
+ * (built by `assembleRawContext` plus `context.label` from `buildLabelContext` - see
+ * `findTextBindings`). 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=` uses that default instead, since the caller has
+ * already said what a missing value should read as.
+ */
+export declare function substituteTextBindings(text: string, context: TemplateContext): string;
 export {};

package/dist/render/binding.js

@@ -5,10 +5,13 @@ exports.resourceContextKey = resourceContextKey;
 exports.findBindings = findBindings;
 exports.resolveBinding = resolveBinding;
 exports.renderBinding = renderBinding;
+exports.buildLabelContext = buildLabelContext;
+exports.findTextBindings = findTextBindings;
+exports.substituteTextBindings = substituteTextBindings;
 const xmldom_1 = require("@xmldom/xmldom");
 const formatters_1 = require("./formatters");
-const SOURCES = ["signalk", "resources", "einklabel"];
-const KNOWN_KEYS = new Set(["source", "context", "resource", "provider", "path", "format", "category", "round", "assets"]);
+const SOURCES = ["signalk", "resources", "einklabel", "label"];
+const KNOWN_KEYS = new Set(["source", "context", "resource", "provider", "path", "format", "category", "round", "assets", "default"]);
 /**
  * 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
@@ -62,6 +65,7 @@ function parseBinding(desc) {
         category: fields.category,
         round: fields.round !== undefined ? Number(fields.round) : undefined,
         assets: fields.assets,
+        default: fields.default,
     };
 }
 /**
@@ -126,6 +130,13 @@ function resolveBinding(binding, context) {
         }
         return getAtPath(meta, binding.path);
     }
+    if (binding.source === "label") {
+        const label = context.label;
+        if (label === undefined) {
+            throw new Error('binding references source "label" but no "label" is present in the render context');
+        }
+        return getAtPath(label, binding.path);
+    }
     const resources = context.resources;
     const resourceKey = resourceContextKey(binding);
     const resource = resources?.[resourceKey];
@@ -166,6 +177,8 @@ function resolveCategoryDisplayUnits(binding, context) {
  * the CLI's `field`/`fields` commands show the same thing a real render would.
  *
  * Precedence for a numeric value:
+ * 0. A missing value (`undefined`/`null`, e.g. an unpublished path) with an explicit `default=` given -
+ *    that default, verbatim, bypassing every step below (there's nothing to format).
  * 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.
@@ -173,10 +186,13 @@ function resolveCategoryDisplayUnits(binding, context) {
  *    `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`.
+ *    `String(value)` -> `"[object Object]"`, else `String`. A missing value with no `default=` given
+ *    still falls through to the pre-existing "" here, unchanged from before `default=` existed.
  */
 function renderBinding(binding, context) {
     const value = resolveBinding(binding, context);
+    if ((value === null || value === undefined) && binding.default !== undefined)
+        return binding.default;
     if (binding.format && binding.format !== "raw")
         return (0, formatters_1.applyFormat)(binding.format, value, context, binding.round);
     if (typeof value === "number") {
@@ -194,3 +210,98 @@ function renderBinding(binding, context) {
         return JSON.stringify(value);
     return String(value);
 }
+const COLOUR_HEX = { black: "#000000", white: "#FFFFFF", red: "#FF0000", yellow: "#FFFF00" };
+/** The only `font-family` values `SvgRenderer` is guaranteed to render - see `expandGenericFontFamilies` in `./svgRenderer.ts`. */
+const SAFE_FONT_FAMILIES = ["serif", "sans-serif", "monospace"];
+/**
+ * Builds the `context.label` object a `source=label,path=...` binding addresses (e.g.
+ * `{source=label,path=width}` in free text, or a `<desc>source=label,path=width</desc>` in an SVG
+ * template - every `{...}`/`<desc>` 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 caller can either use them bare (renders as JSON) or add
+ * `format=csv` (see `./formatters.ts`) for a plain comma-separated list. `position`, if given, is rounded
+ * to ~2 decimal places (~1.1km) - fine-grained enough to be meaningfully "for here", coarse enough that
+ * ordinary GPS jitter at anchor doesn't change it tick to tick, which matters because `considerRepaint`
+ * (`../repaintScheduler.ts`) folds this whole object into every device's dedup hash - full-precision
+ * jitter here would otherwise force a repaint (and, for a provider-rendered template, a fresh paid API
+ * call) far more often than the underlying position has actually meaningfully changed.
+ */
+function buildLabelContext(meta) {
+    const position = meta.position && {
+        latitude: Math.round(meta.position.latitude * 100) / 100,
+        longitude: Math.round(meta.position.longitude * 100) / 100,
+    };
+    return {
+        manufacturer: meta.manufacturer,
+        label: meta.label,
+        width: meta.width,
+        height: meta.height,
+        colours: meta.colours.map((colour) => `${colour} (${COLOUR_HEX[colour]})`),
+        fonts: SAFE_FONT_FAMILIES,
+        description: meta.description ?? "",
+        position: position ? (0, formatters_1.applyFormat)("position", position, {}, 2) : undefined,
+    };
+}
+function placeholderContents(text) {
+    return [...new Set([...text.matchAll(/\{([^{}]+)\}/g)].map((match) => match[1].trim()))];
+}
+/**
+ * Every binding referenced across one or more free-text fragments - every `{...}` placeholder,
+ * deduplicated across all of `texts` combined, parsed exactly the way a template's `<desc>` binding is
+ * (`parseBinding` above), 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 text. `substituteTextBindings` hits
+ * the identical parse error at substitution time and turns it into "???" for just that field.
+ */
+function findTextBindings(...texts) {
+    const seen = new Set();
+    const bindings = [];
+    for (const text of texts) {
+        for (const key of placeholderContents(text)) {
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            try {
+                bindings.push(parseBinding(key));
+            }
+            catch {
+                // see doc comment above - left for `substituteTextBindings` to turn into "???"
+            }
+        }
+    }
+    return bindings;
+}
+/**
+ * Substitutes every `{...}` placeholder in `text` with its resolved binding value against `context`
+ * (built by `assembleRawContext` plus `context.label` from `buildLabelContext` - see
+ * `findTextBindings`). 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=` uses that default instead, since the caller has
+ * already said what a missing value should read as.
+ */
+function substituteTextBindings(text, context) {
+    return text.replace(/\{([^{}]+)\}/g, (_match, raw) => {
+        const key = raw.trim();
+        try {
+            const binding = parseBinding(key);
+            const value = resolveBinding(binding, context);
+            if ((value === undefined || value === null) && binding.default === undefined)
+                return "???";
+            return renderBinding(binding, context);
+        }
+        catch {
+            return "???";
+        }
+    });
+}

package/dist/render/formatters.js

@@ -101,6 +101,22 @@ function formatPosition(value, round) {
     const lonHemisphere = position.longitude >= 0 ? "E" : "W";
     return `${lat}°${latHemisphere} ${lon}°${lonHemisphere}`;
 }
+/**
+ * A resolved value that's an array (e.g. `source=label,path=colours` - see `../render/llmPrompt.ts`'s
+ * `buildLabelContext`) joined into a plain comma-separated list, e.g. `["black","white"]` ->
+ * `"black, white"`. A non-array value falls through to the same null/object/scalar handling
+ * `renderBinding` uses for its own generic fallback, so `format=csv` is harmless on an ordinary
+ * scalar binding too.
+ */
+function formatCsv(value) {
+    if (Array.isArray(value))
+        return value.map((entry) => String(entry)).join(", ");
+    if (value === null || value === undefined)
+        return "";
+    if (typeof value === "object")
+        return JSON.stringify(value);
+    return String(value);
+}
 /** Applies a named `format=` formatter to a resolved binding value. */
 function applyFormat(name, value, context, round) {
     switch (name) {
@@ -114,6 +130,8 @@ function applyFormat(name, value, context, round) {
             return formatUtcOffset(value);
         case "position":
             return formatPosition(value, round);
+        case "csv":
+            return formatCsv(value);
         default:
             throw new Error(`unknown format "${name}"`);
     }

package/dist/render/llmPrompt.d.ts

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

package/dist/render/llmPrompt.js

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