@songsid/agend 2.2.0 → 2.3.0-beta.1

package/dist/web-appearance-limits.js

@@ -0,0 +1,83 @@
+/**
+ * #1629 r4.1 Q3 (b): the identity card's upload limits are fleet configuration (`web.appearance`), under hard bounds
+ * no configuration passes. r4's numbers are the defaults. A value outside its bound is clamped and said so (the config
+ * validator's warnings: `agend doctor`, the fleet log at startup, Settings); one out-of-range number never stops the
+ * fleet. A limit applies to new uploads only: nothing stored is ever checked again or deleted because a limit moved.
+ */
+const KIB = 1024, MIB = 1024 * 1024;
+/** r4 §1's numbers, in `web.appearance`'s own units. */
+export const APPEARANCE_DEFAULTS = {
+    portrait: { max_width: 1024, max_height: 1536, max_kib: 1536 },
+    banner: { max_width: 1600, max_height: 600, max_kib: 768 },
+    instance_quota: { files: 8, mib: 4 },
+};
+/** [floor, ceiling] per setting (r4.1 Q3 (b)). */
+export const APPEARANCE_BOUNDS = {
+    portrait: { max_width: [64, 2048], max_height: [64, 3072], max_kib: [32, 4096] },
+    banner: { max_width: [64, 3200], max_height: [64, 1200], max_kib: [32, 2048] },
+    instance_quota: { files: [2, 16], mib: [1, 16] },
+};
+/**
+ * The limits in force for `config` (the fleet's `web.appearance`, possibly absent or malformed), and why any value
+ * differs from what was written. Unknown keys and wrong types are warned about and their defaults used.
+ */
+export function effectiveAppearanceLimits(config) {
+    const warnings = [];
+    const root = isObj(config) ? config : {};
+    if (config !== undefined && config !== null && !isObj(config))
+        warnings.push({ path: "web.appearance", message: "must be a mapping — the defaults are used" });
+    for (const k of Object.keys(root))
+        if (!Object.hasOwn(APPEARANCE_DEFAULTS, k))
+            warnings.push({ path: `web.appearance.${k}`, message: `unknown key (known: ${Object.keys(APPEARANCE_DEFAULTS).join(", ")}) — ignored` });
+    const read = (group) => {
+        const defaults = APPEARANCE_DEFAULTS[group];
+        const bounds = APPEARANCE_BOUNDS[group];
+        const raw = Object.hasOwn(root, group) ? root[group] : undefined;
+        const given = isObj(raw) ? raw : {};
+        if (raw !== undefined && !isObj(raw))
+            warnings.push({ path: `web.appearance.${group}`, message: "must be a mapping — the defaults are used" });
+        for (const k of Object.keys(given))
+            if (!Object.hasOwn(defaults, k))
+                warnings.push({ path: `web.appearance.${group}.${k}`, message: `unknown key (known: ${Object.keys(defaults).join(", ")}) — ignored` });
+        const out = {};
+        for (const [k, def] of Object.entries(defaults)) {
+            const path = `web.appearance.${group}.${k}`;
+            const v = Object.hasOwn(given, k) ? given[k] : undefined;
+            if (v === undefined) {
+                out[k] = def;
+                continue;
+            }
+            if (typeof v !== "number" || !Number.isInteger(v)) {
+                warnings.push({ path, message: `must be a whole number — the default ${def} is used` });
+                out[k] = def;
+                continue;
+            }
+            const [floor, ceiling] = bounds[k];
+            if (v < floor) {
+                warnings.push({ path, message: `${v} is below the floor ${floor} — ${floor} is used` });
+                out[k] = floor;
+                continue;
+            }
+            if (v > ceiling) {
+                warnings.push({ path, message: `${v} is above the ceiling ${ceiling} — ${ceiling} is used` });
+                out[k] = ceiling;
+                continue;
+            }
+            out[k] = v;
+        }
+        return out;
+    };
+    const p = read("portrait"), b = read("banner"), q = read("instance_quota");
+    return {
+        limits: {
+            portrait: { maxWidth: p.max_width, maxHeight: p.max_height, maxBytes: p.max_kib * KIB },
+            banner: { maxWidth: b.max_width, maxHeight: b.max_height, maxBytes: b.max_kib * KIB },
+            quota: { files: q.files, bytes: q.mib * MIB },
+        },
+        warnings,
+    };
+}
+function isObj(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+//# sourceMappingURL=web-appearance-limits.js.map

package/dist/web-appearance-limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-appearance-limits.js","sourceRoot":"","sources":["../src/web-appearance-limits.ts"],"names":[],"mappings":"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"}

package/dist/web-appearance-policy.d.ts

@@ -0,0 +1,66 @@
+/**
+ * #1629: the one rate limiter for every agent appearance write — theme, effect, widget and mod (r2 (c), r4) — and the
+ * fleet-wide switch. Shared by the theme tools (B1) and the effect tools (B2): one budget per instance, not one each.
+ *
+ * - change: at least 30 s between accepted changes and at most 10 in a rolling hour (set_web_theme, apply/remove of an
+ *   effect or widget, an agent's own reset);
+ * - upload: at most 3 in a rolling hour (theme assets, effects and widgets, proposed mods together);
+ * - data: a placed widget's new values (r4-4) — at least 10 s apart and at most 180 in a rolling hour, a budget of its
+ *   own, so a widget showing progress never spends the theme's changes.
+ *
+ * Only accepted calls count: a handler asks `check` before it validates, and `record`s only after its write is on
+ * disk, all in one synchronous stretch (a refused or invalid call, or a failed write, costs nothing). The clock is
+ * monotonic, so a wall-clock jump neither opens nor closes the window; a fleet restart clears it (documented).
+ * The human's reset, lock and removals are never limited.
+ */
+export type AppearanceBucket = "change" | "upload" | "data";
+export declare const APPEARANCE_LIMITS: {
+    readonly changeGapMs: 30000;
+    readonly changesPerHour: 10;
+    readonly uploadsPerHour: 3;
+    readonly dataGapMs: 10000;
+    readonly dataPerHour: 180;
+};
+export type LimitVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    error: "rate_limited";
+    retry_after_s: number;
+};
+export declare class AppearanceLimiter {
+    private readonly now;
+    private readonly limits;
+    private readonly changes;
+    private readonly uploads;
+    private readonly data;
+    constructor(now?: () => number, limits?: {
+        readonly changeGapMs: 30000;
+        readonly changesPerHour: 10;
+        readonly uploadsPerHour: 3;
+        readonly dataGapMs: 10000;
+        readonly dataPerHour: 180;
+    });
+    private recent;
+    private waitMs;
+    /** Would these buckets admit a call now? Changes nothing. */
+    check(instance: string, buckets: readonly AppearanceBucket[]): LimitVerdict;
+    /** Count an accepted call — only after its write succeeded. */
+    record(instance: string, buckets: readonly AppearanceBucket[]): void;
+    /** What an agent sees in get_web_theme (and B2's tools): what is left, and when the next change may come. */
+    remaining(instance: string): {
+        changes: number;
+        uploads: number;
+        retry_after_s: number;
+        widget_data: number;
+        widget_data_retry_after_s: number;
+    };
+    /** An instance removed: its counters go with it. */
+    forget(instance: string): void;
+}
+/** `web.themes.agent_edit` (default true): false turns every agent appearance write off, fleet-wide; stored choices stay. */
+export declare function agentAppearanceEditAllowed(web: {
+    themes?: {
+        agent_edit?: boolean;
+    };
+} | undefined | null): boolean;

