~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""
Theme Loader - Parse and load theme files with TOML frontmatter.
"""
import re
import tomllib
from functools import lru_cache
from pathlib import Path
from loguru import logger
from .schema import (
LIGHT_THEME_REQUIRED_VARIABLES,
REQUIRED_RGB_VARIANTS,
REQUIRED_VARIABLES,
ThemeMetadata,
)
# Pattern to match TOML frontmatter in CSS comments
# Matches: /*--- ... ---*/
FRONTMATTER_PATTERN = re.compile(r"/\*---\s*(.*?)\s*---\*/", re.DOTALL)
# Pattern to extract theme ID from CSS selector
THEME_ID_PATTERN = re.compile(r'\[data-theme="([^"]+)"\]')
# Matches CSS comments, including the TOML frontmatter block, so declaration
# scanning can ignore anything that is only mentioned in a comment.
CSS_COMMENT_PATTERN = re.compile(r"/\*.*?\*/", re.DOTALL)
# Matches an actual custom-property *declaration* (`--name: value;`) at the
# start of a line or right after a `{` / `;` (so single-line and minified
# rules count too), as opposed to a `var(--name)` usage elsewhere in the
# value, or a longer name that merely starts with the same characters
# (e.g. `--control-border-hover` must not satisfy `--control-border`).
CUSTOM_PROPERTY_DECLARATION_PATTERN = re.compile(
r"(?:^|[{;])\s*(--[\w-]+)\s*:", re.MULTILINE
)
class ThemeLoader:
"""Loads and parses theme files from a directory."""
def __init__(self, themes_dir: Path):
"""Initialize loader with themes directory path."""
self.themes_dir = themes_dir
self._cache: dict[str, ThemeMetadata] = {}
def parse_frontmatter(self, css_content: str) -> dict:
"""Extract and parse TOML frontmatter from CSS file.
Args:
css_content: The CSS file content
Returns:
Parsed TOML as dictionary, or empty dict if no frontmatter
"""
match = FRONTMATTER_PATTERN.search(css_content)
if not match:
return {}
try:
return tomllib.loads(match.group(1))
except tomllib.TOMLDecodeError:
logger.warning("Failed to parse theme frontmatter")
return {}
def extract_theme_id(self, css_content: str) -> str | None:
"""Extract theme ID from CSS selector.
Args:
css_content: The CSS file content
Returns:
Theme ID string or None if not found
"""
match = THEME_ID_PATTERN.search(css_content)
return match.group(1) if match else None
def declared_custom_properties(self, css_content: str) -> set[str]:
"""Custom property names actually *declared* in the CSS.
Comments are stripped first so a variable only mentioned in a
comment (or referenced via `var(--name)`) isn't mistaken for a
declaration, and matching is on the exact property name so
`--control-border` doesn't match `--control-border-hover`.
Args:
css_content: The CSS file content
Returns:
Set of declared custom property names, e.g. {"--text-primary"}
"""
without_comments = CSS_COMMENT_PATTERN.sub("", css_content)
return {
match.group(1)
for match in CUSTOM_PROPERTY_DECLARATION_PATTERN.finditer(
without_comments
)
}
def validate_css_variables(
self, css_content: str, theme_id: str
) -> tuple[list[str], list[str]]:
"""Validate that all required CSS variables are defined.
Args:
css_content: The CSS file content
theme_id: Theme identifier for logging
Returns:
Tuple of (missing_base_vars, missing_rgb_vars)
"""
missing_base = [
var for var in REQUIRED_VARIABLES if var not in css_content
]
missing_rgb = [
var for var in REQUIRED_RGB_VARIANTS if var not in css_content
]
return missing_base, missing_rgb
def load_theme(self, css_path: Path) -> ThemeMetadata | None:
"""Load a single theme from a CSS file.
Args:
css_path: Path to the CSS file
Returns:
ThemeMetadata object or None if loading failed
"""
try:
content = css_path.read_text(encoding="utf-8")
meta = self.parse_frontmatter(content)
# Get theme ID from frontmatter or extract from CSS
theme_id = (
meta.get("id")
or self.extract_theme_id(content)
or css_path.stem
)
# Determine group from parent directory name
parent_name = css_path.parent.name
default_group = (
parent_name
if parent_name in {"core", "nature", "dev", "research"}
else "other"
)
# Auto-generate metadata if not provided
if not meta:
meta = {
"id": theme_id,
"label": theme_id.replace("-", " ").title(),
"icon": "fa-palette",
"group": default_group,
}
logger.debug(f"Auto-generated metadata for theme: {theme_id}")
# Validate CSS variables
missing_base, missing_rgb = self.validate_css_variables(
content, theme_id
)
if missing_base:
logger.warning(
f"Theme {theme_id} missing base variables: {missing_base}"
)
if missing_rgb:
logger.debug(
f"Theme {theme_id} missing RGB variants: {missing_rgb}"
)
# Determine theme type (dark/light)
theme_type = meta.get("type", "dark")
if theme_type not in ("dark", "light"):
theme_type = "dark"
if theme_type == "light":
declared_vars = self.declared_custom_properties(content)
missing_light = [
var
for var in LIGHT_THEME_REQUIRED_VARIABLES
if var not in declared_vars
]
if missing_light:
logger.warning(
f"Light theme {theme_id} missing variables: "
f"{missing_light}"
)
return ThemeMetadata(
id=theme_id,
label=meta.get(
"label",
meta.get("name", theme_id.replace("-", " ").title()),
),
icon=meta.get("icon", "fa-palette"),
group=meta.get("group", default_group),
type=theme_type,
description=meta.get("description", ""),
author=meta.get("author", ""),
css_path=css_path,
)
except Exception:
logger.exception(f"Failed to load theme: {css_path}")
return None
def get_css_content(self, theme: ThemeMetadata) -> str:
"""Get CSS content for a theme, stripping frontmatter.
Args:
theme: ThemeMetadata object
Returns:
CSS content without frontmatter
"""
if not theme.css_path or not theme.css_path.exists():
return ""
content = theme.css_path.read_text(encoding="utf-8")
# Strip frontmatter
return FRONTMATTER_PATTERN.sub("", content).strip()
@lru_cache(maxsize=1)
def load_all_themes(self) -> dict[str, ThemeMetadata]:
"""Load all themes from the themes directory.
Scans subdirectories (core/, nature/, dev/, research/) for .css files.
Returns:
Dictionary mapping theme IDs to ThemeMetadata objects
"""
themes: dict[str, ThemeMetadata] = {}
# Add virtual "system" theme (no CSS file)
themes["system"] = ThemeMetadata(
id="system",
label="System",
icon="fa-desktop",
group="system",
type="dark", # Resolves at runtime based on OS preference
description="Follow system color scheme preference",
css_path=None,
)
# Scan subdirectories for theme files
subdirs = ["core", "nature", "dev", "research"]
for subdir in subdirs:
dir_path = self.themes_dir / subdir
if dir_path.exists():
for css_file in sorted(dir_path.glob("*.css")):
theme = self.load_theme(css_file)
if theme:
themes[theme.id] = theme
# Also scan root themes directory for any loose theme files
for css_file in sorted(self.themes_dir.glob("*.css")):
theme = self.load_theme(css_file)
if theme and theme.id not in themes:
themes[theme.id] = theme
logger.info(f"Loaded {len(themes)} themes from {self.themes_dir}")
return themes
def clear_cache(self) -> None:
"""Clear the theme cache (useful for development/hot-reload)."""
self._cache.clear()
self.load_all_themes.cache_clear()