The foundation of the shell is a Material You colour engine (originally from caelestia-dots): wallpaper images are processed by the materialyoucolor Python library to derive a full M3 tonal palette — primary accent, surface, container, outline, and 16 terminal tokens (term0–term15). These are written to scheme.json and the QML shell rebinds live via a FileView { watchChanges: true } watcher in Colours.qml.

The scheme variant (tonalspot, vibrant, fidelity, expressive, monochrome) and dark/light mode can be set per-theme. This core engine serves as the base for the custom extensions built in this project.

While the original shell relied on a single shared wallpaper folder, this project introduces a per-theme asset bundle concept. Each theme is a self-contained directory under ~/Pictures/themes/ with its own wallpaper collection, profile pictures, and lock screen configurations, tied together by a theme.json metadata file.

Switching themes triggers the complete pipeline atomically: wallpaper changes, M3 colours are re-extracted and propagated to all apps, the profile picture symlink is updated, and the lock screen configuration switches — all in one caelestia theme set <name> call.

{
  "name": "jinx",
  "scheme": "dynamic",
  "schemeMode": "dark",
  "schemeVariant": "tonalspot",
  "selectedWallpaper": "wallpapers/wall1.jpg",
  "selectedLockWallpaper": "wallpapers/wall1.jpg",
  "selectedPfp": "pfp/pfp1.png",
  "lockBackend": "custom-qylock",
  "qylockTheme": "nier-automata"
}

The launcher originally provided a simple >wallpaper selector. I extended this into a unified CarouselList.qml component to support >theme and >pfp carousels as well — routing all content through a single reusable, keyboard-driven PathView list.

A major addition here is live colour previewing: as you hover through wallpapers with arrow keys, the M3 pipeline runs in the background and immediately pushes the candidate palette to all open applications — Kitty terminal sockets, Dolphin via DBus, and the shell UI — without writing anything permanently.

The result is a live before/after preview: the entire desktop recolors in real time as you scroll. If you dismiss the carousel with Esc, stopPreview() in Wallpapers.qml calls caelestia scheme restore and every app snaps back to the previously committed palette. Only Enter makes the selection permanent.

VS Code has no live IPC theming surface. The integration relies on the Wal Theme extension, which monitors the Pywal colors.json cache on disk and applies it to the editor's colour token configuration. Because the same Pywal JSON is already written by the Firefox bridge step, VS Code gets themed as a free side-effect of the same pipeline — no additional plumbing needed.

The editor updates pick up on the next window focus or file save, giving near-live responsiveness. Syntax highlighting, the sidebar, status bar, and integrated terminal all derive from the same 16-colour palette that was extracted from the wallpaper.

Obsidian is integrated into the live colour pipeline with automatic multi-vault discovery. Rather than requiring hardcoded vault paths, lunar-cli parses ~/.config/obsidian/obsidian.json to dynamically locate all active vaults across the filesystem.

When colours are generated, an M3 CSS template (obsidian.css) translates semantic tokens (surface, surfaceContainer, outlineVariant, primary, onPrimary, etc.) into Obsidian's native custom properties and theme overrides (such as Tokyo Night). The CLI writes <vault>/.obsidian/snippets/caelestia.css and ensures the snippet is registered in appearance.json.

Hooked directly into wallpaper.py's get_colours_for_wall(), hovering wallpapers in the launcher carousel hot-reloads Obsidian's appearance in real time alongside terminals and file managers via Obsidian's built-in CSS snippet watcher, reverting cleanly on preview cancellation.

caelestia lock --picker (or qs ipc call lock openPicker) opens LockPickerWindow.qml, a dedicated overlay window loaded lazily via LazyLoader from the existing Lock.qml IPC handler — so it incurs zero rendering cost until triggered.

The picker is fully keyboard-driven with context-sensitive navigation:

• Tab / Shift+Tab — cycle between the four backend tabs
• ← / → — cycle Qylock themes or lock wallpapers depending on active tab
• ↑ / ↓ — cycle profile pictures (Caelestia / Hyprlock) or Qylock themes (Custom Qylock)
• Enter / Space — apply selection and close
• Esc — dismiss without saving

The same LockPickerContent.qml component is also embedded inside the Nexus Settings panel under Wallpaper & Style, so it's accessible both from the launcher and from within the settings UI.

Each theme carries a pfp/ folder containing one or more avatar images. The >pfp launcher carousel or caelestia theme pfp set <path> CLI command selects one and symlinks it to two locations: ~/.local/state/caelestia/pfp.jpg (used by the shell HUD and lock screen) and ~/.face (the XDG standard face file read by display managers and other system tools).

If no PFP has been explicitly set for a theme, ~/.face is used as a fallback — meaning the most recently applied profile picture persists across theme switches until a new one is chosen. This design avoids a broken UI state (missing avatar) when switching to a theme that has no pfp/ folder yet.

The lock screen picker preview shows the currently selected PFP in the Caelestia and Hyprlock backend previews, cycling it with the ↑/↓ keys so you can preview exactly what the lock screen will look like before committing.