@kiosko/core 0.0.0-stage → 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

@@ -0,0 +1,140 @@
+/**
+ * Paints one page of a screen: background, then every tile with its card
+ * and the widget whose turn it is. Pure function of its input (plus the
+ * widgets' own code), so the panel, the editor preview and the gallery all
+ * go through here and can't disagree.
+ */
+import { type Canvas, type SKRSContext2D } from '@napi-rs/canvas';
+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';
+import type { Registry } from './registry.ts';
+export interface ComposeInput {
+    cfg: Config;
+    screen: Pick<Screen, 'width' | 'height' | 'pixelShift'>;
+    page: Page;
+    theme: Theme;
+    registry: Registry;
+    now: number;
+    working: boolean;
+    /** Data of an instance's own fetch. */
+    dataOf: (inst: WidgetInstance) => unknown;
+    /** Latest data of shared sources. */
+    sourcesOf: (types: readonly string[] | undefined) => Record<string, unknown>;
+    /** Painted for the editor, not for the panel. */
+    preview?: boolean;
+    /** Use each widget's demo data where there's no real data yet. */
+    demo?: boolean;
+    /** Also its demo options (gallery thumbnails only). */
+    demoOptions?: boolean;
+    /** Force which widget a tile shows (editor: the one selected in its stack). */
+    forceShown?: Record<string, string>;
+    log?: LogFn;
+    /** Disable pixel shift (editor, gallery). */
+    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;
+    rect: PxRect;
+    /** Id of the widget instance shown, or null if none is visible. */
+    shown: string | null;
+    error?: string;
+}
+export interface ComposeResult {
+    canvas: Canvas;
+    tiles: TileResult[];
+    /** Every widget shown says it's idle (and there's at least one). */
+    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
+ * while urgent) and `hideWhenEmpty` (skip it in the rotation while `empty`).
+ * Each defaults to what the widget declares.
+ */
+export declare function tileState(def: WidgetDefinition<any, any>, inst: Pick<WidgetInstance, 'takeOver' | 'hideWhenEmpty'>, state: Parameters<NonNullable<WidgetDefinition['visible']>>[0]): {
+    visible: boolean;
+    urgent: boolean;
+};
+/** Cuts `text` with an ellipsis to fit `maxW` with the current font (plain fillText, no tracking). */
+export declare function fitText(g: SKRSContext2D, text: string, maxW: number): string;
+export declare function roundRect(g: SKRSContext2D, x: number, y: number, w: number, h: number, r: number): void;
+/** Card padding and title size scale with the panel: a 320×240 can't afford 16 px margins. */
+export declare function chromeMetrics(theme: Theme, screenH: number, rect: PxRect): {
+    pad: number;
+    title: number;
+    titleBar: number;
+};
+/** Rendered tiles kept between frames of one screen, so a frame only repaints what changed. */
+export type TileCache = Map<string, {
+    key: string;
+    refs: unknown[];
+    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. */
+export declare function rotateCanvas(src: Canvas, rotate: number): Canvas;
+/** Renders a single widget alone (gallery thumbnails, plugin tests), with demo data unless given. */
+export declare function composeWidget(o: {
+    cfg: Config;
+    registry: Registry;
+    theme: Theme;
+    type: string;
+    width: number;
+    height: number;
+    options?: Record<string, unknown>;
+    title?: string;
+    data?: unknown;
+    sources?: Record<string, unknown>;
+    now?: number;
+    chrome?: Tile['chrome'];
+    /** The instance's zoom (see `WidgetInstance.zoom`). */
+    zoom?: number;
+}): ComposeResult;

package/dist/compositor.js

@@ -0,0 +1,322 @@
+/**
+ * Paints one page of a screen: background, then every tile with its card
+ * and the widget whose turn it is. Pure function of its input (plus the
+ * widgets' own code), so the panel, the editor preview and the gallery all
+ * go through here and can't disagree.
+ */
+import { createCanvas, loadImage } from '@napi-rs/canvas';
+import { pixelShift } from '@loksly/lcd-canvas-kit';
+import { localize, validate } from '@kiosko/sdk';
+import { toPx } from "./layout/grid.js";
+import { nextTurnAt, pickInStack } from "./layout/stack.js";
+import { whenMatches, zoomOf } from "./config/model.js";
+import { CANVAS, baseContext, kit, resolveLocale } from "./env.js";
+import { registerFonts } from "./fonts.js";
+const images = new Map();
+/** Background images are loaded once, in the background; the first frames go without. */
+function backgroundImage(path) {
+    if (!images.has(path)) {
+        images.set(path, null);
+        loadImage(path).then((img) => images.set(path, img)).catch(() => undefined);
+    }
+    return images.get(path) ?? null;
+}
+function resolve(input, inst) {
+    const def = input.registry.widget(inst.type);
+    if (!def)
+        return null;
+    let options = def.options ? validate(def.options, inst.options).value : {};
+    let data = input.dataOf(inst);
+    let sources = input.sourcesOf(def.sources);
+    if (input.demo && def.demo) {
+        const needData = data === undefined;
+        const needSources = (def.sources ?? []).some((s) => sources[s] === undefined);
+        if (needData || needSources || input.demoOptions) {
+            try {
+                const d = def.demo({ options, now: input.now, locale: resolveLocale(input.cfg) });
+                if (input.demoOptions && d.options && def.options)
+                    options = validate(def.options, { ...d.options, ...inst.options }).value;
+                if (needData)
+                    data = d.data;
+                if (needSources)
+                    sources = { ...(d.sources ?? {}), ...Object.fromEntries(Object.entries(sources).filter(([, v]) => v !== undefined)) };
+            }
+            catch {
+                /* a broken demo shouldn't break the editor */
+            }
+        }
+    }
+    return { inst, def, options, data, sources };
+}
+function stateCtx(r, now, working, cfg) {
+    return { options: r.options, data: r.data, sources: r.sources, now, working, workday: cfg.workday, ...(cfg.location ? { location: cfg.location } : {}) };
+}
+/**
+ * The instance's switches over the widget's hooks: `takeOver` (keep the tile
+ * while urgent) and `hideWhenEmpty` (skip it in the rotation while `empty`).
+ * Each defaults to what the widget declares.
+ */
+export function tileState(def, inst, state) {
+    const takeOver = inst.takeOver ?? def.takeOver ?? true;
+    const hideEmpty = inst.hideWhenEmpty ?? def.hideWhenEmpty ?? false;
+    const visible = safe(() => def.visible?.(state) ?? true, true) && !(hideEmpty && def.empty && safe(() => def.empty(state), false));
+    const urgent = takeOver && safe(() => def.urgent?.(state) ?? false, false);
+    return { visible, urgent };
+}
+function safe(fn, fallback) {
+    if (!fn)
+        return fallback;
+    try {
+        return fn();
+    }
+    catch {
+        return fallback;
+    }
+}
+/** How often a widget wants to be repainted on its own, in ms (0 = only when its data changes). */
+function redrawStep(def, state) {
+    const r = (typeof def.redraw === 'function' ? safe(() => def.redraw(state), 'never') : def.redraw) ?? 'never';
+    if (r === 'never')
+        return 0;
+    return r === 'second' ? 1000 : r === 'minute' ? 60_000 : Math.max(250, r.everyMs);
+}
+/** Cuts `text` with an ellipsis to fit `maxW` with the current font (plain fillText, no tracking). */
+export function fitText(g, text, maxW) {
+    if (g.measureText(text).width <= maxW)
+        return text;
+    const chars = [...text];
+    let lo = 0;
+    let hi = chars.length;
+    while (lo < hi) {
+        const mid = Math.ceil((lo + hi) / 2);
+        if (g.measureText(`${chars.slice(0, mid).join('').trimEnd()}…`).width <= maxW)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return lo > 0 ? `${chars.slice(0, lo).join('').trimEnd()}…` : '…';
+}
+export function roundRect(g, x, y, w, h, r) {
+    g.beginPath();
+    g.roundRect(x, y, w, h, Math.max(0, Math.min(r, w / 2, h / 2)));
+}
+/** Card padding and title size scale with the panel: a 320×240 can't afford 16 px margins. */
+export function chromeMetrics(theme, screenH, rect) {
+    const scale = Math.max(0.45, Math.min(1, screenH / 462, rect.h / 180));
+    const pad = Math.round(16 * scale);
+    const title = Math.round(theme.titleSize * scale);
+    return { pad, title, titleBar: Math.round(title * 1.55) };
+}
+function drawCard(g, rect, theme) {
+    roundRect(g, rect.x, rect.y, rect.w, rect.h, theme.radius);
+    g.fillStyle = theme.colors.surface;
+    g.fill();
+    g.strokeStyle = theme.colors.surfaceEdge;
+    g.lineWidth = 1;
+    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, animatable) {
+    const { theme, now, working } = input;
+    const candidates = tile.widgets
+        .filter((w) => !w.disabled && whenMatches(w.when, working))
+        .map((w) => resolve(input, w))
+        .filter((r) => !!r);
+    const entries = candidates.map((r) => ({ id: r.inst.id, ...tileState(r.def, r.inst, stateCtx(r, now, working, input.cfg)) }));
+    const forced = input.forceShown?.[tile.id];
+    const shownId = forced && candidates.some((c) => c.inst.id === forced) ? forced : pickInStack(entries, now, tile.rotateMs);
+    if (entries.filter((e) => e.visible).length > 1 && !forced)
+        nextAt.v = Math.min(nextAt.v, nextTurnAt(now, tile.rotateMs));
+    out.shown = shownId;
+    const r = candidates.find((c) => c.inst.id === shownId);
+    const chrome = tile.chrome === 'auto' ? (r?.def.chrome ?? 'card') : tile.chrome;
+    if (!r) {
+        if (chrome === 'card')
+            drawCard(g, rect, theme);
+        // An empty tile is invisible on the panel; in the editor it's a hint.
+        if (input.preview && !tile.widgets.length) {
+            g.setLineDash([6, 6]);
+            g.strokeStyle = theme.colors.inkFaint;
+            roundRect(g, rect.x + 1, rect.y + 1, rect.w - 2, rect.h - 2, theme.radius);
+            g.stroke();
+            g.setLineDash([]);
+        }
+        return;
+    }
+    const state = stateCtx(r, now, working, input.cfg);
+    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),
+        });
+    }
+    // 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;
+    }
+    // Same widget, options, size, data and sources (by reference: they're
+    // replaced, never mutated, when they change) and same redraw slot: reuse.
+    const cfg = input.cfg;
+    const key = JSON.stringify([r.inst.id, r.inst.type, r.inst.options, r.inst.title ?? '', zoomOf(r.inst), chrome, rect, theme.id, step ? Math.floor(now / step) : 0, cfg.locale, cfg.timeFormat, cfg.workday, cfg.location ?? null, working]);
+    const refs = [r.data, ...(r.def.sources ?? []).map((s) => r.sources[s])];
+    const hit = input.cache.get(tile.id);
+    if (hit && hit.key === key && hit.refs.length === refs.length && hit.refs.every((x, i) => x === refs[i])) {
+        g.drawImage(hit.canvas, rect.x, rect.y);
+        if (hit.error)
+            out.error = hit.error;
+        return;
+    }
+    const canvas = createCanvas(rect.w, rect.h);
+    const tg = canvas.getContext('2d');
+    tg.translate(-rect.x, -rect.y);
+    draw(tg);
+    g.drawImage(canvas, rect.x, rect.y);
+    input.cache.set(tile.id, { key, refs, canvas, ...(out.error ? { error: out.error } : {}) });
+}
+/**
+ * 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;
+    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);
+    }
+    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),
+        ...stateCtx(r, now, working, input.cfg),
+        box,
+        theme,
+        fonts: theme.fonts,
+        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);
+    g.clip();
+    if (zoom !== 1) {
+        g.translate(outer.x * (1 - zoom), outer.y * (1 - zoom));
+        g.scale(zoom, zoom);
+    }
+    try {
+        r.def.render(g, ctx);
+    }
+    catch (err) {
+        out.error = err instanceof Error ? err.message : String(err);
+        input.log?.(r.inst.type, `render failed: ${out.error}`);
+        const size = Math.max(12, Math.min(20, box.h / 4));
+        kit.drawTracked(g, kit.truncate(g, `⚠ ${localize(r.def.name, ctx.locale)}: ${out.error}`, box.w, { size, family: theme.fonts.mono }), box.x, box.y + size * 1.2, { size, family: theme.fonts.mono, color: theme.colors.alert });
+    }
+    g.restore();
+}
+/** Paints `page` on a new canvas of the screen size. */
+export function composePage(input) {
+    registerFonts();
+    const { screen, page, theme, now } = input;
+    const canvas = createCanvas(screen.width, screen.height);
+    const g = canvas.getContext('2d');
+    g.fillStyle = page.background.color || theme.colors.bg;
+    g.fillRect(0, 0, screen.width, screen.height);
+    if (page.background.image) {
+        const img = backgroundImage(page.background.image);
+        if (img) {
+            const s = Math.max(screen.width / img.width, screen.height / img.height);
+            g.drawImage(img, (screen.width - img.width * s) / 2, (screen.height - img.height * s) / 2, img.width * s, img.height * s);
+        }
+    }
+    const shift = input.noShift || input.preview ? { x: 0, y: 0 } : pixelShift(now, screen.pixelShift);
+    g.save();
+    g.translate(shift.x, shift.y);
+    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, 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, animatable };
+}
+/** A canvas rotated for a panel mounted at `rotate` degrees. */
+export function rotateCanvas(src, rotate) {
+    if (!rotate)
+        return src;
+    const swap = rotate === 90 || rotate === 270;
+    const out = createCanvas(swap ? src.height : src.width, swap ? src.width : src.height);
+    const g = out.getContext('2d');
+    g.translate(out.width / 2, out.height / 2);
+    g.rotate((rotate * Math.PI) / 180);
+    g.drawImage(src, -src.width / 2, -src.height / 2);
+    return out;
+}
+/** Renders a single widget alone (gallery thumbnails, plugin tests), with demo data unless given. */
+export function composeWidget(o) {
+    const inst = { id: 'w', type: o.type, options: o.options ?? {}, ...(o.title ? { title: o.title } : {}), ...(o.zoom !== undefined && o.zoom !== 1 ? { zoom: o.zoom } : {}) };
+    const page = { id: 'p', name: 'p', grid: { cols: 1, rows: 1, gap: 0, padding: 0 }, gravity: 'none', background: { color: o.theme.colors.bg }, tiles: [{ id: 't', x: 0, y: 0, w: 1, h: 1, widgets: [inst], rotateMs: 0, chrome: o.chrome ?? 'auto' }] };
+    return composePage({
+        cfg: o.cfg,
+        screen: { width: o.width, height: o.height, pixelShift: { enabled: false, amplitude: 0, periodMs: 1 } },
+        page,
+        theme: o.theme,
+        registry: o.registry,
+        now: o.now ?? Date.now(),
+        working: true,
+        dataOf: () => o.data,
+        sourcesOf: (types) => Object.fromEntries((types ?? []).map((t) => [t, o.sources?.[t]])),
+        preview: true,
+        demo: o.data === undefined,
+        demoOptions: !o.options || !Object.keys(o.options).length,
+        noShift: true,
+    });
+}

package/dist/config/check.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Validating a config: against its JSON Schema (shape, types, known widget
+ * types and option values) and against what `normalize` makes of it (ids,
+ * tiles that fit the grid and don't overlap, sizes widgets need, option
+ * names no plugin knows). Errors make Kiosko misbehave or lose something;
+ * warnings are worth a look but harmless.
+ *
+ * The messages carry a JSON path and say what to change, so a user can paste
+ * them back to the AI that wrote the file. Pure (no Node).
+ */
+import type { PluginDefinition } from '@kiosko/sdk';
+import { type JsonIssue, type JsonSchema } from './jsonschema.ts';
+export interface ConfigReport {
+    errors: JsonIssue[];
+    warnings: JsonIssue[];
+}
+/** What the schema can't say: checked on `normalize(raw)`, with paths into `raw` (normalize keeps every list's order). */
+export declare function checkConfig(raw: unknown, plugins: readonly PluginDefinition[]): ConfigReport;
+/** Schema errors, then what only `normalize` reveals. `schema` defaults to the one of `plugins`. */
+export declare function validateConfig(raw: unknown, plugins: readonly PluginDefinition[], schema?: JsonSchema): ConfigReport;