@oharness/server 0.10.0 → 0.11.0

package/dist/theme-store.js

@@ -0,0 +1,124 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { userPath } from "@oharness/engine/paths.ts";
+import { parseJson } from "@oharness/engine/util/json.ts";
+import { renameWithRetry } from "@oharness/engine/util/fs.ts";
+import { pruneAssets } from "./theme-assets.js";
+import { resolveTheme, themeAssets, themeCss } from "./user-theme.js";
+const MAX_HISTORY = 10;
+const MAX_UNDO = 20;
+const FILE = () => userPath("theme.json");
+export class ThemeStore {
+    file = { version: 1, active: null, history: [], undo: [] };
+    resolved;
+    static async load() {
+        const store = new ThemeStore();
+        try {
+            const parsed = parseJson(await readFile(FILE(), "utf8"));
+            if (parsed.ok)
+                store.file = clean(parsed.value);
+        }
+        catch {
+            // No file yet, or one that cannot be read: the built-in theme.
+        }
+        store.resolveActive();
+        // Images no theme in the history uses any more. In the background: a slow
+        // disk must not hold up the page.
+        void pruneAssets(store.file.history.flatMap((h) => themeAssets(h.input)));
+        return store;
+    }
+    state() {
+        const entry = this.activeEntry();
+        return {
+            active: entry && this.resolved ? { id: entry.id, name: entry.name } : null,
+            css: this.resolved ? themeCss(this.resolved) : "",
+            canUndo: this.file.undo.length > 0,
+            history: this.file.history.map((h) => ({ id: h.id, name: h.name, appliedAt: h.appliedAt, active: h.id === this.file.active })),
+        };
+    }
+    /** The active theme as given, for the model to start a revision from. */
+    activeInput() {
+        return this.resolved ? this.activeEntry()?.input : undefined;
+    }
+    async apply(input) {
+        const entry = { id: randomUUID(), name: input.name, appliedAt: Date.now(), input };
+        this.file.history = [entry, ...this.file.history].slice(0, MAX_HISTORY);
+        return this.moveTo(entry.id);
+    }
+    async applyHistory(id) {
+        if (!this.file.history.some((h) => h.id === id))
+            return undefined;
+        return this.moveTo(id);
+    }
+    async reset() {
+        return this.moveTo(null);
+    }
+    async undo() {
+        const previous = this.file.undo.pop();
+        if (previous === undefined)
+            return this.state();
+        // An entry pushed out of history since cannot be gone back to; the
+        // built-in theme always can.
+        this.file.active = previous && this.file.history.some((h) => h.id === previous) ? previous : null;
+        this.resolveActive();
+        await this.save();
+        return this.state();
+    }
+    async moveTo(id) {
+        if (id === this.file.active)
+            return this.state();
+        this.file.undo = [...this.file.undo, this.file.active].slice(-MAX_UNDO);
+        this.file.active = id;
+        this.resolveActive();
+        await this.save();
+        return this.state();
+    }
+    activeEntry() {
+        return this.file.history.find((h) => h.id === this.file.active);
+    }
+    resolveActive() {
+        const entry = this.activeEntry();
+        const result = entry ? resolveTheme(entry.input) : undefined;
+        this.resolved = result?.ok ? result.theme : undefined;
+    }
+    async save() {
+        const file = FILE();
+        await mkdir(path.dirname(file), { recursive: true });
+        tempSeq += 1;
+        const temp = `${file}.${process.pid}.${tempSeq}.tmp`;
+        await writeFile(temp, `${JSON.stringify(this.file, null, 2)}\n`, "utf8");
+        await renameWithRetry(temp, file);
+    }
+}
+let tempSeq = 0;
+/** Only the shape this module wrote; anything else is dropped, not trusted. */
+function clean(raw) {
+    const out = { version: 1, active: null, history: [], undo: [] };
+    if (typeof raw !== "object" || raw === null)
+        return out;
+    const body = raw;
+    if (Array.isArray(body["history"])) {
+        for (const item of body["history"]) {
+            if (typeof item !== "object" || item === null)
+                continue;
+            const h = item;
+            if (typeof h["id"] !== "string" || typeof h["input"] !== "object" || h["input"] === null)
+                continue;
+            out.history.push({
+                id: h["id"],
+                name: typeof h["name"] === "string" ? h["name"] : "Custom",
+                appliedAt: typeof h["appliedAt"] === "number" ? h["appliedAt"] : 0,
+                input: h["input"],
+            });
+        }
+    }
+    const ids = new Set(out.history.map((h) => h.id));
+    if (typeof body["active"] === "string" && ids.has(body["active"]))
+        out.active = body["active"];
+    if (Array.isArray(body["undo"])) {
+        out.undo = body["undo"].filter((v) => v === null || (typeof v === "string" && ids.has(v))).slice(-MAX_UNDO);
+    }
+    return out;
+}
+//# sourceMappingURL=theme-store.js.map

