Темы

Темы оверлея Voxis — это папки, содержащие манифест theme.json и автономный ES-модуль theme.js. Они загружаются с диска во время выполнения оверлеем webview.

Безопасность: theme.js — это исполняемый JavaScript-код, которому доверяет приложение. Не устанавливайте темы из ненадежных источников и проверяйте сторонний код перед использованием.

Пользовательские темы находятся в каталоге конфигурации приложения в папке themes/:

Процесс работы для пользователя

  1. Скопируйте существующую папку с темой из каталога пользовательских тем или из src-tauri/themes/<id>/ в исходном коде.
  2. Переименуйте скопированную папку на новый id темы.
  3. Отредактируйте theme.json и theme.js.
  4. В Настройках выберите тему и используйте кнопку Предварительного просмотра (Preview) или Перезагрузки (Reload); перезапуск или повторный выбор темы также перезагружает её.

Текущий интерфейс Настроек позволяет выбирать тему и использовать действия Preview/Reload. В нем нет кнопки Экспорта, хотя существует команда-обертка для разработчиков.

Контракт

Тема экспортирует mount(container, api) и возвращает объект с методом unmount(). Версия Theme API — 1, она предоставляет apiVersion, параметры манифеста params, логический размер size, onState(cb) и actions.cancel().

Состояние темы (Theme state):

{
  mode: "idle" | "recording" | "transcribing" | "error",
  audioLevel: number,
  spectrumBins: number[]
}

Манифесты используют manifest_version: 2, api_version: 1, имя файла entry (например, theme.js), и могут опционально объявлять overlay_width и overlay_height. Оба измерения должны присутствовать и находиться в пределах от 16 до 4096 логических пикселей, чтобы использоваться оверлеем; иначе используется стандартный размер окна 172×36 logical px (ThemeHost / webview).

Идентификаторы (id) тем и имена файлов entry должны быть безопасными компонентами пути: без пустых значений, /, \, .., . или :. При сканировании тем имя папки является авторитетным id, если оно отличается от id в манифесте.

Встроенные темы и сидирование (seeding)

Исходники встроенных тем находятся в src/theme-engine/builtin/ и собираются в src-tauri/themes/ с помощью:

bun run build:themes

Приложение копирует встроенные темы в каталог пользовательских тем при запуске. Отсутствующие темы копируются; существующие копии встроенных тем старого формата (не v2) перезаписываются на версию v2; существующие пользовательские темы формата v2 сохраняются (даже если они временно недействительны). Произвольные custom invalid/non-v2 папки сканер пропускает, а не мигрирует.

Builtin-темы, которые сейчас собирает bun run build:themes: default, winamp_classic, neon, handy_pill, metaballs, metaballs25d, metaballs3d, lavalamp, living_reed, quiet_reed, radiolarian, paramecium_solo, vorticella_bloom, drifting_contour, didinium_drift, euglena_drift, duo_aquarium, all_aquarium.

Темы metaballs, metaballs25d, metaballs3d и lavalamp (src/theme-engine/builtin/<id>/index.ts) — это TypeScript-порты автономного WebGL/Canvas-визуализатора, изначально написанного для того же контракта mount(container, api): github.com/axelbaumlisto/metaballs-viz (MIT). См. Theme Author Guide (на английском) — руководство по написанию WebGL-тем и соответствие этим builtin-темам.

Ссылки для авторов