viberoom 0.6.1 → 0.8.0

package/NOTICE

@@ -11,6 +11,20 @@ This product bundles the following third-party material:
   - JetBrains Mono: Copyright 2020 The JetBrains Mono Project Authors.
   - Fira Code: Copyright 2014-2020 The Fira Code Project Authors.
   - Source Code Pro: Copyright 2010-2019 Adobe (http://www.adobe.com/).
+  - Open Sans: Copyright 2020 The Open Sans Project Authors.
+  - Source Sans 3: Copyright 2010-2020 Adobe (http://www.adobe.com/).
+  - IBM Plex Sans, IBM Plex Mono: Copyright 2017 IBM Corp.
+  - Manrope: Copyright 2018 The Manrope Project Authors.
+  - Rubik: Copyright 2015 The Rubik Project Authors.
+  - Montserrat: Copyright 2011 The Montserrat Project Authors.
+  - Golos Text: Copyright 2023 The Golos Text Project Authors.
+  - Exo 2: Copyright 2013 The Exo 2 Project Authors.
+  - Comfortaa: Copyright 2011 The Comfortaa Project Authors.
+  - Ubuntu Sans: Copyright 2022 The Ubuntu Sans Project Authors.
+  - PT Mono: Copyright 2011 ParaType Ltd.
+  - Victor Mono: Copyright 2019 The Victor Mono Project Authors.
+  - Anonymous Pro: Copyright 2009 The Anonymous Pro Project Authors.
+  - Cascadia Code: Copyright 2019 Microsoft Corporation.
 
 - Vendor icons (assets/vendors/): the logos of Claude, Codex, Gemini, Cursor,
   OpenCode and GitHub Copilot, as published in the Agent Client Protocol

package/README.md

@@ -88,6 +88,17 @@ brief the others would receive, save a template for you to pick under New room,
 the room you are in. A proposal is a card in the chat with the diff; nothing changes until you click
 Apply, and the room is told what you decided.
 
+## Let them design the look
+
+A look (how the window is drawn: colours, light, corners, fonts) is data, not code: which of the shipped
+looks it starts from, a few hues, and what it wants otherwise. Ask a vibemate for "a warm paper look for
+long evenings" and it has a built-in skill on what makes a look good and four tools: read every token
+with what it means, check a draft (the hub measures whether the words read on their paper and reports
+the numbers, since a vibemate cannot see colours), save the look among your own (Settings → Appearance,
+after the shipped ones, with your name on it), or propose wearing it as a card you can try on first. Your
+own looks are files under your data folder: export one to share it, import one someone sent you, delete
+one you are done with. A shipped look can only be fine-tuned, never rewritten.
+
 <br>
 
 ## Talk to all, or to one

package/dist/hub.js

@@ -11,17 +11,72 @@ import { DEFAULT_ROOM_SETTINGS } from "./persona.js";
 import { Room } from "./room.js";
 import { SkillLibrary } from "./skills.js";
 import { TemplateLibrary, roomSettingsFromTemplate } from "./templates.js";
-export const TEXT_FONTS = ["nunito", "inter", "noto-sans", "arial", "system"];
-export const MONO_FONTS = ["jetbrains-mono", "fira-code", "source-code-pro", "system"];
-export const DEFAULT_APPEARANCE = { chatFontSize: 14.5, font: "nunito", mono: "jetbrains-mono" };
+import { LookLibrary, checkLookSpec, loadTokens } from "./looks.js";
+export const ADJUSTABLE = {
+    canvas: "colour", panel: "colour", bubble: "colour", mine: "colour", ring: "colour", ink: "colour", muted: "colour", accent: "colour",
+    face: "colour", logo: "colour", logoInk: "colour", corners: "scale",
+};
+export const TEXT_FONTS = ["nunito", "inter", "noto-sans", "open-sans", "source-sans-3", "ibm-plex-sans", "manrope", "rubik", "montserrat", "golos-text", "exo-2", "comfortaa", "ubuntu-sans", "arial", "system"];
+export const MONO_FONTS = ["jetbrains-mono", "fira-code", "source-code-pro", "ibm-plex-mono", "pt-mono", "victor-mono", "anonymous-pro", "cascadia-code", "system"];
+export const DEFAULT_APPEARANCE = { chatFontSize: 14.5, font: "nunito", mono: "jetbrains-mono", look: "classic", custom: {} };
 export const DIAGRAM_PRESETS = ["pop", "lavender", "mint", "sunset", "slate"];
 const ROOM_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,39}$/;
 const INSTRUCTION_FILES = ["CLAUDE.md", "AGENTS.md", "GEMINI.md", ".cursorrules"];
+export function nextAppearance(current, a) {
+    const chatFontSize = Number(a.chatFontSize ?? current.chatFontSize ?? DEFAULT_APPEARANCE.chatFontSize);
+    if (!Number.isFinite(chatFontSize) || chatFontSize < 12 || chatFontSize > 24)
+        throw new Error("appearance.chatFontSize must be between 12 and 24");
+    const font = String(a.font ?? current.font ?? DEFAULT_APPEARANCE.font);
+    if (!TEXT_FONTS.includes(font))
+        throw new Error(`appearance.font must be one of ${TEXT_FONTS.join(", ")}`);
+    const mono = String(a.mono ?? current.mono ?? DEFAULT_APPEARANCE.mono);
+    if (!MONO_FONTS.includes(mono))
+        throw new Error(`appearance.mono must be one of ${MONO_FONTS.join(", ")}`);
+    const look = String(a.look ?? current.look ?? DEFAULT_APPEARANCE.look);
+    if (!/^[a-z][a-z0-9-]{0,30}$/.test(look))
+        throw new Error("appearance.look must be a short lower-case id");
+    const custom = { ...(current.custom ?? {}) };
+    if (a.custom !== undefined && typeof a.custom === "object" && a.custom) {
+        for (const [lookId, values] of Object.entries(a.custom)) {
+            if (!/^[a-z][a-z0-9-]{0,30}$/.test(lookId))
+                throw new Error("appearance.custom: a look id is a short lower-case id");
+            if (values === null) {
+                delete custom[lookId];
+                continue;
+            }
+            if (typeof values !== "object")
+                throw new Error("appearance.custom: each look takes an object of adjustments");
+            const clean = {};
+            for (const [key, value] of Object.entries(values)) {
+                const kind = ADJUSTABLE[key];
+                if (!kind)
+                    throw new Error(`appearance.custom: "${key}" is not adjustable (${Object.keys(ADJUSTABLE).join(", ")})`);
+                if (kind === "colour") {
+                    if (typeof value !== "string" || !/^#[0-9a-fA-F]{6}$/.test(value))
+                        throw new Error(`appearance.custom.${key} must be a colour like #1a2b3c`);
+                    clean[key] = value.toLowerCase();
+                }
+                else {
+                    const n = typeof value === "string" || typeof value === "number" ? Number(value) : NaN;
+                    if (!Number.isFinite(n) || n < 0 || n > 2)
+                        throw new Error(`appearance.custom.${key} must be a number between 0 and 2`);
+                    clean[key] = String(Math.round(n * 100) / 100);
+                }
+            }
+            if (Object.keys(clean).length)
+                custom[lookId] = clean;
+            else
+                delete custom[lookId];
+        }
+    }
+    return { chatFontSize: Math.round(chatFontSize * 2) / 2, font, mono, look, custom };
+}
 export class Hub extends EventEmitter {
     dataDir;
     rooms = new Map();
     skills;
     templates;
+    looks;
     settings;
     log;
     optionCache = new Map();
@@ -35,6 +90,7 @@ export class Hub extends EventEmitter {
         mkdirSync(join(this.dataDir, "rooms"), { recursive: true });
         this.skills = new SkillLibrary(join(this.dataDir, "skills"), log.child("skills"));
         this.templates = new TemplateLibrary(join(this.dataDir, "templates"), log.child("templates"));
+        this.looks = new LookLibrary(join(this.dataDir, "looks"), log.child("looks"));
         try {
             this.skills.seedBuiltins();
         }
@@ -47,6 +103,30 @@ export class Hub extends EventEmitter {
             hubUrl: () => this.hubUrl,
             templates: this.templates,
             templatesChanged: () => this.emit("event", { type: "templates" }),
+            looks: {
+                list: () => this.looks.list(),
+                describe: () => this.looks.describe(),
+                check: (raw) => checkLookSpec(raw),
+                save: (raw, options) => this.saveLook(raw, options),
+            },
+            appearance: {
+                current: () => ({ ...this.settings.appearance, custom: { ...(this.settings.appearance.custom ?? {}) } }),
+                preview: (patch) => nextAppearance(this.settings.appearance, patch),
+                apply: (patch) => {
+                    this.updateSettings({ appearance: patch });
+                },
+                ownAdjustments: async (lookId) => {
+                    const tokens = await loadTokens();
+                    let look = tokens.looks[lookId];
+                    if (!look) {
+                        const spec = this.looks.get(lookId);
+                        if (!spec)
+                            return null;
+                        look = tokens.make(spec);
+                    }
+                    return { label: look.label, values: Object.fromEntries(tokens.adjustables.map((f) => [f.key, String(f.of(look))])) };
+                },
+            },
             needApproval: () => this.settings.agentSkillsNeedApproval === true,
             save: (draft) => {
                 const { body: _b, ...meta } = this.saveSkillInternal(draft);
@@ -205,17 +285,7 @@ export class Hub extends EventEmitter {
             next.editor = { mode, command };
         }
         if (patch.appearance !== undefined && typeof patch.appearance === "object" && patch.appearance) {
-            const a = patch.appearance;
-            const chatFontSize = Number(a.chatFontSize ?? next.appearance?.chatFontSize ?? DEFAULT_APPEARANCE.chatFontSize);
-            if (!Number.isFinite(chatFontSize) || chatFontSize < 12 || chatFontSize > 24)
-                throw new Error("appearance.chatFontSize must be between 12 and 24");
-            const font = String(a.font ?? next.appearance?.font ?? DEFAULT_APPEARANCE.font);
-            if (!TEXT_FONTS.includes(font))
-                throw new Error(`appearance.font must be one of ${TEXT_FONTS.join(", ")}`);
-            const mono = String(a.mono ?? next.appearance?.mono ?? DEFAULT_APPEARANCE.mono);
-            if (!MONO_FONTS.includes(mono))
-                throw new Error(`appearance.mono must be one of ${MONO_FONTS.join(", ")}`);
-            next.appearance = { chatFontSize: Math.round(chatFontSize * 2) / 2, font, mono };
+            next.appearance = nextAppearance(next.appearance, patch.appearance);
         }
         next.appearance = { ...DEFAULT_APPEARANCE, ...(next.appearance ?? {}) };
         if (!next.editor)
@@ -451,12 +521,28 @@ export class Hub extends EventEmitter {
         this.update = update;
         this.emit("event", { type: "update", update });
     }
+    async saveLook(raw, options) {
+        const saved = await this.looks.save(raw, options);
+        this.emit("event", { type: "looks", looks: this.looks.list() });
+        return saved;
+    }
+    removeLook(id) {
+        const removed = this.looks.remove(id);
+        if (!removed)
+            return false;
+        if (this.settings.appearance?.look === id || this.settings.appearance?.custom?.[id]) {
+            this.updateSettings({ appearance: { look: this.settings.appearance.look === id ? DEFAULT_APPEARANCE.look : this.settings.appearance.look, custom: { [id]: null } } });
+        }
+        this.emit("event", { type: "looks", looks: this.looks.list() });
+        return true;
+    }
     snapshot() {
         return {
             settings: this.settings,
             update: this.update,
             recipes: listRecipes().map(({ build: _b, ...r }) => r),
             skills: this.skills.list(),
+            looks: this.looks.list(),
             roomDefaults: { ...DEFAULT_ROOM_SETTINGS, ...this.settings.roomDefaults },
             rooms: [...this.rooms.values()].map((room) => room.snapshot()),
             openRooms: [...this.openRooms],
@@ -477,6 +563,7 @@ export class Hub extends EventEmitter {
         rmSync(join(this.dataDir, "rooms"), { recursive: true, force: true });
         rmSync(this.roomsPath(), { force: true });
         rmSync(this.skills.dir, { recursive: true, force: true });
+        rmSync(this.looks.dir, { recursive: true, force: true });
         mkdirSync(join(this.dataDir, "rooms"), { recursive: true });
         mkdirSync(this.skills.dir, { recursive: true });
         this.skills.list();

package/dist/look-lint.js

@@ -0,0 +1,180 @@
+// viberoom - Copyright (c) 2026 Todor Rusev - AGPL-3.0-or-later; see LICENSE
+const outsideCalls = (value) => {
+    let out = "";
+    let depth = 0;
+    for (const ch of String(value)) {
+        if (ch === "(") {
+            if (depth === 0)
+                out += "(";
+            depth++;
+        }
+        else if (ch === ")") {
+            depth = Math.max(0, depth - 1);
+            if (depth === 0)
+                out += ")";
+        }
+        else if (depth === 0)
+            out += ch;
+    }
+    return out.replace(/[\w-]+\(\)/g, "x");
+};
+export function lintKinds(look, issues) {
+    const check = (path, key, value, section) => {
+        const v = String(value).trim();
+        const isRadiusKey = section === "shape" ? key !== "rScale" && key !== "rCtlMin" : /[Rr]adius/.test(key);
+        if (isRadiusKey) {
+            const bare = outsideCalls(v);
+            if (/\//.test(bare) || bare.trim().split(/\s+/).filter(Boolean).length > 1)
+                issues.errors.push({ level: "error", key: path, message: `${path} is one length or calc(), not "${v.slice(0, 60)}": the named radii are used inside calc() and max(), so a multi-corner value leaves every corner square` });
+            return;
+        }
+        if ((key === "border" || /Border$/.test(key)) && !/^#|^rgba?\(|^transparent$|^currentColor$/i.test(v)) {
+            if (/^-?\d*\.?\d+(px|em|rem|pt)?$/.test(v) && v !== "0" && v !== "0px")
+                issues.warnings.push({ level: "warning", key: path, message: `${path} "${v}" is a width alone, which draws no border: write width, style and colour ("2px solid $ink")` });
+            return;
+        }
+        if (/Lift$/.test(key)) {
+            const n = parseFloat(v);
+            if (Number.isFinite(n) && n > 0)
+                issues.warnings.push({ level: "warning", key: path, message: `${path} "${v}" pushes the thing down on hover; a lift is negative ("-2px")` });
+            return;
+        }
+        if (/Drop$/.test(key)) {
+            const n = parseFloat(v);
+            if (Number.isFinite(n) && n < 0)
+                issues.warnings.push({ level: "warning", key: path, message: `${path} "${v}" lifts the thing when pressed; a drop is positive ("1px")` });
+        }
+    };
+    for (const [key, value] of Object.entries(look.shape ?? {}))
+        check(`shape.${key}`, key, value, "shape");
+    for (const [group, parts] of Object.entries(look.elements))
+        for (const [key, value] of Object.entries(parts))
+            check(`elements.${group}.${key}`, key, value, "elements");
+}
+export function contrast(a, b) {
+    const hex = (s) => {
+        const m = /^#([0-9a-f]{6})$/i.exec(String(s).trim());
+        return m ? [0, 2, 4].map((i) => parseInt(m[1].slice(i, i + 2), 16)) : null;
+    };
+    const lum = (c) => {
+        const f = (v) => {
+            v /= 255;
+            return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+        };
+        return 0.2126 * f(c[0]) + 0.7152 * f(c[1]) + 0.0722 * f(c[2]);
+    };
+    const x = hex(a);
+    const y = hex(b);
+    if (!x || !y)
+        return null;
+    const [l1, l2] = [lum(x), lum(y)];
+    return +((Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05)).toFixed(2);
+}
+export function luminance(colour) {
+    const c = contrast(colour, "#000000");
+    return c === null ? null : (c * 0.05 - 0.05);
+}
+export function hslHex(h, s, l) {
+    s /= 100;
+    l /= 100;
+    const k = (n) => (n + h / 30) % 12;
+    const a = s * Math.min(l, 1 - l);
+    const f = (n) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
+    return `#${[f(0), f(8), f(4)].map((v) => Math.round(v * 255).toString(16).padStart(2, "0")).join("")}`;
+}
+export function flatten(value, paper) {
+    const v = String(value).trim();
+    if (/^#[0-9a-f]{6}$/i.test(v))
+        return v.toLowerCase();
+    const m = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+)\s*)?\)$/i.exec(v);
+    const p = /^#([0-9a-f]{6})$/i.exec(String(paper).trim());
+    if (!m || !p)
+        return null;
+    const a = m[4] === undefined ? 1 : Math.max(0, Math.min(1, parseFloat(m[4])));
+    const base = [0, 2, 4].map((i) => parseInt(p[1].slice(i, i + 2), 16));
+    const top = [m[1], m[2], m[3]].map((x) => parseInt(x, 10));
+    return `#${top.map((c, i) => Math.round(c * a + base[i] * (1 - a)).toString(16).padStart(2, "0")).join("")}`;
+}
+const NOT_A_PAIR = new Set(["meaning.attentionInk"]);
+export function lintLook(look) {
+    const errors = [];
+    const warnings = [];
+    const report = [];
+    const dark = look.scheme === "dark";
+    const at = (inkKey, ink, bgKey, bg, floor) => {
+        const c = contrast(ink, bg);
+        if (c === null)
+            return;
+        report.push(`${inkKey} on ${bgKey}: ${c}:1 (floor ${floor})`);
+        if (c < floor)
+            errors.push({ level: "error", key: inkKey, message: `${inkKey} ${ink} on ${bgKey} ${bg} reads ${c}:1, under ${floor}:1` });
+    };
+    const e = look.elements;
+    const p = look.palette;
+    const bubble = e.bubble?.bg ?? "";
+    at("elements.bubble.ink", e.bubble?.ink ?? "", "elements.bubble.bg", bubble, 7);
+    at("palette.muted", p.muted, "elements.bubble.bg", bubble, dark ? 4.5 : 3);
+    at("palette.faint", p.faint, "elements.bubble.bg", bubble, dark ? 3 : 2);
+    at("palette.ink", p.ink, "palette.bg", p.bg, 7);
+    at("elements.logoTile.ink", e.logoTile?.ink ?? "", "elements.logoTile.bg", e.logoTile?.bg ?? "", 3);
+    at("elements.logoTile.badgeInk", e.logoTile?.badgeInk ?? "", "elements.logoTile.badgeBg", e.logoTile?.badgeBg ?? "", 3);
+    at("elements.btn.onPrimary", e.btn?.onPrimary ?? "", "palette.primary", p.primary, 3);
+    at("elements.face.humanInk", e.face?.humanInk ?? "", "elements.face.paper", e.face?.paper ?? "", 4.5);
+    if (dark && e.roomMark?.gradFrom) {
+        const [s, l] = e.roomMark.gradFrom.split(" ").map((v) => parseFloat(v));
+        if (Number.isFinite(s) && Number.isFinite(l)) {
+            for (const hue of [0, 60, 120, 180, 240, 300])
+                at(`elements.roomMark.ink (hue ${hue})`, e.roomMark.ink, "the mark's paper", hslHex(hue, s, l), 3);
+        }
+    }
+    const codeBg = e.code?.bg ?? "";
+    for (const [part, colour] of Object.entries(e.syntax ?? {}))
+        at(`elements.syntax.${part}`, colour, "elements.code.bg", codeBg, 3);
+    at("elements.code.ink", e.code?.ink ?? "", "elements.code.bg", codeBg, 4.5);
+    at("elements.code.gutterInk", e.code?.gutterInk ?? "", "elements.code.gutterBg", e.code?.gutterBg ?? "", 3);
+    const headBtnBg = flatten(e.code?.headBtnBg ?? "", codeBg);
+    if (headBtnBg)
+        at("elements.code.headBtnInk", e.code?.headBtnInk ?? "", "elements.code.headBtnBg over the block", headBtnBg, 3);
+    const cardBg = e.fileCard?.bg ?? "";
+    const cardHead = flatten(e.fileCard?.headBg ?? "", cardBg);
+    if (cardHead)
+        at("elements.fileCard.headInk", e.fileCard?.headInk ?? "", "elements.fileCard.headBg over the card", cardHead, 3);
+    const darkBtn = flatten(e.btn?.darkBg ?? "", cardBg);
+    if (darkBtn)
+        at("elements.btn.darkInk", e.btn?.darkInk ?? "", "elements.btn.darkBg over the file card", darkBtn, 3);
+    const groups = { ...e, meaning: look.meaning ?? {} };
+    for (const [group, parts] of Object.entries(groups)) {
+        for (const [key, value] of Object.entries(parts)) {
+            if (!(key === "ink" || /Ink$/.test(key)) || NOT_A_PAIR.has(`${group}.${key}`))
+                continue;
+            const stem = key === "ink" ? "" : key.slice(0, -3);
+            const bgKey = group === "meaning" ? stem : stem ? `${stem}Bg` : "bg";
+            if (!(bgKey in parts))
+                continue;
+            const where = group === "meaning" ? "meaning" : `elements.${group}`;
+            at(`${where}.${key}`, value, `${where}.${bgKey}`, parts[bgKey], 3);
+        }
+    }
+    const off = contrast(bubble, p.bg);
+    if (off !== null) {
+        report.push(`elements.bubble.bg off palette.bg: ${off}:1 (1.1 or a ring)`);
+        const ring = e.bubble?.border ?? "transparent";
+        if (off < 1.1 && /^transparent$/i.test(ring))
+            warnings.push({ level: "warning", key: "elements.bubble.bg", message: `the bubble ${bubble} barely stands off the paper ${p.bg} (${off}:1) and wears no ring: give elements.bubble.border a hairline or the bubble another shade` });
+    }
+    const paperLum = luminance(p.bg);
+    if (paperLum !== null) {
+        if (dark && paperLum > 0.4)
+            warnings.push({ level: "warning", key: "scheme", message: `scheme is dark but the paper ${p.bg} is light: diagrams and the marks are drawn for dark paper` });
+        if (!dark && paperLum < 0.2)
+            warnings.push({ level: "warning", key: "scheme", message: `scheme is light but the paper ${p.bg} is dark: say scheme "dark", so diagrams and the marks are drawn for it` });
+    }
+    lintKinds(look, { errors, warnings });
+    const onPanel = contrast(p.muted, look.aliases?.panel ?? "");
+    if (onPanel !== null) {
+        report.push(`palette.muted on aliases.panel: ${onPanel}:1 (3 wanted)`);
+        if (onPanel < 3)
+            warnings.push({ level: "warning", key: "palette.muted", message: `the quiet words ${p.muted} on a panel ${look.aliases.panel} read ${onPanel}:1; times and hints will be hard to read` });
+    }
+    return { ok: errors.length === 0, errors, warnings, report };
+}

package/dist/looks.js

@@ -0,0 +1,151 @@
+// viberoom - Copyright (c) 2026 Todor Rusev - AGPL-3.0-or-later; see LICENSE
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { writeFileAtomic } from "./atomic.js";
+import { lintLook } from "./look-lint.js";
+export const LOOK_ID = /^[a-z][a-z0-9-]{0,30}$/;
+export const DEFAULT_BASE = "classic";
+const SPEC_SECTIONS = ["palette", "shape", "type", "motion", "elevation", "canvas"];
+let tokensPromise = null;
+export function loadTokens() {
+    if (!tokensPromise) {
+        const file = fileURLToPath(new URL("../ui/tokens.js", import.meta.url));
+        tokensPromise = import(pathToFileURL(file).href).then(() => {
+            const tokens = globalThis.VIBEROOM_TOKENS;
+            if (!tokens)
+                throw new Error("ui/tokens.js did not register VIBEROOM_TOKENS");
+            return tokens;
+        });
+    }
+    return tokensPromise;
+}
+export function cleanLookSpec(raw) {
+    const r = (raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {});
+    const out = { id: String(r.id ?? "").trim().toLowerCase(), label: String(r.label ?? "").trim() };
+    if (typeof r.scheme === "string" && r.scheme.trim())
+        out.scheme = r.scheme.trim();
+    if (typeof r.extends === "string" && r.extends.trim())
+        out.extends = r.extends.trim();
+    if (typeof r.author === "string" && r.author.trim())
+        out.author = r.author.trim().slice(0, 40);
+    if (typeof r.created === "string" && r.created.trim())
+        out.created = r.created.trim();
+    if (typeof r.updatedAt === "string" && r.updatedAt.trim())
+        out.updatedAt = r.updatedAt.trim();
+    const flat = (v) => {
+        if (!v || typeof v !== "object" || Array.isArray(v))
+            return undefined;
+        const o = {};
+        for (const [k, x] of Object.entries(v))
+            if (typeof x === "string")
+                o[k] = x;
+        return Object.keys(o).length ? o : undefined;
+    };
+    for (const section of SPEC_SECTIONS) {
+        const v = flat(r[section]);
+        if (v)
+            out[section] = v;
+    }
+    if (r.elements && typeof r.elements === "object" && !Array.isArray(r.elements)) {
+        const groups = {};
+        for (const [group, parts] of Object.entries(r.elements)) {
+            const v = flat(parts);
+            if (v)
+                groups[group] = v;
+        }
+        if (Object.keys(groups).length)
+            out.elements = groups;
+    }
+    return out;
+}
+export async function checkLookSpec(raw) {
+    const tokens = await loadTokens();
+    const spec = cleanLookSpec(raw);
+    const look = tokens.make(spec);
+    return { spec, look, lint: lintLook(look) };
+}
+export class LookLibrary {
+    dir;
+    log;
+    constructor(dir, log) {
+        this.dir = dir;
+        this.log = log;
+    }
+    list() {
+        const out = [];
+        if (!existsSync(this.dir))
+            return out;
+        for (const entry of readdirSync(this.dir, { withFileTypes: true })) {
+            if (!entry.isFile() || !entry.name.endsWith(".json"))
+                continue;
+            const id = entry.name.slice(0, -5);
+            if (!LOOK_ID.test(id))
+                continue;
+            try {
+                const spec = cleanLookSpec(JSON.parse(readFileSync(join(this.dir, entry.name), "utf8")));
+                if (spec.id !== id)
+                    throw new Error(`the file says id "${spec.id}"`);
+                out.push(spec);
+            }
+            catch (error) {
+                this.log.warn(`look ${id} skipped: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        return out.sort((a, b) => (a.created ?? "").localeCompare(b.created ?? "") || a.label.localeCompare(b.label));
+    }
+    get(id) {
+        return this.list().find((l) => l.id === id);
+    }
+    async save(raw, options) {
+        const checked = await checkLookSpec({ ...raw, author: options.author });
+        if (!checked.lint.ok)
+            throw new Error(`the look does not read: ${checked.lint.errors.map((e) => e.message).join("; ")}`);
+        const existing = this.get(checked.spec.id);
+        if (existing && !options.replace)
+            throw new Error(`a look "${checked.spec.id}" exists already; say replace to overwrite it`);
+        const now = new Date().toISOString();
+        const spec = { ...checked.spec, author: options.author, created: existing?.created ?? now, updatedAt: now };
+        mkdirSync(this.dir, { recursive: true });
+        writeFileAtomic(join(this.dir, `${spec.id}.json`), `${JSON.stringify(spec, null, 2)}\n`);
+        this.log.info(`${existing ? "replaced" : "saved"} look "${spec.label}" (${spec.id}) by ${options.author}`);
+        return { ...checked, spec };
+    }
+    remove(id) {
+        if (!LOOK_ID.test(id))
+            return false;
+        const file = join(this.dir, `${id}.json`);
+        if (!existsSync(file))
+            return false;
+        rmSync(file, { force: true });
+        this.log.info(`removed look ${id}`);
+        return true;
+    }
+    async css() {
+        const tokens = await loadTokens();
+        const lines = ["/* the looks of this hub's human (<dataDir>/looks/*.json), generated by the hub; a window picks one with data-look on <html> */"];
+        for (const spec of this.list()) {
+            let look;
+            try {
+                look = tokens.make(spec);
+            }
+            catch (error) {
+                this.log.warn(`look ${spec.id} does not build: ${error instanceof Error ? error.message : String(error)}`);
+                continue;
+            }
+            lines.push(`:root[data-look="${look.id}"] {`);
+            for (const group of tokens.cssGroups(look)) {
+                lines.push(`  /* ${group.title} */`);
+                for (const [name, value] of group.entries)
+                    lines.push(`  ${name}: ${value};`);
+            }
+            lines.push("}");
+        }
+        return `${lines.join("\n")}\n`;
+    }
+    async describe() {
+        const tokens = await loadTokens();
+        const own = this.list().map((l) => ({ id: l.id, label: l.label, scheme: l.scheme ?? null, extends: l.extends ?? DEFAULT_BASE, author: l.author ?? "human", updatedAt: l.updatedAt ?? null }));
+        return { ...tokens.describe(), ownLooks: own };
+    }
+}

package/dist/mcp-skills-server.js

@@ -40,6 +40,19 @@ const DESIGN_FIELDS = {
         },
     },
 };
+const LOOK_SPEC_FIELDS = {
+    id: { type: "string", description: "short lower-case id (letters, digits, hyphens; 1-31 characters, starting with a letter): the file's name; never the id of a look viberoom ships" },
+    label: { type: "string", description: "the name the picker shows (1-40 characters)" },
+    extends: { type: "string", description: "the shipped look it starts from (describe_looks lists them: classic is VibeClassic, light; classic-dark; clay; comfort; plush is 3D; terminal); classic when omitted" },
+    scheme: { type: "string", enum: ["light", "dark"], description: "light or dark paper (diagrams and marks are drawn for it); the base's when omitted" },
+    palette: { type: "object", description: "hues laid over the base's palette, by name, each a flat colour #rrggbb: { primary: \"#b5533c\", bg: \"#f6f1e7\" }; describe_looks tells what every hue is for", additionalProperties: { type: "string" } },
+    shape: { type: "object", description: "corners: rScale (0 square … 1.6 very round), rCtlMin (0px keeps each control's own corner, 99px makes every control a pill)", additionalProperties: { type: "string" } },
+    type: { type: "object", description: "text: font and mono (an id from describe_looks fonts, or a family stack), lineHeight, fsScale", additionalProperties: { type: "string" } },
+    motion: { type: "object", description: "tFast, tBase, tSlow (durations, 0ms for none), easeOut, easePop", additionalProperties: { type: "string" } },
+    elevation: { type: "object", description: "shadows and light, as CSS: a shadow, none, or for bevel a gradient; $name, alpha($name, 0.2) and mix($a, $b, 0.5) may stand inside", additionalProperties: { type: "string" } },
+    canvas: { type: "object", description: "the chat's paper: gradCanvas (a colour or gradients), canvasPattern (none, or a pattern), canvasPatternSize, gradPage, the scrollbar", additionalProperties: { type: "string" } },
+    elements: { type: "object", description: "per element group, the parts to change: { bubble: { bg: \"$white\", border: \"alpha($ink, 0.12)\" }, btn: { shadow: \"none\" } }; describe_looks lists every group and key with its VibeClassic value", additionalProperties: { type: "object", additionalProperties: { type: "string" } } },
+};
 const TOOLS = [
     {
         name: TOOL_NAME,
@@ -124,6 +137,46 @@ const TOOLS = [
             required: ["why"],
         },
     },
+    {
+        name: "describe_looks",
+        description: "Everything about the looks before you design one: the looks that exist (the ones viberoom ships and the human's own), how the window is set now (the look worn, its fine-tuning, the fonts, the text size), every token a look may set with what it means and its VibeClassic value, how a value is written ($name, alpha(), mix()), the fonts by id, and what may be fine-tuned on any look without a spec. Read-only. Load the built-in skill \"look-designer\" for what makes a look good.",
+        inputSchema: { type: "object", properties: {} },
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: "lint_look",
+        description: "Check a look spec without saving anything: whether every key exists and every value is of the right kind, and whether the words read on their paper (the contrast floors every look must pass), with the ratio of every pair measured, so you see the numbers you cannot see as colours. Errors must go before create_look takes it; warnings are advice.",
+        inputSchema: { type: "object", properties: LOOK_SPEC_FIELDS, required: ["id", "label"] },
+        annotations: { readOnlyHint: true },
+    },
+    {
+        name: "create_look",
+        description: "Save a look among the human's own looks: a file the human picks under Settings → Appearance, listed after the looks viberoom ships with the human's name on it. The spec extends a shipped look and changes only what it gives. The hub checks it first (an error stops the save, warnings come back with it). Nothing is worn until the human picks it (or applies a propose_look_changes card). A taken id needs replace: true (one of the human's own looks may be replaced; a look viberoom ships never).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...LOOK_SPEC_FIELDS,
+                replace: { type: "boolean", description: "optional: overwrite the human's look with this id instead of refusing" },
+            },
+            required: ["id", "label"],
+        },
+    },
+    {
+        name: "propose_look_changes",
+        description: "Propose a change to how the human's window looks, as a card the human applies or rejects: which look to wear (a shipped one, or one of the human's own by its id, e.g. one you just saved), the fine-tuning of a look (the adjustables describe_looks lists: a colour as #rrggbb, a scale as a number 0-2), the fonts, the text size. This is the whole window, not this room alone; nothing changes until the human clicks Apply, and the room gets a line with the outcome. Say in why what it improves.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                why: { type: "string", description: "one or two sentences: what this change improves; shown on the card" },
+                look: { type: "string", description: "optional: the id of the look to wear" },
+                adjust: { type: "object", description: "optional: the fine-tuning of the look named in look (or of the one worn now): { accent: \"#b5533c\", corners: 0.5 }; describe_looks lists the keys", additionalProperties: {} },
+                chatFontSize: { type: "number", description: "optional: the text size in px, 12-24" },
+                font: { type: "string", description: "optional: a text font id (describe_looks fonts.text)" },
+                mono: { type: "string", description: "optional: a code font id (describe_looks fonts.mono)" },
+            },
+            required: ["why"],
+        },
+    },
     {
         name: "read_message",
         description: "One message of this room by its number: the whole of a message that was quoted to you as \"> Name (#N, time): …\", or any message whose #N you have seen. Returns who wrote it, to whom, when, its text, its images as file paths and, with around > 0, up to that many messages before and after it. Read-only; the human sees the call like any other tool call.",
@@ -276,6 +329,40 @@ async function handle(message) {
                 reply(id, { content: [{ type: "text", text: String(res.body.message ?? "proposed") }] });
                 return;
             }
+            if (name === "describe_looks") {
+                const res = await hub(`/api/mcp/looks?token=${encodeURIComponent(TOKEN)}`);
+                if (!res.ok)
+                    return errorResult("the looks could not be described", res);
+                reply(id, { content: [{ type: "text", text: JSON.stringify(res.body, null, 2) }] });
+                return;
+            }
+            if (name === "lint_look" || name === "create_look") {
+                const { replace, ...spec } = args;
+                const res = await hub(name === "lint_look" ? "/api/mcp/looks/lint" : "/api/mcp/looks/create", {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ token: TOKEN, spec, replace }),
+                });
+                if (!res.ok)
+                    return errorResult(name === "lint_look" ? "the look could not be checked" : "the look could not be saved", res);
+                if (name === "lint_look") {
+                    reply(id, { content: [{ type: "text", text: JSON.stringify(res.body, null, 2) }], isError: res.body.ok === false ? true : undefined });
+                    return;
+                }
+                reply(id, { content: [{ type: "text", text: String(res.body.message ?? "saved") }] });
+                return;
+            }
+            if (name === "propose_look_changes") {
+                const res = await hub("/api/mcp/looks/propose", {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ token: TOKEN, ...args }),
+                });
+                if (!res.ok)
+                    return errorResult("the proposal could not be made", res);
+                reply(id, { content: [{ type: "text", text: String(res.body.message ?? "proposed") }] });
+                return;
+            }
             if (name === "read_message") {
                 const seq = Number(args.seq);
                 if (!Number.isInteger(seq))