@kiosko/core 0.1.0 → 0.2.1

package/src/runtime.ts

@@ -12,7 +12,8 @@
 import { EventEmitter } from 'node:events';
 import { themeById, validate, type Theme } from '@kiosko/sdk';
 import type { Canvas } from '@napi-rs/canvas';
-import { composePage, composeWidget, rotateCanvas, type ComposeResult, type TileCache } from './compositor.ts';
+import { AnimationScheduler, MAX_CONCURRENT, type PlayablePlan } from './animation.ts';
+import { composePage, composeWidget, rotateCanvas, type Animatable, type ComposeResult, type TileCache } from './compositor.ts';
 import { isWorking, whenMatches, widgetsOf, type Config, type Page, type Screen, type WidgetInstance } from './config/model.ts';
 import { FetchHost, SourceHub } from './data.ts';
 import { encodeFor, openDevice, type Device, type DeviceStatus } from './devices.ts';
@@ -38,6 +39,8 @@ 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;
 }
 
@@ -52,6 +55,30 @@ function encode(c: Canvas, kind: 'png' | 'jpeg', quality: number): Buffer {
   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: Canvas, kind: 'png' | 'jpeg', quality: number, maxBytes: number): { out: Buffer; quality: number; over: boolean } {
+  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: number) => `${Math.round(n / 1000)} KB`;
+
 class ScreenRunner {
   device: Device;
   private deviceKey: string;
@@ -63,12 +90,20 @@ class ScreenRunner {
   pinned: string | null = null;
   private playedSlot = new Map<string, number>();
   interlude: { slotId: string; type: string; stopAt: number } | null = null;
+  /** When `fit` last told the log that frames were shrunk, to say it now and then, not every frame. */
+  private fitLoggedAt = 0;
   /** Instance ids on the current page, to know if a data change concerns us. */
   visibleIds = new Set<string>();
   sourceTypes = new Set<string>();
   page: Page | null = null;
   /** Rendered tiles reused between frames (see compositor's TileCache). */
   private tiles: TileCache = new Map();
+  /** The widgets of the last painted page that can animate, and when to ask them (see animation.ts). */
+  private animatable: Animatable[] = [];
+  private scheduler: AnimationScheduler;
+  /** Set while a widget's animation plays: its widget type. */
+  animating: string | null = null;
+  private closed = false;
 
   screen: Screen;
   private readonly rt: Runtime;
@@ -76,15 +111,31 @@ class ScreenRunner {
     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. */
+  private fit(c: Canvas, kind: 'png' | 'jpeg', quality: number, screen: Screen): Buffer {
+    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: Screen): void {
     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;
     }
@@ -111,9 +162,13 @@ class ScreenRunner {
         this.dirty = true;
         this.rt.refreshWanted();
       }
-      if (!this.dirty && now < this.nextAt) return;
+      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)}`);
     } finally {
@@ -142,6 +197,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.
     } else {
@@ -149,6 +205,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);
@@ -158,7 +215,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)) return;
@@ -207,7 +264,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.
@@ -225,6 +282,124 @@ class ScreenRunner {
     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.
+   */
+  private async maybeAnimate(now: number): Promise<void> {
+    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.
+   */
+  private async playAnimations(items: { animatable: Animatable; play: PlayablePlan }[], now: number): Promise<boolean> {
+    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<string, unknown>();
+    const memoSources = new Map<string, Record<string, unknown>>();
+    const working = this.rt.working(now);
+    const kind = encodeFor(screen.device, screen.jpegQuality || 85);
+    const sent: { out: Buffer; snap: Canvas | null }[] = [];
+    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: string): Promise<void> {
     if (this.busy) return;
     this.busy = true;
@@ -240,6 +415,7 @@ class ScreenRunner {
   }
 
   close(): void {
+    this.closed = true;
     this.interlude = null;
     this.device.close();
   }
@@ -252,6 +428,10 @@ export class Runtime extends EventEmitter {
   private runners = new Map<string, ScreenRunner>();
   private timer: NodeJS.Timeout | null = null;
   readonly logs: LogEntry[] = [];
+  /** How many animations play together on a screen (see animation.ts). */
+  maxConcurrent: number = MAX_CONCURRENT;
+  /** Random numbers for the animations; tests replace it with a seeded one. */
+  rnd: () => number = Math.random;
 
   readonly registry: Registry;
   /**
@@ -394,6 +574,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 as DeviceStatus,
         lastFrameAt: r.lastInfo?.at ?? null,
         sleeping: r.lastInfo?.sleeping ?? false,