@kiosko/core 0.1.0 → 0.2.1

package/dist/runtime.js

@@ -11,6 +11,7 @@
  */
 import { EventEmitter } from 'node:events';
 import { themeById, validate } from '@kiosko/sdk';
+import { AnimationScheduler, MAX_CONCURRENT } from "./animation.js";
 import { composePage, composeWidget, rotateCanvas } from "./compositor.js";
 import { isWorking, whenMatches, widgetsOf } from "./config/model.js";
 import { FetchHost, SourceHub } from "./data.js";
@@ -25,6 +26,29 @@ function lazyJpeg(c) {
 function encode(c, kind, quality) {
     return kind === 'jpeg' ? c.toBuffer('image/jpeg', Math.max(1, Math.min(100, quality || 90))) : c.toBuffer('image/png');
 }
+/** Lowest JPEG quality `encodeFit` goes down to. */
+const MIN_FIT_QUALITY = 20;
+/**
+ * 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 function encodeFit(c, kind, quality, maxBytes) {
+    const q0 = Math.max(1, Math.min(100, quality || 90));
+    let out = encode(c, kind, q0);
+    if (kind !== 'jpeg' || !(maxBytes > 0) || out.length <= maxBytes)
+        return { out, quality: q0, over: false };
+    let q = q0;
+    while (q > MIN_FIT_QUALITY) {
+        q = Math.max(MIN_FIT_QUALITY, q - 10);
+        out = encode(c, kind, q);
+        if (out.length <= maxBytes)
+            return { out, quality: q, over: false };
+    }
+    return { out, quality: q, over: true };
+}
+const kb = (n) => `${Math.round(n / 1000)} KB`;
 class ScreenRunner {
     device;
     deviceKey;
@@ -36,26 +60,46 @@ class ScreenRunner {
     pinned = null;
     playedSlot = new Map();
     interlude = null;
+    /** When `fit` last told the log that frames were shrunk, to say it now and then, not every frame. */
+    fitLoggedAt = 0;
     /** Instance ids on the current page, to know if a data change concerns us. */
     visibleIds = new Set();
     sourceTypes = new Set();
     page = null;
     /** Rendered tiles reused between frames (see compositor's TileCache). */
     tiles = new Map();
+    /** The widgets of the last painted page that can animate, and when to ask them (see animation.ts). */
+    animatable = [];
+    scheduler;
+    /** Set while a widget's animation plays: its widget type. */
+    animating = null;
+    closed = false;
     screen;
     rt;
     constructor(screen, rt) {
         this.screen = screen;
         this.rt = rt;
         this.deviceKey = JSON.stringify(screen.device);
-        this.device = openDevice(screen.device, (m) => rt.log(`screen:${screen.name}`, m));
+        this.device = openDevice(screen.device, (m) => rt.log(`screen:${screen.name}`, m), screen.rotate);
         this.pinned = screen.pinnedPage ?? null;
+        this.scheduler = new AnimationScheduler(() => rt.rnd(), (type, why) => rt.log(type, `animation ignored: ${why}`));
+    }
+    /** Encodes a frame within the screen's `maxBytes`, saying so in the log (at most every 10 min) when it had to shrink it. */
+    fit(c, kind, quality, screen) {
+        const r = encodeFit(c, kind, quality, screen.maxBytes);
+        if ((r.quality !== Math.max(1, Math.min(100, quality || 90)) || r.over) && Date.now() - this.fitLoggedAt > 10 * 60_000) {
+            this.fitLoggedAt = Date.now();
+            this.rt.log(`screen:${screen.name}`, r.over
+                ? `frames don't fit in ${kb(screen.maxBytes)} even at JPEG quality ${r.quality} (${kb(r.out.length)}); the panel may drop them`
+                : `frames over ${kb(screen.maxBytes)} at quality ${quality}: sent at quality ${r.quality} (${kb(r.out.length)})`);
+        }
+        return r.out;
     }
     reconfigure(screen) {
         const key = JSON.stringify(screen.device);
         if (key !== this.deviceKey) {
             this.device.close();
-            this.device = openDevice(screen.device, (m) => this.rt.log(`screen:${screen.name}`, m));
+            this.device = openDevice(screen.device, (m) => this.rt.log(`screen:${screen.name}`, m), screen.rotate);
             this.deviceKey = key;
             this.last = null;
         }
@@ -83,10 +127,13 @@ class ScreenRunner {
                 this.dirty = true;
                 this.rt.refreshWanted();
             }
-            if (!this.dirty && now < this.nextAt)
+            if (!this.dirty && now < this.nextAt) {
+                await this.maybeAnimate(now);
                 return;
+            }
             this.dirty = false;
             await this.paint(page, now);
+            await this.maybeAnimate(now);
         }
         catch (err) {
             this.rt.log(`screen:${this.screen.name}`, `paint failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -116,6 +163,7 @@ class ScreenRunner {
                 cache: this.tiles,
             });
             canvas = result.canvas;
+            this.animatable = result.animatable;
             this.nextAt = Math.min(result.nextAt, now + 60_000);
             // Pages and work hours change by the clock: check at least every minute.
         }
@@ -124,6 +172,7 @@ class ScreenRunner {
             const g = canvas.getContext('2d');
             g.fillStyle = '#000';
             g.fillRect(0, 0, screen.width, screen.height);
+            this.animatable = [];
             this.nextAt = now + 60_000;
         }
         const sleeping = !!(screen.sleepWhenIdle && result?.idle);
@@ -133,7 +182,7 @@ class ScreenRunner {
             g.fillRect(0, 0, screen.width, screen.height);
         }
         const kind = encodeFor(screen.device, screen.jpegQuality);
-        const out = encode(rotateCanvas(canvas, screen.rotate), kind, screen.jpegQuality);
+        const out = this.fit(rotateCanvas(canvas, screen.rotate), kind, screen.jpegQuality, screen);
         this.lastInfo = { screenId: screen.id, pageId: page?.id ?? null, at: now, image: lazyJpeg(canvas), tiles: result?.tiles ?? [], interlude: null, sleeping };
         this.rt.emit('frame', this.lastInfo);
         if (this.last?.equals(out))
@@ -189,7 +238,7 @@ class ScreenRunner {
             finally {
                 g.restore();
             }
-            const out = encode(rotateCanvas(canvas, this.screen.rotate), kind, this.screen.jpegQuality || 85);
+            const out = this.fit(rotateCanvas(canvas, this.screen.rotate), kind, this.screen.jpegQuality || 85, this.screen);
             await this.device.send(out);
             if (i % 3 === 0) {
                 // The interlude draws every frame on the same canvas: snapshot it.
@@ -207,6 +256,133 @@ class ScreenRunner {
         this.dirty = true;
         return true;
     }
+    /**
+     * Plays the animations the shown widgets ask for, if any is due (see
+     * animation.ts). Like an interlude it runs inside `update`, so nothing else
+     * is painted meanwhile, but unlike it the page stays in place: only the
+     * widgets' tiles change from frame to frame. How many play together is
+     * `Runtime.maxConcurrent` (one by default); the rest wait their turn.
+     */
+    async maybeAnimate(now) {
+        if (!this.screen.enabled || this.closed || this.lastInfo?.sleeping || !this.animatable.length)
+            return;
+        const due = this.scheduler.next(this.animatable, now, this.screen.maxFps, this.rt.maxConcurrent);
+        if (!due.length)
+            return;
+        this.animating = due.map((d) => d.animatable.type).join(', ');
+        let completed = false;
+        try {
+            completed = await this.playAnimations(due, now);
+        }
+        finally {
+            this.animating = null;
+            // Whatever happened, the next paint is a real one with the current data.
+            this.last = null;
+            this.dirty = true;
+            for (const d of due) {
+                this.scheduler.ended(d.animatable.instanceId, Date.now(), d.animatable);
+                d.animatable.ended(d.play.plan, completed);
+            }
+        }
+    }
+    /**
+     * One timeline for all: the fastest plan sets the rate and each animation
+     * advances at its own, so they start together and the longest decides when
+     * it is over. The ones that finish earlier stay at rest. With only one it
+     * is just that animation's own frames.
+     */
+    async playAnimations(items, now) {
+        const page = this.page;
+        if (!page)
+            return false;
+        const { screen } = this;
+        const fps = Math.max(...items.map((x) => x.play.fps));
+        const seconds = Math.max(...items.map((x) => (x.play.frames - 1) / x.play.fps));
+        const frames = Math.round(seconds * fps) + 1;
+        // Cut short by new data only if every one of them can be (an urgent one is not).
+        const interruptible = items.every((x) => x.play.interruptible);
+        // A hold has a meaning for a single animation: with several it is ignored.
+        const hold = items.length === 1 ? items[0].play.hold : undefined;
+        const abort = () => this.closed || (interruptible && this.dirty) || !this.screen.enabled;
+        this.dirty = false;
+        // The page as it was at the start: same clock, same data for every frame, so
+        // only the animated tiles move (a changing clock would flicker) and, if it
+        // can't be cut short, a data change during it doesn't leak in.
+        const memoData = new Map();
+        const memoSources = new Map();
+        const working = this.rt.working(now);
+        const kind = encodeFor(screen.device, screen.jpegQuality || 85);
+        const sent = [];
+        const t0 = Date.now();
+        // Every frame is painted before the first is sent: painting and sending
+        // at once is slower than either, and the panel drops what comes late.
+        for (let s = 1; s < frames - 1; s++) {
+            if (abort())
+                return false;
+            const animate = items.flatMap(({ animatable: a, play }) => {
+                // Frame of this animation at this moment of the timeline; at either end it is at rest.
+                const i = Math.round((s / fps) * play.fps);
+                return i <= 0 || i >= play.frames - 1 ? [] : [{ tileId: a.tileId, instanceId: a.instanceId, frame: { plan: play.plan, i, t: i / (play.frames - 1) } }];
+            });
+            const result = composePage({
+                cfg: this.rt.config,
+                screen,
+                page,
+                theme: this.rt.theme(),
+                registry: this.rt.registry,
+                now,
+                working,
+                dataOf: (inst) => {
+                    if (!memoData.has(inst.id))
+                        memoData.set(inst.id, this.rt.fetches.data(inst.id));
+                    return memoData.get(inst.id);
+                },
+                sourcesOf: (types) => {
+                    const k = JSON.stringify(types ?? []);
+                    if (!memoSources.has(k))
+                        memoSources.set(k, this.rt.hub.pick(types));
+                    return memoSources.get(k);
+                },
+                log: this.rt.log,
+                demo: this.rt.demoMode,
+                cache: this.tiles,
+                animate,
+            });
+            sent.push({ out: this.fit(rotateCanvas(result.canvas, screen.rotate), kind, screen.jpegQuality || 85, screen), snap: s % 3 === 1 ? result.canvas : null });
+            // Let the loop breathe: a long animation must not freeze the timers and the other screens.
+            await new Promise((r) => setImmediate(r));
+        }
+        const what = items.map((x) => `${x.animatable.type} ${x.play.plan.id}`).join(' + ');
+        this.rt.log(`screen:${screen.name}`, `animating ${what}: ${sent.length} frames at ${fps} fps (painted in ${Date.now() - t0} ms)`);
+        const holdAt = hold ? Math.max(0, Math.min(sent.length - 1, hold.index - 1)) : -1;
+        let start = Date.now();
+        for (let k = 0; k < sent.length; k++) {
+            if (abort())
+                return false;
+            // Late: skip the frame rather than let the delay pile up.
+            const due = Math.floor(((Date.now() - start) * fps) / 1000);
+            if (k < due - 1 && k !== holdAt && k < sent.length - 1)
+                continue;
+            await this.device.send(sent[k].out);
+            const snap = sent[k].snap;
+            if (snap) {
+                this.lastInfo = { screenId: screen.id, pageId: page.id, at: Date.now(), image: lazyJpeg(snap), tiles: [], interlude: null, animation: items.map((x) => x.animatable.type).join(', '), sleeping: false };
+                this.rt.emit('frame', this.lastInfo);
+            }
+            if (hold && k === holdAt) {
+                // Still: the panel keeps the picture without being sent it again.
+                const until = Date.now() + hold.ms;
+                while (Date.now() < until && !abort())
+                    await new Promise((r) => setTimeout(r, Math.min(250, until - Date.now())));
+                start = Date.now() - ((k + 1) * 1000) / fps;
+                continue;
+            }
+            const wait = start + ((k + 1) * 1000) / fps - Date.now();
+            if (wait > 0)
+                await new Promise((r) => setTimeout(r, wait));
+        }
+        return true;
+    }
     async playNow(slotId) {
         if (this.busy)
             return;
@@ -222,6 +398,7 @@ class ScreenRunner {
         this.interlude = null;
     }
     close() {
+        this.closed = true;
         this.interlude = null;
         this.device.close();
     }
@@ -233,6 +410,10 @@ export class Runtime extends EventEmitter {
     runners = new Map();
     timer = null;
     logs = [];
+    /** How many animations play together on a screen (see animation.ts). */
+    maxConcurrent = MAX_CONCURRENT;
+    /** Random numbers for the animations; tests replace it with a seeded one. */
+    rnd = Math.random;
     registry;
     /**
      * Demo mode: no source or fetch runs, every widget paints its sample data.
@@ -374,6 +555,7 @@ export class Runtime extends EventEmitter {
                 page: r.page?.id ?? null,
                 pinned: r.pinned,
                 interlude: r.interlude?.type ?? null,
+                animation: r.animating,
                 device: r.device.status,
                 lastFrameAt: r.lastInfo?.at ?? null,
                 sleeping: r.lastInfo?.sleeping ?? false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kiosko/core",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Kiosko runtime: grid layout engine, plugin host, compositor and panel drivers.",
   "type": "module",
   "license": "MIT",
@@ -27,10 +27,11 @@
     }
   },
   "dependencies": {
-    "@loksly/lcd-canvas-kit": "0.1.0",
-    "@loksly/trcc-client": "0.1.0",
+    "@loksly/lcd-canvas-kit": "0.2.1",
+    "@loksly/trcc-client": "0.2.1",
+    "@loksly/usb-ly": "0.2.1",
     "@napi-rs/canvas": "^1.0.10",
-    "@kiosko/sdk": "0.1.0",
+    "@kiosko/sdk": "0.2.1",
     "dejavu-fonts-ttf": "^2.37.3"
   },
   "scripts": {

package/src/animation.ts

@@ -0,0 +1,140 @@
+/**
+ * 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 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 };
+
+/** 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 function checkPlan(plan: unknown, maxFps: number): PlayablePlan | string {
+  const p = plan as Partial<AnimationPlan> | null;
+  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 as AnimationPlan, frames, fps: Math.max(1, Math.min(p.fps!, maxFps)), interruptible: p.interruptible !== false, ...(hold ? { hold } : {}) };
+}
+
+interface Memory {
+  data: unknown;
+  sources: Record<string, unknown>;
+  nextIdleAt: number;
+  endedAt: number;
+  /** Since when it has had a question due that was not answered with a plan (Infinity: none). */
+  dueSince: number;
+  /** A data change that was due but had to wait its turn: what the widget had before it. */
+  pending?: { data: unknown; sources: Record<string, unknown> };
+}
+
+export class AnimationScheduler {
+  private memory = new Map<string, Memory>();
+
+  private readonly rnd: () => number;
+  private readonly onInvalid: (type: string, why: string) => void;
+
+  constructor(rnd: () => number = Math.random, onInvalid: (type: string, why: string) => void = () => undefined) {
+    this.rnd = rnd;
+    this.onInvalid = onInvalid;
+  }
+
+  private gapAfter(a: Animatable, now: number): number {
+    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: Animatable[], now: number, maxFps: number, limit: number = MAX_CONCURRENT): { animatable: Animatable; play: PlayablePlan }[] {
+    const seen = new Set<string>();
+    const due: { a: Animatable; m: Memory; trigger: 'idle' | 'data'; prev: { data: unknown; sources: Record<string, unknown> } }[] = [];
+    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: { animatable: Animatable; play: PlayablePlan }[] = [];
+    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: string, now: number, a?: Animatable): void {
+    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/src/compositor.ts

@@ -6,7 +6,7 @@
  */
 import { createCanvas, loadImage, type Canvas, type Image, type SKRSContext2D } from '@napi-rs/canvas';
 import { pixelShift } from '@loksly/lcd-canvas-kit';
-import { localize, validate, type Box, type Redraw, type RenderContext, type Theme, type WidgetDefinition } from '@kiosko/sdk';
+import { localize, validate, type AnimationFrame, type AnimationPlan, type Box, type Redraw, type RenderContext, type Theme, type WidgetDefinition } from '@kiosko/sdk';
 import { toPx, type PxRect } from './layout/grid.ts';
 import { nextTurnAt, pickInStack } from './layout/stack.ts';
 import { whenMatches, zoomOf, type Config, type Page, type Screen, type Tile, type WidgetInstance } from './config/model.ts';
@@ -39,6 +39,29 @@ 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 {
@@ -56,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[];
 }
 
 const images = new Map<string, Image | null>();
@@ -172,7 +197,7 @@ function drawCard(g: SKRSContext2D, rect: PxRect, theme: Theme): void {
   g.stroke();
 }
 
-function paintTile(g: SKRSContext2D, input: ComposeInput, tile: Tile, rect: PxRect, out: TileResult, nextAt: { v: number }, idles: boolean[]): void {
+function paintTile(g: SKRSContext2D, input: ComposeInput, tile: Tile, rect: PxRect, out: TileResult, nextAt: { v: number }, idles: boolean[], animatable: Animatable[]): void {
   const { theme, now, working } = input;
   const candidates = tile.widgets
     .filter((w) => !w.disabled && whenMatches(w.when, working))
@@ -202,9 +227,27 @@ function paintTile(g: SKRSContext2D, input: ComposeInput, tile: Tile, rect: PxRe
   idles.push(safe(() => r.def.idle?.(state) ?? false, false));
   const step = redrawStep(r.def, state);
   if (step) nextAt.v = Math.min(nextAt.v, (Math.floor(now / step) + 1) * step);
+  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),
+    });
+  }
 
-  const draw = (tg: SKRSContext2D) => drawTileContent(tg, input, r, rect, chrome, out);
-  if (!input.cache) {
+  // 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: SKRSContext2D) => drawTileContent(tg, input, r, rect, chrome, out, frame);
+  if (frame || !input.cache) {
     draw(g);
     return;
   }
@@ -227,26 +270,37 @@ function paintTile(g: SKRSContext2D, input: ComposeInput, tile: Tile, rect: PxRe
   input.cache.set(tile.id, { key, refs, canvas, ...(out.error ? { error: out.error } : {}) });
 }
 
-function drawTileContent(g: SKRSContext2D, input: ComposeInput, r: Resolved, rect: PxRect, chrome: 'card' | 'bare', out: TileResult): void {
+/**
+ * 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: Theme, screenH: number, inst: WidgetInstance, rect: PxRect, chrome: 'card' | 'bare'): { outer: Box; box: Box; zoom: number } {
+  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: Box = { 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: 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: SKRSContext2D, input: ComposeInput, r: Resolved, rect: PxRect, chrome: 'card' | 'bare', out: TileResult, anim?: AnimationFrame): void {
   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: Box = { 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: 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: RenderContext<any, any> = {
     ...baseContext(input.cfg, plugin!, input.log ?? (() => undefined), now),
@@ -257,6 +311,7 @@ function drawTileContent(g: SKRSContext2D, input: ComposeInput, r: Resolved, rec
     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);
@@ -297,16 +352,17 @@ export function composePage(input: ComposeInput): ComposeResult {
   const nextAt = { v: Infinity };
   const idles: boolean[] = [];
   const tiles: TileResult[] = [];
+  const animatable: Animatable[] = [];
   for (const tile of page.tiles) {
     const rect = toPx(tile, page.grid, screen.width, screen.height);
     const out: TileResult = { 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()) if (!page.tiles.some((t) => t.id === id)) input.cache.delete(id);
   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. */

package/src/config/diff.ts

@@ -50,7 +50,7 @@ const pageText = (p: Page) => {
   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: DeviceConfig) => (d.driver === 'trcc' ? `trcc ${d.url}` : d.driver === 'file' ? `file ${d.dir}` : d.driver);
+const deviceText = (d: DeviceConfig) => (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: Record<string, unknown>, b: Record<string, unknown>) => [...new Set([...Object.keys(a), ...Object.keys(b)])].filter((k) => !same(a[k], b[k]));
 
 function diffTiles(before: Page, after: Page, depth: number, out: DiffLine[]): void {

package/src/config/model.ts

@@ -31,6 +31,8 @@ export type DeviceConfig =
   | { driver: 'virtual' }
   /** `trcc serve` REST API (thermalright-trcc-linux). */
   | { driver: 'trcc'; url: string; tokenFile?: string; deviceKey?: string; 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'; dir: string; format?: 'jpeg' | 'png'; quality?: number };
 
@@ -129,10 +131,19 @@ 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 const DEFAULT_MAX_BYTES = 480_000;
+
 export interface Config {
   /** JSON Schema of the file, for editors. Kept as written; `CONFIG_SCHEMA_ID` when missing. */
   $schema?: string;
@@ -186,6 +197,7 @@ export function newScreen(name: string, width = 1920, height = 462, device: Devi
     pixelShift: { enabled: true, amplitude: 2, periodMs: 8 * 60_000 },
     sleepWhenIdle: false,
     jpegQuality: 90,
+    maxBytes: DEFAULT_MAX_BYTES,
     maxFps: 12,
   };
 }