@capybara-hq/plugin-sdk 0.1.0-rc.6 → 0.1.0-rc.8

package/dist/theme-tokens.generated.d.ts

@@ -0,0 +1,275 @@
+/** The built-in token values a theme overrides (design spec §2). */
+export declare const THEME_TOKENS: {
+    readonly color: {
+        readonly bg: {
+            readonly dark: "#0A0A0A";
+            readonly light: "#FAF9F6";
+        };
+        readonly panel: {
+            readonly dark: "#111110";
+            readonly light: "#FFFFFF";
+        };
+        readonly "panel-2": {
+            readonly dark: "#0E0E0D";
+            readonly light: "#FCFBF9";
+        };
+        readonly sidebar: {
+            readonly dark: "#111110";
+            readonly light: "#F3F2EE";
+        };
+        readonly "sidebar-active": {
+            readonly dark: "#1A1A18";
+            readonly light: "rgba(26,26,24,0.09)";
+        };
+        readonly raised: {
+            readonly dark: "#141413";
+            readonly light: "#FFFFFF";
+        };
+        readonly selected: {
+            readonly dark: "#1F1F1D";
+            readonly light: "rgba(26,26,24,0.07)";
+        };
+        readonly hover: {
+            readonly dark: "#171716";
+            readonly light: "rgba(26,26,24,0.04)";
+        };
+        readonly "line-soft": {
+            readonly dark: "#1C1C1A";
+            readonly light: "#E8E7E2";
+        };
+        readonly line: {
+            readonly dark: "#2A2A28";
+            readonly light: "#D9D8D2";
+        };
+        readonly "line-strong": {
+            readonly dark: "#3A3A37";
+            readonly light: "#B5B5AE";
+        };
+        readonly "line-card": {
+            readonly dark: "rgba(255,255,255,0.08)";
+            readonly light: "rgba(26,26,24,0.07)";
+        };
+        readonly "scroll-thumb": {
+            readonly dark: "rgba(255,255,255,0.15)";
+            readonly light: "rgba(26,26,24,0.20)";
+        };
+        readonly ink: {
+            readonly dark: "#E6E6E3";
+            readonly light: "#1A1A18";
+        };
+        readonly muted: {
+            readonly dark: "#8E8E89";
+            readonly light: "#5E5E5A";
+        };
+        readonly faint: {
+            readonly dark: "#5A5A56";
+            readonly light: "#9A9A94";
+        };
+        readonly disabled: {
+            readonly dark: "#6E6E69";
+            readonly light: "#82827C";
+        };
+        readonly accent: {
+            readonly dark: "#FF6A13";
+            readonly light: "#CC4609";
+        };
+        readonly "accent-hover": {
+            readonly dark: "#FF8240";
+            readonly light: "#B83F08";
+        };
+        readonly "accent-press": {
+            readonly dark: "#E85A08";
+            readonly light: "#A33707";
+        };
+        readonly "on-accent": {
+            readonly dark: "#0A0A0A";
+            readonly light: "#FFFFFF";
+        };
+        readonly "accent-tint": {
+            readonly dark: "color-mix(in srgb, var(--cb-accent) 12%, transparent)";
+            readonly light: "color-mix(in srgb, var(--cb-accent) 12%, transparent)";
+        };
+        readonly "focus-ring": {
+            readonly dark: "rgba(255,106,19,.25)";
+            readonly light: "rgba(204,70,9,.18)";
+        };
+        readonly ok: {
+            readonly dark: "#3FD483";
+            readonly light: "#16803F";
+        };
+        readonly fail: {
+            readonly dark: "#FF5C52";
+            readonly light: "#C8302A";
+        };
+        readonly warn: {
+            readonly dark: "#F2C14B";
+            readonly light: "#8F6500";
+        };
+        readonly scrim: {
+            readonly dark: "rgba(0,0,0,.60)";
+            readonly light: "rgba(10,10,10,.25)";
+        };
+        readonly "diff-add": {
+            readonly dark: "rgba(63,212,131,.08)";
+            readonly light: "rgba(22,128,63,.10)";
+        };
+        readonly "diff-del": {
+            readonly dark: "rgba(255,92,82,.08)";
+            readonly light: "rgba(207,34,46,.08)";
+        };
+        readonly "avatar-black": {
+            readonly dark: "#1C1C1A";
+            readonly light: "#1C1C1A";
+        };
+        readonly "avatar-white": {
+            readonly dark: "#F2F2EE";
+            readonly light: "#FFFFFF";
+        };
+        readonly "avatar-capybara-ground": {
+            readonly dark: "#3D2213";
+            readonly light: "#FBE3D2";
+        };
+        readonly "avatar-black-bear-ground": {
+            readonly dark: "#9C8468";
+            readonly light: "#E6D6C1";
+        };
+        readonly "avatar-black-bear-snout": {
+            readonly dark: "#C9A074";
+            readonly light: "#C49A6C";
+        };
+        readonly "avatar-panda-ground": {
+            readonly dark: "#5E9168";
+            readonly light: "#669D71";
+        };
+        readonly "avatar-elephant-ground": {
+            readonly dark: "#2A2838";
+            readonly light: "#E6E3F2";
+        };
+        readonly "avatar-elephant": {
+            readonly dark: "#9AA0A8";
+            readonly light: "#757B84";
+        };
+        readonly "avatar-elephant-ear": {
+            readonly dark: "#7D838C";
+            readonly light: "#5A6068";
+        };
+        readonly "avatar-fox-ground": {
+            readonly dark: "#3A2414";
+            readonly light: "#FCEBD9";
+        };
+        readonly "avatar-fox": {
+            readonly dark: "#F07A2E";
+            readonly light: "#D8601A";
+        };
+        readonly "avatar-fox-ear": {
+            readonly dark: "#8A3E16";
+            readonly light: "#7A3310";
+        };
+        readonly "avatar-owl-ground": {
+            readonly dark: "#2E2618";
+            readonly light: "#EFE6D4";
+        };
+        readonly "avatar-owl": {
+            readonly dark: "#B07D52";
+            readonly light: "#875A36";
+        };
+        readonly "avatar-owl-belly": {
+            readonly dark: "#D9B68C";
+            readonly light: "#D9B68C";
+        };
+        readonly "avatar-owl-eye": {
+            readonly dark: "#F5C542";
+            readonly light: "#F5C542";
+        };
+        readonly "avatar-beak": {
+            readonly dark: "#EE8A2A";
+            readonly light: "#EE8A2A";
+        };
+        readonly "avatar-penguin-ground": {
+            readonly dark: "#5F8AAD";
+            readonly light: "#6692B6";
+        };
+        readonly "avatar-rabbit-ground": {
+            readonly dark: "#3A2229";
+            readonly light: "#F8DDE3";
+        };
+        readonly "avatar-rabbit": {
+            readonly dark: "#B89A84";
+            readonly light: "#8F725C";
+        };
+        readonly "avatar-rabbit-pink": {
+            readonly dark: "#F2A7B5";
+            readonly light: "#F2A7B5";
+        };
+        readonly "avatar-turtle-ground": {
+            readonly dark: "#2E2A18";
+            readonly light: "#F2E8C9";
+        };
+        readonly "avatar-turtle": {
+            readonly dark: "#5FA548";
+            readonly light: "#4E8F3A";
+        };
+        readonly "avatar-turtle-shell": {
+            readonly dark: "#3B7330";
+            readonly light: "#2F5E24";
+        };
+        readonly "avatar-turtle-skin": {
+            readonly dark: "#A8C66C";
+            readonly light: "#9FBF62";
+        };
+        readonly "avatar-whale-ground": {
+            readonly dark: "#16283A";
+            readonly light: "#DCEFF5";
+        };
+        readonly "avatar-whale": {
+            readonly dark: "#5A92D6";
+            readonly light: "#3A72B5";
+        };
+        readonly "avatar-whale-belly": {
+            readonly dark: "#DCEAF5";
+            readonly light: "#FFFFFF";
+        };
+        readonly "avatar-whale-spout": {
+            readonly dark: "#8EC3E8";
+            readonly light: "#8EC3E8";
+        };
+    };
+    readonly shadow: {
+        readonly "shadow-1": {
+            readonly dark: "0 8px 24px rgba(0,0,0,.40)";
+            readonly light: "0 2px 8px rgba(10,10,10,.08)";
+        };
+        readonly "shadow-2": {
+            readonly dark: "0 16px 48px rgba(0,0,0,.50)";
+            readonly light: "0 8px 24px rgba(10,10,10,.12)";
+        };
+        readonly "shadow-sheet": {
+            readonly dark: "-16px 0 40px rgba(0,0,0,.40)";
+            readonly light: "-4px 0 16px rgba(10,10,10,.08)";
+        };
+        readonly "shadow-float": {
+            readonly dark: "0 8px 24px rgba(0,0,0,.45)";
+            readonly light: "0 8px 24px rgba(26,26,24,.08)";
+        };
+    };
+    readonly radius: {
+        readonly sm: 4;
+        readonly md: 8;
+        readonly bubble: 10;
+    };
+};
+/** The built-in font stacks a theme's fonts go in front of: `mono` is `--cb-font`, `prose` `--cb-font-prose`. */
+export declare const THEME_FONTS: {
+    readonly mono: "\"Sarasa Mono SC\", ui-monospace, monospace";
+    readonly prose: "\"Inter\", \"Source Han Sans SC\", system-ui, sans-serif";
+};
+/** The tokens a theme may override: no avatar colors, no color-mix values (they derive). */
+export declare const THEME_OVERRIDABLE: {
+    readonly color: readonly ["bg", "panel", "panel-2", "sidebar", "sidebar-active", "raised", "selected", "hover", "line-soft", "line", "line-strong", "line-card", "scroll-thumb", "ink", "muted", "faint", "disabled", "accent", "accent-hover", "accent-press", "on-accent", "focus-ring", "ok", "fail", "warn", "scrim", "diff-add", "diff-del"];
+    readonly shadow: readonly ["shadow-1", "shadow-2", "shadow-sheet", "shadow-float"];
+    readonly radius: readonly ["sm", "md", "bubble"];
+};
+/** [foreground, background, floor] or, with a fourth element, the surface it sits on. */
+export declare const THEME_CONTRAST: readonly (readonly [fg: string, bg: string, floor: number, over?: string])[];
+/** [ground, surface, minimum OKLab lightness difference x100]. */
+export declare const THEME_SEPARATION: readonly (readonly [ground: string, surface: string, floor: number])[];