package/dist/theme-store.js.map

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

package/dist/theme-tools.d.ts

@@ -0,0 +1,25 @@
+import type { Tool } from "@oharness/engine/tools/types.ts";
+import type { ResolvedTheme, ThemeInput } from "./user-theme.ts";
+/**
+ * The agent's side of theming: learn what can change, and propose a theme.
+ *
+ * Proposing is all it can do. `set_theme` makes a preview card in the
+ * conversation and returns; the theme is applied only when the person clicks
+ * Apply on it. That is why the tool is read-only and needs no approval: the
+ * card is the approval, and it comes with the result in front of them rather
+ * than a description of it.
+ *
+ * Registered by the web server only. A terminal has no page to theme.
+ */
+export declare const GET_THEME_SCHEMA_TOOL = "get_theme_schema";
+export declare const SET_THEME_TOOL = "set_theme";
+export declare const RESET_THEME_TOOL = "reset_theme";
+export interface ThemeToolHost {
+    /** The theme in use as it was given, or undefined for the built-in one. */
+    activeInput(): ThemeInput | undefined;
+    /** Put a preview card in front of the person; returns its id. */
+    propose(sessionId: string, theme: ResolvedTheme): string;
+    /** Go back to the built-in theme; returns the name of the one it replaced. */
+    reset(): Promise<string | undefined>;
+}
+export declare function createThemeTools(host: ThemeToolHost): Tool[];

package/dist/theme-tools.js

