@kiosko/core 0.1.0 → 0.2.1

package/dist/animation.d.ts

@@ -0,0 +1,60 @@
+/**
+ * When a widget's animation plays. The planning is here, apart from the
+ * painting and the sending (runtime.ts), so it can be tested without a
+ * screen: which shown widget is asked, and why (`idle`, now and then, or
+ * `data`, because what it paints with changed), and what the answer is worth.
+ *
+ * One animation at a time per screen is the caller's business (it asks
+ * only while nothing plays); what is kept here is per widget instance: when
+ * it was last asked, when its last animation ended and what it had then.
+ */
+import type { AnimationPlan } from '@kiosko/sdk';
+import type { Animatable } from './compositor.ts';
+/** The most frames one animation may have: 30 s at 20 fps. A wrong plan must not eat the CPU. */
+export declare const MAX_FRAMES = 600;
+/**
+ * How many animations the runtime plays together on a screen. Widgets don't
+ * know: every one asks as if it were alone, and what doesn't fit waits its
+ * turn. The whole chain (planner, compositor, player) works for any number;
+ * one is what the panel's USB budget is sized for.
+ */
+export declare const MAX_CONCURRENT = 1;
+/** Default time between the `idle` questions of a widget. */
+export declare const DEFAULT_GAP: {
+    minMs: number;
+    maxMs: number;
+};
+/** A plan as the runtime plays it: checked, with the screen's fps ceiling applied. */
+export interface PlayablePlan {
+    plan: AnimationPlan;
+    frames: number;
+    fps: number;
+    interruptible: boolean;
+    /** Index (into 0..frames-1) where it holds, and for how long. */
+    hold?: {
+        index: number;
+        ms: number;
+    };
+}
+/** Why a plan isn't playable, or the plan ready to play. */
+export declare function checkPlan(plan: unknown, maxFps: number): PlayablePlan | string;
+export declare class AnimationScheduler {
+    private memory;
+    private readonly rnd;
+    private readonly onInvalid;
+    constructor(rnd?: () => number, onInvalid?: (type: string, why: string) => void);
+    private gapAfter;
+    /**
+     * The animations to play now, up to `limit`, among the shown widgets that
+     * have one. Call it only while nothing is playing. A widget seen for the
+     * first time isn't asked: starting up must not set off a gesture. When more
+     * are due than fit, the one that has waited longest goes first (the order
+     * of the page doesn't decide), so none starves.
+     */
+    next(list: Animatable[], now: number, maxFps: number, limit?: number): {
+        animatable: Animatable;
+        play: PlayablePlan;
+    }[];
+    /** An animation of `instanceId` has just ended (or was cut): its cooldown starts. */
+    ended(instanceId: string, now: number, a?: Animatable): void;
+}

package/dist/animation.js

