@agentdeck/bridge 0.2.2 → 1.0.0

package/dist/trmnl/image-renderer.js

@@ -0,0 +1,235 @@
+/**
+ * TRMNL image renderer — rasterizes the shared 800×480 dashboard SVG to a
+ * 1-bit (black/white) grayscale PNG sized for the TRMNL 7.5" e-ink panel.
+ *
+ * Pipeline: shared `renderTrmnlDashboard` SVG → resvg rasterize (800×480 RGBA)
+ * → luminance threshold → packed 1-bit PNG (color type 0, bit depth 1) encoded
+ * with Node's built-in `zlib` (no new dependency). A 1-bit PNG of mostly-white
+ * line art deflates to a few KB, comfortably under TRMNL's 90 KB download cap.
+ *
+ * Falls back to a blank 1-bit PNG when resvg-js is unavailable (matches the
+ * D200H renderer's optional-dependency pattern).
+ */
+import { deflateSync } from 'zlib';
+import { createHash } from 'crypto';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { renderTrmnlDashboard, TRMNL_WIDTH, TRMNL_HEIGHT } from '@agentdeck/shared';
+import { debug, logTagged } from '../logger.js';
+const TAG = 'trmnl-render';
+// --- Font supply for resvg (same trap/fix as the D200H renderer) ---
+// resvg drops every <text> element unless given a font to shape glyphs with.
+// Load the bundled OFL faces via `fontFiles` for crisp Latin/mono, AND enable
+// `loadSystemFonts` so resvg can FALL BACK to the OS's CJK faces — session goals
+// are user prompts, often Korean/Chinese, which the Latin-only bundled fonts
+// render as boxes. Unlike the 14-tile-per-frame D200H renderer, TRMNL renders one
+// frame only on real state change, so the per-`new Resvg()` system-font scan is an
+// acceptable cost here.
+const FONT_OPTS = (() => {
+    try {
+        // bridge/{src,dist}/trmnl/image-renderer.{ts,js} → bridge/assets/fonts
+        const here = dirname(fileURLToPath(import.meta.url));
+        const fontsDir = join(here, '..', '..', 'assets', 'fonts');
+        const files = [
+            'IBMPlexSans-Regular.ttf',
+            'IBMPlexSans-Bold.ttf',
+            'JetBrainsMono-Regular.ttf',
+            'JetBrainsMono-Bold.ttf',
+        ]
+            .map((n) => join(fontsDir, n))
+            .filter((p) => existsSync(p));
+        if (files.length > 0) {
+            return { fontFiles: files, loadSystemFonts: true, defaultFontFamily: 'IBM Plex Sans' };
+        }
+        debug(TAG, `bundled fonts not found under ${fontsDir} — falling back to system fonts`);
+    }
+    catch (err) {
+        debug(TAG, `font path resolution failed (${err}) — falling back to system fonts`);
+    }
+    return { loadSystemFonts: true, defaultFontFamily: 'Helvetica Neue' };
+})();
+let Resvg = null;
+let resvgLoaded = false;
+async function loadResvg() {
+    if (resvgLoaded)
+        return Resvg;
+    resvgLoaded = true;
+    try {
+        const mod = await import('@resvg/resvg-js');
+        Resvg = mod.Resvg ?? mod.default?.Resvg;
+        debug(TAG, 'resvg-js loaded — SVG rendering enabled');
+        return Resvg;
+    }
+    catch {
+        debug(TAG, 'resvg-js not available — falling back to blank 1-bit PNG');
+        return null;
+    }
+}
+/** Initialize the renderer (loads resvg-js if available). Call once at start. */
+export async function initTrmnlRenderer() {
+    await loadResvg();
+}
+export function isTrmnlResvgLoaded() {
+    return Resvg !== null;
+}
+// --- PNG (1-bit grayscale) encoding ---
+const crcTable = new Uint32Array(256);
+for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++)
+        c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    crcTable[n] = c >>> 0;
+}
+function crc32(buf) {
+    let crc = 0xffffffff;
+    for (let i = 0; i < buf.length; i++)
+        crc = crcTable[(crc ^ buf[i]) & 0xff] ^ (crc >>> 8);
+    return (crc ^ 0xffffffff) >>> 0;
+}
+function pngChunk(type, data) {
+    const typeBytes = Buffer.from(type, 'ascii');
+    const len = Buffer.alloc(4);
+    len.writeUInt32BE(data.length, 0);
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(Buffer.concat([typeBytes, data])), 0);
+    return Buffer.concat([len, typeBytes, data, crc]);
+}
+const PNG_SIG = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+/**
+ * Encode a 1-bit grayscale PNG from a packed bitmap.
+ * `bits` holds one bit per pixel, MSB-first, `bytesPerRow` bytes per scanline,
+ * where 1 = white and 0 = black (PNG grayscale convention).
+ */
+function encode1BitPng(bits, width, height, bytesPerRow) {
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(width, 0);
+    ihdr.writeUInt32BE(height, 4);
+    ihdr[8] = 1; // bit depth
+    ihdr[9] = 0; // color type: grayscale
+    ihdr[10] = 0; // compression
+    ihdr[11] = 0; // filter
+    ihdr[12] = 0; // interlace
+    // Raw image data: each scanline prefixed with filter byte 0 (None).
+    const raw = Buffer.alloc((bytesPerRow + 1) * height);
+    for (let y = 0; y < height; y++) {
+        const dst = y * (bytesPerRow + 1);
+        raw[dst] = 0; // filter: None
+        for (let x = 0; x < bytesPerRow; x++)
+            raw[dst + 1 + x] = bits[y * bytesPerRow + x];
+    }
+    const idat = deflateSync(raw, { level: 9 });
+    return Buffer.concat([
+        PNG_SIG,
+        pngChunk('IHDR', ihdr),
+        pngChunk('IDAT', idat),
+        pngChunk('IEND', Buffer.alloc(0)),
+    ]);
+}
+/**
+ * Box-downsample a supersampled RGBA buffer (`ss`× the target size) to a packed
+ * 1-bit bitmap (1 = white, 0 = black). Averaging each ss×ss block of luma BEFORE
+ * thresholding is what sharpens text on a 1-bit panel: a hard threshold of a
+ * 1×-rendered glyph drops/jaggies thin strokes (notably Hangul), whereas the
+ * averaged edge lands on the majority-coverage boundary, so the same glyph reads
+ * crisp. `ss === 1` degrades to a plain threshold.
+ */
+function rgbaToPacked1Bit(pixels, srcWidth, srcHeight, ss = 1) {
+    const width = Math.floor(srcWidth / ss);
+    const height = Math.floor(srcHeight / ss);
+    const bytesPerRow = (width + 7) >> 3;
+    const bits = new Uint8Array(bytesPerRow * height);
+    bits.fill(0xff); // default white
+    const norm = 1 / (ss * ss);
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            let sum = 0;
+            for (let dy = 0; dy < ss; dy++) {
+                const sy = Math.min(y * ss + dy, srcHeight - 1);
+                const rowBase = sy * srcWidth;
+                for (let dx = 0; dx < ss; dx++) {
+                    const sx = Math.min(x * ss + dx, srcWidth - 1);
+                    const p = (rowBase + sx) * 4;
+                    // Rec.601 luma; transparent pixels (alpha 0) read as white since our SVG
+                    // paints a full white background, so alpha is effectively always 255.
+                    sum += (pixels[p] * 299 + pixels[p + 1] * 587 + pixels[p + 2] * 114) / 1000;
+                }
+            }
+            if (sum * norm < 128) {
+                // black pixel → clear the bit
+                bits[y * bytesPerRow + (x >> 3)] &= ~(0x80 >> (x & 7));
+            }
+        }
+    }
+    return { bits, bytesPerRow, width, height };
+}
+/** A fully-white 1-bit PNG (fallback when resvg is unavailable). */
+function blankPng(width, height) {
+    const bytesPerRow = (width + 7) >> 3;
+    const bits = new Uint8Array(bytesPerRow * height).fill(0xff);
+    return encode1BitPng(bits, width, height, bytesPerRow);
+}
+function hashBuffer(buf) {
+    return createHash('sha1').update(buf).digest('hex').slice(0, 16);
+}
+/**
+ * Render the AgentDeck dashboard for the given broadcast state into a 1-bit PNG.
+ * Accepts a raw state event or a pre-parsed DashState (passed through to the
+ * shared layout). `now` may be supplied for deterministic tests.
+ */
+export function renderTrmnlFrame(stateEvt, now, size) {
+    const width = size?.width && size.width > 0 ? Math.round(size.width) : TRMNL_WIDTH;
+    const height = size?.height && size.height > 0 ? Math.round(size.height) : TRMNL_HEIGHT;
+    let buffer;
+    let degraded = false;
+    if (Resvg) {
+        try {
+            const svg = renderTrmnlDashboard(stateEvt, { ...(now ? { now } : {}), width, height });
+            // Supersample so the 1-bit threshold has sub-pixel edge info (crisper text,
+            // esp. Hangul). Cap the rasterized width so large panels don't blow up the
+            // per-frame render: 800→3×, ~1200→2×, ≥2400→1×.
+            const ss = Math.max(1, Math.min(3, Math.floor(2400 / width)));
+            const resvg = new Resvg(svg, {
+                fitTo: { mode: 'width', value: width * ss },
+                font: FONT_OPTS,
+                background: '#ffffff',
+            });
+            const rendered = resvg.render();
+            const packed = rgbaToPacked1Bit(rendered.pixels, rendered.width, rendered.height, ss);
+            buffer = encode1BitPng(packed.bits, packed.width, packed.height, packed.bytesPerRow);
+        }
+        catch (err) {
+            // Always visible (not debug-gated): a failed render used to silently ship
+            // a blank white frame to the panel — the classic "dashboard disappeared"
+            // report with zero trace. Rate-limited per error message.
+            noteRenderFailure(String(err));
+            buffer = blankPng(width, height);
+            degraded = true;
+        }
+    }
+    else {
+        buffer = blankPng(width, height);
+        degraded = true;
+    }
+    return {
+        buffer,
+        contentHash: hashBuffer(buffer),
+        width,
+        height,
+        contentType: 'image/png',
+        ...(degraded ? { degraded: true } : {}),
+    };
+}
+// Rate-limit render-failure logging so a hot broadcast loop can't spam stderr:
+// each distinct error message logs at most once per minute.
+const RENDER_FAIL_LOG_INTERVAL_MS = 60_000;
+const lastRenderFailLogAt = new Map();
+function noteRenderFailure(message) {
+    const now = Date.now();
+    const last = lastRenderFailLogAt.get(message) ?? 0;
+    if (now - last < RENDER_FAIL_LOG_INTERVAL_MS)
+        return;
+    lastRenderFailLogAt.set(message, now);
+    logTagged(TAG, `render failed (frame cache keeps the last good frame): ${message}`);
+}
+//# sourceMappingURL=image-renderer.js.map