package/dist/theme-tokens.generated.js

@@ -0,0 +1,167 @@
+// Generated by pnpm gen:tokens from docs/design/tokens.json; do not edit.
+// biome-ignore-all format: token values stay verbatim (uppercase hex, rgba spelling)
+/** The built-in token values a theme overrides (design spec §2). */
+export const THEME_TOKENS = {
+    color: {
+        "bg": { dark: "#0A0A0A", light: "#FAF9F6" },
+        "panel": { dark: "#111110", light: "#FFFFFF" },
+        "panel-2": { dark: "#0E0E0D", light: "#FCFBF9" },
+        "sidebar": { dark: "#111110", light: "#F3F2EE" },
+        "sidebar-active": { dark: "#1A1A18", light: "rgba(26,26,24,0.09)" },
+        "raised": { dark: "#141413", light: "#FFFFFF" },
+        "selected": { dark: "#1F1F1D", light: "rgba(26,26,24,0.07)" },
+        "hover": { dark: "#171716", light: "rgba(26,26,24,0.04)" },
+        "line-soft": { dark: "#1C1C1A", light: "#E8E7E2" },
+        "line": { dark: "#2A2A28", light: "#D9D8D2" },
+        "line-strong": { dark: "#3A3A37", light: "#B5B5AE" },
+        "line-card": { dark: "rgba(255,255,255,0.08)", light: "rgba(26,26,24,0.07)" },
+        "scroll-thumb": { dark: "rgba(255,255,255,0.15)", light: "rgba(26,26,24,0.20)" },
+        "ink": { dark: "#E6E6E3", light: "#1A1A18" },
+        "muted": { dark: "#8E8E89", light: "#5E5E5A" },
+        "faint": { dark: "#5A5A56", light: "#9A9A94" },
+        "disabled": { dark: "#6E6E69", light: "#82827C" },
+        "accent": { dark: "#FF6A13", light: "#CC4609" },
+        "accent-hover": { dark: "#FF8240", light: "#B83F08" },
+        "accent-press": { dark: "#E85A08", light: "#A33707" },
+        "on-accent": { dark: "#0A0A0A", light: "#FFFFFF" },
+        "accent-tint": { dark: "color-mix(in srgb, var(--cb-accent) 12%, transparent)", light: "color-mix(in srgb, var(--cb-accent) 12%, transparent)" },
+        "focus-ring": { dark: "rgba(255,106,19,.25)", light: "rgba(204,70,9,.18)" },
+        "ok": { dark: "#3FD483", light: "#16803F" },
+        "fail": { dark: "#FF5C52", light: "#C8302A" },
+        "warn": { dark: "#F2C14B", light: "#8F6500" },
+        "scrim": { dark: "rgba(0,0,0,.60)", light: "rgba(10,10,10,.25)" },
+        "diff-add": { dark: "rgba(63,212,131,.08)", light: "rgba(22,128,63,.10)" },
+        "diff-del": { dark: "rgba(255,92,82,.08)", light: "rgba(207,34,46,.08)" },
+        "avatar-black": { dark: "#1C1C1A", light: "#1C1C1A" },
+        "avatar-white": { dark: "#F2F2EE", light: "#FFFFFF" },
+        "avatar-capybara-ground": { dark: "#3D2213", light: "#FBE3D2" },
+        "avatar-black-bear-ground": { dark: "#9C8468", light: "#E6D6C1" },
+        "avatar-black-bear-snout": { dark: "#C9A074", light: "#C49A6C" },
+        "avatar-panda-ground": { dark: "#5E9168", light: "#669D71" },
+        "avatar-elephant-ground": { dark: "#2A2838", light: "#E6E3F2" },
+        "avatar-elephant": { dark: "#9AA0A8", light: "#757B84" },
+        "avatar-elephant-ear": { dark: "#7D838C", light: "#5A6068" },
+        "avatar-fox-ground": { dark: "#3A2414", light: "#FCEBD9" },
+        "avatar-fox": { dark: "#F07A2E", light: "#D8601A" },
+        "avatar-fox-ear": { dark: "#8A3E16", light: "#7A3310" },
+        "avatar-owl-ground": { dark: "#2E2618", light: "#EFE6D4" },
+        "avatar-owl": { dark: "#B07D52", light: "#875A36" },
+        "avatar-owl-belly": { dark: "#D9B68C", light: "#D9B68C" },
+        "avatar-owl-eye": { dark: "#F5C542", light: "#F5C542" },
+        "avatar-beak": { dark: "#EE8A2A", light: "#EE8A2A" },
+        "avatar-penguin-ground": { dark: "#5F8AAD", light: "#6692B6" },
+        "avatar-rabbit-ground": { dark: "#3A2229", light: "#F8DDE3" },
+        "avatar-rabbit": { dark: "#B89A84", light: "#8F725C" },
+        "avatar-rabbit-pink": { dark: "#F2A7B5", light: "#F2A7B5" },
+        "avatar-turtle-ground": { dark: "#2E2A18", light: "#F2E8C9" },
+        "avatar-turtle": { dark: "#5FA548", light: "#4E8F3A" },
+        "avatar-turtle-shell": { dark: "#3B7330", light: "#2F5E24" },
+        "avatar-turtle-skin": { dark: "#A8C66C", light: "#9FBF62" },
+        "avatar-whale-ground": { dark: "#16283A", light: "#DCEFF5" },
+        "avatar-whale": { dark: "#5A92D6", light: "#3A72B5" },
+        "avatar-whale-belly": { dark: "#DCEAF5", light: "#FFFFFF" },
+        "avatar-whale-spout": { dark: "#8EC3E8", light: "#8EC3E8" },
+    },
+    shadow: {
+        "shadow-1": { dark: "0 8px 24px rgba(0,0,0,.40)", light: "0 2px 8px rgba(10,10,10,.08)" },
+        "shadow-2": { dark: "0 16px 48px rgba(0,0,0,.50)", light: "0 8px 24px rgba(10,10,10,.12)" },
+        "shadow-sheet": { dark: "-16px 0 40px rgba(0,0,0,.40)", light: "-4px 0 16px rgba(10,10,10,.08)" },
+        "shadow-float": { dark: "0 8px 24px rgba(0,0,0,.45)", light: "0 8px 24px rgba(26,26,24,.08)" },
+    },
+    radius: { sm: 4, md: 8, bubble: 10 },
+};
+/** The built-in font stacks a theme's fonts go in front of: `mono` is `--cb-font`, `prose` `--cb-font-prose`. */
+export const THEME_FONTS = {
+    mono: "\"Sarasa Mono SC\", ui-monospace, monospace",
+    prose: "\"Inter\", \"Source Han Sans SC\", system-ui, sans-serif",
+};
+/** The tokens a theme may override: no avatar colors, no color-mix values (they derive). */
+export const THEME_OVERRIDABLE = {
+    color: [
+        "bg",
+        "panel",
+        "panel-2",
+        "sidebar",
+        "sidebar-active",
+        "raised",
+        "selected",
+        "hover",
+        "line-soft",
+        "line",
+        "line-strong",
+        "line-card",
+        "scroll-thumb",
+        "ink",
+        "muted",
+        "faint",
+        "disabled",
+        "accent",
+        "accent-hover",
+        "accent-press",
+        "on-accent",
+        "focus-ring",
+        "ok",
+        "fail",
+        "warn",
+        "scrim",
+        "diff-add",
+        "diff-del",
+    ],
+    shadow: [
+        "shadow-1",
+        "shadow-2",
+        "shadow-sheet",
+        "shadow-float",
+    ],
+    radius: ["sm", "md", "bubble"],
+};
+/** [foreground, background, floor] or, with a fourth element, the surface it sits on. */
+export const THEME_CONTRAST = [
+    ["ink", "bg", 4.5],
+    ["muted", "bg", 4.5],
+    ["muted", "panel", 4.5],
+    ["muted", "sidebar", 4.5],
+    ["muted", "panel-2", 4.5],
+    ["muted", "raised", 4.5],
+    ["muted", "selected", 4.5],
+    ["muted", "hover", 4.5],
+    ["disabled", "bg", 3],
+    ["disabled", "panel", 3],
+    ["disabled", "hover", 3],
+    ["disabled", "selected", 3],
+    ["ink", "sidebar-active", 4.5],
+    ["muted", "selected", 4.5, "sidebar"],
+    ["muted", "hover", 4.5, "sidebar"],
+    ["ink", "sidebar-active", 4.5, "sidebar"],
+    ["on-accent", "accent", 4.5],
+    ["fail", "bg", 4.5],
+    ["warn", "bg", 4.5],
+    ["fail", "panel", 4.5],
+    ["warn", "panel", 4.5],
+    ["accent", "bg", 3],
+    ["line", "bg", 1],
+    ["ink", "diff-add", 4.5],
+    ["ink", "diff-del", 4.5],
+    ["accent", "avatar-capybara-ground", 3],
+    ["avatar-black", "avatar-black-bear-ground", 3],
+    ["avatar-black", "avatar-panda-ground", 3],
+    ["avatar-elephant", "avatar-elephant-ground", 3],
+    ["avatar-fox", "avatar-fox-ground", 3],
+    ["avatar-owl", "avatar-owl-ground", 3],
+    ["avatar-black", "avatar-penguin-ground", 3],
+    ["avatar-rabbit", "avatar-rabbit-ground", 3],
+    ["avatar-turtle", "avatar-turtle-ground", 3],
+    ["avatar-whale", "avatar-whale-ground", 3],
+    ["avatar-white", "avatar-panda-ground", 3],
+    ["avatar-white", "avatar-penguin-ground", 3],
+];
+/** [ground, surface, minimum OKLab lightness difference x100]. */
+export const THEME_SEPARATION = [
+    ["hover", "bg", 2.5],
+    ["hover", "panel", 2.5],
+    ["hover", "sidebar", 2.5],
+    ["selected", "bg", 2.5],
+    ["selected", "panel", 2.5],
+    ["selected", "sidebar", 2.5],
+    ["sidebar-active", "sidebar", 2.5],
+];

