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

package/CHANGELOG.md

@@ -1,6 +1,24 @@
 # 1.3.0
 
-First implementation of using new SignalK BLE Manager rather than directly using the `bluez` services. Off by default until longer term stability demonstrated.
+## BLE Manager
+
+First implementation of using new SignalK BLE Manager rather than directly using the `bluez` services.
+
+- Off by default until longer term stability demonstrated.
+- It may be less reliable for some devices that can be reached with direct bluez access - try it and fall back to the direct mode if so.
+- BLE Manager use reduces interference between plugins competing for same BLE devices
+- Recommend using SignalK at least release v2.33.0.
+
+## Compression
+
+Images are now compressed before sending - no change to what's displayed, but send time is massively reduced for labels with lots of empty space, so less battery is used and sends are less likely to fail.
+
+- On by default for Zhsunyco labels and Gicisky 7.5"/10.2" labels; can be turned off per label, or with `--no-compress` on the CLI
+- Experimental opt-in _Wire format_ `chunked` sends a Gicisky 4.2" BWR compressed too (`--compression-format chunked` on the CLI)
+
+## Mirroring
+
+Some labels may need images flipped, so a per-label _Mirror_ option can flip the image horizontally, vertically, or both (rotate 180°, for a label mounted upside down). Also available as `--mirror` on the CLI `paint` and `render` commands.
 
 # 1.2.3
 

package/README.md

@@ -178,6 +178,14 @@ Templates are simply SVG files, to which expressions can be added to use SignalK
 
 There's some wiggle room with the `reframe` options to use a template that's a bit too small, or too large, for the label, although best results come from a template that's precisely matching the pixel height and width of the label. Next best is template that has the same aspect ratio, so it can be cleanly scaled. `crop` is the 2nd least worst, though if its only a handful of pixels its often not worth worring about a separate template and `crop` is just fine. `scale` is likely to look worst, since it will force an image in regardless of aspect ratio.
 