package/dist/trmnl/image-renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-renderer.js","sourceRoot":"","sources":["../../src/trmnl/image-renderer.ts"],"names":[],"mappings":"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"}

package/dist/trmnl/trmnl-settings.d.ts

@@ -0,0 +1,96 @@
+export declare const TRMNL_DEFAULT_REFRESH = 180;
+/**
+ * Cadence used only while an agent is AWAITING the user. NOT used for "working":
+ * a battery e-ink panel deep-sleeps between polls and full-flashes the screen on
+ * every refresh, so we only tighten the loop when the user actually needs to act.
+ */
+export declare const TRMNL_DEFAULT_REFRESH_ACTIVE = 60;
+/** Floor on any cadence — too-frequent polls drain the panel battery + flash it. */
+export declare const TRMNL_MIN_REFRESH = 30;
+/**
+ * Seconds the firmware waits for the image download before giving up (its
+ * `image_url_timeout`). Generous so a slow/flaky WiFi link doesn't trip the
+ * device's "not responding" (WIFI_FAILED) screen. Firmware caps at ~65s, so we
+ * keep a healthy default (most "not responding" cycles are a lossy image GET
+ * timing out, not a server error — see docs/devices.md TRMNL section).
+ */
+export declare const TRMNL_DEFAULT_IMAGE_TIMEOUT = 50;
+/** Hard cap the firmware honors (it clamps `image_url_timeout` ~65s internally). */
+export declare const TRMNL_MAX_IMAGE_TIMEOUT = 65;
+/**
+ * RSSI (dBm) at or below which the panel's WiFi link is treated as weak/lossy.
+ * A weak link is the dominant real-world cause of "not responding" (WIFI_FAILED):
+ * the image download drops packets and times out. RSSI is sent by the firmware on
+ * every poll, so we can react per-poll. (-78 ≈ marginal; below it, retransmits
+ * stack up and the default window can be too tight.)
+ */
+export declare const TRMNL_WEAK_RSSI_DBM = -78;
+/** Image-download window served on a weak link — near the firmware cap. */
+export declare const TRMNL_WEAK_LINK_IMAGE_TIMEOUT = 60;
+export interface TrmnlDevice {
+    /** Normalized (uppercase, colon-separated) MAC address — the device identity. */
+    mac: string;
+    /** Secret issued at /api/setup, presented back as the Access-Token header. */
+    apiKey: string;
+    /** Short human-friendly id shown on the device + in logs. */
+    friendlyId: string;
+    /** Optional user label. */
+    name?: string;
+}
+export interface TrmnlConfig {
+    enabled: boolean;
+    /** Idle/working cadence (seconds) — the slow, battery-friendly default. */
+    refreshRate: number;
+    /** Cadence (seconds) while a session is AWAITING the user. */
+    refreshActive: number;
+    /** Image-download timeout (seconds) handed to the firmware as image_url_timeout. */
+    imageUrlTimeout: number;
+    autoRegister: boolean;
+    devices: TrmnlDevice[];
+}
+/**
+ * Cadence for a poll. We only speed up for AWAITING (the user needs to act);
+ * "working" stays on the slow cadence because a deep-sleep e-ink panel can't be
+ * pushed and each wake full-flashes the screen + costs battery.
+ */
+export declare function effectiveRefreshRate(cfg: TrmnlConfig, activity: {
+    awaiting: number;
+    working: number;
+}): number;
+/**
+ * Image-download timeout (seconds) for a single poll. Widens toward the firmware
+ * cap when the panel reports a weak WiFi signal, so a lossy image GET still has
+ * the maximum window to finish before the firmware shows "not responding"
+ * (WIFI_FAILED) — the #1 source of TRMNL flicker on a marginal link. A strong link
+ * keeps the lower default so a genuinely dead link doesn't hold the radio on
+ * (battery). RSSI absent (older firmware) ⇒ default; the default itself is already
+ * generous. Clamped to [5, firmware cap].
+ */
+export declare function effectiveImageTimeout(cfg: TrmnlConfig, opts?: {
+    rssi?: number | null;
+}): number;
+/** Load the trmnl config with defaults filled in. */
+export declare function loadTrmnlConfig(): TrmnlConfig;
+/**
+ * Normalize a MAC to a stable identity key. A canonical 12-hex address becomes
+ * uppercase colon-separated pairs; any other id (some firmware/cloud setups
+ * report non-standard or punctuated identifiers) collapses to its bare uppercase
+ * hex digits. Returning the raw, untrimmed string for the odd case would orphan
+ * or duplicate a device whose punctuation varies between polls — so we always
+ * derive a deterministic key from the hex content.
+ */
+export declare function normalizeMac(mac: string): string;
+/** True when two MAC spellings resolve to the same canonical identity. */
+export declare function sameMac(a: string, b: string): boolean;
+export declare function findDeviceByMac(mac: string): TrmnlDevice | undefined;
+/**
+ * Find or create a device record for the given MAC. Returns the device and
+ * whether it was newly created. Respects `autoRegister`: when off, a new MAC
+ * is NOT persisted and `created` is false with `device` undefined.
+ */
+export declare function ensureDevice(mac: string, name?: string): {
+    device?: TrmnlDevice;
+    created: boolean;
+};
+export declare function removeDevice(mac: string): boolean;
+//# sourceMappingURL=trmnl-settings.d.ts.map