@@ -0,0 +1,243 @@
+import path from "node:path";
+import { toolError, toolText } from "@oharness/engine/tools/types.ts";
+import { DARK, LIGHT } from "./theme.js";
+import { assetExists, importAsset } from "./theme-assets.js";
+import { ASSET_ID, IMAGE_SLOTS, SEEDS, TOKENS, describeReport, resolveTheme } from "./user-theme.js";
+/**
+ * The agent's side of theming: learn what can change, and propose a theme.
+ *
+ * Proposing is all it can do. `set_theme` makes a preview card in the
+ * conversation and returns; the theme is applied only when the person clicks
+ * Apply on it. That is why the tool is read-only and needs no approval: the
+ * card is the approval, and it comes with the result in front of them rather
+ * than a description of it.
+ *
+ * Registered by the web server only. A terminal has no page to theme.
+ */
+export const GET_THEME_SCHEMA_TOOL = "get_theme_schema";
+export const SET_THEME_TOOL = "set_theme";
+export const RESET_THEME_TOOL = "reset_theme";
+const paletteSchema = {
+    type: "object",
+    description: "Token → hex colour (#rrggbb, or #rrggbbaa for translucent non-seed tokens).",
+    additionalProperties: { type: "string" },
+};
+const imageRef = {
+    type: "string",
+    description: "Path to a PNG, JPEG or WebP file in the workspace (for example one you just generated), or an asset id already used by the current theme.",
+};
+const imagesSchema = {
+    type: "object",
+    description: "Optional images, by slot. Call get_theme_schema for what each slot is and its options.",
+    properties: {
+        conversation: {
+            type: "object",
+            properties: {
+                image: imageRef,
+                fit: { type: "string", enum: ["cover", "contain", "tile"] },
+                anchor: { type: "string", enum: ["top-left", "top", "top-right", "left", "center", "right", "bottom-left", "bottom", "bottom-right"] },
+                scrim: { type: "number", minimum: 0.5, maximum: 0.95 },
+                blend: { type: "string", enum: ["normal", "multiply", "screen", "luminosity", "soft-light"] },
+                dark: { type: "object", properties: { image: imageRef, scrim: { type: "number", minimum: 0.5, maximum: 0.95 } } },
+            },
+            required: ["image"],
+        },
+        empty: {
+            type: "object",
+            properties: { image: imageRef, size: { type: "string", enum: ["small", "medium", "large"] }, align: { type: "string", enum: ["left", "center"] } },
+            required: ["image"],
+        },
+        avatar: {
+            type: "object",
+            properties: { image: imageRef, shape: { type: "string", enum: ["circle", "rounded", "square"] } },
+            required: ["image"],
+        },
+    },
+    additionalProperties: false,
+};
+/**
+ * Turn every `image` the model named into a stored asset, in place, as
+ * `asset`. A file outside what the agent may read is refused by the same
+ * policy that guards its other tools; a file that is not a still image is
+ * refused by its bytes. Either way the slot is dropped and the reason is
+ * reported, and the rest of the theme still goes through.
+ */
+async function importImages(input, ctx) {
+    const problems = [];
+    if (typeof input !== "object" || input === null)
+        return { input, problems };
+    const copy = structuredClone(input);
+    const images = copy["images"];
+    if (typeof images !== "object" || images === null)
+        return { input: copy, problems };
+    const toAsset = async (where, slot) => {
+        // `asset` too: get_theme_schema shows the theme in use as stored, where
+        // an image is an asset id under that name, and a model revising it copies
+        // what it was shown.
+        const ref = slot["image"] ?? slot["asset"];
+        delete slot["image"];
+        delete slot["asset"];
+        if (typeof ref !== "string" || !ref.trim()) {
+            problems.push(`images.${where}: no image given`);
+            return false;
+        }
+        if (ASSET_ID.test(ref)) {
+            if (await assetExists(ref)) {
+                slot["asset"] = ref;
+                return true;
+            }
+            problems.push(`images.${where}: no stored asset ${ref}`);
+            return false;
+        }
+        let file;
+        try {
+            file = ctx.host?.resolvePath ? ctx.host.resolvePath(ref, "read") : path.resolve(ctx.cwd, ref);
+        }
+        catch (err) {
+            problems.push(`images.${where}: ${err instanceof Error ? err.message : String(err)}`);
+            return false;
+        }
+        const imported = await importAsset(file);
+        if (!imported.ok) {
+            problems.push(`images.${where}: ${imported.error}`);
+            return false;
+        }
+        slot["asset"] = imported.id;
+        return true;
+    };
+    for (const [name, value] of Object.entries(images)) {
+        if (typeof value !== "object" || value === null)
+            continue;
+        const slot = value;
+        if (!(await toAsset(name, slot))) {
+            delete images[name];
+            continue;
+        }
+        const dark = slot["dark"];
+        if (typeof dark === "object" && dark !== null && "image" in dark) {
+            if (!(await toAsset(`${name}.dark`, dark)))
+                delete dark["asset"];
+        }
+    }
+    return { input: copy, problems };
+}
+export function createThemeTools(host) {
+    const schemaTool = {
+        name: GET_THEME_SCHEMA_TOOL,
+        description: "Describe what the app's colour theme can change: the tokens, what each colours, the rules a theme must follow, and the theme in use now. Call this before set_theme.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        readOnly: true,
+        source: "builtin",
+        renderTitle: () => "Theme schema",
+        async execute() {
+            return toolText(schemaText(host.activeInput()));
+        },
+    };
+    const setTool = {
+        name: SET_THEME_TOOL,
+        description: [
+            "Propose a theme for this app's interface: colours, and optionally images in fixed slots (conversation background, empty-session art, assistant avatar). It is shown to the user as a preview card and is NOT applied until they click Apply.",
+            "Give the four seeds (bg, fg, accent, brand) for each side you change; everything else is derived from them. Override any other token only when the user asked for something specific.",
+            "Colours are hex only. Text colours that fail contrast are adjusted, and the result says what moved.",
+            "For an image, generate or find a PNG, JPEG or WebP file first and pass its path. Pick seed colours that suit the image.",
+            "Use only for the app's own look. Call get_theme_schema first.",
+        ].join(" "),
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "A short name for the theme, e.g. \"Ember\"." },
+                mode: {
+                    type: "string",
+                    enum: ["both", "light", "dark"],
+                    description: "both (default): follows the system and the light/dark switch. light or dark: always that side.",
+                },
+                light: paletteSchema,
+                dark: paletteSchema,
+                images: imagesSchema,
+            },
+            required: ["name"],
+            additionalProperties: false,
+        },
+        // Changes nothing by itself: see the header.
+        readOnly: true,
+        concurrencySafe: false,
+        source: "builtin",
+        renderTitle: (input) => {
+            const name = typeof input === "object" && input && typeof input.name === "string"
+                ? input.name
+                : "";
+            return name ? `Theme(${name})` : "Theme";
+        },
+        async execute(input, ctx) {
+            const imported = await importImages(input, ctx);
+            const result = resolveTheme(imported.input);
+            if (!result.ok) {
+                const why = [result.error, ...imported.problems].join("; ");
+                return toolError(`The theme was not accepted: ${why}. Call get_theme_schema for the format.`);
+            }
+            result.theme.report.dropped.unshift(...imported.problems);
+            const id = host.propose(ctx.sessionId, result.theme);
+            return toolText([
+                `A preview card for "${result.theme.input.name}" now follows your reply in the conversation. It is not applied: the user previews, applies or discards it from that card. Do not say the theme has changed, and do not say where on screen the card is.`,
+                describeReport(result.theme.report),
+            ].join("\n\n"), { themePreview: id });
+        },
+    };
+    /*
+     * The one theme tool that changes something by itself, and the reason it
+     * may: going back to the built-in look cannot make the app unreadable, and
+     * it is one click to undo from the account menu. Asking for approval to
+     * undo a theme the person wants gone would only stand in their way.
+     */
+    const resetTool = {
+        name: RESET_THEME_TOOL,
+        description: "Put the app back on its built-in theme, removing any custom colours and images. Use when the user asks to reset, restore the default look, or remove a custom theme. It takes effect at once and can be undone from the account menu.",
+        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+        readOnly: true,
+        concurrencySafe: false,
+        source: "builtin",
+        renderTitle: () => "Reset theme",
+        async execute() {
+            const was = await host.reset();
+            return toolText(was
+                ? `The built-in theme is back; "${was}" is no longer applied. The user can undo this from the account menu.`
+                : "The built-in theme was already in use; nothing changed.");
+        },
+    };
+    return [schemaTool, setTool, resetTool];
+}
+function schemaText(active) {
+    const tokens = Object.entries(TOKENS)
+        .map(([token, meaning]) => `- ${token}: ${meaning} Built-in: light ${LIGHT[token]}, dark ${DARK[token]}.`)
+        .join("\n");
+    return [
+        "The interface is coloured by a set of tokens with a light and a dark value each. A theme sets some of them; set_theme derives the rest.",
+        "",
+        `Seeds: ${SEEDS.join(", ")}. Give all four for each side you change. panel, frame, dim, line, hover, sel, field, track, focus, ring, brand-tint and brand-ink are derived from them; the status and syntax colours keep their built-in values unless set.`,
+        "",
+        "Rules:",
+        "- Values are hex colours. Seeds must be opaque.",
+        "- light describes the light side and dark the dark side. mode \"both\" keeps the system and the user's light/dark switch working; a side you leave out keeps the built-in palette.",
+        "- Text pairs are held to contrast (4.5:1 for text, 3:1 for marks) and moved if they fail; prefer colours that already pass.",
+        "- Colours and the image slots below are all that can change: not layout, size, fonts or which elements show.",
+        "",
+        "Tokens:",
+        tokens,
+        "",
+        "Image slots (optional, under \"images\"; each takes an \"image\": a workspace path to a PNG, JPEG or WebP, or an asset id from the current theme):",
+        ...Object.entries(IMAGE_SLOTS).map(([slot, about]) => `- ${slot}: ${about}`),
+        "Images are copied into the theme when proposed; SVG, GIF and animated images are refused. The page decides where each slot is drawn and keeps text over the conversation background readable.",
+        "",
+        active ? `Theme in use now:\n${JSON.stringify(active, null, 2)}` : "Theme in use now: the built-in one.",
+        "",
+        "Example:",
+        JSON.stringify({
+            name: "Ember",
+            mode: "both",
+            light: { bg: "#fffaf5", fg: "#1c1410", accent: "#3a1d0e", brand: "#c25300" },
+            dark: { bg: "#120c09", fg: "#f3e9e1", accent: "#f3e9e1", brand: "#ff8a3d" },
+            images: { conversation: { image: "./ember-wall.png", fit: "cover", scrim: 0.82 }, avatar: { image: "./ember-avatar.png" } },
+        }),
+    ].join("\n");
+}
+//# sourceMappingURL=theme-tools.js.map