package/dist/web-appearance-policy.js

@@ -0,0 +1,94 @@
+/**
+ * #1629: the one rate limiter for every agent appearance write — theme, effect, widget and mod (r2 (c), r4) — and the
+ * fleet-wide switch. Shared by the theme tools (B1) and the effect tools (B2): one budget per instance, not one each.
+ *
+ * - change: at least 30 s between accepted changes and at most 10 in a rolling hour (set_web_theme, apply/remove of an
+ *   effect or widget, an agent's own reset);
+ * - upload: at most 3 in a rolling hour (theme assets, effects and widgets, proposed mods together);
+ * - data: a placed widget's new values (r4-4) — at least 10 s apart and at most 180 in a rolling hour, a budget of its
+ *   own, so a widget showing progress never spends the theme's changes.
+ *
+ * Only accepted calls count: a handler asks `check` before it validates, and `record`s only after its write is on
+ * disk, all in one synchronous stretch (a refused or invalid call, or a failed write, costs nothing). The clock is
+ * monotonic, so a wall-clock jump neither opens nor closes the window; a fleet restart clears it (documented).
+ * The human's reset, lock and removals are never limited.
+ */
+export const APPEARANCE_LIMITS = { changeGapMs: 30_000, changesPerHour: 10, uploadsPerHour: 3, dataGapMs: 10_000, dataPerHour: 180 };
+const HOUR_MS = 60 * 60 * 1000;
+export class AppearanceLimiter {
+    now;
+    limits;
+    changes = new Map();
+    uploads = new Map();
+    data = new Map();
+    constructor(now = () => performance.now(), limits = APPEARANCE_LIMITS) {
+        this.now = now;
+        this.limits = limits;
+    }
+    recent(map, instance, now) {
+        const kept = (map.get(instance) ?? []).filter(t => now - t < HOUR_MS);
+        if (kept.length)
+            map.set(instance, kept);
+        else
+            map.delete(instance);
+        return kept;
+    }
+    waitMs(instance, buckets, now) {
+        const waits = [];
+        if (buckets.includes("change")) {
+            const c = this.recent(this.changes, instance, now);
+            const last = c.at(-1);
+            if (last !== undefined && now - last < this.limits.changeGapMs)
+                waits.push(this.limits.changeGapMs - (now - last));
+            if (c.length >= this.limits.changesPerHour)
+                waits.push(HOUR_MS - (now - c[0]));
+        }
+        if (buckets.includes("upload")) {
+            const u = this.recent(this.uploads, instance, now);
+            if (u.length >= this.limits.uploadsPerHour)
+                waits.push(HOUR_MS - (now - u[0]));
+        }
+        if (buckets.includes("data")) {
+            const d = this.recent(this.data, instance, now);
+            const last = d.at(-1);
+            if (last !== undefined && now - last < this.limits.dataGapMs)
+                waits.push(this.limits.dataGapMs - (now - last));
+            if (d.length >= this.limits.dataPerHour)
+                waits.push(HOUR_MS - (now - d[0]));
+        }
+        return waits.length ? Math.max(...waits) : 0;
+    }
+    /** Would these buckets admit a call now? Changes nothing. */
+    check(instance, buckets) {
+        const wait = this.waitMs(instance, buckets, this.now());
+        return wait > 0 ? { ok: false, error: "rate_limited", retry_after_s: Math.ceil(wait / 1000) } : { ok: true };
+    }
+    /** Count an accepted call — only after its write succeeded. */
+    record(instance, buckets) {
+        const now = this.now();
+        if (buckets.includes("change"))
+            this.changes.set(instance, [...this.recent(this.changes, instance, now), now]);
+        if (buckets.includes("upload"))
+            this.uploads.set(instance, [...this.recent(this.uploads, instance, now), now]);
+        if (buckets.includes("data"))
+            this.data.set(instance, [...this.recent(this.data, instance, now), now]);
+    }
+    /** What an agent sees in get_web_theme (and B2's tools): what is left, and when the next change may come. */
+    remaining(instance) {
+        const now = this.now();
+        return {
+            changes: Math.max(0, this.limits.changesPerHour - this.recent(this.changes, instance, now).length),
+            uploads: Math.max(0, this.limits.uploadsPerHour - this.recent(this.uploads, instance, now).length),
+            retry_after_s: Math.ceil(this.waitMs(instance, ["change"], now) / 1000),
+            widget_data: Math.max(0, this.limits.dataPerHour - this.recent(this.data, instance, now).length),
+            widget_data_retry_after_s: Math.ceil(this.waitMs(instance, ["data"], now) / 1000),
+        };
+    }
+    /** An instance removed: its counters go with it. */
+    forget(instance) { this.changes.delete(instance); this.uploads.delete(instance); this.data.delete(instance); }
+}
+/** `web.themes.agent_edit` (default true): false turns every agent appearance write off, fleet-wide; stored choices stay. */
+export function agentAppearanceEditAllowed(web) {
+    return web?.themes?.agent_edit !== false;
+}
+//# sourceMappingURL=web-appearance-policy.js.map