package/dist/trmnl/trmnl-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trmnl-settings.d.ts","sourceRoot":"","sources":["../../src/trmnl/trmnl-settings.ts"],"names":[],"mappings":"AA2BA,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,KAAK,CAAC;AAC/C,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAC9C,oFAAoF;AACpF,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAC1C;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,2EAA2E;AAC3E,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD,MAAM,WAAW,WAAW;IAC1B,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,UAAU,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,2EAA2E;IAC3E,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,aAAa,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC9C,MAAM,CAER;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAO,GAAG,MAAM,CAMnG;AAeD,qDAAqD;AACrD,wBAAgB,eAAe,IAAI,WAAW,CAoB7C;AAQD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIhD;AAED,0EAA0E;AAC1E,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAEpE;AAWD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAgBnG;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAOjD"}

package/dist/trmnl/trmnl-settings.js

@@ -0,0 +1,177 @@
+/**
+ * TRMNL BYOS settings — reads/writes the `trmnl` block in
+ * ~/.agentdeck/settings.json, preserving all other keys (same pattern as
+ * pixoo-settings.ts).
+ *
+ * Shape:
+ *   "trmnl": {
+ *     "enabled": false,            // force the module on even with no device yet
+ *     "refreshRate": 180,          // seconds between device polls
+ *     "autoRegister": true,        // auto-enroll a device that hits /api/setup
+ *     "devices": [ { mac, apiKey, friendlyId, name? } ]
+ *   }
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { randomBytes } from 'crypto';
+// Resolve lazily so tests (and explicit pinning) can redirect via
+// AGENTDECK_DATA_DIR, matching apme/settings.ts and esp32-serial.ts.
+function settingsDir() {
+    return process.env.AGENTDECK_DATA_DIR || join(homedir(), '.agentdeck');
+}
+function settingsPath() {
+    return join(settingsDir(), 'settings.json');
+}
+export const TRMNL_DEFAULT_REFRESH = 180;
+/**
+ * Cadence used only while an agent is AWAITING the user. NOT used for "working":
+ * a battery e-ink panel deep-sleeps between polls and full-flashes the screen on
+ * every refresh, so we only tighten the loop when the user actually needs to act.
+ */
+export const TRMNL_DEFAULT_REFRESH_ACTIVE = 60;
+/** Floor on any cadence — too-frequent polls drain the panel battery + flash it. */
+export const TRMNL_MIN_REFRESH = 30;
+/**
+ * Seconds the firmware waits for the image download before giving up (its
+ * `image_url_timeout`). Generous so a slow/flaky WiFi link doesn't trip the
+ * device's "not responding" (WIFI_FAILED) screen. Firmware caps at ~65s, so we
+ * keep a healthy default (most "not responding" cycles are a lossy image GET
+ * timing out, not a server error — see docs/devices.md TRMNL section).
+ */
+export const TRMNL_DEFAULT_IMAGE_TIMEOUT = 50;
+/** Hard cap the firmware honors (it clamps `image_url_timeout` ~65s internally). */
+export const TRMNL_MAX_IMAGE_TIMEOUT = 65;
+/**
+ * RSSI (dBm) at or below which the panel's WiFi link is treated as weak/lossy.
+ * A weak link is the dominant real-world cause of "not responding" (WIFI_FAILED):
+ * the image download drops packets and times out. RSSI is sent by the firmware on
+ * every poll, so we can react per-poll. (-78 ≈ marginal; below it, retransmits
+ * stack up and the default window can be too tight.)
+ */
+export const TRMNL_WEAK_RSSI_DBM = -78;
+/** Image-download window served on a weak link — near the firmware cap. */
+export const TRMNL_WEAK_LINK_IMAGE_TIMEOUT = 60;
+/**
+ * Cadence for a poll. We only speed up for AWAITING (the user needs to act);
+ * "working" stays on the slow cadence because a deep-sleep e-ink panel can't be
+ * pushed and each wake full-flashes the screen + costs battery.
+ */
+export function effectiveRefreshRate(cfg, activity) {
+    return Math.max(TRMNL_MIN_REFRESH, activity.awaiting > 0 ? cfg.refreshActive : cfg.refreshRate);
+}
+/**
+ * Image-download timeout (seconds) for a single poll. Widens toward the firmware
+ * cap when the panel reports a weak WiFi signal, so a lossy image GET still has
+ * the maximum window to finish before the firmware shows "not responding"
+ * (WIFI_FAILED) — the #1 source of TRMNL flicker on a marginal link. A strong link
+ * keeps the lower default so a genuinely dead link doesn't hold the radio on
+ * (battery). RSSI absent (older firmware) ⇒ default; the default itself is already
+ * generous. Clamped to [5, firmware cap].
+ */
+export function effectiveImageTimeout(cfg, opts = {}) {
+    let t = cfg.imageUrlTimeout;
+    if (opts.rssi != null && Number.isFinite(opts.rssi) && opts.rssi <= TRMNL_WEAK_RSSI_DBM) {
+        t = Math.max(t, TRMNL_WEAK_LINK_IMAGE_TIMEOUT);
+    }
+    return Math.min(TRMNL_MAX_IMAGE_TIMEOUT, Math.max(5, Math.floor(t)));
+}
+function readSettings() {
+    try {
+        return JSON.parse(readFileSync(settingsPath(), 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeSettings(settings) {
+    mkdirSync(settingsDir(), { recursive: true });
+    writeFileSync(settingsPath(), JSON.stringify(settings, null, 2) + '\n');
+}
+/** Load the trmnl config with defaults filled in. */
+export function loadTrmnlConfig() {
+    const raw = (readSettings().trmnl ?? {});
+    const refreshRate = typeof raw.refreshRate === 'number' && raw.refreshRate >= 5 ? Math.floor(raw.refreshRate) : TRMNL_DEFAULT_REFRESH;
+    const refreshActive = typeof raw.refreshActive === 'number' && raw.refreshActive >= 5
+        ? Math.floor(raw.refreshActive)
+        : TRMNL_DEFAULT_REFRESH_ACTIVE;
+    const imageUrlTimeout = typeof raw.imageUrlTimeout === 'number' && raw.imageUrlTimeout > 0
+        ? Math.min(TRMNL_MAX_IMAGE_TIMEOUT, Math.floor(raw.imageUrlTimeout))
+        : TRMNL_DEFAULT_IMAGE_TIMEOUT;
+    return {
+        enabled: raw.enabled === true,
+        refreshRate,
+        refreshActive,
+        imageUrlTimeout,
+        autoRegister: raw.autoRegister !== false, // default on
+        devices: Array.isArray(raw.devices) ? raw.devices.filter((d) => d && typeof d.mac === 'string') : [],
+    };
+}
+function saveTrmnlConfig(cfg) {
+    const settings = readSettings();
+    settings.trmnl = cfg;
+    writeSettings(settings);
+}
+/**
+ * Normalize a MAC to a stable identity key. A canonical 12-hex address becomes
+ * uppercase colon-separated pairs; any other id (some firmware/cloud setups
+ * report non-standard or punctuated identifiers) collapses to its bare uppercase
+ * hex digits. Returning the raw, untrimmed string for the odd case would orphan
+ * or duplicate a device whose punctuation varies between polls — so we always
+ * derive a deterministic key from the hex content.
+ */
+export function normalizeMac(mac) {
+    const hex = (mac || '').replace(/[^0-9a-fA-F]/g, '').toUpperCase();
+    if (hex.length === 12)
+        return hex.match(/.{2}/g).join(':');
+    return hex || (mac || '').trim().toUpperCase();
+}
+/** True when two MAC spellings resolve to the same canonical identity. */
+export function sameMac(a, b) {
+    return normalizeMac(a) === normalizeMac(b);
+}
+export function findDeviceByMac(mac) {
+    return loadTrmnlConfig().devices.find((d) => sameMac(d.mac, mac));
+}
+function genFriendlyId() {
+    // 6 chars from an unambiguous base32 alphabet (no 0/1/O/I).
+    const alphabet = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789';
+    const bytes = randomBytes(6);
+    let out = '';
+    for (let i = 0; i < 6; i++)
+        out += alphabet[bytes[i] % alphabet.length];
+    return out;
+}
+/**
+ * Find or create a device record for the given MAC. Returns the device and
+ * whether it was newly created. Respects `autoRegister`: when off, a new MAC
+ * is NOT persisted and `created` is false with `device` undefined.
+ */
+export function ensureDevice(mac, name) {
+    const cfg = loadTrmnlConfig();
+    const norm = normalizeMac(mac);
+    const existing = cfg.devices.find((d) => sameMac(d.mac, mac));
+    if (existing)
+        return { device: existing, created: false };
+    if (!cfg.autoRegister)
+        return { created: false };
+    const device = {
+        mac: norm,
+        apiKey: randomBytes(16).toString('hex'),
+        friendlyId: genFriendlyId(),
+        name,
+    };
+    cfg.devices.push(device);
+    saveTrmnlConfig(cfg);
+    return { device, created: true };
+}
+export function removeDevice(mac) {
+    const cfg = loadTrmnlConfig();
+    const filtered = cfg.devices.filter((d) => !sameMac(d.mac, mac));
+    if (filtered.length === cfg.devices.length)
+        return false;
+    cfg.devices = filtered;
+    saveTrmnlConfig(cfg);
+    return true;
+}
+//# sourceMappingURL=trmnl-settings.js.map

package/dist/trmnl/trmnl-settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trmnl-settings.js","sourceRoot":"","sources":["../../src/trmnl/trmnl-settings.ts"],"names":[],"mappings":"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"}

package/dist/trmnl/trmnl-telemetry.d.ts

@@ -0,0 +1,47 @@
+export interface DeviceTelemetry {
+    /** Normalized MAC identity (matches TrmnlDevice.mac). */
+    mac: string;
+    fwVersion: string;
+    batteryVoltage: number | null;
+    rssi: number | null;
+    width: number | null;
+    height: number | null;
+    /** Cadence the device says it's polling at (we still dictate it on response). */
+    refreshRate: number | null;
+    userAgent: string;
+    /** Epoch ms of the most recent poll. */
+    lastSeen: number;
+}
+export interface TelemetryInput {
+    fwVersion?: string;
+    batteryVoltage?: number | null;
+    rssi?: number | null;
+    width?: number | null;
+    height?: number | null;
+    refreshRate?: number | null;
+    userAgent?: string;
+}
+/**
+ * Upsert the last-seen telemetry for a device. `now` is injected at the daemon
+ * boundary (defaults to wall clock) so layout/render code stays clock-free.
+ * Returns the previous `lastSeen` (epoch ms) so callers can detect poll gaps.
+ */
+export declare function recordTelemetry(mac: string, t: TelemetryInput, now?: number): number | null;
+/** Snapshot of all known device telemetry, most-recently-seen first. */
+export declare function getTelemetry(): DeviceTelemetry[];
+/** Telemetry plus derived freshness — `secondsSinceSeen` and a `stale` flag. */
+export interface DeviceHealth extends DeviceTelemetry {
+    secondsSinceSeen: number;
+    /** True when the panel hasn't polled in over 2× its expected cadence. */
+    stale: boolean;
+}
+/**
+ * Telemetry annotated with health. A panel that hasn't polled within 2× its
+ * cadence is flagged `stale` so the dashboard can distinguish "panel stuck /
+ * offline" from "nothing changed". `now`/`refreshRate` are injected at the daemon
+ * boundary so this stays clock- and config-free.
+ */
+export declare function getTelemetryHealth(refreshRate: number, now?: number): DeviceHealth[];
+/** Test helper — clear the runtime map. */
+export declare function _resetTelemetry(): void;
+//# sourceMappingURL=trmnl-telemetry.d.ts.map

package/dist/trmnl/trmnl-telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trmnl-telemetry.d.ts","sourceRoot":"","sources":["../../src/trmnl/trmnl-telemetry.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,eAAe;IAC9B,yDAAyD;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,iFAAiF;IACjF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAID;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,cAAc,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,GAAG,IAAI,CAgBvG;AAED,wEAAwE;AACxE,wBAAgB,YAAY,IAAI,eAAe,EAAE,CAEhD;AAED,gFAAgF;AAChF,MAAM,WAAW,YAAa,SAAQ,eAAe;IACnD,gBAAgB,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,YAAY,EAAE,CAMhG;AAED,2CAA2C;AAC3C,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}

package/dist/trmnl/trmnl-telemetry.js

@@ -0,0 +1,56 @@
+/**
+ * TRMNL device telemetry — a runtime-only, per-MAC snapshot of the headers a
+ * BYOS panel reports on each /api/setup or /api/display poll (firmware version,
+ * battery voltage, WiFi signal, panel resolution). This is NOT persisted to
+ * settings.json: polls arrive every ~180s and writing the settings file on each
+ * one would thrash it and race the user's manual edits. The daemon status
+ * snapshot reads this map for diagnostics; it's lost on daemon restart, which is
+ * fine — the next poll repopulates it.
+ */
+import { normalizeMac } from './trmnl-settings.js';
+const telemetry = new Map();
+/**
+ * Upsert the last-seen telemetry for a device. `now` is injected at the daemon
+ * boundary (defaults to wall clock) so layout/render code stays clock-free.
+ * Returns the previous `lastSeen` (epoch ms) so callers can detect poll gaps.
+ */
+export function recordTelemetry(mac, t, now = Date.now()) {
+    const key = normalizeMac(mac);
+    if (!key)
+        return null;
+    const prevLastSeen = telemetry.get(key)?.lastSeen ?? null;
+    telemetry.set(key, {
+        mac: key,
+        fwVersion: t.fwVersion ?? '',
+        batteryVoltage: t.batteryVoltage ?? null,
+        rssi: t.rssi ?? null,
+        width: t.width ?? null,
+        height: t.height ?? null,
+        refreshRate: t.refreshRate ?? null,
+        userAgent: t.userAgent ?? '',
+        lastSeen: now,
+    });
+    return prevLastSeen;
+}
+/** Snapshot of all known device telemetry, most-recently-seen first. */
+export function getTelemetry() {
+    return [...telemetry.values()].sort((a, b) => b.lastSeen - a.lastSeen);
+}
+/**
+ * Telemetry annotated with health. A panel that hasn't polled within 2× its
+ * cadence is flagged `stale` so the dashboard can distinguish "panel stuck /
+ * offline" from "nothing changed". `now`/`refreshRate` are injected at the daemon
+ * boundary so this stays clock- and config-free.
+ */
+export function getTelemetryHealth(refreshRate, now = Date.now()) {
+    const staleAfterMs = Math.max(30, refreshRate) * 2 * 1000;
+    return getTelemetry().map((t) => {
+        const ageMs = now - t.lastSeen;
+        return { ...t, secondsSinceSeen: Math.round(ageMs / 1000), stale: ageMs > staleAfterMs };
+    });
+}
+/** Test helper — clear the runtime map. */
+export function _resetTelemetry() {
+    telemetry.clear();
+}
+//# sourceMappingURL=trmnl-telemetry.js.map

package/dist/trmnl/trmnl-telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trmnl-telemetry.js","sourceRoot":"","sources":["../../src/trmnl/trmnl-telemetry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AA2BnD,MAAM,SAAS,GAAG,IAAI,GAAG,EAA2B,CAAC;AAErD;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,CAAiB,EAAE,MAAc,IAAI,CAAC,GAAG,EAAE;IACtF,MAAM,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,MAAM,YAAY,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,QAAQ,IAAI,IAAI,CAAC;IAC1D,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE;QACjB,GAAG,EAAE,GAAG;QACR,SAAS,EAAE,CAAC,CAAC,SAAS,IAAI,EAAE;QAC5B,cAAc,EAAE,CAAC,CAAC,cAAc,IAAI,IAAI;QACxC,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,IAAI;QACpB,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI;QACtB,MAAM,EAAE,CAAC,CAAC,MAAM,IAAI,IAAI;QACxB,WAAW,EAAE,CAAC,CAAC,WAAW,IAAI,IAAI;QAClC,SAAS,EAAE,CAAC,CAAC,SAAS,IAAI,EAAE;QAC5B,QAAQ,EAAE,GAAG;KACd,CAAC,CAAC;IACH,OAAO,YAAY,CAAC;AACtB,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,YAAY;IAC1B,OAAO,CAAC,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;AACzE,CAAC;AASD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAAmB,EAAE,MAAc,IAAI,CAAC,GAAG,EAAE;IAC9E,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,WAAW,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IAC1D,OAAO,YAAY,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC9B,MAAM,KAAK,GAAG,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC;QAC/B,OAAO,EAAE,GAAG,CAAC,EAAE,gBAAgB,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,GAAG,YAAY,EAAE,CAAC;IAC3F,CAAC,CAAC,CAAC;AACL,CAAC;AAED,2CAA2C;AAC3C,MAAM,UAAU,eAAe;IAC7B,SAAS,CAAC,KAAK,EAAE,CAAC;AACpB,CAAC"}