Katana Studio¶

Katana Studio — визуальный редактор для GANSS ARDOR Katana на Electron. Приложение умеет всё то же, что katana.py: режимы подсветки, раскраску клавиш, переназначения, макросы, scan, raw, reset и применение YAML-профиля.

Протокол и порядок записи те же, что у CLI. Профиль тоже общий, но две секции названы по-старому: lighting и macros вместо mode и macro, поэтому ./katana.py apply такой файл отклонит.

Установка¶

Приложение рассчитано на Linux: транспорт — те же hidraw-узлы, что у katana.py, через node-hid. Поэтому нужны udev-правило и /dev/hidrawN. Без правила доступ к клавиатуре есть только у root.

Пакет deb¶

sudo apt install ./dist/katana-studio-0.1.0-amd64.deb

Пакет сам кладёт 70-ganss-katana.rules в /etc/udev/rules.d/ и перезагружает правила. После установки переподключите клавиатуру. При удалении пакета правило удаляется.

AppImage¶

Правило ставится вручную, как для CLI:

sudo cp 70-ganss-katana.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger
chmod +x dist/katana-studio-0.1.0-x86_64.AppImage
./dist/katana-studio-0.1.0-x86_64.AppImage

Сборка¶

Нужен Node.js 22 или новее. Команды выполняются из каталога studio.

npm ci
npm run dist        # AppImage и deb в dist/

Запуск из исходников и отладка описаны в разделе Запуск и отладка.

Если в окружении задан ELECTRON_RUN_AS_NODE=1, Electron запустится как обычный Node.js. Тогда используйте env -u ELECTRON_RUN_AS_NODE npm run dev.

Стек¶

Компонент	Назначение
electron-vite	Сборка main, preload и renderer
React	Интерфейс окна
TypeScript	Типы и общий код
Bootstrap	Оформление
`node-hid`	Обмен feature-репортами через hidraw
`usb`	Только для USB reset
`yaml`	Чтение и запись профилей
vitest	Офлайн-тесты
eslint	Проверка стиля

Команды¶

npm ci              # зависимости
npm run dev         # запуск с горячей перезагрузкой
npm run typecheck   # tsc для main и preload, затем для окна
npm run lint        # eslint
npm test            # vitest без клавиатуры
npm run build       # сборка в out/
npm run dist        # AppImage и deb в dist/

Подробности запуска, отладки в VS Code и сборки пакетов — в разделе Запуск и отладка.

Карта документации¶

Документ	Тема
Окно приложения	Панель профиля, вкладки, предпросмотр, ограничения.
Архитектура	Структура каталогов, очередь операций, потоки кадров.
TypeScript API	Соответствие Python-версии и использование вне окна.
Тесты и фикстуры	Что проверяют тесты и как обновлять эталоны.
Запуск и отладка	Команды npm, конфигурации VS Code, сборка пакетов и доступ к HID.
Протокол	Общее описание обмена с прошивкой.

Ограничения¶

между USB-запросами выдерживается пауза 40 мс, поэтому запись таблицы раскраски занимает около 0,6 секунды, а смена режима — около 0,3 секунды;
все операции идут в одной очереди: пока выполняется одна, кнопки записи недоступны;
флеш-память клавиатуры имеет ограниченный ресурс перезаписи, а предпросмотр раскраски никогда не пишет во флеш;
пока открыта вкладка «Раскраска», клавиатура показывает таблицу вместо режима с вкладки «Подсветка».

Подробнее о скорости и флеше — в разделе Свои скрипты.