package/dist/web-appearance-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-appearance-policy.js","sourceRoot":"","sources":["../src/web-appearance-policy.ts"],"names":[],"mappings":"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"}

package/dist/web-appearance-tools.d.ts

@@ -0,0 +1,50 @@
+import { type AppearanceInput, type FrameEntry } from "./web-appearance-view.js";
+import type { ResolvedCard } from "./web-card.js";
+import type { Theme } from "./web-theme.js";
+type Picture = {
+    bytes: Buffer;
+    mime: string;
+} | null;
+export interface AppearanceDeps {
+    frame(name: string): FrameEntry;
+    theme(name: string): {
+        theme: Theme;
+        locked: boolean;
+        widgets?: AppearanceInput["widgets"];
+    };
+    card(name: string): ResolvedCard;
+    /** The resolved card's picture for a slot (the person's, else the agent's). */
+    cardPicture(name: string, slot: "portrait" | "banner"): Picture;
+    themeAsset(name: string, id: string): Picture;
+    profileAvatar(name: string): Picture;
+    botAvatar(name: string, key: string): Picture;
+    /** get_web_theme's agent_edit and limits (one source for both tools). */
+    themeAnswer(name: string): {
+        agent_edit?: unknown;
+        limits?: unknown;
+    };
+    /** #1958: the host's identity-colour settings (web prefs color.show / color.off), for the colour view. */
+    colorPrefs?(): {
+        show?: unknown;
+        off?: boolean;
+    };
+    clock?: () => number;
+}
+/** A preview whose files (base64) fit one message is sent whole; a larger one is fetched in parts. */
+export declare const PREVIEW_INLINE_BYTES: number;
+export declare const PREVIEW_IDLE_MS = 60000;
+export declare class AppearanceTools {
+    private readonly deps;
+    private readonly previews;
+    constructor(deps: AppearanceDeps);
+    private now;
+    private input;
+    /** The face drawn, as bytes of this instance's: the theme's picture, the person's upload, or its own bot's. */
+    private avatar;
+    handle(name: string, tool: string, args: Record<string, unknown>): Record<string, unknown>;
+    /** One part of the caller's own preview in progress (its id, a file it holds, an index in range, not gone stale). */
+    private part;
+    /** An instance was removed. */
+    forget(name: string): void;
+}
+export {};

