@oharness/server 0.10.0 → 0.12.0

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 {};

package/dist/user-theme.js

@@ -0,0 +1,510 @@
+import { DARK, LIGHT } from "./theme.js";
+/** A stored image: the sha-256 of its bytes and its type. See theme-assets.ts. */
+export const ASSET_ID = /^[0-9a-f]{64}\.(png|jpg|webp)$/;
+export const FITS = ["cover", "contain", "tile"];
+export const ANCHORS = [
+    "top-left", "top", "top-right", "left", "center", "right", "bottom-left", "bottom", "bottom-right",
+];
+export const BLENDS = ["normal", "multiply", "screen", "luminosity", "soft-light"];
+/** The slots, as the model is told about them in `get_theme_schema`. */
+export const IMAGE_SLOTS = {
+    conversation: "Background of the conversation area, behind the messages. Options: fit (cover | contain | tile, default cover), anchor (top-left … center … bottom-right, default center), scrim (0.5–0.95, default 0.8: how much of the page colour covers the image; raised automatically if text would be hard to read), blend (normal | multiply | screen | luminosity | soft-light), dark ({ image?, scrim? } for the dark side). Best: a calm, low-detail landscape image around 2560×1600.",
+    empty: "Art above the title of a new, empty session. Options: size (small | medium | large), align (left | center). Best: a transparent PNG, square or a little wider than tall.",
+    avatar: "The assistant's avatar beside each reply, shown at 20px. Options: shape (circle | rounded | square). Best: a square image with a simple, bold subject.",
+};
+/** The four colours the rest of a palette is derived from. */
+export const SEEDS = ["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 const TOKENS = {
+    bg: "Page background behind the conversation. Seed.",
+    fg: "Body text. Seed.",
+    accent: "Primary buttons and committing actions; their text is drawn in bg. Seed.",
+    brand: "The harness being alive: thinking sweep, a call in flight, the caret, a switch that is on. Marks, not words. Seed.",
+    panel: "Raised surfaces: cards, menus, code blocks.",
+    frame: "The window frame: top bar and rail, set back behind both page and panel.",
+    dim: "Secondary text: labels, timestamps, hints.",
+    line: "Hairline borders. Usually fg at low alpha.",
+    "brand-tint": "Soft fill behind brand-coloured marks. Usually brand at low alpha.",
+    "brand-ink": "Brand-coloured words, such as the thinking label.",
+    "brand-shine": "The band that sweeps across the thinking label.",
+    ok: "Success text and marks.",
+    warn: "Warning text and marks.",
+    err: "Error text and marks.",
+    add: "Added lines in a diff.",
+    "add-bg": "Background of added lines.",
+    del: "Removed lines in a diff.",
+    "del-bg": "Background of removed lines.",
+    hover: "Row and button hover wash. Usually fg at very low alpha.",
+    sel: "Selected row wash. Usually fg at low alpha.",
+    focus: "Focus outline.",
+    ring: "Soft focus ring around fields.",
+    field: "Input field fill.",
+    "field-focus": "Input field fill while focused.",
+    track: "Scrollbar and slider tracks.",
+    kw: "Syntax: keywords.",
+    str: "Syntax: strings.",
+    com: "Syntax: comments.",
+    num: "Syntax: numbers.",
+};
+/**
+ * Pairs that carry text or marks, and the ratio each needs. The first token is
+ * the one moved when a pair fails: the colour drawn on top, never the surface
+ * under it, because a surface is shared by many pairs and text is not.
+ */
+const PAIRS = [
+    ["fg", "bg", 4.5],
+    ["fg", "panel", 4.5],
+    ["fg", "frame", 4.5],
+    ["dim", "bg", 4.5],
+    ["dim", "panel", 4.5],
+    ["dim", "frame", 4.5],
+    ["accent", "bg", 4.5],
+    ["brand-ink", "bg", 4.5],
+    ["brand", "bg", 3],
+    ["focus", "bg", 3],
+    ["ok", "bg", 4.5],
+    ["warn", "bg", 4.5],
+    ["err", "bg", 4.5],
+    ["add", "add-bg", 4.5],
+    ["del", "del-bg", 4.5],
+    ["kw", "panel", 4.5],
+    ["str", "panel", 4.5],
+    ["num", "panel", 4.5],
+    ["com", "panel", 3],
+];
+const MAX_NAME = 60;
+/** `#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa`; anything else is not a colour here. */
+export function parseHex(value) {
+    const match = /^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.exec(value.trim());
+    if (!match)
+        return undefined;
+    let hex = match[1];
+    if (hex.length <= 4)
+        hex = [...hex].map((c) => c + c).join("");
+    const n = (i) => parseInt(hex.slice(i, i + 2), 16);
+    return { r: n(0), g: n(2), b: n(4), a: hex.length === 8 ? n(6) / 255 : 1 };
+}
+const byte = (v) => Math.round(Math.min(255, Math.max(0, v))).toString(16).padStart(2, "0");
+export function toHex(c) {
+    const base = `#${byte(c.r)}${byte(c.g)}${byte(c.b)}`;
+    return c.a >= 1 ? base : base + byte(c.a * 255);
+}
+/** A colour drawn over an opaque one, as the eye sees it. */
+function over(top, under) {
+    const a = top.a;
+    return { r: top.r * a + under.r * (1 - a), g: top.g * a + under.g * (1 - a), b: top.b * a + under.b * (1 - a), a: 1 };
+}
+const linear = (v) => {
+    const s = v / 255;
+    return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+};
+const gamma = (v) => 255 * (v <= 0.0031308 ? v * 12.92 : 1.055 * v ** (1 / 2.4) - 0.055);
+function luminance(c) {
+    return 0.2126 * linear(c.r) + 0.7152 * linear(c.g) + 0.0722 * linear(c.b);
+}
+/** WCAG contrast ratio, with a translucent colour composited first. */
+export function contrast(top, under) {
+    const a = luminance(over(top, under));
+    const b = luminance(under);
+    return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+}
+function toOklch(c) {
+    const r = linear(c.r), g = linear(c.g), b = linear(c.b);
+    const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+    const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+    const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+    const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+    const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+    const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+    return { l: L, c: Math.hypot(A, B), h: Math.atan2(B, A) };
+}
+function fromOklch(o, alpha = 1) {
+    const A = o.c * Math.cos(o.h), B = o.c * Math.sin(o.h);
+    const l = (o.l + 0.3963377774 * A + 0.2158037573 * B) ** 3;
+    const m = (o.l - 0.1055613458 * A - 0.0638541728 * B) ** 3;
+    const s = (o.l - 0.0894841775 * A - 1.291485548 * B) ** 3;
+    return {
+        r: gamma(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s),
+        g: gamma(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s),
+        b: gamma(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s),
+        a: alpha,
+    };
+}
+function mix(a, b, t) {
+    return { r: a.r + (b.r - a.r) * t, g: a.g + (b.g - a.g) * t, b: a.b + (b.b - a.b) * t, a: 1 };
+}
+function withAlpha(c, alpha) {
+    return { ...c, a: alpha };
+}
+function shiftLightness(c, delta) {
+    const o = toOklch(c);
+    return fromOklch({ ...o, l: Math.min(1, Math.max(0, o.l + delta)) }, c.a);
+}
+const isDark = (c) => luminance(c) < 0.18;
+/**
+ * The smallest move in OKLCH lightness that lifts `top` to `min` against
+ * `under`, keeping its hue and chroma. Lighter over a dark surface, darker over
+ * a light one. Returns undefined when even black or white would not do.
+ */
+function nudge(top, under, ratio) {
+    // Aimed a little past the ratio: the result is rounded to whole bytes when
+    // printed as hex, and that rounding alone can land it just short.
+    const min = ratio + 0.05;
+    const start = toOklch(over(top, under));
+    const up = isDark(under);
+    const at = (l) => fromOklch({ ...start, l });
+    const end = up ? 1 : 0;
+    if (contrast(at(end), under) < min)
+        return undefined;
+    let near = start.l, far = end;
+    for (let i = 0; i < 24; i++) {
+        const mid = (near + far) / 2;
+        if (contrast(at(mid), under) >= min)
+            far = mid;
+        else
+            near = mid;
+    }
+    return at(far);
+}
+// --- validation ------------------------------------------------------------
+/**
+ * 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 function readThemeInput(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return { ok: false, error: "the theme must be an object" };
+    const body = raw;
+    const dropped = [];
+    const name = typeof body["name"] === "string" ? body["name"].trim().slice(0, MAX_NAME) : "";
+    const mode = body["mode"] === "light" || body["mode"] === "dark" ? body["mode"] : "both";
+    const readPalette = (key) => {
+        const value = body[key];
+        if (value === undefined || value === null)
+            return undefined;
+        if (typeof value !== "object" || Array.isArray(value)) {
+            dropped.push(`${key}: not an object of token → colour`);
+            return undefined;
+        }
+        const out = {};
+        for (const [token, colour] of Object.entries(value)) {
+            if (!(token in TOKENS)) {
+                dropped.push(`${key}.${token}: not a theme token`);
+                continue;
+            }
+            const parsed = typeof colour === "string" ? parseHex(colour) : undefined;
+            if (!parsed) {
+                dropped.push(`${key}.${token}: ${JSON.stringify(colour)} is not a hex colour`);
+                continue;
+            }
+            if (SEEDS.includes(token) && parsed.a < 1) {
+                dropped.push(`${key}.${token}: seeds must be opaque`);
+                continue;
+            }
+            out[token] = toHex(parsed);
+        }
+        return Object.keys(out).length ? out : undefined;
+    };
+    const light = mode === "dark" ? undefined : readPalette("light");
+    const dark = mode === "light" ? undefined : readPalette("dark");
+    if (mode === "dark" && body["light"])
+        dropped.push("light: ignored, the theme is dark-only");
+    if (mode === "light" && body["dark"])
+        dropped.push("dark: ignored, the theme is light-only");
+    const images = readImages(body["images"], dropped);
+    if (mode === "light" && !light)
+        return { ok: false, error: "a light-only theme needs a light palette" };
+    if (mode === "dark" && !dark)
+        return { ok: false, error: "a dark-only theme needs a dark palette" };
+    if (!light && !dark && !images) {
+        return { ok: false, error: "the theme sets nothing: give at least bg and fg in light or dark, or an image" };
+    }
+    return {
+        ok: true,
+        input: {
+            version: 1, name: name || "Custom", mode,
+            ...(light ? { light } : {}), ...(dark ? { dark } : {}), ...(images ? { images } : {}),
+        },
+        dropped,
+    };
+}
+const oneOf = (options, value, fallback) => typeof value === "string" && options.includes(value) ? value : fallback;
+const clampNumber = (value, min, max, fallback) => typeof value === "number" && Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : fallback;
+/**
+ * Image slots, by asset id only. Turning a file the model names into an asset
+ * is the tool's job (theme-tools.ts), done before this runs, so a stored theme
+ * can be re-validated later without the file it came from.
+ */
+function readImages(raw, dropped) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        dropped.push("images: not an object of slot → options");
+        return undefined;
+    }
+    const body = raw;
+    const out = {};
+    const asset = (slot, value) => {
+        if (typeof value === "string" && ASSET_ID.test(value))
+            return value;
+        dropped.push(`images.${slot}: no usable image`);
+        return undefined;
+    };
+    for (const key of Object.keys(body)) {
+        if (!(key in IMAGE_SLOTS))
+            dropped.push(`images.${key}: not an image slot`);
+    }
+    const wall = body["conversation"];
+    if (wall && typeof wall === "object") {
+        const w = wall;
+        const id = asset("conversation", w["asset"]);
+        if (id) {
+            const slot = {
+                asset: id,
+                fit: oneOf(FITS, w["fit"], "cover"),
+                anchor: oneOf(ANCHORS, w["anchor"], "center"),
+                scrim: clampNumber(w["scrim"], 0.5, 0.95, 0.8),
+                blend: oneOf(BLENDS, w["blend"], "normal"),
+            };
+            const d = w["dark"];
+            if (d && typeof d === "object") {
+                const dd = d;
+                const darkAsset = dd["asset"] === undefined ? undefined : asset("conversation.dark", dd["asset"]);
+                const darkScrim = dd["scrim"] === undefined ? undefined : clampNumber(dd["scrim"], 0.5, 0.95, slot.scrim);
+                if (darkAsset || darkScrim !== undefined) {
+                    slot.dark = { ...(darkAsset ? { asset: darkAsset } : {}), ...(darkScrim !== undefined ? { scrim: darkScrim } : {}) };
+                }
+            }
+            out.conversation = slot;
+        }
+    }
+    const empty = body["empty"];
+    if (empty && typeof empty === "object") {
+        const e = empty;
+        const id = asset("empty", e["asset"]);
+        if (id) {
+            out.empty = {
+                asset: id,
+                size: oneOf(["small", "medium", "large"], e["size"], "medium"),
+                align: oneOf(["left", "center"], e["align"], "left"),
+            };
+        }
+    }
+    const avatar = body["avatar"];
+    if (avatar && typeof avatar === "object") {
+        const a = avatar;
+        const id = asset("avatar", a["asset"]);
+        if (id)
+            out.avatar = { asset: id, shape: oneOf(["circle", "rounded", "square"], a["shape"], "circle") };
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+/**
+ * A whole palette from what the theme set. Seeds the theme left out come from
+ * the built-in palette of the same lightness, so a theme that only gives bg
+ * and fg still has a sensible accent.
+ */
+function derive(given, side, report) {
+    const builtin = side === "light" ? LIGHT : DARK;
+    const pick = (token) => parseHex(given[token] ?? builtin[token]);
+    const bg = pick("bg");
+    // The base for the tokens nobody derives: whichever built-in palette this
+    // background resembles, not the side it was filed under.
+    const base = isDark(bg) ? DARK : LIGHT;
+    const dark = isDark(bg);
+    if (dark !== (side === "dark")) {
+        report.notes.push(`${side}.bg is a ${dark ? "dark" : "light"} colour; the palette was derived as ${dark ? "dark" : "light"}`);
+    }
+    let fg = pick("fg");
+    const fgFixed = nudge(fg, bg, 7);
+    if (contrast(fg, bg) < 4.5 && fgFixed) {
+        report.fixed.push(`${side}.fg ${toHex(fg)} → ${toHex(fgFixed)} (was ${contrast(fg, bg).toFixed(1)}:1 on bg)`);
+        fg = fgFixed;
+    }
+    const accent = given["accent"] ? pick("accent") : parseHex(base["accent"]);
+    const brand = given["brand"] ? pick("brand") : parseHex(base["brand"]);
+    const fgA = (alpha) => toHex(withAlpha(fg, alpha / 255));
+    const dim = mix(fg, bg, 0.42);
+    const palette = {
+        ...base,
+        bg: toHex(bg),
+        fg: toHex(fg),
+        accent: toHex(accent),
+        brand: toHex(brand),
+        panel: toHex(mix(bg, fg, dark ? 0.045 : 0.03)),
+        frame: toHex(shiftLightness(bg, dark ? -0.035 : -0.055)),
+        dim: toHex(dim),
+        line: fgA(dark ? 0x14 : 0x10),
+        hover: fgA(dark ? 0x0a : 0x08),
+        sel: fgA(dark ? 0x1a : 0x12),
+        field: fgA(dark ? 0x08 : 0x06),
+        "field-focus": fgA(dark ? 0x12 : 0x0d),
+        track: fgA(dark ? 0x2e : 0x1f),
+        focus: toHex(dark ? dim : accent),
+        ring: toHex(withAlpha(dark ? fg : accent, dark ? 0x14 / 255 : 0x1a / 255)),
+        "brand-tint": toHex(withAlpha(brand, (dark ? 0x33 : 0x24) / 255)),
+        "brand-ink": toHex(brand),
+    };
+    // Explicit values win over derivation; seeds were already taken above.
+    for (const [token, value] of Object.entries(given)) {
+        if (!SEEDS.includes(token))
+            palette[token] = value;
+    }
+    return palette;
+}
+/** Hold every text pair to its ratio, moving the colour on top when it fails. */
+function enforce(palette, side, given, report) {
+    // One line per colour the model picked, however many pairs moved it: from
+    // what it asked for to where it ended up, and the pair that decided it.
+    const moves = new Map();
+    for (const [top, under, min] of PAIRS) {
+        const surface = parseHex(palette[under]);
+        // A translucent surface is judged as it is seen: over the page.
+        const seen = surface.a < 1 ? over(surface, parseHex(palette["bg"])) : surface;
+        const colour = parseHex(palette[top]);
+        const ratio = contrast(colour, seen);
+        if (ratio >= min)
+            continue;
+        const moved = nudge(colour, seen, min);
+        if (!moved) {
+            report.notes.push(`${side}.${top} cannot reach ${min}:1 on ${under}; left at ${ratio.toFixed(1)}:1`);
+            continue;
+        }
+        palette[top] = toHex(moved);
+        // Derived tokens are adjusted quietly unless the theme chose them; the
+        // report is for the colours the model picked.
+        if (top in given) {
+            const first = moves.get(top);
+            moves.set(top, { from: first?.from ?? toHex(colour), why: `${ratio.toFixed(1)}:1 on ${under}, needs ${min}:1` });
+        }
+    }
+    for (const [token, move] of moves) {
+        report.fixed.push(`${side}.${token} ${move.from} → ${palette[token]} (${move.why})`);
+    }
+    const bg = toOklch(parseHex(palette["bg"])), panel = toOklch(parseHex(palette["panel"]));
+    if (Math.abs(bg.l - panel.l) < 0.012)
+        report.notes.push(`${side}.panel is barely distinguishable from bg`);
+}
+/** Validate, derive and check: everything between the model's JSON and the CSS. */
+export function resolveTheme(raw) {
+    const read = readThemeInput(raw);
+    if (!read.ok)
+        return read;
+    const report = { dropped: read.dropped, fixed: [], notes: [] };
+    const { input } = read;
+    const theme = { input, report };
+    for (const side of ["light", "dark"]) {
+        const given = input[side];
+        if (!given)
+            continue;
+        if (!given["bg"] || !given["fg"])
+            report.notes.push(`${side}: no ${!given["bg"] ? "bg" : "fg"} given, the built-in one was used`);
+        const palette = derive(given, side, report);
+        enforce(palette, side, given, report);
+        theme[side] = palette;
+    }
+    if (input.mode === "both" && (theme.light ? !theme.dark : theme.dark)) {
+        report.notes.push(`only the ${theme.light ? "light" : "dark"} side was set; the other keeps the built-in palette`);
+    }
+    return { ok: true, theme };
+}
+// --- css -------------------------------------------------------------------
+const vars = (palette) => Object.keys(TOKENS)
+    .filter((token) => palette[token] !== undefined)
+    .map((token) => `--${token}:${palette[token]};`)
+    .join(" ");
+/**
+ * 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 function themeCss(theme) {
+    const light = theme.light, dark = theme.dark, images = theme.input.images;
+    if (theme.input.mode !== "both") {
+        const side = theme.input.mode;
+        const palette = (side === "light" ? light : dark);
+        const body = `color-scheme:${side}; ${vars(palette)} ${imageVars(images, side)}`;
+        return (`:root{${body}}\n` +
+            `@media (prefers-color-scheme:dark){:root:not([data-theme="light"]){${body}}}\n` +
+            `:root[data-theme="dark"],:root[data-theme="light"]{${body}}\n`);
+    }
+    const lightBody = `${light ? vars(light) : ""} ${imageVars(images, "light")}`.trim();
+    const darkBody = `${dark ? vars(dark) : ""} ${imageVars(images, "dark")}`.trim();
+    let css = "";
+    if (lightBody)
+        css += `:root{${lightBody}}\n:root[data-theme="light"]{${lightBody}}\n`;
+    if (darkBody) {
+        css += `@media (prefers-color-scheme:dark){:root:not([data-theme="light"]){${darkBody}}}\n`;
+        css += `:root[data-theme="dark"]{${darkBody}}\n`;
+    }
+    return css;
+}
+/** Where a stored image is served; see `GET /theme-asset/` in server.ts. */
+export const assetUrl = (asset) => `/theme-asset/${asset}`;
+const POSITIONS = {
+    "top-left": "left top", top: "center top", "top-right": "right top",
+    left: "left center", center: "center center", right: "right center",
+    "bottom-left": "left bottom", bottom: "center bottom", "bottom-right": "right bottom",
+};
+/**
+ * The image slots as custom properties, read by the rules in style.ts that
+ * own them. Every value is printed from an enumerated option, a clamped
+ * number or an asset id that matched ASSET_ID — nothing here is passed through
+ * from the model.
+ */
+function imageVars(images, side) {
+    if (!images)
+        return "";
+    const out = [];
+    const wall = images.conversation;
+    if (wall) {
+        const asset = side === "dark" && wall.dark?.asset ? wall.dark.asset : wall.asset;
+        const scrim = side === "dark" && wall.dark?.scrim !== undefined ? wall.dark.scrim : wall.scrim;
+        out.push(`--wall-image:url("${assetUrl(asset)}");`, 
+        // The colour the blend mixes the image with: the page's own.
+        `--wall-base:var(--bg);`, `--wall-size:${wall.fit === "tile" ? "auto" : wall.fit};`, `--wall-repeat:${wall.fit === "tile" ? "repeat" : "no-repeat"};`, `--wall-position:${POSITIONS[wall.anchor]};`, `--wall-scrim:${Math.round(scrim * 100)}%;`, `--wall-blend:normal, ${wall.blend};`);
+    }
+    const empty = images.empty;
+    if (empty) {
+        out.push(`--empty-art:url("${assetUrl(empty.asset)}");`, `--empty-art-display:block;`, `--empty-art-height:${{ small: 120, medium: 180, large: 240 }[empty.size]}px;`, `--empty-art-position:${empty.align === "center" ? "center" : "left"} center;`);
+    }
+    const avatar = images.avatar;
+    if (avatar) {
+        out.push(`--avatar:url("${assetUrl(avatar.asset)}");`, `--avatar-display:inline-block;`, `--avatar-radius:${{ circle: "999px", rounded: "6px", square: "2px" }[avatar.shape]};`);
+    }
+    return out.join(" ");
+}
+/** Every asset a theme refers to, for keeping and for cleaning up. */
+export function themeAssets(input) {
+    const images = input.images;
+    if (!images)
+        return [];
+    const ids = [images.conversation?.asset, images.conversation?.dark?.asset, images.empty?.asset, images.avatar?.asset];
+    return [...new Set(ids.filter((id) => !!id))];
+}
+/** A few colours per side for a card to show before anything is applied. */
+export function swatches(theme) {
+    const pick = (p) => (p ? ["bg", "panel", "fg", "dim", "accent", "brand"].map((t) => p[t]) : undefined);
+    const light = pick(theme.light), dark = pick(theme.dark);
+    return { ...(light ? { light } : {}), ...(dark ? { dark } : {}) };
+}
+/** What the model reads back after `set_theme`. */
+export function describeReport(report) {
+    const lines = [];
+    if (report.fixed.length)
+        lines.push("Adjusted for contrast:", ...report.fixed.map((l) => `- ${l}`));
+    if (report.dropped.length)
+        lines.push("Dropped:", ...report.dropped.map((l) => `- ${l}`));
+    if (report.notes.length)
+        lines.push("Notes:", ...report.notes.map((l) => `- ${l}`));
+    return lines.length ? lines.join("\n") : "Every value passed as given.";
+}
+//# sourceMappingURL=user-theme.js.map