+### Other Image Options
+
+Each label has a few more settings for how the image is sent. The CLI `paint` command has matching options (see [Command Line Interface](#command-line-interface)), so you can try them on a label before changing the plugin config.
+
+- _Compress upload_ - on by default. Sends much less data over Bluetooth, so painting is quicker, uses less of the label's battery and is less likely to time out. Works for Zhsunyco labels and Gicisky 7.5"/10.2" labels, and is ignored for others. Turn it off if a label stops updating.
+- _Wire format (Gicisky, experimental)_ - `auto` by default. `chunked` sends a Gicisky 4.2" BWR label compressed, the same way as the 7.5"/10.2". The vendor's own app has been seen doing this, but it hasn't been tested on current firmware. Set it back to `auto` if the label stops updating.
+- _Mirror_ - `none` by default. `horizontal` or `vertical` fixes a label model whose image comes out mirrored. `both` rotates the image 180°, for a label that has to be mounted upside down.
+
 ### Template Families (multiple panel sizes/colours)
 
 A "Template" selection can either be one specific `.svg` file, or a _directory_ holding several versions of the same template for different panel sizes/colour-sets, e.g. `templates/tides/416x240-BWRY.svg` and `templates/tides/250x128-BWRY.svg` both implement the tide clock, just at different sizes.
@@ -309,6 +317,12 @@ Left unset, both `render` and `paint` default `-w/--width`/`--height` to the tem
 
 The main SignalK plugin offers the same choice per device (defaulting to `crop` there too) in each device's own config - "If the render doesn't match the panel size".
 
+`paint` has matching options for the other per-label image settings too (see [Other Image Options](#other-image-options)):
+
+- `--mirror <mode>` - `none` (default), `horizontal`, `vertical`, or `both` (rotate 180°). `render` also takes `--mirror`, to preview the flip as a PNG without a label
+- `--no-compress` - send the image uncompressed, to rule compression out if a label won't update
+- `--compression-format <format>` - `auto` (default) or `chunked`, to try the experimental compressed format on a Gicisky 4.2" BWR
+
 `esl-cli` can also be extended with new subcommands by a `-r/--require`'d package - see [Extending](#extending) below - which is how [`@rhizomatics/signalk-einklabel-genai-plugin`](#genai-rendering) adds its own `prompt`/`generate` commands for testing prompts without a device.
 
 ( The CLI can also be run from a checked out module, or by opening a terminal shell at `~/.signalk/node_modules/@rhizomatics/signalk-einklabel-plugin`, as `npx esl-cli command --args` )
@@ -377,12 +391,24 @@ The label address previously discovered via `esl-cli scan`
 npx esl-cli paint -t templates/tides/250x128-BWRY.svg -a FF:FF:92:84:53:93
 ```
 
-If the label turns out to be a different size than the template (e.g. it's a 250x128 template on a 416x240 panel), that's normally rejected as a mismatch - add `--reframe` to fit it instead:
+If the label turns out to be a different size than the template (e.g. it's a 250x128 template on a 416x240 panel), it's cropped to fit by default - add `--reframe scale` to stretch it instead:
 
 ```bash
 npx esl-cli paint -t templates/tides/250x128-BWRY.svg -a FF:FF:92:84:53:93 --reframe scale
 ```
 
+If a label doesn't update, try sending it uncompressed to see whether compression is the cause:
+
+```bash
+npx esl-cli paint -t templates/tides/250x128-BWRY.svg -a FF:FF:92:84:53:93 --no-compress
+```
+
+If the image comes out mirrored, try each `--mirror` mode until it looks right, then set the same _Mirror_ option in the label's config:
+
+```bash
+npx esl-cli paint -t templates/tides/250x128-BWRY.svg -a FF:FF:92:84:53:93 --mirror horizontal
+```
+
 #### Test Template Without Updating Label
 
 This will work even if you don't have a label, or even bluetooth. (The `-u` can be left out if your SignalK server running locally on default ports).
@@ -537,6 +563,8 @@ USB_DENYLIST="0b05:190e"
 
 ## Other ESL and General eInk Resources
 
+### Components
+
 - [Open ePaper Link](https://openepaperlink.de) - Alternative open source firmware to flash onto eInk shelf labels, with Home Assistant integration.
 - [zhsunyco-esl](https://github.com/roxburghm/zhsunyco-esl) - Python interface
 - [WoLink](https://github.com/NickWaterton/Wolink) - Python interface and protocol analysis
@@ -545,9 +573,14 @@ USB_DENYLIST="0b05:190e"
 - [esp32-esl-system](https://github.com/giobauermeister/esp32-esl-system) - Docker and ESP32 based system for updating ESLs.
 - [hass-gicisky](https://github.com/eigger/hass-gicisky) - Home Assistant integration for Gicisky ESLs ( a similar vendor to Zhsunyco). Uses [imagespec](https://github.com/eigger/imagespec) for templating.
 - [ha-panda](https://github.com/moryoav/ha-panda) - Home Assistant integration for Panda ESLs ( a similar vendor to Zhsunyco).
+
+### Notes and Experiences
+
+- [Cabalist Gicisky Image Notes](https://github.com/Cabalist/gicisky_image_notes)
 - [Dmitry.gr](https://dmitry.gr/?r=05.Projects&proj=29.%20eInk%20Price%20Tags) - Personal site of an ESL hacker
 - [Aaron Christobel](https://www.youtube.com/@atc1441) - YouTube channel of an ESL hacker.
 - [rbaron.net](https://rbaron.net/blog/2022/07/29/Daisy-chaining-multiple-electronic-shelf-labels) - Blog of an early ESL hacker.
+  ### Retail
 - [Pimoroni](https://shop.pimoroni.com/collections/displays?tags=e-ink%20Displays) - All shapes and sizes of eInk displays, aimed at hackers, and with an [inky](https://github.com/pimoroni/inky) GitHub project to support them.
 - [WaveShare](https://www.waveshare.com/product/displays/e-paper.htm) - Wide range of eInk displays for hardware projects, not limited to ESLs.
 

package/dist/cli/index.d.ts

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { Colour } from "../devices/types";
+import { Colour, CompressionFormat } from "../devices/types";
 import { ReframeMode } from "../render/reframe";
+import { MirrorMode } from "../render/mirror";
 import { Binding } from "../render/binding";
 import { TemplateContext } from "../render/types";
 /** Tried in order when -u/--url is omitted (and -e/--example-data isn't given) - first one that answers wins. */
 export declare const DEFAULT_SIGNALK_URLS: string[];
 export declare function parseColours(code: string): Colour[];
 export declare function parseReframeMode(value: string): ReframeMode;
+export declare function parseMirrorMode(value: string): MirrorMode;
+export declare function parseCompressionFormat(value: string): CompressionFormat;
 /** Shared by every command that takes -u/--url and -e/--example-data - -e wins when both are present; when neither is given, probes DEFAULT_SIGNALK_URLS for a default. */
 export declare function assembleContext(opts: {
     url?: string;

package/dist/cli/index.js

@@ -4,6 +4,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.program = exports.DEFAULT_SIGNALK_URLS = void 0;
 exports.parseColours = parseColours;
 exports.parseReframeMode = parseReframeMode;
+exports.parseMirrorMode = parseMirrorMode;
+exports.parseCompressionFormat = parseCompressionFormat;
 exports.assembleContext = assembleContext;
 const promises_1 = require("fs/promises");
 const path_1 = require("path");
@@ -13,6 +15,8 @@ const registry_1 = require("../devices/registry");
 const zhsunyco_1 = require("../devices/zhsunyco");
 const gicisky_1 = require("../devices/gicisky");
 const bleDiscovery_1 = require("../devices/bleDiscovery");
+const types_1 = require("../devices/types");
+const mirror_1 = require("../render/mirror");
 const svgRenderer_1 = require("../render/svgRenderer");
 const png_1 = require("../render/png");
 const binding_1 = require("../render/binding");
@@ -45,6 +49,18 @@ function parseReframeMode(value) {
     }
     return value;
 }
+function parseMirrorMode(value) {
+    if (!mirror_1.MIRROR_MODES.includes(value)) {
+        throw new Error(`unknown --mirror value "${value}" - expected one of ${mirror_1.MIRROR_MODES.join(", ")}`);
+    }
+    return value;
+}
+function parseCompressionFormat(value) {
+    if (!types_1.COMPRESSION_FORMATS.includes(value)) {
+        throw new Error(`unknown --compression-format value "${value}" - expected one of ${types_1.COMPRESSION_FORMATS.join(", ")}`);
+    }
+    return value;
+}
 /** Probes DEFAULT_SIGNALK_URLS in order and returns the first that answers a plain GET - used when -u/--url is omitted. */
 async function resolveDefaultUrl() {
     for (const candidate of exports.DEFAULT_SIGNALK_URLS) {
@@ -226,6 +242,9 @@ exports.program
     .option("--voffset <px>", "vertical pixel offset of the panel - overrides the looked-up model for unsupported hardware (requires --colours)", "0")
     .option("--colours <code>", "device colour palette for unsupported hardware: BW, BWR, or BWRY - overrides the looked-up model (uses --width/--height/--voffset)")
     .option("--reframe <mode>", "how to fit the rendered image onto the device's actual panel size when it doesn't match: crop (default - place at top-left, truncating or leaving the rest blank), scale (stretch the template to the panel), fixed (reject the mismatch instead)", "crop")
+    .option("--mirror <mode>", "flip the image before sending: none (default), horizontal, vertical, or both (rotate 180°)", "none")
+    .option("--no-compress", 'send the image uncompressed (zhsunyco; gicisky 7.5"/10.2" or --compression-format chunked - compression is on by default)')
+    .option("--compression-format <format>", 'gicisky wire format: auto (default - the model\'s usual format) or chunked (experimental - send a 4.2" BWR compressed like the 7.5"/10.2")', "auto")
     .option("--connect-timeout <seconds>", "BLE connect timeout before giving up on an attempt", "30")
     .option("--retries <n>", "number of paint attempts (including the first) before giving up", "3")
     .action(async (opts) => {
@@ -269,6 +288,9 @@ exports.program
             modelOverride,
             connectTimeoutMs,
             reframe: parseReframeMode(opts.reframe),
+            mirror: parseMirrorMode(opts.mirror),
+            compress: opts.compress,
+            compressionFormat: parseCompressionFormat(opts.compressionFormat),
         });
     });
     console.log(`painted ${opts.address} (${bitmap.width}x${bitmap.height}) ${opts.colours}`);
@@ -287,7 +309,9 @@ exports.program
     .option("-f, --font <path>", "override a bundled font with this file (repeatable) - defaults to the bundled monospace/sans-serif/serif trio", 
 // See the -r/--require option above for why `| undefined` is needed here despite commander's typings.
 (value, previous = []) => [...previous, value])
+    .option("--mirror <mode>", "flip the PNG the same way paint --mirror would: none (default), horizontal, vertical, or both", "none")
     .action(async (opts) => {
+    const mirror = parseMirrorMode(opts.mirror);
     const svgSource = await (0, promises_1.readFile)(opts.template, "utf-8");
     const declared = (0, binding_1.readTemplateDimensions)(svgSource);
     const width = resolveDimension(opts.width, [declared.width], DEFAULT_RENDER_WIDTH);
@@ -295,7 +319,7 @@ exports.program
     const bindings = (0, binding_1.findBindings)(svgSource);
     const context = await assembleContext(opts, bindings);
     const renderer = opts.font ? new svgRenderer_1.SvgRenderer(opts.font) : new svgRenderer_1.SvgRenderer();
-    const bitmap = await renderer.render(opts.template, context, width, height, (0, path_1.dirname)(opts.template), config_1.BUNDLED_TEMPLATES_DIR);
+    const bitmap = (0, mirror_1.mirrorBitmap)(await renderer.render(opts.template, context, width, height, (0, path_1.dirname)(opts.template), config_1.BUNDLED_TEMPLATES_DIR), mirror);
     await (0, promises_1.writeFile)(opts.output, (0, png_1.bitmapToPng)(bitmap));
     console.log(`wrote ${opts.output} (${bitmap.width}x${bitmap.height})`);
 });

package/dist/config.d.ts

@@ -1,6 +1,8 @@
 import { ServerAPI } from "@signalk/server-api";
 import { Colour, DiscoveredDevice } from "./devices/types";
 import { ReframeMode } from "./render/reframe";
+import { MirrorMode } from "./render/mirror";
+import { CompressionFormat } from "./devices/types";
 /**
  * Special `device` value meaning "every currently-known discovered device" instead of one specific
  * BLE address - lets a single `DeviceConfig` entry (one template, one trigger) broadcast to every
@@ -58,6 +60,16 @@ export interface DeviceConfig {
      * showing *something*, even off-size, beats a repaint that just fails outright.
      */
     reframe?: ReframeMode;
+    /** Flip the image before sending - for a panel whose layout is mirrored, or one mounted upside down (`"both"`). Unset means `"none"`. */
+    mirror?: MirrorMode;
+    /** 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;
+    /**
+     * Experimental opt-in wire format (gicisky only) - `"chunked"` sends a 4.2" BWR (or another plain
+     * two-plane panel) QuickLZ-compressed like the 7.5"/10.2". Unset means `"auto"`, the model's own
+     * format. See `CompressionFormat`.
+     */
+    compressionFormat?: CompressionFormat;
 }
 export interface PluginConfig {
     /**

package/dist/config.js

@@ -12,6 +12,8 @@ exports.configUiSchema = configUiSchema;
 const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
+const mirror_1 = require("./render/mirror");
+const types_1 = require("./devices/types");
 const templateProviders_1 = require("./render/templateProviders");
 const resolveApiUrl_1 = require("./resolveApiUrl");
 /**
@@ -433,6 +435,27 @@ function configSchema(app, discovered = []) {
                             enum: ["crop", "scale", "fixed"],
                             default: "crop",
                         },
+                        mirror: {
+                            type: "string",
+                            title: "Mirror",
+                            description: "Flip the image if it shows up mirrored on the label. Both = rotate 180°, e.g. for a label mounted upside down.",
+                            enum: mirror_1.MIRROR_MODES,
+                            default: "none",
+                        },
+                        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.",
+                            default: true,
+                        },
+                        compressionFormat: {
+                            type: "string",
+                            title: "Wire format (Gicisky, experimental)",
+                            description: 'Auto: the model\'s usual format. Chunked: send compressed like the 7.5"/10.2" panels - may speed up a 4.2" BWR, ' +
+                                "but untested on current firmware. Needs Compress upload on to actually compress. Switch back to Auto if the label stops updating.",
+                            enum: types_1.COMPRESSION_FORMATS,
+                            default: "auto",
+                        },
                     },
                 },
             },
@@ -446,6 +469,8 @@ function configUiSchema() {
                 description: { "ui:widget": "textarea" },
                 repaintTrigger: { "ui:widget": "radio" },
                 reframe: { "ui:widget": "radio" },
+                mirror: { "ui:widget": "radio" },
+                compressionFormat: { "ui:widget": "radio" },
             },
         },
     };

package/dist/devices/gicisky/compression.d.ts

@@ -1,16 +1,29 @@
 /**
  * Wire framing for `packing: "chunked"` devices (the 7.5"/10.2" panels).
  *
- * The vendor firmware's real format supports each 64-byte chunk being either a `0x75`-tagged
- * QuickLZ-compressed block or a `0x74`-tagged raw one - see hass-gicisky's `gicisky_ble/compression.py`,
- * which ports a vendor-specific 64-bucket-hash variant of QuickLZ Level 1 to produce the smaller
- * `0x75` form. This driver always emits the `0x74` raw form instead: larger over the wire, but the
- * framing itself (chunk headers, the part1/part2 split) is unchanged, so a device that accepts
- * hass-gicisky's output accepts this too - it just costs more BLE writes per repaint than a real
- * compressor would.
+ * Each 64-byte chunk of a plane is sent either as a `0x75`-tagged QuickLZ-compressed block or a
+ * `0x74`-tagged raw one, whichever the compressor decides - a port of hass-gicisky's
+ * `gicisky_ble/compression.py`. That's QuickLZ Level 1, but with the vendor firmware's 6-bit
+ * (64-bucket) hash rather than stock QuickLZ's 12-bit one: match tokens carry a hash-table slot, not
+ * an offset, and the panel's decoder only ever fills 64 slots - a token naming a slot above that
+ * reads one that was never written and silently decodes garbage. So this must stay byte-compatible
+ * with the vendor's hash, not just any valid QuickLZ.
+ *
+ * One deliberate difference from hass-gicisky: `UNCONDITIONAL_MATCHLEN` is stock QuickLZ's 6, not
+ * its 12, so matches may start closer to a chunk's end. That's what the vendor's own app does - with
+ * 6 this reproduces 483 of the 486 distinct `0x75` chunks in Cabalist's BLE captures of the app
+ * (https://github.com/Cabalist/gicisky_image_notes) byte for byte, against 408 with 12. The other 3
+ * are chunks the app sends "compressed" despite them growing; this sends those raw (`0x74`) instead.
+ */
+/**
+ * QuickLZ L1 compression of one chunk, mirroring `_qlz_compress_core` step for step (including its
+ * quirks, e.g. the run-of-identical-bytes special case) so the output matches the vendor app's byte for
+ * byte. Returns `undefined` when compressing wouldn't save anything.
  */
+export declare function qlzCompressChunk(source: Buffer): Buffer | undefined;
 /**
  * Frames two equal-length bit-planes (e.g. BW and red) as `[4-byte LE length of planeB]` followed
- * by each plane's raw-chunked bytes, matching `compress()`'s output shape in the reference driver.
+ * by each plane's chunked bytes, matching `compress()`'s output shape in the reference driver.
+ * `compress: false` sends every chunk raw (`0x74`), like hass-gicisky's `force_raw`.
  */
-export declare function frameChunkedPlanes(planeA: Buffer, planeB: Buffer): Buffer;
+export declare function frameChunkedPlanes(planeA: Buffer, planeB: Buffer, compress?: boolean): Buffer;

package/dist/devices/gicisky/compression.js

@@ -2,33 +2,148 @@
 /**
  * Wire framing for `packing: "chunked"` devices (the 7.5"/10.2" panels).
  *
- * The vendor firmware's real format supports each 64-byte chunk being either a `0x75`-tagged
- * QuickLZ-compressed block or a `0x74`-tagged raw one - see hass-gicisky's `gicisky_ble/compression.py`,
- * which ports a vendor-specific 64-bucket-hash variant of QuickLZ Level 1 to produce the smaller
- * `0x75` form. This driver always emits the `0x74` raw form instead: larger over the wire, but the
- * framing itself (chunk headers, the part1/part2 split) is unchanged, so a device that accepts
- * hass-gicisky's output accepts this too - it just costs more BLE writes per repaint than a real
- * compressor would.
+ * Each 64-byte chunk of a plane is sent either as a `0x75`-tagged QuickLZ-compressed block or a
+ * `0x74`-tagged raw one, whichever the compressor decides - a port of hass-gicisky's
+ * `gicisky_ble/compression.py`. That's QuickLZ Level 1, but with the vendor firmware's 6-bit
+ * (64-bucket) hash rather than stock QuickLZ's 12-bit one: match tokens carry a hash-table slot, not
+ * an offset, and the panel's decoder only ever fills 64 slots - a token naming a slot above that
+ * reads one that was never written and silently decodes garbage. So this must stay byte-compatible
+ * with the vendor's hash, not just any valid QuickLZ.
+ *
+ * One deliberate difference from hass-gicisky: `UNCONDITIONAL_MATCHLEN` is stock QuickLZ's 6, not
+ * its 12, so matches may start closer to a chunk's end. That's what the vendor's own app does - with
+ * 6 this reproduces 483 of the 486 distinct `0x75` chunks in Cabalist's BLE captures of the app
+ * (https://github.com/Cabalist/gicisky_image_notes) byte for byte, against 408 with 12. The other 3
+ * are chunks the app sends "compressed" despite them growing; this sends those raw (`0x74`) instead.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.qlzCompressChunk = qlzCompressChunk;
 exports.frameChunkedPlanes = frameChunkedPlanes;
 const CHUNK_SIZE = 64;
 const RAW_CHUNK_TAG = 0x74;
-function chunkRaw(data) {
+const COMPRESSED_CHUNK_TAG = 0x75;
+const CWORD_LEN = 4;
+const HASH_VALUES = 64;
+const NO_ENTRY = -1;
+const MIN_OFFSET = 2;
+const UNCONDITIONAL_MATCHLEN = 6;
+const UNCOMPRESSED_END = 4;
+/** Control-word sentinel: the top bit marks where the 31 flag bits below it run out. */
+const CWORD_SENTINEL = 0x80000000;
+function hashOf(fetch) {
+    return ((fetch >>> 12) ^ fetch) & (HASH_VALUES - 1);
+}
+function read3(data, pos) {
+    return pos + 3 > data.length ? 0 : data[pos] | (data[pos + 1] << 8) | (data[pos + 2] << 16);
+}
+/** Whether the `n + 1` bytes from `pos` are all equal. */
+function allSame(data, pos, n) {
+    if (pos < 0 || pos + n >= data.length)
+        return false;
+    for (let i = 1; i <= n; i++) {
+        if (data[pos + i] !== data[pos])
+            return false;
+    }
+    return true;
+}
+/**
+ * QuickLZ L1 compression of one chunk, mirroring `_qlz_compress_core` step for step (including its
+ * quirks, e.g. the run-of-identical-bytes special case) so the output matches the vendor app's byte for
+ * byte. Returns `undefined` when compressing wouldn't save anything.
+ */
+function qlzCompressChunk(source) {
+    const size = source.length;
+    const lastByte = size - 1;
+    const lastMatchStart = lastByte - UNCONDITIONAL_MATCHLEN - UNCOMPRESSED_END;
+    if (lastMatchStart < 0)
+        return undefined;
+    const out = Buffer.alloc(size * 2 + 400);
+    let cwordPtr = 0;
+    let dst = CWORD_LEN;
+    let cword = CWORD_SENTINEL;
+    let src = 0;
+    let lits = 0;
+    const hashOffset = new Int32Array(HASH_VALUES).fill(NO_ENTRY);
+    const hashCache = new Int32Array(HASH_VALUES);
+    const flushCword = () => {
+        out.writeUInt32LE(((cword >>> 1) | CWORD_SENTINEL) >>> 0, cwordPtr);
+        cwordPtr = dst;
+        dst += CWORD_LEN;
+        cword = CWORD_SENTINEL;
+    };
+    while (src <= lastMatchStart) {
+        if ((cword & 1) === 1) {
+            if (src > size >> 1 && dst > src - (src >> 5))
+                return undefined;
+            flushCword();
+        }
+        const fetch = read3(source, src);
+        const h = hashOf(fetch);
+        const cached = fetch ^ hashCache[h];
+        hashCache[h] = fetch;
+        const o = hashOffset[h];
+        hashOffset[h] = src;
+        if ((cached & 0xffffff) === 0 &&
+            o !== NO_ENTRY &&
+            (src - o > MIN_OFFSET || (src === o + 1 && lits >= 3 && src > 3 && allSame(source, src - 3, 6)))) {
+            let matchLen = 3;
+            const remaining = Math.min(255, lastByte - UNCOMPRESSED_END - src + 1);
+            while (matchLen < remaining && source[src + matchLen] === source[o + matchLen])
+                matchLen++;
+            const hShifted = h << 4;
+            cword = ((cword >>> 1) | CWORD_SENTINEL) >>> 0;
+            if (matchLen < 18) {
+                out.writeUInt16LE((matchLen - 2) | hShifted, dst);
+                dst += 2;
+            }
+            else {
+                out.writeUInt16LE(hShifted, dst);
+                out[dst + 2] = matchLen;
+                dst += 3;
+            }
+            src += matchLen;
+            lits = 0;
+        }
+        else {
+            lits++;
+            out[dst++] = source[src++];
+            cword >>>= 1;
+        }
+    }
+    while (src <= lastByte) {
+        if ((cword & 1) === 1)
+            flushCword();
+        if (src <= lastByte - 2) {
+            const f = read3(source, src);
+            const hh = hashOf(f);
+            hashCache[hh] = f;
+            hashOffset[hh] = src;
+        }
+        out[dst++] = source[src++];
+        cword >>>= 1;
+    }
+    while ((cword & 1) !== 1)
+        cword >>>= 1;
+    out.writeUInt32LE(((cword >>> 1) | CWORD_SENTINEL) >>> 0, cwordPtr);
+    return dst >= size ? undefined : out.subarray(0, dst);
+}
+function chunkPlane(data, compress) {
     const chunks = [];
     for (let offset = 0; offset < data.length; offset += CHUNK_SIZE) {
         const chunk = data.subarray(offset, Math.min(offset + CHUNK_SIZE, data.length));
-        const header = Buffer.from([RAW_CHUNK_TAG, 3 + chunk.length, chunk.length]);
-        chunks.push(header, chunk);
+        const compressed = compress ? qlzCompressChunk(chunk) : undefined;
+        const body = compressed ?? chunk;
+        chunks.push(Buffer.from([compressed ? COMPRESSED_CHUNK_TAG : RAW_CHUNK_TAG, 3 + body.length, chunk.length]), body);
     }
     return Buffer.concat(chunks);
 }
 /**
  * Frames two equal-length bit-planes (e.g. BW and red) as `[4-byte LE length of planeB]` followed
- * by each plane's raw-chunked bytes, matching `compress()`'s output shape in the reference driver.
+ * by each plane's chunked bytes, matching `compress()`'s output shape in the reference driver.
+ * `compress: false` sends every chunk raw (`0x74`), like hass-gicisky's `force_raw`.
  */
-function frameChunkedPlanes(planeA, planeB) {
+function frameChunkedPlanes(planeA, planeB, compress = true) {
     const header = Buffer.alloc(4);
     header.writeUInt32LE(planeB.length, 0);
-    return Buffer.concat([header, chunkRaw(planeA), chunkRaw(planeB)]);
+    return Buffer.concat([header, chunkPlane(planeA, compress), chunkPlane(planeB, compress)]);
 }

package/dist/devices/gicisky/encode.d.ts

@@ -7,4 +7,4 @@ import { GiciskyLayout } from "./layout";
  * colour selection uses palette-nearest classification (matching this codebase's `zhsunyco`
  * driver) rather than the reference driver's raw-luminance thresholds.
  */
-export declare function encodeBitmap(bitmap: Bitmap, metadata: DeviceMetadata, layout: GiciskyLayout): Buffer;
+export declare function encodeBitmap(bitmap: Bitmap, metadata: DeviceMetadata, layout: GiciskyLayout, compress?: boolean): Buffer;

package/dist/devices/gicisky/encode.js

@@ -115,7 +115,7 @@ function packFourColour(bitmap, layout, supported) {
  * colour selection uses palette-nearest classification (matching this codebase's `zhsunyco`
  * driver) rather than the reference driver's raw-luminance thresholds.
  */
-function encodeBitmap(bitmap, metadata, layout) {
+function encodeBitmap(bitmap, metadata, layout, compress = true) {
     if (layout.packing === "unsupported") {
         throw new Error(`gicisky paint: device "${metadata.label}" isn't supported yet (needs compression/resize support this driver doesn't implement)`);
     }
@@ -134,7 +134,7 @@ function encodeBitmap(bitmap, metadata, layout) {
     }
     const redPlane = packPlane(rotated, layout, supported, (colour) => colour === "red");
     if (layout.packing === "chunked") {
-        return (0, compression_1.frameChunkedPlanes)(bwPlane, redPlane);
+        return (0, compression_1.frameChunkedPlanes)(bwPlane, redPlane, compress);
     }
     return Buffer.concat([bwPlane, redPlane]);
 }

package/dist/devices/gicisky/index.js

@@ -6,6 +6,7 @@ const metadata_1 = require("./metadata");
 const layout_1 = require("./layout");
 const encode_1 = require("./encode");
 const reframe_1 = require("../../render/reframe");
+const mirror_1 = require("../../render/mirror");
 const protocol_1 = require("./protocol");
 /** How long to actively rescan for a fresh advertisement when the cached one is missing/stale - see `BleBackend.waitForManufacturerData`. */
 const MANUFACTURER_DATA_RESCAN_TIMEOUT_MS = 15000;
@@ -69,9 +70,9 @@ class GiciskyDriver {
                 : `gicisky device reports unrecognised deviceId 0x${pid.toString(16).padStart(4, "0")} - ` +
                     "pass --width/--height/--voffset/--colours to describe it manually");
         }
-        const layout = (pid !== undefined && layout_1.GICISKY_PID_LAYOUT[pid]) || (0, layout_1.defaultLayoutFor)(metadata.colours);
-        const framed = (0, reframe_1.reframeBitmap)(bitmap, metadata.width, metadata.height, config.reframe ?? "crop");
-        const payload = (0, encode_1.encodeBitmap)(framed, metadata, layout);
+        const layout = (0, layout_1.withCompressionFormat)((pid !== undefined && layout_1.GICISKY_PID_LAYOUT[pid]) || (0, layout_1.defaultLayoutFor)(metadata.colours), config.compressionFormat ?? "auto", metadata.colours);
+        const framed = (0, mirror_1.mirrorBitmap)((0, reframe_1.reframeBitmap)(bitmap, metadata.width, metadata.height, config.reframe ?? "crop"), config.mirror ?? "none");
+        const payload = (0, encode_1.encodeBitmap)(framed, metadata, layout, config.compress ?? true);
         const conn = await backend.connectGatt(config.address, config.connectTimeoutMs ?? DEFAULT_PAINT_CONNECT_TIMEOUT_MS);
         try {
             const { cmdServiceUuid, cmdUuid, imgServiceUuid, imgUuid } = await findCommandAndImageCharacteristics(conn);

package/dist/devices/gicisky/layout.d.ts

@@ -1,3 +1,4 @@
+import { CompressionFormat } from "../types";
 /**
  * Per-model wire-layout quirks, keyed the same way as `GICISKY_PID_METADATA` (by `deviceId`).
  * These aren't part of the shared `DeviceMetadata` shape since no other vendor needs them -
@@ -9,7 +10,7 @@
 export type GiciskyPacking = 
 /** Plain concatenated bit-planes, no framing - covers most panels. */
 "plain"
-/** Two bit-planes each split into raw 64-byte chunks framed per `compression.ts`'s `compress()` - the 7.5"/10.2" panels. */
+/** Two bit-planes each split into 64-byte chunks (QuickLZ-compressed or raw) framed per `compression.ts` - the 7.5"/10.2" panels. */
  | "chunked"
 /**
  * A panel this driver can identify (for `scan`/discovery) but can't paint correctly yet - either
@@ -33,3 +34,14 @@ export interface GiciskyLayout {
 export declare const GICISKY_PID_LAYOUT: Record<number, GiciskyLayout>;
 /** Best-effort layout for a `modelOverride`d PID this table has no entry for - assumes the common case. */
 export declare function defaultLayoutFor(colours: string[]): GiciskyLayout;
+/**
+ * Applies a user's opt-in `compressionFormat: "chunked"` - switching a `"plain"` two-plane (BW + red)
+ * layout to the QuickLZ-chunked framing, with the flagged `writeScreen` command that goes with it.
+ * Opt-in rather than a model default because only one data point says a plain panel accepts it:
+ * Cabalist's 2023 BLE captures (https://github.com/Cabalist/gicisky_image_notes) of the vendor app
+ * sending a 4.2" BWR exactly this way, on firmware that may not match what's shipping now.
+ *
+ * Throws for layouts the framing can't carry, rather than quietly sending plain anyway - the user
+ * asked for chunked, so a repaint error says why they're not getting it.
+ */
+export declare function withCompressionFormat(layout: GiciskyLayout, format: CompressionFormat, colours: string[]): GiciskyLayout;

package/dist/devices/gicisky/layout.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GICISKY_PID_LAYOUT = void 0;
 exports.defaultLayoutFor = defaultLayoutFor;
+exports.withCompressionFormat = withCompressionFormat;
 const DEFAULT_LAYOUT = {
     rotation: 0,
     mirrorX: false,
@@ -33,3 +34,23 @@ exports.GICISKY_PID_LAYOUT = {
 function defaultLayoutFor(colours) {
     return { ...DEFAULT_LAYOUT, fourColour: colours.includes("yellow") };
 }
+/**
+ * Applies a user's opt-in `compressionFormat: "chunked"` - switching a `"plain"` two-plane (BW + red)
+ * layout to the QuickLZ-chunked framing, with the flagged `writeScreen` command that goes with it.
+ * Opt-in rather than a model default because only one data point says a plain panel accepts it:
+ * Cabalist's 2023 BLE captures (https://github.com/Cabalist/gicisky_image_notes) of the vendor app
+ * sending a 4.2" BWR exactly this way, on firmware that may not match what's shipping now.
+ *
+ * Throws for layouts the framing can't carry, rather than quietly sending plain anyway - the user
+ * asked for chunked, so a repaint error says why they're not getting it.
+ */
+function withCompressionFormat(layout, format, colours) {
+    if (format === "auto" || layout.packing === "chunked") {
+        return layout;
+    }
+    if (layout.packing !== "plain" || layout.fourColour || !colours.includes("red")) {
+        throw new Error('gicisky paint: compressionFormat "chunked" needs a panel sent as separate black/white and red planes - ' +
+            'this model isn\'t (four-colour, black/white only, or unsupported) - set it back to "auto"');
+    }
+    return { ...layout, packing: "chunked" };
+}

package/dist/devices/types.d.ts

@@ -1,8 +1,17 @@
 import { Bitmap } from "../render/types";
 import { ReframeMode } from "../render/reframe";
+import { MirrorMode } from "../render/mirror";
 import { BleBackend } from "./bleBackend";
 import { GattConnection } from "./gattConnection";
 export type Colour = "black" | "white" | "red" | "yellow";
+/**
+ * Which wire format to send in - `"auto"` uses whatever the driver's model table says;
+ * `"chunked"` opts a gicisky panel with separate BW/red planes (e.g. the 4.2" BWR, normally sent
+ * plain) into the QuickLZ-compressed chunk framing the 7.5"/10.2" use - see `withCompressionFormat`
+ * in `gicisky/layout.ts`. Ignored by other vendors.
+ */
+export type CompressionFormat = "auto" | "chunked";
+export declare const COMPRESSION_FORMATS: CompressionFormat[];
 /**
  * Static facts about one device model, keyed by (vendor, pid) by the registry —
  * PID alone is not assumed unique across vendors.
@@ -68,6 +77,12 @@ export interface VendorDeviceConfig {
     connectTimeoutMs?: number;
     /** How to fit the bitmap onto the panel when its size doesn't already match - see `ReframeMode`. Defaults to `"crop"` - a live label showing *something*, even off-size, beats a repaint that just fails outright; pass `"fixed"` explicitly to get the old reject-the-mismatch behaviour back. */
     reframe?: ReframeMode;
+    /** Flips the image after reframing, before encoding - see `MirrorMode`. Defaults to `"none"`. */
+    mirror?: MirrorMode;
+    /** Compress the upload where the vendor protocol supports it (zhsunyco; gicisky's chunked 7.5"/10.2" panels); ignored otherwise. Defaults to `true`. */
+    compress?: boolean;
+    /** Overrides the model's own wire format - see `CompressionFormat`. Defaults to `"auto"`. */
+    compressionFormat?: CompressionFormat;
     /**
      * How `paint()` reaches the device's BLE hardware - omitted (always true for the CLI, which has no
      * `ServerAPI`/`app.bleApi` to source one from) means direct BlueZ access via a fresh

package/dist/devices/types.js

@@ -1,2 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMPRESSION_FORMATS = void 0;
+exports.COMPRESSION_FORMATS = ["auto", "chunked"];

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

@@ -0,0 +1 @@
+export declare function compressWolinkBlocks(data: Buffer): Buffer;

package/dist/devices/zhsunyco/compression.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compressWolinkBlocks = compressWolinkBlocks;
+const zlib_1 = require("zlib");
+/**
+ * Wolink block-deflate payload format, ported from the `zhsunyco_esl` package bundled with the
+ * Home Assistant Wolink ESL integration (`zhsunyco_esl/protocol.py`):
+ *
+ *   A5 A6 <blockCount u8> 02, then per block: <1-based index u8> <compressedLength u16le> <raw deflate>
+ *
+ * Each block holds up to 8 KB of the uncompressed 2bpp buffer. Sent in place of the raw buffer,
+ * followed by `COMMAND.refreshCompressed` carrying the compressed length.
+ */
+const WOLINK_BLOCK_SIZE = 8192;
+const WOLINK_BLOCK_FORMAT = 0x02;
+function compressWolinkBlocks(data) {
+    const blockCount = Math.ceil(data.length / WOLINK_BLOCK_SIZE);
+    if (blockCount > 0xff) {
+        throw new Error(`zhsunyco compression: ${data.length} bytes needs ${blockCount} blocks, format allows at most 255`);
+    }
+    const parts = [Buffer.from([0xa5, 0xa6, blockCount, WOLINK_BLOCK_FORMAT])];
+    for (let i = 0; i < blockCount; i++) {
+        const deflated = (0, zlib_1.deflateRawSync)(data.subarray(i * WOLINK_BLOCK_SIZE, (i + 1) * WOLINK_BLOCK_SIZE), { level: 9 });
+        const header = Buffer.alloc(3);
+        header[0] = i + 1;
+        header.writeUInt16LE(deflated.length, 1);
+        parts.push(header, deflated);
+    }
+    return Buffer.concat(parts);
+}

package/dist/devices/zhsunyco/index.js

@@ -7,6 +7,8 @@ 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;
@@ -77,14 +79,18 @@ 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");
+                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);
+                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;
+                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]), true);
                     await (0, bleDiscovery_1.sleep)(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), true);
                 // `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.

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

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);
+    }
+}