package/dist/theme-tools.js.map

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

package/dist/turn-shots.d.ts

@@ -1,4 +1,3 @@
-import type { ComputerSnapshotEvent } from "@oharness/engine/computer/session.ts";
 /**
  * The windows a Computer use turn left behind, as the person saw them.
  *
@@ -14,11 +13,28 @@ import type { ComputerSnapshotEvent } from "@oharness/engine/computer/session.ts
  */
 export interface TurnShot {
     at: number;
+    /** The app the window belongs to; for a browser tab, the site's host. */
     app: string;
     title?: string;
+    /** Absent for a Computer use window. */
+    kind?: "browser";
     file: string;
 }
-export declare function saveTurnShots(session: string, at: number, shots: ComputerSnapshotEvent["shots"]): Promise<TurnShot[]>;
+/** One picture to keep: base64 JPEG and what it shows. */
+export interface TurnShotInput {
+    app: string;
+    title?: string;
+    kind?: "browser";
+    data: string;
+}
+/** A kept picture as the page draws it. */
+export declare function turnShotView(session: string, shot: TurnShot): {
+    app: string;
+    title?: string;
+    kind?: "browser";
+    src: string;
+};
+export declare function saveTurnShots(session: string, at: number, shots: readonly TurnShotInput[]): Promise<TurnShot[]>;
 /** Synchronous: the transcript is flattened synchronously, and this file is a few lines. */
 export declare function listTurnShots(session: string): TurnShot[];
 /** The bytes of one picture, or nothing for a name that is not one of ours. */