@@ -0,0 +1,111 @@
+/** The most frames one animation may have: 30 s at 20 fps. A wrong plan must not eat the CPU. */
+export const MAX_FRAMES = 600;
+/**
+ * How many animations the runtime plays together on a screen. Widgets don't
+ * know: every one asks as if it were alone, and what doesn't fit waits its
+ * turn. The whole chain (planner, compositor, player) works for any number;
+ * one is what the panel's USB budget is sized for.
+ */
+export const MAX_CONCURRENT = 1;
+/** Default time between the `idle` questions of a widget. */
+export const DEFAULT_GAP = { minMs: 20_000, maxMs: 60_000 };
+/** Why a plan isn't playable, or the plan ready to play. */
+export function checkPlan(plan, maxFps) {
+    const p = plan;
+    if (!p || typeof p !== 'object')
+        return 'not an object';
+    if (typeof p.id !== 'string' || !p.id)
+        return 'no id';
+    if (!Number.isInteger(p.frames) || p.frames < 3)
+        return `frames must be an integer of at least 3 (got ${String(p.frames)})`;
+    if (p.frames > MAX_FRAMES)
+        return `too many frames (${p.frames}, at most ${MAX_FRAMES})`;
+    if (typeof p.fps !== 'number' || !(p.fps > 0))
+        return `fps must be positive (got ${String(p.fps)})`;
+    const frames = p.frames;
+    const hold = p.hold && Number.isFinite(p.hold.at) && p.hold.ms > 0 ? { index: Math.max(1, Math.min(frames - 2, Math.round(p.hold.at * (frames - 1)))), ms: p.hold.ms } : undefined;
+    return { plan: p, frames, fps: Math.max(1, Math.min(p.fps, maxFps)), interruptible: p.interruptible !== false, ...(hold ? { hold } : {}) };
+}
+export class AnimationScheduler {
+    memory = new Map();
+    rnd;
+    onInvalid;
+    constructor(rnd = Math.random, onInvalid = () => undefined) {
+        this.rnd = rnd;
+        this.onInvalid = onInvalid;
+    }
+    gapAfter(a, now) {
+        const g = a.def.animationGap ?? DEFAULT_GAP;
+        const min = Math.max(0, g.minMs), max = Math.max(min, g.maxMs);
+        return now + min + this.rnd() * (max - min);
+    }
+    /**
+     * The animations to play now, up to `limit`, among the shown widgets that
+     * have one. Call it only while nothing is playing. A widget seen for the
+     * first time isn't asked: starting up must not set off a gesture. When more
+     * are due than fit, the one that has waited longest goes first (the order
+     * of the page doesn't decide), so none starves.
+     */
+    next(list, now, maxFps, limit = MAX_CONCURRENT) {
+        const seen = new Set();
+        const due = [];
+        for (const a of list) {
+            seen.add(a.instanceId);
+            const m = this.memory.get(a.instanceId);
+            if (!m) {
+                this.memory.set(a.instanceId, { data: a.data, sources: a.sources, nextIdleAt: this.gapAfter(a, now), endedAt: -Infinity, dueSince: Infinity });
+                continue;
+            }
+            const changed = a.data !== m.data || Object.keys(a.sources).some((k) => a.sources[k] !== m.sources[k]);
+            const prev = m.pending ?? { data: m.data, sources: m.sources };
+            m.data = a.data;
+            m.sources = a.sources;
+            if ((changed || m.pending) && now - m.endedAt >= (a.def.animationCooldownMs ?? 0)) {
+                m.pending = prev;
+                due.push({ a, m, trigger: 'data', prev });
+            }
+            else if (now >= m.nextIdleAt)
+                due.push({ a, m, trigger: 'idle', prev });
+        }
+        // Forget the instances that are gone (removed, or no longer shown).
+        for (const id of this.memory.keys())
+            if (!seen.has(id))
+                this.memory.delete(id);
+        // Who has waited longest first; a tie keeps the page's order.
+        for (const d of due)
+            d.m.dueSince = Math.min(d.m.dueSince, d.trigger === 'data' ? now : d.m.nextIdleAt);
+        due.sort((x, y) => x.m.dueSince - y.m.dueSince);
+        const out = [];
+        for (const { a, m, trigger, prev } of due) {
+            if (out.length >= limit)
+                break;
+            if (trigger === 'idle')
+                m.nextIdleAt = this.gapAfter(a, now);
+            else
+                m.pending = undefined;
+            const plan = a.ask(trigger, this.rnd, trigger === 'data' ? prev : undefined);
+            if (plan === null) {
+                m.dueSince = Infinity;
+                continue;
+            }
+            const ok = checkPlan(plan, maxFps);
+            if (typeof ok === 'string') {
+                this.onInvalid(a.type, ok);
+                m.dueSince = Infinity;
+                continue;
+            }
+            out.push({ animatable: a, play: ok });
+        }
+        return out;
+    }
+    /** An animation of `instanceId` has just ended (or was cut): its cooldown starts. */
+    ended(instanceId, now, a) {
+        const m = this.memory.get(instanceId);
+        if (!m)
+            return;
+        m.endedAt = now;
+        m.dueSince = Infinity;
+        if (a)
+            m.nextIdleAt = Math.max(m.nextIdleAt, this.gapAfter(a, now));
+    }
+}

package/dist/compositor.d.ts