package/dist/web-appearance-tools.js

@@ -0,0 +1,105 @@
+/**
+ * #1629 r4 §1: get_web_appearance and preview_web_appearance, on the fleet's side. Both read only the caller's own
+ * record (no target), through resolvers the fleet passes in — the status frame's entry, the theme, the card, this
+ * instance's pictures. The preview's files are bytes for the daemon or the CLI to write in the agent's working
+ * directory (the fleet never names a path); a preview larger than one message is handed over in parts.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { appearanceView, PICTURE_ROLES, pictureFileName, previewSvg } from "./web-appearance-view.js";
+import { ASSET_PART_BYTES } from "./web-asset-parts.js";
+/** A preview whose files (base64) fit one message is sent whole; a larger one is fetched in parts. */
+export const PREVIEW_INLINE_BYTES = 600 * 1024;
+export const PREVIEW_IDLE_MS = 60_000;
+const MODES = ["light", "dark"];
+export class AppearanceTools {
+    deps;
+    previews = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    now() { return (this.deps.clock ?? (() => performance.now()))(); }
+    input(name) {
+        const entry = this.deps.frame(name);
+        const t = this.deps.theme(name);
+        const answer = this.deps.themeAnswer(name);
+        return { entry, theme: t.theme, card: this.deps.card(name), locked: t.locked, agentEdit: answer.agent_edit !== false, limits: (answer.limits ?? {}), widgets: t.widgets,
+            colorPrefs: this.deps.colorPrefs?.() ?? {} };
+    }
+    /** The face drawn, as bytes of this instance's: the theme's picture, the person's upload, or its own bot's. */
+    avatar(name, input) {
+        const e = input.entry;
+        if (e.theme_avatar?.kind === "image" && input.theme.avatar)
+            return this.deps.themeAsset(name, input.theme.avatar);
+        const src = e.avatar?.kind === "image" ? e.avatar.src ?? "" : "";
+        if (src.startsWith("/ui/img/avatar/"))
+            return this.deps.profileAvatar(name);
+        const bot = /^\/ui\/img\/bot\/([^/?#]+)/.exec(src);
+        if (bot) {
+            try {
+                return this.deps.botAvatar(name, decodeURIComponent(bot[1]));
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+    handle(name, tool, args) {
+        const now = this.now();
+        for (const [k, b] of this.previews)
+            if (now - b.last > PREVIEW_IDLE_MS)
+                this.previews.delete(k); // nothing stale stays
+        if (tool === "get_web_appearance")
+            return appearanceView(this.input(name));
+        if (tool !== "preview_web_appearance")
+            return { error: "unknown_tool" };
+        if (args.part !== undefined)
+            return this.part(name, args.part, now);
+        const modes = args.modes === undefined ? MODES : args.modes;
+        if (!Array.isArray(modes) || !modes.length || modes.length > 2 || !modes.every(m => m === "light" || m === "dark") || new Set(modes).size !== modes.length) {
+            return { error: "modes", message: "modes: light and/or dark" };
+        }
+        const input = this.input(name);
+        const bytes = {
+            avatar: this.avatar(name, input),
+            portrait: input.card.portrait ? this.deps.cardPicture(name, "portrait") : null,
+            banner: input.card.banner ? this.deps.cardPicture(name, "banner") : null,
+            background: input.theme.background ? this.deps.themeAsset(name, input.theme.background.image) : null,
+        };
+        // Each picture is its own file next to the SVGs (#1890 review: inside, they outgrew what an agent's Read takes).
+        const names = {};
+        const files = [];
+        const add = (fileName, data) => files.push({ name: fileName, data, sha256: createHash("sha256").update(data).digest("hex") });
+        for (const role of PICTURE_ROLES) {
+            const p = bytes[role], fileName = p ? pictureFileName(role, p.mime) : null;
+            names[role] = fileName;
+            if (p && fileName)
+                add(fileName, p.bytes);
+        }
+        for (const mode of modes)
+            add(`${mode}.svg`, Buffer.from(previewSvg(input, mode, names), "utf8"));
+        const total = files.reduce((n, f) => n + f.data.length, 0);
+        if (total <= PREVIEW_INLINE_BYTES)
+            return { files: files.map(f => ({ name: f.name, data_b64: f.data.toString("base64") })) };
+        const built = { id: randomBytes(8).toString("hex"), files, last: now };
+        this.previews.set(name, built); // one per instance: a new preview replaces it
+        return { preview: built.id, files: files.map(f => ({ name: f.name, bytes: f.data.length, sha256: f.sha256, parts: Math.ceil(f.data.length / ASSET_PART_BYTES) })) };
+    }
+    /** One part of the caller's own preview in progress (its id, a file it holds, an index in range, not gone stale). */
+    part(name, raw, now) {
+        const p = raw;
+        const b = this.previews.get(name);
+        if (!p || typeof p !== "object" || !b || p.preview !== b.id)
+            return { error: "preview", message: "No such preview: ask for it again." };
+        const f = b.files.find(x => x.name === p.name);
+        const count = f ? Math.ceil(f.data.length / ASSET_PART_BYTES) : 0;
+        if (!f || !Number.isSafeInteger(p.index) || p.index < 0 || p.index >= count)
+            return { error: "part", message: "No such part." };
+        b.last = now; // a preview being fetched stays while it is
+        const i = p.index;
+        return { data_b64: f.data.subarray(i * ASSET_PART_BYTES, (i + 1) * ASSET_PART_BYTES).toString("base64") };
+    }
+    /** An instance was removed. */
+    forget(name) { this.previews.delete(name); }
+}
+//# sourceMappingURL=web-appearance-tools.js.map

package/dist/web-appearance-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-appearance-tools.js","sourceRoot":"","sources":["../src/web-appearance-tools.ts"],"names":[],"mappings":"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"}

package/dist/web-appearance-view.d.ts

@@ -0,0 +1,99 @@
+/**
+ * #1629 r4 §1: the agent's read-only view of how it appears on the dashboard — `get_web_appearance` (what the page
+ * draws now, resolved exactly as the status frame resolves it) and `preview_web_appearance` (an SVG per mode, built
+ * from the page's own layout numbers). Pure: the fleet passes in what it already resolved; nothing here reads a file,
+ * a path or another instance.
+ *
+ * The SVG names only this instance's pictures, as side files next to it (`avatar.png`, …: #1890 review — an SVG with a
+ * picture inside outgrew what an agent's Read takes); text is XML-escaped; colours are checked again; fonts are generic
+ * families. No browser, no live session, no other instance's content.
+ */
+import { type IdentityColorSource, type IdentityColorTiers, type Placement, type PlacementSource, type PlacementTiers } from "./web-identity-color.js";
+import { type Palette, type Theme, type ThemeMode } from "./web-theme.js";
+import type { ResolvedCard } from "./web-card.js";
+export type AvatarSource = "profile" | "theme" | "bot" | "emoji" | "initial";
+/** The status frame's entry for one instance (getUiStatus): the fields the page draws a face and a ring from. */
+export interface FrameEntry {
+    name: string;
+    display_name?: string;
+    avatar?: {
+        kind: string;
+        src?: string;
+        text?: string;
+        alt?: string;
+    };
+    accent?: string;
+    theme_avatar?: {
+        kind: string;
+        src?: string;
+    };
+    theme_accent?: string;
+    /** #1958: the identity colour's tiers and its placements' (getUiStatus). */
+    color?: IdentityColorTiers;
+    color_show?: PlacementTiers;
+}
+/**
+ * #1958: the identity colour drawn for this instance while agents' themes are shown, where it comes from, its value on
+ * a light and a dark page, where it shows (and whose choice that is), and whether the host turned colours off — what
+ * the agent needs to know: a person's choice wins over its own (theme.identity), field by field.
+ */
+export declare function resolvedIdentityColor(e: FrameEntry, host?: {
+    show?: unknown;
+    off?: boolean;
+}): {
+    color: string;
+    source: IdentityColorSource;
+    light: string;
+    dark: string;
+    show: Placement[];
+    show_source: PlacementSource;
+    off: boolean;
+};
+/** The face the page draws while agents' themes are shown (the default), and where it comes from. */
+export declare function resolvedAvatar(e: FrameEntry): {
+    source: AvatarSource;
+    url?: string;
+    text?: string;
+};
+/** The ring the page draws round a picture face: the theme's colour, else an own bot's; none for an emoji or initial. */
+export declare function resolvedRing(e: FrameEntry): {
+    color: string;
+    source: "theme" | "bot";
+} | null;
+/** The effective look per mode: the palette over the token defaults, and the fixed choices. */
+export declare function effectiveTheme(theme: Theme): Record<ThemeMode, Required<Palette> & {
+    font: string;
+    bubbleRadius: number;
+    bubbleBorder: string;
+}>;
+export interface AppearanceInput {
+    entry: FrameEntry;
+    theme: Theme;
+    card: ResolvedCard;
+    locked: boolean;
+    agentEdit: boolean;
+    limits: Record<string, unknown>;
+    /** #1958: the host's identity-colour settings (color.show / color.off). */
+    colorPrefs?: {
+        show?: unknown;
+        off?: boolean;
+    };
+    /** r4-4: its placed widgets, by slot. */
+    widgets?: Partial<Record<"chat_header" | "details", {
+        spec: unknown;
+        data: unknown;
+        by: string;
+    }>>;
+}
+/** get_web_appearance's answer. Effects: none can be applied yet (they wait on the effects runtime). */
+export declare function appearanceView(i: AppearanceInput): Record<string, unknown>;
+export declare const PICTURE_ROLES: readonly ["avatar", "portrait", "banner", "background"];
+export type PictureRole = typeof PICTURE_ROLES[number];
+/** This instance's pictures by role, as the side files' names (null: none). */
+export type PreviewPictures = Record<PictureRole, string | null>;
+/** A side file's name for a picture of this role and type, or null for a type no page shows. */
+export declare function pictureFileName(role: PictureRole, mime: string): string | null;
+/** Every name a preview writes: an SVG per mode, and the pictures it names. */
+export declare const PREVIEW_FILE: RegExp;
+/** One mode's SVG. Every picture is one of `pics` (this instance's), inline; nothing else is referenced. */
+export declare function previewSvg(i: AppearanceInput, mode: ThemeMode, pics: PreviewPictures): string;