Merge pull request #126 from QueryaHub/issue/96-theme-parser-planning

docs(theme): custom theme parser planning (#96)

Author: ZhuchkaTriplesix

docs/README.md

@@ -25,6 +25,10 @@ Index of Querya Desktop documentation, grouped by audience.
 ## Planning
 
 - [Roadmap](roadmap.md) — current direction and follow-ups.
+- [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/scheme-parcer.md

@@ -0,0 +1,54 @@
+ТЗ 1: Разработка парсера кастомных JSON-тем
+
+Цель: Реализовать утилиту, которая динамически считывает .json файлы (например, пресеты cyberpunk ) и конвертирует их в объекты ThemeData (для shadcn_flutter) и ThemeExtension (для уникальных элементов).
+
+1. Архитектура и расположение
+
+    Локация: Вся логика парсинга должна находиться в lib/core/ (например, lib/core/theme/theme_parser.dart).
+
+    Интеграция: Применение распарсенной темы происходит в lib/app/.
+
+2. Требования к JSON-структуре
+Файл темы должен быть разделен на две логические части:
+
+    shadcn_colors: базовые токены для кнопок, фонов и инпутов (соответствуют палитре shadcn_flutter ).
+
+    editor_colors: кастомные токены для подсветки синтаксиса и сайдбаров (базовых цветов для этого не хватит ).
+
+3. Функционал парсера
+
+    Десериализация: Чтение JSON и безопасное извлечение строковых значений HEX-цветов (например, #1E1E1E или 1E1E1E).
+
+    Конвертер HEX -> Color: Утилита для преобразования строковых HEX-значений в объекты Color фреймворка Flutter.
+
+    Маппинг: Генерация объекта ColorScheme (для shadcn_flutter) и пользовательского EditorThemeExtension.
+
+4. Обработка ошибок (Фолбэк)
+
+    Если JSON файл поврежден или отсутствуют обязательные ключи, парсер должен тихо (без краша приложения) откатываться к дефолтной темной теме приложения.
+
+ТЗ 2: Аудит и масштабирование системы тем (Подготовка к 50+ темам)
+
+Цель: Обеспечить плавную работу UI, отсутствие утечек памяти и удобный UX при наличии большого количества кастомных тем.
+
+1. Оптимизация UI выбора тем (Preferences)
+
+    Проблема: Если тем станет много, простой список вызовет проблемы с отрисовкой и перекрытием окна.
+
+    Решение: Выпадающий список выбора темы должен использовать MenuAnchor. Обязательно внедрить жесткое ограничение высоты (например, maxHeight: 300.0) и внутренний скроллбар.
+
+    Предпросмотр (Live Preview): При наведении на название темы в списке (состояние hover ), интерфейс не должен полностью перестраиваться, если тема еще не применена окончательно (избегаем лагов).
+
+2. Управление состоянием и хранение
+
+    Кэширование: Парсинг JSON-файлов — это ресурсоемкая операция. Распарсенные объекты ThemeData должны кэшироваться в памяти (например, в Map<String, ThemeData>), чтобы повторное переключение происходило мгновенно.
+
+    Персистентность: Сохранять выбранный ID темы (или путь к файлу) необходимо в локальную базу данных SQLite, которая уже используется в проекте для метаданных.  
+
+3. Интеграция с нативными элементами окна
+
+    Синхронизация рамок: Приложение использует bitsdojo_window для отрисовки кастомных заголовков. При смене темы через парсер, цвета кнопок управления окном (свернуть/развернуть/закрыть) и цвет самого заголовка должны динамически перекрашиваться в цвет background новой темы.  
+
+4. Динамическая загрузка из файловой системы
+
+    Необходимо заложить возможность сканирования определенной папки в ОС пользователя (например, ~/.querya/themes/) при старте приложения, чтобы подтягивать не только встроенные themes/samples/, но и скачанные пользователями файлы.