@@ -5,7 +5,7 @@
  * go through here and can't disagree.
  */
 import { type Canvas, type SKRSContext2D } from '@napi-rs/canvas';
-import { type Theme, type WidgetDefinition } from '@kiosko/sdk';
+import { type AnimationFrame, type AnimationPlan, type Box, type Theme, type WidgetDefinition } from '@kiosko/sdk';
 import { type PxRect } from './layout/grid.ts';
 import { type Config, type Page, type Screen, type Tile, type WidgetInstance } from './config/model.ts';
 import { type LogFn } from './env.ts';
@@ -35,6 +35,35 @@ export interface ComposeInput {
     noShift?: boolean;
     /** Reuse tiles whose inputs didn't change (the panel; not previews). */
     cache?: TileCache;
+    /**
+     * Paint these frames of animations, each in its own tile (see
+     * `AnimationFrame`); every other tile as usual. Any number at once: how
+     * many the runtime plays together is its decision (`MAX_CONCURRENT`).
+     */
+    animate?: {
+        tileId: string;
+        instanceId: string;
+        frame: AnimationFrame;
+    }[];
+}
+/**
+ * A widget on screen that has an `animation` hook: asks it, with the state
+ * the page was painted with. The runtime decides when to ask.
+ */
+export interface Animatable {
+    tileId: string;
+    instanceId: string;
+    type: string;
+    def: Pick<WidgetDefinition<any, any>, 'animationGap' | 'animationCooldownMs'>;
+    /** What the widget painted with, by reference (replaced, never mutated), to tell when it changed. */
+    data: unknown;
+    sources: Record<string, unknown>;
+    ask: (trigger: 'idle' | 'data', rnd: () => number, prev?: {
+        data: unknown;
+        sources: Record<string, unknown>;
+    }) => AnimationPlan | null;
+    /** Tells the widget an animation of its has ended (see `WidgetDefinition.animationEnded`). */
+    ended: (plan: AnimationPlan, completed: boolean) => void;
 }
 export interface TileResult {
     id: string;
@@ -50,6 +79,8 @@ export interface ComposeResult {
     idle: boolean;
     /** When something will change by itself (clock, rotation): next repaint. */
     nextAt: number;
+    /** The shown widgets that can animate. */
+    animatable: Animatable[];
 }
 /**
  * The instance's switches over the widget's hooks: `takeOver` (keep the tile
@@ -76,6 +107,16 @@ export type TileCache = Map<string, {
     canvas: Canvas;
     error?: string;
 }>;
+/**
+ * Where a widget paints inside its tile: `outer` is the area left by the
+ * card's padding and title, and `box` is what the widget sees: the same area
+ * `zoom` times smaller when zoomed (it keeps its top-left corner).
+ */
+export declare function tileBoxes(theme: Theme, screenH: number, inst: WidgetInstance, rect: PxRect, chrome: 'card' | 'bare'): {
+    outer: Box;
+    box: Box;
+    zoom: number;
+};
 /** Paints `page` on a new canvas of the screen size. */
 export declare function composePage(input: ComposeInput): ComposeResult;
 /** A canvas rotated for a panel mounted at `rotate` degrees. */

package/dist/compositor.js

@@ -116,7 +116,7 @@ function drawCard(g, rect, theme) {
     roundRect(g, rect.x + 0.5, rect.y + 0.5, rect.w - 1, rect.h - 1, theme.radius);
     g.stroke();
 }
-function paintTile(g, input, tile, rect, out, nextAt, idles) {
+function paintTile(g, input, tile, rect, out, nextAt, idles, animatable) {
     const { theme, now, working } = input;
     const candidates = tile.widgets
         .filter((w) => !w.disabled && whenMatches(w.when, working))
@@ -148,8 +148,26 @@ function paintTile(g, input, tile, rect, out, nextAt, idles) {
     const step = redrawStep(r.def, state);
     if (step)
         nextAt.v = Math.min(nextAt.v, (Math.floor(now / step) + 1) * step);
-    const draw = (tg) => drawTileContent(tg, input, r, rect, chrome, out);
-    if (!input.cache) {
+    const animation = r.def.animation;
+    if (animation && !input.preview) {
+        animatable.push({
+            tileId: tile.id,
+            instanceId: r.inst.id,
+            type: r.inst.type,
+            def: r.def,
+            data: r.data,
+            sources: r.sources,
+            ended: (plan, completed) => {
+                const [plugin] = r.inst.type.split('/');
+                safe(() => r.def.animationEnded?.({ ...baseContext(input.cfg, plugin, input.log ?? (() => undefined), input.now), options: r.options, plan, completed, data: r.data }), undefined);
+            },
+            ask: (trigger, rnd, prev) => safe(() => animation({ ...state, box: tileBoxes(theme, input.screen.height, r.inst, rect, chrome).box, trigger, rnd, ...(prev !== undefined ? { prev } : {}) }), null),
+        });
+    }
+    // The tile whose animation is being painted: this frame, never from or into the cache.
+    const frame = input.animate?.find((a) => a.tileId === tile.id && a.instanceId === r.inst.id)?.frame;
+    const draw = (tg) => drawTileContent(tg, input, r, rect, chrome, out, frame);
+    if (frame || !input.cache) {
         draw(g);
         return;
     }
@@ -172,27 +190,37 @@ function paintTile(g, input, tile, rect, out, nextAt, idles) {
     g.drawImage(canvas, rect.x, rect.y);
     input.cache.set(tile.id, { key, refs, canvas, ...(out.error ? { error: out.error } : {}) });
 }
-function drawTileContent(g, input, r, rect, chrome, out) {
+/**
+ * Where a widget paints inside its tile: `outer` is the area left by the
+ * card's padding and title, and `box` is what the widget sees: the same area
+ * `zoom` times smaller when zoomed (it keeps its top-left corner).
+ */
+export function tileBoxes(theme, screenH, inst, rect, chrome) {
+    const m = chromeMetrics(theme, screenH, rect);
+    const pad = chrome === 'card' ? m.pad : 0;
+    const top = rect.y + pad + (inst.title?.trim() && chrome === 'card' ? m.titleBar : 0);
+    const outer = { x: rect.x + pad, y: top, w: Math.max(1, rect.w - 2 * pad), h: Math.max(1, rect.y + rect.h - pad - top) };
+    // Zoom: the widget gets a box `zoom` times smaller and is painted `zoom`
+    // times bigger, so it fills the same space with bigger (or smaller) type.
+    // Its box keeps its top-left corner, so widgets see nothing unusual.
+    const zoom = zoomOf(inst);
+    const box = zoom === 1 ? outer : { x: outer.x, y: outer.y, w: Math.max(1, outer.w / zoom), h: Math.max(1, outer.h / zoom) };
+    return { outer, box, zoom };
+}
+function drawTileContent(g, input, r, rect, chrome, out, anim) {
     const { theme, now, working } = input;
     const m = chromeMetrics(theme, input.screen.height, rect);
     if (chrome === 'card')
         drawCard(g, rect, theme);
     const pad = chrome === 'card' ? m.pad : 0;
-    let top = rect.y + pad;
     const title = r.inst.title?.trim();
     if (title && chrome === 'card') {
         g.font = `${m.title}px "${theme.fonts.sans}"`;
         g.fillStyle = theme.colors.inkDim;
         g.textBaseline = 'alphabetic';
         g.fillText(fitText(g, title, rect.w - 2 * pad), rect.x + pad, rect.y + pad + m.title * 0.8);
-        top = rect.y + pad + m.titleBar;
     }
-    const outer = { x: rect.x + pad, y: top, w: Math.max(1, rect.w - 2 * pad), h: Math.max(1, rect.y + rect.h - pad - top) };
-    // Zoom: the widget gets a box `zoom` times smaller and is painted `zoom`
-    // times bigger, so it fills the same space with bigger (or smaller) type.
-    // Its box keeps its top-left corner, so widgets see nothing unusual.
-    const zoom = zoomOf(r.inst);
-    const box = zoom === 1 ? outer : { x: outer.x, y: outer.y, w: Math.max(1, outer.w / zoom), h: Math.max(1, outer.h / zoom) };
+    const { outer, box, zoom } = tileBoxes(theme, input.screen.height, r.inst, rect, chrome);
     const [plugin] = r.inst.type.split('/');
     const ctx = {
         ...baseContext(input.cfg, plugin, input.log ?? (() => undefined), now),
@@ -203,6 +231,7 @@ function drawTileContent(g, input, r, rect, chrome, out) {
         kit,
         canvas: CANVAS,
         preview: !!input.preview,
+        ...(anim ? { anim, frame: anim.i } : {}),
     };
     g.save();
     roundRect(g, rect.x, rect.y, rect.w, rect.h, chrome === 'card' ? theme.radius : 0);
@@ -243,11 +272,12 @@ export function composePage(input) {
     const nextAt = { v: Infinity };
     const idles = [];
     const tiles = [];
+    const animatable = [];
     for (const tile of page.tiles) {
         const rect = toPx(tile, page.grid, screen.width, screen.height);
         const out = { id: tile.id, rect, shown: null };
         tiles.push(out);
-        paintTile(g, input, tile, rect, out, nextAt, idles);
+        paintTile(g, input, tile, rect, out, nextAt, idles, animatable);
     }
     if (input.cache)
         for (const id of input.cache.keys())
@@ -256,7 +286,7 @@ export function composePage(input) {
     g.restore();
     if (screen.pixelShift.enabled && !input.preview)
         nextAt.v = Math.min(nextAt.v, (Math.floor(now / screen.pixelShift.periodMs) + 1) * screen.pixelShift.periodMs);
-    return { canvas, tiles, idle: idles.length > 0 && idles.every(Boolean), nextAt: nextAt.v };
+    return { canvas, tiles, idle: idles.length > 0 && idles.every(Boolean), nextAt: nextAt.v, animatable };
 }
 /** A canvas rotated for a panel mounted at `rotate` degrees. */
 export function rotateCanvas(src, rotate) {

package/dist/config/diff.js

@@ -35,7 +35,7 @@ const pageText = (p) => {
     const ts = pageTypes(p);
     return `page ${q(p.name)}: ${plural(p.tiles.length, 'tile')}${ts.length ? ` (${ts.slice(0, 6).join(', ')}${ts.length > 6 ? `, +${ts.length - 6} more` : ''})` : ''}`;
 };
-const deviceText = (d) => (d.driver === 'trcc' ? `trcc ${d.url}` : d.driver === 'file' ? `file ${d.dir}` : d.driver);
+const deviceText = (d) => (d.driver === 'trcc' ? `trcc ${d.url}` : d.driver === 'file' ? `file ${d.dir}` : d.driver === 'usb' ? `usb${d.serial ? ` ${d.serial}` : ''}` : d.driver);
 const changedKeys = (a, b) => [...new Set([...Object.keys(a), ...Object.keys(b)])].filter((k) => !same(a[k], b[k]));
 function diffTiles(before, after, depth, out) {
     const m = match(before.tiles, after.tiles, rect);

package/dist/config/model.d.ts

@@ -34,6 +34,12 @@ export type DeviceConfig = {
     serial?: string;
     keepalive?: boolean;
 }
+/** Straight over USB from Node (LY panels, Trofeo Vision…): no trcc, no Python. */
+ | {
+    driver: 'usb';
+    serial?: string;
+    keepalive?: number;
+}
 /** Writes `frame.jpg` atomically to `dir`; a sender (e.g. by USB serial) takes it to the panel. */
  | {
     driver: 'file';
@@ -136,9 +142,17 @@ export interface Screen {
     sleepWhenIdle: boolean;
     /** JPEG quality for photo-like pages; 0 = PNG. */
     jpegQuality: number;
+    /**
+     * Largest frame to send, in bytes; a bigger one is re-encoded at a lower
+     * JPEG quality until it fits. LY panels (Trofeo Vision and friends) silently
+     * drop frames over ~500 KB and keep showing the last one. 0 = no limit.
+     */
+    maxBytes: number;
     /** Frames per second ceiling for animations. */
     maxFps: number;
 }
+/** Default `maxBytes`: under the ~500 KB LY panels accept, with some margin. */
+export declare const DEFAULT_MAX_BYTES = 480000;
 export interface Config {
     /** JSON Schema of the file, for editors. Kept as written; `CONFIG_SCHEMA_ID` when missing. */
     $schema?: string;

package/dist/config/model.js

@@ -16,6 +16,8 @@ export function zoomOf(inst) {
         return 1;
     return Math.round(Math.min(ZOOM.max, Math.max(ZOOM.min, z)) * 100) / 100;
 }
+/** Default `maxBytes`: under the ~500 KB LY panels accept, with some margin. */
+export const DEFAULT_MAX_BYTES = 480_000;
 let counter = 0;
 /** Short unique id. Not crypto: only needs to be unique inside one config. */
 export function newId(prefix = 'id') {
@@ -46,6 +48,7 @@ export function newScreen(name, width = 1920, height = 462, device = { driver: '
         pixelShift: { enabled: true, amplitude: 2, periodMs: 8 * 60_000 },
         sleepWhenIdle: false,
         jpegQuality: 90,
+        maxBytes: DEFAULT_MAX_BYTES,
         maxFps: 12,
     };
 }

package/dist/config/normalize.js

@@ -6,7 +6,7 @@
 import { TIME_FORMATS } from '@kiosko/sdk/format';
 import { DEFAULT_WORKDAY } from '@kiosko/sdk/workday';
 import { suggestGrid } from "../layout/grid.js";
-import { CONFIG_VERSION, DEFAULT_CONFIG } from "./model.js";
+import { CONFIG_VERSION, DEFAULT_CONFIG, DEFAULT_MAX_BYTES } from "./model.js";
 /**
  * Fills gaps of a config written by hand or by an older version. Never throws.
  * The top-level shape it accepts is described, for other tools, by
@@ -56,6 +56,7 @@ function normalizeScreen(s, i) {
         pixelShift: { enabled: true, amplitude: 2, periodMs: 8 * 60_000, ...(s.pixelShift ?? {}) },
         sleepWhenIdle: s.sleepWhenIdle ?? false,
         jpegQuality: s.jpegQuality ?? 90,
+        maxBytes: Math.max(0, Math.round(s.maxBytes ?? DEFAULT_MAX_BYTES)),
         maxFps: s.maxFps ?? 12,
     };
 }

package/dist/config/schema.js

@@ -243,6 +243,18 @@ export function configSchema(plugins) {
                             keepalive: { type: 'boolean', default: true, description: 'Re-send the last frame now and then so the panel keeps it.' },
                         },
                     },
+                    {
+                        title: 'USB (LY panels)',
+                        description: 'Talks to the panel over USB from Kiosko itself (Thermalright Trofeo Vision and other LY panels): no trcc, no Python. On Windows the device needs the WinUSB driver; on Linux a udev rule.',
+                        type: 'object',
+                        additionalProperties: false,
+                        required: ['driver'],
+                        properties: {
+                            driver: { const: 'usb' },
+                            serial: { type: 'string', description: 'USB serial number of the panel. With several identical panels it is the only way to tell them apart, and a serial that is not found is an error, never "another panel". Empty: the first one found.' },
+                            keepalive: { type: 'number', minimum: 0.1, maximum: 2, default: 1, description: 'Seconds between re-sends of an unchanged frame; the firmware drops the picture after 2-3 s without one.' },
+                        },
+                    },
                     {
                         title: 'Frame file',
                         description: 'Writes frame.jpg atomically into a folder; an external sender takes it to the panel.',
@@ -341,6 +353,7 @@ export function configSchema(plugins) {
                     },
                     sleepWhenIdle: { type: 'boolean', default: false, description: 'Black panel while every widget of the page has nothing worth showing.' },
                     jpegQuality: { type: 'integer', minimum: 0, maximum: 100, default: 90, description: 'JPEG quality of the frames; 0 = PNG.' },
+                    maxBytes: { type: 'integer', minimum: 0, maximum: 20_000_000, default: 480_000, description: 'Largest frame to send, in bytes: a bigger one is re-encoded at a lower JPEG quality until it fits. LY panels (Trofeo Vision…) drop frames over ~500 KB. 0 = no limit.' },
                     maxFps: { type: 'integer', minimum: 1, maximum: 30, default: 12, description: 'Frames per second ceiling for animations.' },
                 },
             },

package/dist/config/store.js

@@ -1,9 +1,11 @@
 /**
  * Reading and writing the config file. The file holds secrets (calendar
- * URLs, tokens), so it's written with 0600 and atomically.
+ * URLs, tokens), so it's written atomically and readable by its owner only (0600; an ACL
+ * on Windows).
  */
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
+import { restrictToOwner } from "../fsperm.js";
 import { paths } from "../paths.js";
 import { CONFIG_SCHEMA_ID } from "./model.js";
 import { normalize } from "./normalize.js";
@@ -24,7 +26,7 @@ export function saveConfig(config, path = paths.config) {
     if (existsSync(path)) {
         try {
             copyFileSync(path, `${path}.bak`);
-            chmodSync(`${path}.bak`, 0o600);
+            restrictToOwner(`${path}.bak`);
         }
         catch {
             /* best effort */
@@ -36,10 +38,5 @@ export function saveConfig(config, path = paths.config) {
     const out = { $schema: $schema || CONFIG_SCHEMA_ID, ...rest };
     writeFileSync(tmp, `${JSON.stringify(out, null, 2)}\n`, { mode: 0o600 });
     renameSync(tmp, path);
-    try {
-        chmodSync(path, 0o600);
-    }
-    catch {
-        /* Windows */
-    }
+    restrictToOwner(path);
 }

package/dist/devices.d.ts

@@ -1,3 +1,4 @@
+import { LyPanel } from '@loksly/usb-ly';
 import type { DeviceConfig } from './config/model.ts';
 export interface DeviceStatus {
     driver: DeviceConfig['driver'];
@@ -18,7 +19,74 @@ export interface Device {
     close(): void;
 }
 export declare function encodeFor(device: DeviceConfig, jpegQuality: number): 'png' | 'jpeg';
-export declare function openDevice(cfg: DeviceConfig, log: (m: string) => void): Device;
+/**
+ * `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 declare function renameReplacing(from: string, to: string, rename?: (a: string, b: string) => void, tries?: number): Promise<void>;
+/**
+ * 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 declare class UsbDevice implements Device {
+    status: DeviceStatus;
+    private readonly cfg;
+    private readonly log;
+    private readonly rotate;
+    private readonly open;
+    private readonly retryMs;
+    private panel;
+    private latest;
+    private fresh;
+    private lastWrite;
+    private retryAt;
+    private failures;
+    private closed;
+    private pumping;
+    private timer;
+    private lastMessage;
+    constructor(cfg: Extract<DeviceConfig, {
+        driver: 'usb';
+    }>, log: (m: string) => void, o?: {
+        rotate?: number;
+        open?: (serial?: string) => Promise<LyPanel>;
+        retryMs?: number;
+    });
+    private say;
+    private due;
+    /** Writes what is pending; concurrent callers share one run. */
+    private pump;
+    private describe;
+    private connect;
+    send(frame: Buffer): Promise<void>;
+    close(): void;
+}
+/** The LY panels libusb sees (serial and where), without claiming any: for `kiosko doctor`. */
+export declare function listUsb(): Promise<{
+    ok: boolean;
+    panels: {
+        serial?: string;
+        pid: number;
+        location: string;
+        error?: string;
+    }[];
+    error?: string;
+}>;
+/** The LY panels libusb sees right now, for the "add screen" menu. Never throws. */
+export declare function discoverUsb(): Promise<{
+    serial: string;
+    key: string;
+    width: number;
+    height: number;
+    location: string;
+    error?: string;
+}[]>;
+export declare function openDevice(cfg: DeviceConfig, log: (m: string) => void, rotate?: number): Device;
 /** Panels `trcc serve` can see right now (for the "add screen" dialog). */
 export declare function discoverTrcc(url?: string, tokenFile?: string): Promise<{
     key: string;