@kiosko/core 0.1.0 → 0.2.1

package/dist/devices.js

@@ -3,16 +3,21 @@
  *
  *   virtual  only the editor shows it (no hardware, demos, development)
  *   trcc     `trcc serve` REST API (thermalright-trcc-linux), via @loksly/trcc-client
+ *   usb      straight over USB from Node, via @loksly/usb-ly (LY panels)
  *   file     writes `frame.jpg` atomically for an external sender (e.g. a USB
  *            sender bound to a serial number, for several identical panels)
  */
 import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { LyPanel, MAX_FRAME_BYTES, findPanels, loadUsb, modelFor } from '@loksly/usb-ly';
 import { connectPanel, detectPanel, pinFrame, sendFrame, serverAlive } from '@loksly/trcc-client';
 import { expandPath } from "./paths.js";
 export function encodeFor(device, jpegQuality) {
     if (device.driver === 'file')
         return device.format ?? 'jpeg';
+    // The LY firmware only takes JPEG.
+    if (device.driver === 'usb')
+        return 'jpeg';
     return jpegQuality > 0 ? 'jpeg' : 'png';
 }
 class VirtualDevice {
@@ -23,6 +28,25 @@ class VirtualDevice {
     }
     close() { }
 }
+/**
+ * `rename` over a file another process has open fails on Windows with
+ * EPERM/EBUSY/EACCES (the sender is reading it right now): it passes in a few
+ * milliseconds, so try again a few times before giving up.
+ */
+export async function renameReplacing(from, to, rename = renameSync, tries = 8) {
+    for (let i = 1;; i++) {
+        try {
+            rename(from, to);
+            return;
+        }
+        catch (err) {
+            const code = err.code;
+            if (i >= tries || !(code === 'EPERM' || code === 'EBUSY' || code === 'EACCES'))
+                throw err;
+            await new Promise((r) => setTimeout(r, 5 * i));
+        }
+    }
+}
 class FileDevice {
     status;
     dir;
@@ -36,7 +60,7 @@ class FileDevice {
             const tmp = join(this.dir, '.frame.tmp');
             writeFileSync(tmp, frame);
             // Atomic: the sender never reads half a JPEG.
-            renameSync(tmp, join(this.dir, 'frame.jpg'));
+            await renameReplacing(tmp, join(this.dir, 'frame.jpg'));
             this.status.ok = true;
             this.status.framesSent++;
             this.status.lastSentAt = Date.now();
@@ -97,10 +121,163 @@ class TrccDevice {
         this.stopPin?.();
     }
 }
-export function openDevice(cfg, log) {
+/**
+ * A panel over USB, owned by this process. Two things the firmware asks for:
+ * a new frame goes out as soon as it exists, and an unchanged one is sent
+ * again every `keepalive` seconds, or the panel falls back to the factory logo
+ * after 2-3 s. A bus error drops the connection and reconnects with a growing
+ * pause; a panel with the configured serial number that is not there is
+ * waited for, never replaced by another one.
+ */
+export class UsbDevice {
+    status = { driver: 'usb', ok: false, message: 'connecting…', framesSent: 0, lastSentAt: null };
+    cfg;
+    log;
+    rotate;
+    open;
+    retryMs;
+    panel = null;
+    latest = null;
+    fresh = false;
+    lastWrite = 0;
+    retryAt = 0;
+    failures = 0;
+    closed = false;
+    pumping = null;
+    timer = null;
+    lastMessage = '';
+    constructor(cfg, log, o = {}) {
+        this.cfg = cfg;
+        this.log = log;
+        this.rotate = o.rotate;
+        this.open = o.open ?? ((serial) => LyPanel.open(serial ? { serial } : {}));
+        this.retryMs = o.retryMs ?? 1000;
+        const every = Math.round(Math.min(2, Math.max(0.1, cfg.keepalive ?? 1)) * 1000);
+        this.timer = setInterval(() => void this.pump(), Math.min(every, 250));
+        this.timer.unref();
+    }
+    say(message, ok) {
+        this.status.ok = ok;
+        this.status.message = message;
+        if (message !== this.lastMessage) {
+            this.lastMessage = message;
+            this.log(message);
+        }
+    }
+    due(now) {
+        return now - this.lastWrite >= Math.min(2, Math.max(0.1, this.cfg.keepalive ?? 1)) * 1000;
+    }
+    /** Writes what is pending; concurrent callers share one run. */
+    pump() {
+        if (this.pumping)
+            return this.pumping;
+        const run = async () => {
+            while (!this.closed && this.latest && Date.now() >= this.retryAt && (this.fresh || this.due(Date.now()))) {
+                try {
+                    const frame = this.latest;
+                    this.fresh = false;
+                    if (!this.panel)
+                        await this.connect();
+                    const kept = await this.panel.send(frame);
+                    this.lastWrite = Date.now();
+                    this.failures = 0;
+                    this.status.framesSent++;
+                    this.status.lastSentAt = this.lastWrite;
+                    if (!kept)
+                        this.say(`the panel dropped a ${Math.round(frame.length / 1024)} KB frame (limit ${Math.round(MAX_FRAME_BYTES / 1024)} KB): lower the JPEG quality`, false);
+                    else if (!this.status.ok)
+                        this.say(this.describe(), true);
+                }
+                catch (err) {
+                    this.fresh = true; // a reconnected panel has nothing on it
+                    const p = this.panel;
+                    this.panel = null;
+                    void p?.close().catch(() => undefined);
+                    this.failures++;
+                    this.retryAt = Date.now() + Math.min(30 * this.retryMs, this.retryMs * 2 ** Math.min(this.failures, 5));
+                    const why = err instanceof Error ? err.message : String(err);
+                    this.say(`${why}${this.cfg.serial && !why.includes(this.cfg.serial) ? ` (serial ${this.cfg.serial})` : ''}; retrying`, false);
+                }
+            }
+        };
+        this.pumping = run().finally(() => (this.pumping = null));
+        return this.pumping;
+    }
+    describe() {
+        const i = this.panel?.info;
+        if (!i)
+            return 'usb';
+        return `usb ${i.serial ?? i.location ?? ''} PM ${i.pm} SUB ${i.sub}${i.model ? ` ${i.model.width}×${i.model.height}` : ''}`.replace(/\s+/g, ' ');
+    }
+    async connect() {
+        const panel = await this.open(this.cfg.serial);
+        this.panel = panel;
+        const m = panel.info?.model;
+        if (m) {
+            this.status.detected = { width: m.width, height: m.height };
+            // The picture is turned in the compositor, before encoding: the firmware's mount angle must match the screen's.
+            if (this.rotate !== undefined && m.rotate !== this.rotate)
+                this.log(`the panel's firmware expects rotation ${m.rotate}° but this screen has ${this.rotate}°: the picture may come out turned`);
+        }
+        this.say(this.describe(), true);
+    }
+    async send(frame) {
+        this.latest = frame;
+        this.fresh = true;
+        await this.pump();
+    }
+    close() {
+        this.closed = true;
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        const p = this.panel;
+        this.panel = null;
+        void p?.close().catch(() => undefined);
+    }
+}
+/** The LY panels libusb sees (serial and where), without claiming any: for `kiosko doctor`. */
+export async function listUsb() {
+    try {
+        const found = await findPanels(await loadUsb());
+        return { ok: true, panels: found.map((f) => ({ ...(f.serial ? { serial: f.serial } : {}), pid: f.pid, location: f.location, ...(f.error ? { error: f.error } : {}) })) };
+    }
+    catch (err) {
+        return { ok: false, panels: [], error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** The LY panels libusb sees right now, for the "add screen" menu. Never throws. */
+export async function discoverUsb() {
+    try {
+        const found = await findPanels(await loadUsb());
+        const out = [];
+        for (const f of found) {
+            // The resolution needs the hello, which needs the device: only if no other process has it.
+            let model;
+            if (f.serial) {
+                try {
+                    const p = await LyPanel.open({ serial: f.serial });
+                    model = p.info?.model;
+                    await p.close();
+                }
+                catch {
+                    /* held by another process, or no driver: listed anyway */
+                }
+            }
+            out.push({ serial: f.serial ?? '', key: f.serial ?? `usb ${f.location}`, width: model?.width ?? 0, height: model?.height ?? 0, location: f.location, ...(f.error ? { error: f.error } : {}) });
+        }
+        return out;
+    }
+    catch {
+        return [];
+    }
+}
+export function openDevice(cfg, log, rotate) {
     switch (cfg.driver) {
         case 'trcc':
             return new TrccDevice(cfg, log);
+        case 'usb':
+            return new UsbDevice(cfg, log, rotate === undefined ? {} : { rotate });
         case 'file':
             return new FileDevice(cfg);
         default:

package/dist/env.js

@@ -24,9 +24,25 @@ export function resolveLocale(cfg) {
 export function baseContext(cfg, plugin, log, now) {
     let made = false;
     const dir = paths.data(plugin);
+    const cache = paths.cache(plugin);
+    let cacheMade = false;
     const base = createBaseContext({ now, locale: resolveLocale(cfg), timeFormat: cfg.timeFormat, workday: cfg.workday, ...(cfg.location ? { location: cfg.location } : {}), log: (msg) => log(plugin, msg) });
     return {
         ...base,
+        get cacheDir() {
+            if (!cache)
+                return this.dataDir;
+            if (!cacheMade) {
+                try {
+                    mkdirSync(cache, { recursive: true });
+                }
+                catch {
+                    return this.dataDir;
+                }
+                cacheMade = true;
+            }
+            return cache;
+        },
         get dataDir() {
             if (!made) {
                 try {

package/dist/fsperm.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Makes `path` readable by its owner only: mode 0600, or, on Windows (where
+ * `chmod` can't do it), an ACL without inheritance that grants just the
+ * current user. Best effort: a file system without permissions (FAT, some
+ * network shares) just keeps what it has.
+ */
+export declare function restrictToOwner(path: string, os?: NodeJS.Platform): void;

package/dist/fsperm.js

@@ -0,0 +1,23 @@
+import { execFileSync } from 'node:child_process';
+import { chmodSync } from 'node:fs';
+import { userInfo } from 'node:os';
+/**
+ * Makes `path` readable by its owner only: mode 0600, or, on Windows (where
+ * `chmod` can't do it), an ACL without inheritance that grants just the
+ * current user. Best effort: a file system without permissions (FAT, some
+ * network shares) just keeps what it has.
+ */
+export function restrictToOwner(path, os = process.platform) {
+    try {
+        if (os !== 'win32') {
+            chmodSync(path, 0o600);
+            return;
+        }
+        const user = process.env.USERNAME || userInfo().username;
+        const domain = process.env.USERDOMAIN;
+        execFileSync('icacls', [path, '/inheritance:r', '/grant:r', `${domain ? `${domain}\\` : ''}${user}:F`], { stdio: 'ignore', windowsHide: true, timeout: 5000 });
+    }
+    catch {
+        /* best effort */
+    }
+}

package/dist/index.d.ts

@@ -14,3 +14,5 @@ export * from './devices.ts';
 export * from './fonts.ts';
 export * from './paths.ts';
 export * from './env.ts';
+export * from './fsperm.ts';
+export * from './sdk-resolver.ts';

package/dist/index.js

@@ -14,3 +14,5 @@ export * from "./devices.js";
 export * from "./fonts.js";
 export * from "./paths.js";
 export * from "./env.js";
+export * from "./fsperm.js";
+export * from "./sdk-resolver.js";

package/dist/paths.d.ts

@@ -1,11 +1,18 @@
+import { expandPath } from '@kiosko/sdk';
 export declare function kioskoHome(): string;
 export declare const paths: {
     readonly home: string;
     readonly config: string;
     /** External plugins: one folder (or npm package) per plugin. */
     readonly plugins: string;
-    /** Per-plugin caches: `data/<plugin>`. */
+    /**
+     * Per-plugin re-fetchable caches, in RAM: `$XDG_RUNTIME_DIR/kiosko-cache/<plugin>`
+     * (or `/dev/shm/kiosko-cache-<uid>/<plugin>`). Null where there is no tmpfs.
+     * On Windows there is none, but the cache belongs in the machine-local
+     * profile (`%LOCALAPPDATA%\\Kiosko\\cache`), not in the roaming one `data/` uses.
+     */
+    cache(plugin: string): string | null;
+    /** Per-plugin data that must persist: `data/<plugin>`. */
     data(plugin: string): string;
 };
-/** `~/x` and `$VAR`/`${VAR}` expanded. */
-export declare function expandPath(p: string): string;
+export { expandPath };

package/dist/paths.js

@@ -1,3 +1,4 @@
+import { existsSync } from 'node:fs';
 /**
  * Where Kiosko keeps its things, per platform:
  *   Linux   $XDG_CONFIG_HOME/kiosko  (~/.config/kiosko)
@@ -6,6 +7,7 @@
  * `KIOSKO_HOME` overrides all of them (tests, portable installs).
  */
 import { homedir, platform } from 'node:os';
+import { expandPath } from '@kiosko/sdk';
 import { join } from 'node:path';
 export function kioskoHome() {
     if (process.env.KIOSKO_HOME)
@@ -31,13 +33,21 @@ export const paths = {
     get plugins() {
         return join(kioskoHome(), 'plugins');
     },
-    /** Per-plugin caches: `data/<plugin>`. */
+    /**
+     * Per-plugin re-fetchable caches, in RAM: `$XDG_RUNTIME_DIR/kiosko-cache/<plugin>`
+     * (or `/dev/shm/kiosko-cache-<uid>/<plugin>`). Null where there is no tmpfs.
+     * On Windows there is none, but the cache belongs in the machine-local
+     * profile (`%LOCALAPPDATA%\\Kiosko\\cache`), not in the roaming one `data/` uses.
+     */
+    cache(plugin) {
+        if (platform() === 'win32')
+            return join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'Kiosko', 'cache', plugin.replace(/[^a-z0-9._-]/gi, '_'));
+        const base = process.env.XDG_RUNTIME_DIR && existsSync(process.env.XDG_RUNTIME_DIR) ? join(process.env.XDG_RUNTIME_DIR, 'kiosko-cache') : existsSync('/dev/shm') ? `/dev/shm/kiosko-cache-${process.getuid?.() ?? 'u'}` : null;
+        return base && join(base, plugin.replace(/[^a-z0-9._-]/gi, '_'));
+    },
+    /** Per-plugin data that must persist: `data/<plugin>`. */
     data(plugin) {
         return join(kioskoHome(), 'data', plugin.replace(/[^a-z0-9._-]/gi, '_'));
     },
 };
-/** `~/x` and `$VAR`/`${VAR}` expanded. */
-export function expandPath(p) {
-    const v = p.replace(/\$(?:\{(\w+)\}|(\w+))/g, (whole, a, b) => process.env[a ?? b ?? ''] ?? whole);
-    return v === '~' || v.startsWith('~/') ? join(homedir(), v.slice(1)) : v;
-}
+export { expandPath };

package/dist/runtime.d.ts

@@ -11,6 +11,7 @@
  */
 import { EventEmitter } from 'node:events';
 import { type Theme } from '@kiosko/sdk';
+import type { Canvas } from '@napi-rs/canvas';
 import { type ComposeResult } from './compositor.ts';
 import { type Config, type Page, type Screen } from './config/model.ts';
 import { FetchHost, SourceHub } from './data.ts';
@@ -34,8 +35,21 @@ export interface FrameInfo {
     image: () => Buffer;
     tiles: ComposeResult['tiles'];
     interlude: string | null;
+    /** Type of the widget whose animation is playing (a frame of it), if any. */
+    animation?: string;
     sleeping: boolean;
 }
+/**
+ * Encodes a frame no bigger than `maxBytes`: when the JPEG at `quality` is
+ * over it, tries lower qualities (10 at a time, down to 20) until one fits.
+ * LY panels drop frames over ~500 KB and keep showing the previous one, so a
+ * photo-heavy page at quality 100 looked frozen. `over` says nothing fitted.
+ */
+export declare function encodeFit(c: Canvas, kind: 'png' | 'jpeg', quality: number, maxBytes: number): {
+    out: Buffer;
+    quality: number;
+    over: boolean;
+};
 export declare class Runtime extends EventEmitter {
     config: Config;
     readonly hub: SourceHub;
@@ -43,6 +57,10 @@ export declare class Runtime extends EventEmitter {
     private runners;
     private timer;
     readonly logs: LogEntry[];
+    /** How many animations play together on a screen (see animation.ts). */
+    maxConcurrent: number;
+    /** Random numbers for the animations; tests replace it with a seeded one. */
+    rnd: () => number;
     readonly registry: Registry;
     /**
      * Demo mode: no source or fetch runs, every widget paints its sample data.
@@ -78,6 +96,7 @@ export declare class Runtime extends EventEmitter {
             page: string | null;
             pinned: string | null;
             interlude: string | null;
+            animation: string | null;
             device: DeviceStatus;
             lastFrameAt: number | null;
             sleeping: boolean;