package/dist/theme.d.ts

@@ -0,0 +1,152 @@
+import { z } from "zod";
+import { type LocalizedName } from "./plugin-package.js";
+import { type MergedScheme, type ThemeScheme } from "./theme-readability.js";
+/**
+ * A theme file `themes/<id>.json` (themes spec §4): a partial override of the design tokens per
+ * scheme, optional fonts and an optional logo. The id is the file's base name
+ * ({@link themeIdOf}, `CATALOG_ITEM_NAME_RE`).
+ *
+ * {@link parseThemeFile} is the CSS-injection boundary: every token value is parsed against the
+ * grammar `tokens.json` uses (`#RRGGBB`, `rgba(r,g,b,a)`, shadows `<x> <y> <blur> [<spread>]
+ * <color>`) and re-rendered from its parts in canonical form. Asset paths (`fonts[].file`,
+ * `logo.*`) are relative to the plugin root (an optional leading `./`) and every segment is limited
+ * to `[A-Za-z0-9._-]`, so they need no escaping inside `url(...)`. Font families are limited to
+ * letters, digits, spaces and `-`. Free text (`name`, `description`, `logo.wordmark`) carries no
+ * control, format, line / paragraph separator or lone surrogate characters; it is text for the UI,
+ * never CSS. Whether the files exist and their size / signature / SVG rules are checked by
+ * the reader of the package, with {@link THEME_LIMITS}.
+ *
+ * The committed JSON Schema (`schemas/theme.v1.schema.json`) is generated from
+ * {@link ThemeFileSchema} (the shape only) by `pnpm gen:package-schemas`; token names, value
+ * grammar, path safety and readability are decided only by {@link parseThemeFile}.
+ */
+/** Limits of theme files and their assets. */
+export declare const THEME_LIMITS: {
+    /** UTF-8 bytes of one theme file. */
+    readonly fileBytes: number;
+    /** Themes per plugin. */
+    readonly perPlugin: 10;
+    /** Total bytes of a plugin's theme assets (fonts and logos). */
+    readonly assetsBytes: number;
+    /** Fonts per theme. */
+    readonly fonts: 8;
+    /** Bytes of one woff2 font. */
+    readonly fontBytes: number;
+    /** Bytes of a logo SVG. */
+    readonly svgBytes: number;
+    /** Bytes of a logo PNG. */
+    readonly pngBytes: number;
+    /** Minimum pixel height of a logo PNG. */
+    readonly pngMinHeight: 64;
+    /** Characters of the wordmark. */
+    readonly wordmark: 24;
+};
+/** A theme of the plugin: a `./…/<id>.json` file ({@link ThemeFile}). */
+export interface PluginThemeRef {
+    path: string;
+}
+/** One scheme's partial override; tokens left out keep the built-in value of that scheme. */
+export interface ThemeSchemeOverride {
+    /** Overridable color tokens (`THEME_OVERRIDABLE.color`): `#RRGGBB` or `rgba(r,g,b,a)`. */
+    color?: Record<string, string>;
+    /** Shadow tokens: `<x> <y> <blur> [<spread>] <color>`. */
+    shadow?: Record<string, string>;
+    /** Pixels, integers 0-16. */
+    radius?: Partial<Record<"sm" | "md" | "bubble", number>>;
+}
+/** A woff2 font of the theme, put first in its role's font stack. */
+export interface ThemeFont {
+    /** Letters, digits, spaces and `-`, ≤ 64 characters. */
+    family: string;
+    /** A `.woff2` path inside the plugin. */
+    file: string;
+    /** 100-900. */
+    weight: number;
+    style?: "normal" | "italic";
+    /** `prose` (`--cb-font-prose`) or `mono` (`--cb-font`, the UI's body font). */
+    role: "prose" | "mono";
+}
+/** The theme's logo; each part omitted keeps the built-in one. */
+export interface ThemeLogo {
+    /** `.svg` or `.png` path inside the plugin. */
+    mark?: string;
+    /** Replaces `CAPYBARA`: ≤ 24 characters, no control or format characters. */
+    wordmark?: string;
+    /** `.svg` or `.png` path inside the plugin. */
+    favicon?: string;
+}
+/** `themes/<id>.json`. */
+export interface ThemeFile {
+    name: LocalizedName;
+    description?: {
+        en: string;
+        zh?: string;
+    };
+    /** `dark`, `light` or both. */
+    schemes: Partial<Record<ThemeScheme, ThemeSchemeOverride>>;
+    fonts?: ThemeFont[];
+    logo?: ThemeLogo;
+}
+/**
+ * A theme file after {@link parseThemeFile}: values canonical. It holds only the file's own
+ * content (no built-in values), so it is what a catalog stores and compares: a change of the
+ * built-in tokens in core changes no stored theme. {@link mergeThemeSchemes} merges it onto the
+ * current built-in values where they are needed.
+ */
+export interface ParsedTheme extends ThemeFile {
+    id: string;
+    /** The only scheme of a single-scheme theme, else null. */
+    singleScheme: ThemeScheme | null;
+}
+/** Options of {@link parseThemeFile}. */
+export interface ParseThemeOptions {
+    /**
+     * Check readability on the schemes merged onto the current built-in values (default true).
+     * False for a theme version already accepted into a catalog: its readability verdict was given
+     * when it was imported, so a later change of the built-in tokens does not block it. Grammar and
+     * token names are always checked.
+     */
+    readability?: boolean;
+}
+/** `themes/night-city.json` → `night-city`. */
+export declare function themeIdOf(path: string): string;
+/**
+ * The zod schema of a theme file's shape (strict objects). Token names and values are only
+ * strings here; see {@link parseThemeFile}. The JSON Schema is generated with
+ * `z.toJSONSchema(ThemeFileSchema, { io: "input" })`.
+ */
+export declare const ThemeFileSchema: z.ZodType<ThemeFile>;
+/**
+ * The canonical form of a token value under the grammar of `group` (the one {@link parseThemeFile}
+ * applies), or undefined when `value` is not a string within it. For readers of stored themes that
+ * emit values again (the kernel's stylesheet, themes spec §8): a stored value is re-validated
+ * before it reaches CSS, so a changed database row cannot inject CSS.
+ */
+export declare function canonicalThemeValue(group: "color" | "shadow", value: unknown): string | undefined;
+/** Whether `v` is a font family a theme may name: 1-64 letters, digits, spaces or `-`. */
+export declare function isThemeFontFamily(v: unknown): v is string;
+/**
+ * Whether `v` is an asset path a theme may name: plugin-root relative (an optional leading `./`),
+ * every segment of `[A-Za-z0-9._-]`, no `.` / `..` segments (the extension is not checked).
+ */
+export declare function isThemeAssetPath(v: unknown): v is string;
+/**
+ * Each scheme the theme defines, merged onto the current built-in values (for swatches, the
+ * readability check and anything else that needs full values). A stored theme is read leniently:
+ * an override whose token name the built-in tokens no longer know (renamed in core), that is not
+ * overridable, or whose value falls outside the grammar is skipped, as the stylesheet skips it.
+ */
+export declare function mergeThemeSchemes(theme: Pick<ThemeFile, "schemes">): Partial<Record<ThemeScheme, MergedScheme>>;
+/**
+ * Parses and validates a theme file: the parsed JSON value or the file text (larger than
+ * {@link THEME_LIMITS}`.fileBytes`, measured as text or as the value's JSON, is refused). Checks the id, the shape, token names against
+ * the generated allowlist (an unknown or non-overridable name is an error), the value grammar,
+ * fonts and logo; then (unless `options.readability` is false) merges every defined scheme onto
+ * the built-in tokens ({@link mergeThemeSchemes}) and reports each readability issue as an error
+ * starting `unreadable:`. Returned values are canonical (uppercase
+ * hex, rgba and shadows re-rendered from their parts). Invalid input returns `{ errors }`
+ * (`<path>: <reason>`, English, at most 50); never throws.
+ */
+export declare function parseThemeFile(id: string, json: unknown, options?: ParseThemeOptions): ParsedTheme | {
+    errors: string[];
+};