Release 0.4.2 — custom theme registry (#96–#125)

CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Planned (0.4.3)
+
+Theme and extensions follow-ups — see [docs/planned-0.4.3.md](docs/planned-0.4.3.md): file watcher (TP-F1), marketplace metadata (TP-F2), visual theme editor (TP-F3), remote theme install (TP-F4).
+
+## [0.4.2] - 2026-06-14
+
+Custom theme registry release (parser epic TP-01–TP-30, GitHub issues **#96–#125**). Git tag **`0.4.2`**.
+
+### Added
+
+- **Custom theme registry** — scan `{appSupport}/themes/` for `querya.theme.v1` and VS Code JSON/JSONC; **Theme** picker with search, hover preview, **Refresh themes**, and **Open themes folder** (Preferences → Appearance).
+- **Built-in bundled themes** — **Querya Cyberpunk Neon** from `assets/themes/` (no manual install).
+- **Theme import** — **Import theme…** copies into the user themes directory with content-hash and id deduplication; selection persists across restarts.
+- **Startup safety** — missing or broken selected theme falls back to Querya Dark with a Preferences error; saved theme id is kept until the user picks another theme.
+- **Window chrome** — title bar and window controls follow active `QueryaThemeScope` workbench tokens.
+- **Docs / QA** — [theme-custom-json.md](docs/theme-custom-json.md), updated [theme-import.md](docs/theme-import.md), custom-theme section in [release-checklist.md](docs/release-checklist.md).
+- **Tests** — registry/parser/controller coverage, 60-theme picker performance guard, end-to-end import flow (`theme_import_flow_test.dart`).
+
 ## [0.4.1] - 2026-06-13
 
 Performance and UX release ([#93](https://github.com/QueryaHub/Querya-Desktop/issues/93)). Git tag **`0.4.1`**.

README.md

@@ -26,7 +26,7 @@ a clean, dark UI inspired by tools like pgAdmin.
   statement timeouts, query history, and CSV/JSON export.
 - **Object browsing** — connection tree with databases, tables, views, and
   server stats.
-- **Themeable** — runtime dark/light/system modes and **VS Code theme import**.
+- **Themeable** — dark/light/system, **VS Code theme import**, custom `querya.theme.v1` registry, and bundled themes (0.4.2).
 - **Scalable UI** — global interface scaling for high-DPI and accessibility.
 - **Secure by default** — passwords and connection strings live in the OS secure
   store, never in plaintext.

assets/themes/cyberpunk-neon.json

@@ -0,0 +1,96 @@
+{
+  "name": "Querya Cyberpunk Neon",
+  "type": "dark",
+  "colors": {
+    "activityBar.background": "#050508",
+    "statusBar.background": "#050508",
+    "sideBar.background": "#0c0820",
+    "sideBar.foreground": "#8b7cf8",
+    "tab.activeBackground": "#14102a",
+    "panel.background": "#14102a",
+    "input.background": "#14102a",
+    "editor.background": "#0a0a14",
+    "editor.foreground": "#e8f4ff",
+    "editor.selectionBackground": "#ff2a6d44",
+    "editorLineNumber.foreground": "#4a3f7a",
+    "editorBracketMatch.background": "#00f5ff33",
+    "editorWidget.border": "#00f5ff66",
+    "focusBorder": "#00f5ff",
+    "list.hoverBackground": "#ff2a6d22",
+    "gitDecoration.modifiedResourceForeground": "#fcee09",
+    "gitDecoration.untrackedResourceForeground": "#39ff14"
+  },
+  "tokenColors": [
+    {
+      "name": "Comments",
+      "scope": ["comment", "comment.line", "comment.block", "punctuation.definition.comment"],
+      "settings": {
+        "foreground": "#5c4d8a",
+        "fontStyle": "italic"
+      }
+    },
+    {
+      "name": "Keywords",
+      "scope": [
+        "keyword",
+        "keyword.control",
+        "keyword.operator.logical",
+        "storage.type",
+        "storage.modifier"
+      ],
+      "settings": {
+        "foreground": "#ff2a6d",
+        "fontStyle": "bold"
+      }
+    },
+    {
+      "name": "Strings",
+      "scope": ["string", "string.quoted.single", "string.quoted.double"],
+      "settings": {
+        "foreground": "#fcee09"
+      }
+    },
+    {
+      "name": "Numbers",
+      "scope": ["constant.numeric", "constant.language"],
+      "settings": {
+        "foreground": "#bd00ff"
+      }
+    },
+    {
+      "name": "Functions",
+      "scope": ["entity.name.function", "support.function"],
+      "settings": {
+        "foreground": "#00f5ff"
+      }
+    },
+    {
+      "name": "Types / classes",
+      "scope": ["entity.name.type", "support.type"],
+      "settings": {
+        "foreground": "#8b7cf8"
+      }
+    },
+    {
+      "name": "Variables",
+      "scope": ["variable", "variable.other"],
+      "settings": {
+        "foreground": "#e8f4ff"
+      }
+    },
+    {
+      "name": "JSON keys",
+      "scope": ["support.type.property-name.json"],
+      "settings": {
+        "foreground": "#00f5ff"
+      }
+    },
+    {
+      "name": "JSON strings",
+      "scope": ["string.quoted.double.json"],
+      "settings": {
+        "foreground": "#39ff14"
+      }
+    }
+  ]
+}

docs/README.md

@@ -14,6 +14,7 @@ Index of Querya Desktop documentation, grouped by audience.
 - [Architecture](architecture.md) — `lib/` layout and module responsibilities.
 - [Theme system](theme.md) — runtime theming and VS Code theme tokens.
 - [Theme import](theme-import.md) — supported `colors` keys and merge behavior.
+- [Custom theme JSON](theme-custom-json.md) — `querya.theme.v1` schema and fallback rules.
 - [Performance baseline](perf-baseline.md) — per-milestone DevTools checklist.
 
 ## For release managers
@@ -25,6 +26,11 @@ Index of Querya Desktop documentation, grouped by audience.
 ## Planning
 
 - [Roadmap](roadmap.md) — current direction and follow-ups.
+- [Planned 0.4.3](planned-0.4.3.md) — deferred theme/extensions follow-ups after 0.4.2.
+- [Custom theme parser requirements](scheme-parcer.md) — JSON theme format and scaling spec.
+- [Theme parser implementation plan](theme-parser-implementation-tasks.md) — task breakdown and architecture.
+- [Theme parser GitHub issues](theme-parser-github-issues.md) — issue templates for epic #96–#125.
+- [Marketplace extensions spec](market-tech.md) — extensions manager and marketplace integration.
 
 ## Archive
 

docs/market-tech.md

@@ -0,0 +1,103 @@
+Это потрясающая новость! Разработка собственного маркетплейса параллельно с клиентом — это переход от создания просто "инструмента" к созданию полноценной экосистемы (как у VS Code или Obsidian). Это невероятно мощный драйвер для роста сообщества и получения звезд на GitHub.
+
+Чтобы Querya Desktop оставалась легковесной, функционал маркетплейса должен быть реализован архитектурно грамотно: ядро ничего не знает о логике плагинов, оно лишь предоставляет интерфейс (API) для их загрузки и применения.
+
+Вот подробное техническое задание (ТЗ) на создание менеджера расширений и задел для интеграции с твоим будущим маркетом.
+ТЗ 3: Встроенный Менеджер Расширений и Интеграция с Маркетплейсом
+
+Цель: Создать в интерфейсе Querya Desktop выделенный раздел для управления дополнениями (темами, UI-твиками, коннекторами) и заложить сетевую/файловую архитектуру для связи с внешним API маркетплейса.
+1. UI/UX: Раздел «Extensions» (В стиле VS Code)
+
+В интерфейсе приложения (например, в левом боковом меню) появляется новая иконка (🧩 Пазл).
+
+Структура раздела:
+
+    Левая панель (Навигация и Поиск):
+
+        Строка поиска (с debounce-задержкой, чтобы не спамить API твоего маркета).
+
+        Вкладки-фильтры: Installed (Установленные), Explore (Поиск по маркету), Updates (Доступные обновления).
+
+    Центральная панель (Список):
+
+        Карточки расширений с использованием компонентов shadcn_flutter.
+
+        На карточке: Иконка, Название, Автор, Рейтинг (⭐), Бейдж типа (Theme, Plugin, Driver) и кнопка Install / Uninstall.
+
+    Правая панель (Детали - Markdown View):
+
+        При клике на карточку справа открывается подробное описание (парсится из README расширения), скриншоты и Changelog.
+
+2. Архитектура: Задел под Маркетплейс (Сетевой слой)
+
+В директории lib/core/ необходимо создать новый модуль market/, который будет отвечать за связь с твоим бэкендом.
+
+Ожидаемые контракты (Интерфейсы для будущего API):
+Мобильный/десктопный клиент должен общаться с маркетом через четкие модели данных. Тебе нужно заложить класс ExtensionManifest, который клиент будет ожидать от бэкенда:
+Dart
+
+class ExtensionManifest {
+  final String id;             // e.g., 'reei.cyberpunk-theme'
+  final String name;           // 'Cyberpunk 2077 Theme'
+  final String type;           // 'theme', 'sql-formatter', 'visualizer'
+  final String version;        // '1.0.2'
+  final String downloadUrl;    // Ссылка на .zip или .json в твоем хранилище
+  final String sha256Checksum; // КРИТИЧНО: Хэш для проверки целостности
+}
+
+Абстракция клиента (MarketplaceClient):
+Сделай интерфейс, чтобы сейчас его можно было замокать (Mock), а потом просто подставить реальный HTTP-клиент:
+
+    Future<List<ExtensionManifest>> fetchTrending()
+
+    Future<List<ExtensionManifest>> search(String query)
+
+    Future<File> downloadExtension(String downloadUrl)
+
+3. Файловая система и Безопасность (Локальный слой)
+
+Querya Desktop — это клиент базы данных, поэтому безопасность (особенно при скачивании сторонних файлов) — приоритет №1.
+
+    Директории: При старте приложение должно проверять и создавать папки в домашней директории пользователя:
+
+        Linux/macOS: ~/.querya/extensions/themes/ и ~/.querya/extensions/plugins/
+
+        Windows: %APPDATA%\Querya\extensions\
+
+    Процесс установки (Флоу):
+
+        Пользователь жмет Install.
+
+        Приложение скачивает файл во временную папку.
+
+        Сверяет sha256 скачанного файла с тем, что отдал API маркета.
+
+        Распаковывает в нужную папку внутри ~/.querya/extensions/.
+
+        Обновляет локальную базу данных SQLite (таблица installed_extensions).
+
+    Изоляция (Sandboxing): На первом этапе (для тем) это просто JSON файлы, они безопасны. Но в ТЗ нужно указать, что исполняемые плагины в будущем должны загружаться как изолированные модули (например, через Dart Isolates или WASM), чтобы плагин не мог украсть креды от БД из ОС.
+
+4. Стейт-менеджмент (Управление состояниями)
+
+Для бесшовного опыта нужно создать ExtensionProvider (или использовать Bloc/Riverpod — в зависимости от того, что у вас в lib/core/).
+
+Отслеживаемые состояния:
+
+    isMarketReachable: Проверка, доступен ли сервер маркета (если нет — показываем только вкладку Installed с заглушкой "Marketplace offline").
+
+    downloadProgress: Мапа Map<String, double> для отображения прогресс-баров загрузки на кнопках Install.
+
+    requireRestart: Флаг. Некоторым темам (или сложным плагинам) может потребоваться перезапуск приложения или сброс кэша редактора. Если флаг true, показываем всплывающий Toast (через shadcn_flutter).
+
+Маркетинговый совет для GitHub (Как использовать маркетплейс для звезд):
+
+Когда ты сделаешь этот раздел, добавь в README.md красивый бейдж:
+[🔌 Querya Extension Market: Live]
+
+И напиши блок:
+
+    Build your own tools for Querya
+    Querya Desktop features a built-in Marketplace. Don't like our UI? Download a new theme. Need a specific data visualizer? Write a plugin and publish it to the Querya Market in 5 minutes.
+
+Как тебе такой план? Если концепция ясна, мы можем углубиться в то, как именно ThemeParser (из предыдущего ТЗ) будет автоматически подхватывать свежескачанные JSON-файлы из папки ~/.querya/extensions/themes/ без перезагрузки приложения!

docs/planned-0.4.3.md

@@ -0,0 +1,44 @@
+# Planned release 0.4.3 — theme and extensions follow-ups
+
+**Status:** planning (not started).  
+**Depends on:** **0.4.2** custom theme registry (TP-01–TP-30, shipped).
+
+This document captures work intentionally deferred from the first custom-theme pass.
+See also [theme-parser-github-issues.md](theme-parser-github-issues.md) (TP-F1–TP-F4) and
+[market-tech.md](market-tech.md) for the broader extensions marketplace direction.
+
+## Theme folder and discovery
+
+| ID | Scope | Summary |
+|----|--------|---------|
+| **TP-F1** | `theme`, `filesystem` | **File watcher** for `{appSupport}/themes/` — auto-refresh the registry when files are added, removed, or renamed. Deferred: OS-specific watcher APIs and app lifecycle edge cases. |
+
+## Theme distribution and metadata
+
+| ID | Scope | Summary |
+|----|--------|---------|
+| **TP-F2** | `theme`, `marketplace` | **Marketplace metadata** on `ThemeDefinition` / manifests — preview image, tags, homepage, license, author. Prerequisite for listing themes in a future Extensions UI. |
+| **TP-F4** | `theme`, `network` | **Remote theme install** — download from URL with checksum/trust policy. Requires security review (HTTPS, signatures, user consent). |
+
+## Authoring UX
+
+| ID | Scope | Summary |
+|----|--------|---------|
+| **TP-F3** | `theme`, `settings` | **Visual theme editor** in Preferences — tweak colors, export `querya.theme.v1`. Larger than parser/import; likely multiple PRs. |
+
+## Extensions marketplace (optional overlap)
+
+If **0.4.3** also starts the extensions shell from [market-tech.md](market-tech.md), align **TP-F2** theme metadata with `ExtensionManifest` so themes can appear as a category in **Explore**. Keep `lib/core/market/` isolated from theme parser internals.
+
+## Suggested PR order (draft)
+
+1. TP-F1 — watcher + debounced `loadAvailableThemes()`
+2. TP-F2 — manifest fields + docs (no remote API yet)
+3. TP-F3 — minimal editor MVP (export only) or split to **0.4.4**
+4. TP-F4 — install-from-URL behind explicit user action
+
+## Out of scope for 0.4.3
+
+- Full marketplace backend and **Extensions** sidebar UI (may land in **0.5.0** per market-tech.md)
+- P2 Mongo/Redis semantic token colors ([roadmap.md](roadmap.md))
+- `re_editor` / LSP editor replacement

docs/release-checklist.md

@@ -1,6 +1,7 @@
-# Pre-release checklist (toward 1.0)
+# Pre-release checklist (release **0.4.2**)
 
-Use this before tagging or running the **Release** workflow.
+Use this before tagging **`0.4.2`** or running the **Release** workflow.
+See [tags-and-releases.md](tags-and-releases.md) and [CHANGELOG.md](../CHANGELOG.md).
 
 ## Product smoke (manual)
 
@@ -10,6 +11,20 @@ Use this before tagging or running the **Release** workflow.
 - [ ] **Connection → New Database Connection** from the menu saves and shows in the tree.
 - [ ] **Driver Manager** shows only built-in drivers (no misleading JDBC requirement).
 
+## Custom themes (manual QA)
+
+Use **Preferences → Appearance** unless noted. Fixtures for copy/import tests live under
+`test/fixtures/themes/`; bundled built-in sample: **Querya Cyberpunk Neon** in the theme picker.
+
+- [ ] **Import valid custom dark** — import `test/fixtures/themes/querya_custom_dark.json` (or copy to themes folder + **Refresh themes**). Theme appears in picker; UI uses custom primary (`#38BDF8`).
+- [ ] **Import valid custom light** — import `test/fixtures/themes/querya_custom_light.json`. App switches to light brightness; readable text on cards and sidebar.
+- [ ] **Import VS Code JSONC** — import `test/fixtures/themes/querya_custom_jsonc.jsonc` or `themes/samples/cyberpunk-neon.jsonc`. Parser accepts comments/trailing commas; theme applies without crash.
+- [ ] **Picker with many themes** — install 50+ themes (copy fixtures with unique ids, or duplicate renamed files) → open theme picker: no overflow, list scrolls, search filters rows.
+- [ ] **Restart persists selection** — select a registry theme (not only Querya Dark/Light), quit and relaunch: same theme active, no error in Preferences.
+- [ ] **Missing file fallback** — with a registry theme selected, delete its file from `{appSupport}/themes/`, restart: app starts on **Querya Dark**, Preferences shows *Selected theme failed to load. Using Querya Dark.*; saved selection id remains until user picks another theme.
+- [ ] **Title bar / window controls** — switch Querya Dark, Querya Light, Cyberpunk Neon, and a custom theme: title bar background and minimize/maximize/close hover colors track the active theme.
+- [ ] **SQL / JSON syntax** — open SQL editor with a theme that defines `tokenColors` (e.g. cyberpunk sample): comments, keywords, and strings use distinct colors; changing theme updates highlighting after editor refresh.
+
 ## Automated
 
 - [ ] `flutter analyze` — clean (on Linux, if the analyzer crashes with **Too many open files**, try `ulimit -n 8192`; see [CONTRIBUTING.md](../CONTRIBUTING.md)).
@@ -18,7 +33,8 @@ Use this before tagging or running the **Release** workflow.
 
 ## Versioning and release
 
-- [ ] `pubspec.yaml` `version` matches the release you intend to ship.
+- [ ] `pubspec.yaml` on **`dev`** is **`0.4.1+7`** before merging to `main` (auto version-bump sets **`0.4.2+8`** on `main`).
+- [ ] After merge, confirm GitHub Action **Auto Version Bump** committed **`0.4.2+…`** on `main`.
 - [ ] **Tag** is placed on the **commit that includes all fixes** you want in binaries (a tag does not auto-include later commits; see [CONTRIBUTING.md](../CONTRIBUTING.md)).
 - [ ] Run the **Release** workflow from GitHub Actions (see [tags-and-releases.md](tags-and-releases.md)).
 - [ ] Verify **Linux** and **Windows** zip artifacts and `SHA256SUMS.txt` on the GitHub Release.