package/dist/turn-shots.js

@@ -2,6 +2,15 @@ import { existsSync, readFileSync } from "node:fs";
 import { appendFile, mkdir, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { userPath } from "@oharness/engine/paths.ts";
+/** A kept picture as the page draws it. */
+export function turnShotView(session, shot) {
+    return {
+        app: shot.app,
+        ...(shot.title ? { title: shot.title } : {}),
+        ...(shot.kind ? { kind: shot.kind } : {}),
+        src: turnShotSrc(session, shot.file),
+    };
+}
 function dir(session) {
     // Session ids are the store's own (date_hex), but the id also arrives on a
     // URL: anything that could climb out of the directory is refused.
@@ -17,7 +26,7 @@ export async function saveTurnShots(session, at, shots) {
     for (const [index, shot] of shots.entries()) {
         const file = `${at}-${stamp}-${index}.jpg`;
         await writeFile(path.join(root, file), Buffer.from(shot.data, "base64"));
-        saved.push({ at, app: shot.app, ...(shot.title ? { title: shot.title } : {}), file });
+        saved.push({ at, app: shot.app, ...(shot.title ? { title: shot.title } : {}), ...(shot.kind ? { kind: shot.kind } : {}), file });
     }
     await appendFile(path.join(root, "index.jsonl"), saved.map((one) => JSON.stringify(one) + "\n").join(""));
     return saved;

package/dist/turn-shots.js.map

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

package/dist/user-theme.d.ts

@@ -0,0 +1,143 @@
+/**
+ * A theme the agent proposes, and what the page does with it.
+ *
+ * The agent never writes CSS. It hands over a few colours — the seeds — and
+ * optionally a value for any other colour token, and everything here is what
+ * turns that into a stylesheet that cannot break the page: the rest of the
+ * palette is derived from the seeds the way the built-in palettes relate to
+ * theirs, every pair that carries text is held to a contrast ratio, and the
+ * printed CSS only ever sets the custom properties `theme.ts` already defines.
+ * There is no selector, property or URL in a theme for anything to go wrong
+ * with.
+ *
+ * Images go in slots the page defines — the conversation background, the art
+ * on an empty session, the assistant's avatar — each with a few enumerated or
+ * clamped options. A theme names a stored asset, never a URL; where the image
+ * lands, what sits above it and how readable the text over it stays are the
+ * page's decisions, not the theme's.
+ *
+ * See docs/plans/ai-theming.md. This covers global colour tokens and image
+ * slots. Shape tokens, part-scoped variables and layout variants come later.
+ */
+export type ThemeMode = "both" | "light" | "dark";
+/** A stored image: the sha-256 of its bytes and its type. See theme-assets.ts. */
+export declare const ASSET_ID: RegExp;
+export declare const FITS: readonly ["cover", "contain", "tile"];
+export declare const ANCHORS: readonly ["top-left", "top", "top-right", "left", "center", "right", "bottom-left", "bottom", "bottom-right"];
+export declare const BLENDS: readonly ["normal", "multiply", "screen", "luminosity", "soft-light"];
+/** Behind the conversation. Text sits over it, so it always has a scrim. */
+export interface WallpaperSlot {
+    asset: string;
+    fit: (typeof FITS)[number];
+    anchor: (typeof ANCHORS)[number];
+    /** How much of the page colour covers the image, 0.5–0.95. The page raises it further if text would be hard to read. */
+    scrim: number;
+    blend: (typeof BLENDS)[number];
+    /** The dark side's own image or scrim; the rest is shared. */
+    dark?: {
+        asset?: string;
+        scrim?: number;
+    };
+}
+/** Above the title of a new, empty session. Nothing is drawn over it. */
+export interface EmptyArtSlot {
+    asset: string;
+    size: "small" | "medium" | "large";
+    align: "left" | "center";
+}
+/** Beside the "assistant" label of every reply. */
+export interface AvatarSlot {
+    asset: string;
+    shape: "circle" | "rounded" | "square";
+}
+export interface ThemeImages {
+    conversation?: WallpaperSlot;
+    empty?: EmptyArtSlot;
+    avatar?: AvatarSlot;
+}
+/** What `set_theme` accepts, after validation. */
+export interface ThemeInput {
+    version: 1;
+    name: string;
+    mode: ThemeMode;
+    light?: Record<string, string>;
+    dark?: Record<string, string>;
+    images?: ThemeImages;
+}
+/** The slots, as the model is told about them in `get_theme_schema`. */
+export declare const IMAGE_SLOTS: Record<keyof ThemeImages, string>;
+export interface ThemeReport {
+    /** Keys or values thrown away, and why. */
+    dropped: string[];
+    /** Colours moved to pass a contrast check. */
+    fixed: string[];
+    /** Things worth knowing that did not change anything. */
+    notes: string[];
+}
+export interface ResolvedTheme {
+    input: ThemeInput;
+    light?: Record<string, string>;
+    dark?: Record<string, string>;
+    report: ThemeReport;
+}
+/** The four colours the rest of a palette is derived from. */
+export declare const SEEDS: readonly ["bg", "fg", "accent", "brand"];
+/**
+ * Every token a theme may set, with what it is for. The meanings are what the
+ * model reads in `get_theme_schema`, so they say where the colour shows rather
+ * than restating its name.
+ */
+export declare const TOKENS: Record<string, string>;
+interface Rgba {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** `#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa`; anything else is not a colour here. */
+export declare function parseHex(value: string): Rgba | undefined;
+export declare function toHex(c: Rgba): string;
+/** WCAG contrast ratio, with a translucent colour composited first. */
+export declare function contrast(top: Rgba, under: Rgba): number;
+/**
+ * Check what the model sent and turn it into a theme.
+ *
+ * Lenient where leniency cannot hurt: an unknown key or a bad value is dropped
+ * and reported, so one typo does not cost the whole proposal. Strict where it
+ * can: nothing that is not a known token with a hex colour reaches the CSS.
+ */
+export declare function readThemeInput(raw: unknown): {
+    ok: true;
+    input: ThemeInput;
+    dropped: string[];
+} | {
+    ok: false;
+    error: string;
+};
+/** Validate, derive and check: everything between the model's JSON and the CSS. */
+export declare function resolveTheme(raw: unknown): {
+    ok: true;
+    theme: ResolvedTheme;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * The stylesheet, printed after the built-in one with the same selectors so it
+ * wins on order alone. A one-sided theme pins `color-scheme` and prints its
+ * palette under every selector, so the system setting and the light/dark
+ * switch cannot bring the other side back.
+ */
+export declare function themeCss(theme: ResolvedTheme): string;
+/** Where a stored image is served; see `GET /theme-asset/` in server.ts. */
+export declare const assetUrl: (asset: string) => string;
+/** Every asset a theme refers to, for keeping and for cleaning up. */
+export declare function themeAssets(input: ThemeInput): string[];
+/** A few colours per side for a card to show before anything is applied. */
+export declare function swatches(theme: ResolvedTheme): {
+    light?: string[];
+    dark?: string[];
+};
+/** What the model reads back after `set_theme`. */
+export declare function describeReport(report: ThemeReport): string;
+export {};