A local-first multi-agent app development platform, built on PenguinHarness
/**
* Imported themes (src/internal/external-theme.ts).
*
* Two things break without a test here and neither shows up on the machine that wrote the file: a
* value that escapes its declaration (the file becomes CSS once it is served, so `red} body{…`
* would repaint — or unhide — anything), and a base rule that does not reach dark mode (the
* theme's own value would lose to Primer's `.dark` rule, which is the one thing an imported theme
* is allowed to assume it beats).
*/
import { describe, expect, it } from "vitest";
import {
THEME_ID_PATTERN,
externalThemeCss,
externalThemesCss,
isThemeId,
readExternalTheme,
} from "../src/internal/external-theme.js";
const VALID = {
schemaVersion: 1,
id: "warm-paper",
name: "Warm paper",
nameZh: "暖纸",
light: { "--ui-canvas": "#f7f2e8", "--ui-accent": "#a4471f", "--ui-fg": "#2b2620" },
dark: { "--ui-canvas": "#1a1713", "--ui-fg": "#ece6dc" },
accents: [
{ id: "clay", light: { "--ui-accent": "#b8552f" }, dark: { "--ui-accent": "#d9906c" } },
],
};
function read(value: unknown) {
const result = readExternalTheme(value);
if (!result.ok) throw new Error(`expected ok, got: ${result.errors.join(" / ")}`);
return result.theme;
}
describe("readExternalTheme", () => {
it("reads a whole file, keeping the optional parts", () => {
const theme = read(VALID);
expect(theme.id).toBe("warm-paper");
expect(theme.nameZh).toBe("暖纸");
expect(theme.dark?.["--ui-canvas"]).toBe("#1a1713");
expect(theme.accents?.[0]?.id).toBe("clay");
});
it("reads a file that only sets light values", () => {
const theme = read({ id: "bare", name: "Bare", light: { "--ui-canvas": "#ffffff" } });
expect(theme.dark).toBeUndefined();
// One rule, whose selector list already reaches dark mode: no second `.dark` rule.
expect(externalThemeCss(theme).match(/\.dark\{/g)).toHaveLength(1);
});
it("refuses a value that would leave its declaration", () => {
for (const value of [
"#fff; } body { display: none",
"url(https://example.com/x.png)",
"image-set(url(a.png) 1x)",
"@import 'x.css'",
"red}",
"back\\slash",
"<script>",
"#fff\n--ui-accent: red",
]) {
const result = readExternalTheme({
id: "escape",
name: "Escape",
light: { "--ui-canvas": value },
});
expect(result.ok, value).toBe(false);
}
});
it("refuses names that are not spelled like a token", () => {
const result = readExternalTheme({ id: "x", name: "X", light: { "ui-canvas": "#fff" } });
expect(result.ok).toBe(false);
if (!result.ok) expect(result.errors[0]).toContain("ui-canvas");
});
it("refuses ids that are not ids", () => {
for (const id of ["Warm", "9lives", "-lead", "a".repeat(33), ""]) {
const result = readExternalTheme({ ...VALID, id });
expect(result.ok, id).toBe(false);
}
// The shipped ids are legal ids (the module has no list of its own): an imported theme that
// takes one simply never matches, because its rules are scoped to its own data-theme.
expect(readExternalTheme({ ...VALID, id: "github" }).ok).toBe(true);
});
it("refuses a file with no light values, no name, or an unknown schemaVersion", () => {
expect(readExternalTheme({ ...VALID, light: {} }).ok).toBe(false);
expect(readExternalTheme({ ...VALID, name: "" }).ok).toBe(false);
expect(readExternalTheme({ ...VALID, schemaVersion: 2 }).ok).toBe(false);
expect(readExternalTheme([]).ok).toBe(false);
expect(readExternalTheme("hi").ok).toBe(false);
});
it("refuses `neutral`, duplicate and malformed accents", () => {
const result = readExternalTheme({
...VALID,
accents: [
{ id: "neutral", light: { "--ui-accent": "#111111" } },
{ id: "clay", light: { "--ui-accent": "#b8552f" } },
{ id: "clay", light: { "--ui-accent": "#999999" } },
{ id: "Slate", light: { "--ui-accent": "#5c6470" } },
{ id: "honey", light: {} },
],
});
expect(result.ok).toBe(false);
if (!result.ok) {
const all = result.errors.join("\n");
expect(all).toContain("neutral");
expect(all).toContain("两次");
expect(all).toContain("Slate");
}
});
it("caps a runaway file instead of turning it into a stylesheet", () => {
const many = Object.fromEntries(
Array.from({ length: 401 }, (_v, i) => [`--ui-token-${i}`, "#ffffff"]),
);
expect(readExternalTheme({ id: "huge", name: "Huge", light: many }).ok).toBe(false);
const thirteen = Array.from({ length: 13 }, (_v, i) => ({
id: `accent-${i}`,
light: { "--ui-accent": "#ffffff" },
}));
expect(readExternalTheme({ ...VALID, accents: thirteen }).ok).toBe(false);
});
});
describe("externalThemeCss", () => {
it("writes the base rule for both modes and the accent presets into their layers", () => {
const css = externalThemeCss(read(VALID));
expect(css).toContain("@layer ui-theme{");
expect(css).toContain("@layer ui-accent{");
// The base rule reaches dark mode by itself: :root[data-theme="warm-paper"].dark is in the
// SAME selector list as the light one, so a name dark does not change keeps the theme's value
// rather than falling back to Primer's `.dark` rule.
expect(css).toContain(
':root[data-theme="warm-paper"],:root[data-theme="warm-paper"].dark{--ui-canvas:#f7f2e8;--ui-accent:#a4471f;--ui-fg:#2b2620}',
);
expect(css).toContain(
':root[data-theme="warm-paper"].dark{--ui-canvas:#1a1713;--ui-fg:#ece6dc}',
);
expect(css).toContain(
':root[data-theme="warm-paper"][data-accent="clay"],:root[data-theme="warm-paper"][data-accent="clay"].dark{--ui-accent:#b8552f}',
);
expect(css).toContain(
':root[data-theme="warm-paper"][data-accent="clay"].dark{--ui-accent:#d9906c}',
);
// Nothing is emitted outside a layer: an unlayered rule would beat `ui-font`, where the user's
// own font pairing lives.
let depth = 0;
const outside: string[] = [];
for (const line of css.split("\n")) {
if (depth === 0 && line !== "" && !line.startsWith("/*") && !line.startsWith("@layer ")) {
outside.push(line);
}
depth += (line.match(/\{/g) ?? []).length - (line.match(/\}/g) ?? []).length;
}
expect(outside).toEqual([]);
expect(depth).toBe(0);
});
it("says so when there is nothing to serve", () => {
expect(externalThemesCss([])).toContain("no imported themes");
expect(externalThemesCss([read(VALID)])).toContain('data-theme="warm-paper"');
});
/**
* The palette bridge: most of the app still spells `bg-white` / `text-gray-500` /
* `border-gray-200`, and a shipped theme keeps those following it by re-pointing Tailwind's
* `--color-gray-*` from its own values. An imported theme cannot declare those names itself, so
* without this it paints its own tokens dark and leaves every palette-class rung on the default
* theme's ramp — dark cards with white header bands, light borders and unreadable ink.
*/
const FULL = {
id: "full",
name: "Full",
light: {
"--ui-canvas": "#ffffff",
"--ui-surface": "#ffffff",
"--ui-surface-muted": "#f1f0ee",
"--ui-line-muted": "#eeeeee",
"--ui-line": "#dddddd",
"--ui-line-emphasis": "#cccccc",
"--ui-fg-subtle": "#999999",
"--ui-fg-muted": "#777777",
"--ui-fg": "#222222",
"--ui-fg-emphasis": "#000000",
},
dark: {
"--ui-canvas": "#111111",
"--ui-surface": "#1a1a1a",
"--ui-surface-muted": "#222222",
"--ui-line": "#333333",
"--ui-fg": "#eeeeee",
"--ui-fg-emphasis": "#ffffff",
},
};
it("re-points Tailwind's gray ramp onto the theme's own tokens, in both modes", () => {
const css = externalThemeCss(read(FULL));
// Light: the correspondence the default theme declares for itself, expressed in this theme's
// tokens instead of its literals — so a dark imported theme moves the whole ramp with it.
expect(css).toContain(
':root[data-theme="full"],:root[data-theme="full"].dark{--color-gray-50:var(--ui-surface-muted);' +
"--color-gray-100:var(--ui-line-muted);--color-gray-200:var(--ui-line);" +
"--color-gray-300:var(--ui-line-emphasis);--color-gray-400:var(--ui-fg-subtle);" +
"--color-gray-500:var(--ui-fg-muted);--color-gray-600:var(--ui-fg-muted);" +
"--color-gray-700:var(--ui-fg);--color-gray-800:var(--ui-fg);" +
"--color-gray-900:var(--ui-fg-emphasis);--color-gray-950:var(--ui-fg-emphasis)}",
);
// Dark: the ramp inverts — the low rungs carry the ink, the high ones the fills. Emitted after
// the light bridge, which is what lets it win the `.dark` selector the two share.
expect(css).toContain(
':root[data-theme="full"].dark{--color-gray-50:var(--ui-surface-muted);' +
"--color-gray-100:var(--ui-fg);--color-gray-200:var(--ui-line);" +
"--color-gray-300:var(--ui-fg-muted);--color-gray-400:var(--ui-fg-muted);" +
"--color-gray-500:var(--ui-fg-subtle);--color-gray-600:var(--ui-fg-subtle);" +
"--color-gray-700:var(--ui-line);--color-gray-800:var(--ui-line);" +
"--color-gray-900:var(--ui-surface);--color-gray-950:var(--ui-canvas)}",
);
// `--color-white` is left to the default theme: it is `var(--ui-surface)` there in every mode.
expect(css).not.toContain("--color-white");
// The dark bridge is the LATER of the two, which is what makes it win the `.dark` selector they
// share (same specificity, so the cascade decides by position).
expect(css.indexOf("--color-gray-100:var(--ui-fg)")).toBeGreaterThan(
css.indexOf("--color-gray-100:var(--ui-line-muted)"),
);
});
it("bridges only the rungs whose token this theme declares", () => {
// `warm-paper` declares ink and a canvas and nothing else: no line, wash or subtle rung is
// bridged, because pointing one at a token the default theme aliases back onto that same rung
// would leave css with a cycle — which it resolves by discarding both values.
const css = externalThemeCss(read(VALID));
expect(css).toContain(
':root[data-theme="warm-paper"],:root[data-theme="warm-paper"].dark' +
"{--color-gray-700:var(--ui-fg);--color-gray-800:var(--ui-fg)}",
);
expect(css).not.toContain("--color-gray-200");
expect(css).not.toContain("--color-gray-500");
expect(css).not.toContain("--color-gray-50:");
});
it("leaves a rung alone when the theme's own value is an alias back into the palette", () => {
const css = externalThemeCss(
read({
id: "aliased",
name: "Aliased",
light: { "--ui-line": "var(--color-gray-200)", "--ui-fg": "#222222" },
}),
);
expect(css).toContain("--ui-line:var(--color-gray-200)");
expect(css).not.toContain("--color-gray-200:var(--ui-line)");
// The rung beside it, whose token is a plain colour, is still bridged.
expect(css).toContain("--color-gray-700:var(--ui-fg)");
});
it("writes no dark bridge for a theme that only sets light values", () => {
const css = externalThemeCss(
read({ id: "bare", name: "Bare", light: { "--ui-fg": "#111111", "--ui-canvas": "#ffffff" } }),
);
expect(css).toContain("--color-gray-700:var(--ui-fg)");
expect(css).not.toContain("--color-gray-950");
});
});
describe("the id pattern", () => {
it("accepts the shipped ids and what an author would plausibly write, refusing the rest", () => {
for (const id of ["github", "modern", "geek", "warm-paper", "a", "x-9-9"]) {
expect(isThemeId(id), id).toBe(true);
}
for (const id of ["", "-a", "A", "a b", "a_b", "a.b", "a".repeat(33), 7, null, undefined]) {
expect(isThemeId(id), String(id)).toBe(false);
}
expect(THEME_ID_PATTERN.source).toBe("^[a-z][a-z0-9-]{0,31}$");
});
});