package/dist/render/mirror.d.ts

@@ -0,0 +1,11 @@
+import { Bitmap } from "./types";
+/**
+ * Flips the rendered image before it's encoded for the panel - for hardware whose RAM layout is
+ * mirrored relative to what a driver's encoder assumes (the Wolink HA integration found the 2.9"
+ * and 3.5" panels differ from the 3.7" this plugin's zhsunyco encoder was confirmed against), or a
+ * label that's simply mounted upside down (`"both"` is a 180° rotation).
+ */
+export type MirrorMode = "none" | "horizontal" | "vertical" | "both";
+export declare const MIRROR_MODES: MirrorMode[];
+/** Returns `bitmap` unchanged for `"none"`, otherwise a flipped copy. */
+export declare function mirrorBitmap(bitmap: Bitmap, mode: MirrorMode): Bitmap;

package/dist/render/mirror.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIRROR_MODES = void 0;
+exports.mirrorBitmap = mirrorBitmap;
+exports.MIRROR_MODES = ["none", "horizontal", "vertical", "both"];
+/** Returns `bitmap` unchanged for `"none"`, otherwise a flipped copy. */
+function mirrorBitmap(bitmap, mode) {
+    if (mode === "none") {
+        return bitmap;
+    }
+    const { width, height } = bitmap;
+    const flipX = mode === "horizontal" || mode === "both";
+    const flipY = mode === "vertical" || mode === "both";
+    const data = new Uint8Array(bitmap.data.length);
+    for (let y = 0; y < height; y++) {
+        const srcY = flipY ? height - 1 - y : y;
+        for (let x = 0; x < width; x++) {
+            const srcX = flipX ? width - 1 - x : x;
+            const srcOffset = (srcY * width + srcX) * 4;
+            data.set(bitmap.data.subarray(srcOffset, srcOffset + 4), (y * width + x) * 4);
+        }
+    }
+    return { width, height, data };
+}

package/dist/repaintScheduler.js

@@ -358,6 +358,9 @@ async function considerRepaint(app, config, device, target, state, getApiUrl) {
             aesKey: device.aesKey,
             connectTimeoutMs,
             reframe: device.reframe,
+            mirror: device.mirror,
+            compress: device.compress,
+            compressionFormat: device.compressionFormat,
             gattBackend,
         });
         paintDurationMs = Date.now() - startedAt;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rhizomatics/signalk-einklabel-plugin",
-  "version": "1.3.0-beta8",
+  "version": "1.3.0-beta9",
   "description": "Display SignalK data on eInk Electronic Shelf Labels, includes working examples for tide clock and watch schedule.",
   "keywords": [
     "ble",