@kiosko/core 0.0.0-stage → 0.1.0

package/dist/compositor.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 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 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;
+}
+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 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;
+}>;
+/** 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,292 @@
+/**
+ * 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) {
+    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 draw = (tg) => drawTileContent(tg, input, r, rect, chrome, out);
+    if (!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 } : {}) });
+}
+function drawTileContent(g, input, r, rect, chrome, out) {
+    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 [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,
+    };
+    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 = [];
+    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);
+    }
+    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 };
+}
+/** 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;

package/dist/config/check.js

@@ -0,0 +1,163 @@
+import { cellsFor, inBounds, overlaps, toPx } from "../layout/grid.js";
+import { closest, formatPath, toPointer, validateJson } from "./jsonschema.js";
+import { zoomOf } from "./model.js";
+import { normalize } from "./normalize.js";
+import { configSchema, TYPE_PATTERN } from "./schema.js";
+import { sourceOptionsField } from "./sources.js";
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+const issue = (path, message, context) => ({ path: formatPath(path), pointer: toPointer(path), message, ...(context ? { context } : {}) });
+const near = (word, names) => {
+    const c = closest(word, names);
+    return c.length ? ` (did you mean ${c.map((x) => JSON.stringify(x)).join(' or ')}?)` : '';
+};
+/** Option names a plugin doesn't know (typos, invented ones): ignored by Kiosko, so worth a warning. */
+function unknownOptions(f, v, path, out, owner) {
+    if (f.kind === 'object' && isObj(v)) {
+        const props = f.props;
+        const names = Object.keys(props);
+        for (const [k, x] of Object.entries(v)) {
+            const sub = props[k];
+            if (sub)
+                unknownOptions(sub, x, [...path, k], out, owner);
+            else
+                out.push(issue([...path, k], `is not an option of ${owner}${near(k, names)}, so it is ignored. Its options: ${names.join(', ') || 'none'}`, owner));
+        }
+    }
+    else if (f.kind === 'list' && Array.isArray(v))
+        v.forEach((x, i) => unknownOptions(f.item, x, [...path, i], out, owner));
+}
+const validGrid = (g) => isObj(g) && ['cols', 'rows', 'gap', 'padding'].every((k) => Number.isInteger(g[k])) && g.cols >= 1 && g.rows >= 1;
+const validRect = (t) => isObj(t) && ['x', 'y', 'w', 'h'].every((k) => Number.isInteger(t[k]));
+function repeated(items, path, what, out) {
+    const seen = new Map();
+    items.forEach((x, i) => {
+        if (!isObj(x) || typeof x.id !== 'string')
+            return;
+        const first = seen.get(x.id);
+        if (first !== undefined)
+            out.push(issue([...path, i, 'id'], `repeats the id ${JSON.stringify(x.id)} of ${formatPath([...path, first])}: ${what} ids must be unique`));
+        else
+            seen.set(x.id, i);
+    });
+}
+/** What the schema can't say: checked on `normalize(raw)`, with paths into `raw` (normalize keeps every list's order). */
+export function checkConfig(raw, plugins) {
+    const errors = [];
+    const warnings = [];
+    if (!isObj(raw))
+        return { errors: [issue([], 'the config must be a JSON object')], warnings };
+    let cfg;
+    try {
+        cfg = normalize(raw);
+    }
+    catch {
+        // Lists where objects should be (or the other way round): the schema errors say where.
+        return { errors, warnings };
+    }
+    const widgets = new Map(plugins.flatMap((p) => (p.widgets ?? []).map((w) => [`${p.id}/${w.id}`, w])));
+    const sources = new Map(plugins.flatMap((p) => (p.sources ?? []).map((s) => [`${p.id}/${s.id}`, s])));
+    const interludes = new Map(plugins.flatMap((p) => (p.interludes ?? []).map((i) => [`${p.id}/${i.id}`, i])));
+    const pluginIds = plugins.map((p) => p.id);
+    const disabled = new Set(Array.isArray(cfg.plugins.disabled) ? cfg.plugins.disabled : []);
+    const widgetIds = new Map();
+    if (!Array.isArray(cfg.screens))
+        return { errors, warnings };
+    repeated(cfg.screens, ['screens'], 'screen', errors);
+    cfg.screens.forEach((s, si) => {
+        const sp = ['screens', si];
+        if (!isObj(s) || !Array.isArray(s.pages))
+            return;
+        repeated(s.pages, [...sp, 'pages'], 'page', errors);
+        if (!s.pages.length)
+            warnings.push(issue([...sp, 'pages'], 'the screen has no pages, so it shows nothing'));
+        if (s.pinnedPage && !s.pages.some((p) => p.id === s.pinnedPage))
+            errors.push(issue([...sp, 'pinnedPage'], `names no page of this screen; its pages are ${s.pages.map((p) => JSON.stringify(p.id)).join(', ') || 'none'}`));
+        s.pages.forEach((p, pi) => {
+            const pp = [...sp, 'pages', pi];
+            if (!isObj(p) || !Array.isArray(p.tiles))
+                return;
+            repeated(p.tiles, [...pp, 'tiles'], 'tile', errors);
+            const grid = validGrid(p.grid) ? p.grid : null;
+            p.tiles.forEach((t, ti) => {
+                const tp = [...pp, 'tiles', ti];
+                if (!isObj(t))
+                    return;
+                const geometry = grid && validRect(t) && Number.isInteger(s.width) && Number.isInteger(s.height);
+                if (geometry && !inBounds(t, grid)) {
+                    const past = [t.x + t.w > grid.cols && `x + w = ${t.x + t.w} but the grid has ${grid.cols} columns`, t.y + t.h > grid.rows && `y + h = ${t.y + t.h} but the grid has ${grid.rows} rows`, (t.x < 0 || t.y < 0) && 'x and y start at 0', (t.w < 1 || t.h < 1) && 'w and h are at least 1'].filter(Boolean);
+                    errors.push(issue(tp, `does not fit the ${grid.cols}×${grid.rows} grid: ${past.join('; ')}`));
+                }
+                if (geometry) {
+                    p.tiles.forEach((o, oi) => {
+                        if (oi > ti && isObj(o) && validRect(o) && overlaps(t, o))
+                            warnings.push(issue(tp, `overlaps ${formatPath([...pp, 'tiles', oi])} (${JSON.stringify(o.id)}): one hides part of the other; move or shrink one`));
+                    });
+                }
+                if (!Array.isArray(t.widgets))
+                    return;
+                if (!t.widgets.length)
+                    warnings.push(issue([...tp, 'widgets'], 'the tile has no widgets, so it stays empty'));
+                t.widgets.forEach((w, wi) => {
+                    const wp = [...tp, 'widgets', wi];
+                    if (!isObj(w))
+                        return;
+                    if (typeof w.id === 'string') {
+                        const first = widgetIds.get(w.id);
+                        if (first)
+                            errors.push(issue([...wp, 'id'], `repeats the id ${JSON.stringify(w.id)} of ${formatPath(first)}: widget ids must be unique in the whole config`));
+                        else
+                            widgetIds.set(w.id, wp);
+                    }
+                    const def = typeof w.type === 'string' ? widgets.get(w.type) : undefined;
+                    if (!def)
+                        return; // unknown types are schema errors
+                    const plugin = w.type.split('/')[0];
+                    if (disabled.has(plugin))
+                        warnings.push(issue(wp, `its plugin ${JSON.stringify(plugin)} is switched off in plugins.disabled, so it won't show`, w.type));
+                    const zoom = zoomOf(w);
+                    const min = def.size?.min && { w: Math.ceil(def.size.min.w * zoom), h: Math.ceil(def.size.min.h * zoom) };
+                    if (min && geometry) {
+                        const px = toPx(t, grid, s.width, s.height);
+                        if (px.w < min.w || px.h < min.h) {
+                            const need = cellsFor(min, grid, s.width, s.height);
+                            warnings.push(issue(tp, `is ${px.w}×${px.h} px but ${w.type} needs at least ${min.w}×${min.h} px${zoom !== 1 ? ` at zoom ${zoom}` : ''}: make it at least ${Math.max(need.w, t.w)}×${Math.max(need.h, t.h)} cells (w×h)${zoom !== 1 ? ' or lower its zoom' : ''}`, w.type));
+                        }
+                    }
+                    if (def.options)
+                        unknownOptions(def.options, w.options, [...wp, 'options'], warnings, w.type);
+                });
+            });
+        });
+        if (!Array.isArray(s.interludes))
+            return;
+        repeated(s.interludes, [...sp, 'interludes'], 'interlude', errors);
+        s.interludes.forEach((x, xi) => {
+            const def = isObj(x) && typeof x.type === 'string' ? interludes.get(x.type) : undefined;
+            if (def?.options)
+                unknownOptions(def.options, x.options, [...sp, 'interludes', xi, 'options'], warnings, x.type);
+        });
+    });
+    if (isObj(cfg.sources)) {
+        for (const [type, opts] of Object.entries(cfg.sources)) {
+            const def = sources.get(type);
+            const field = def && sourceOptionsField(def);
+            if (field)
+                unknownOptions(field, opts, ['sources', type], warnings, type);
+            else if (!def && new RegExp(TYPE_PATTERN).test(type))
+                warnings.push(issue(['sources', type], `no installed plugin provides this source, so it is ignored${near(type, [...sources.keys()])}`));
+        }
+    }
+    if (Array.isArray(cfg.plugins.disabled)) {
+        cfg.plugins.disabled.forEach((id, i) => {
+            if (typeof id === 'string' && !pluginIds.includes(id))
+                warnings.push(issue(['plugins', 'disabled', i], `no installed plugin is called ${JSON.stringify(id)}${near(id, pluginIds)}`));
+        });
+    }
+    return { errors, warnings };
+}
+/** Schema errors, then what only `normalize` reveals. `schema` defaults to the one of `plugins`. */
+export function validateConfig(raw, plugins, schema = configSchema(plugins)) {
+    const shape = validateJson(schema, raw);
+    const more = checkConfig(raw, plugins);
+    return { errors: [...shape, ...more.errors], warnings: more.warnings };
+}

package/dist/config/diff.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A short, readable summary of what changes between two configs: screens,
+ * pages and tiles added or removed, sources and settings changed. For
+ * `kiosko config import`, so a config written elsewhere can be reviewed
+ * before it replaces the current one. Never prints option values (they may
+ * be secrets), only which ones changed. Pure (no Node).
+ */
+import type { Config } from './model.ts';
+export interface DiffLine {
+    /** Nesting: 0 for screens, sources and settings, 1 for pages, 2 for tiles. */
+    depth: number;
+    op: '+' | '-' | '~';
+    kind: 'setting' | 'source' | 'screen' | 'page' | 'tile' | 'interlude';
+    text: string;
+}
+export declare function diffConfigs(before: Config, after: Config): DiffLine[];
+/** "1 screen added, 3 pages added, 5 tiles removed, 1 source changed". */
+export declare function summarizeDiff(lines: readonly DiffLine[]): string;