Запуск и отладка¶

Приложение собирается на electron-vite: main, preload и renderer собираются отдельно, а окно работает на React и TypeScript.

Требования¶

Компонент	Версия или примечание
Node.js	22 и новее
npm	идёт вместе с Node.js
Linux	hidraw и udev-правило `70-ganss-katana.rules`
macOS	только для разработки: чтение работает, запись не разрешена

Для запуска окна нужен бинарник Electron. Начиная с Electron 44 пакет electron не скачивает его при установке, поэтому в проекте есть postinstall с командой install-electron. Если загрузка сорвалась, повторите её отдельно: npm run postinstall.

Установка зависимостей¶

npm ci

Компилятор не нужен: node-hid и usb приходят готовыми сборками и совместимы с Electron через N-API.

Команды¶

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

Полный цикл проверки перед коммитом:

npm run typecheck && npm run lint && npm test && npm run build

Отладка в VS Code¶

В репозитории лежат готовые конфигурации: .vscode/launch.json, .vscode/tasks.json и .vscode/extensions.json. Откройте панель «Запуск и отладка» и выберите Katana Studio: main + renderer.

Конфигурация	Что делает
`Katana Studio: main`	запускает electron-vite с картами исходников
`Katana Studio: renderer`	подключается к Chromium по порту 9222
`Katana Studio: main + renderer`	обе конфигурации сразу, с общей остановкой

Main-процесс запускается через electron-vite с ключом --sourcemap, окно подключается к Chromium по порту 9222. Конфигурация наследует окружение VS Code: если ELECTRON_RUN_AS_NODE=1 задан в нём, перезапустите VS Code без этой переменной.

Для отладки в npm run dev DevTools можно открыть временной строкой win.webContents.openDevTools() в src/main/index.ts. Штатное меню приложения отключено целиком, поэтому его ускорители, включая Ctrl + Shift + I, не работают.

Переменные окружения¶

Если задан ELECTRON_RUN_AS_NODE=1, Electron запускается как обычный Node.js и окно не открывается. Снимите переменную на один запуск:

env -u ELECTRON_RUN_AS_NODE npm run dev

Доступ к клавиатуре¶

На Linux приложению нужны те же права, что и утилите: udev-правило и узел /dev/hidrawN. Правило ставится один раз:

sudo cp 70-ganss-katana.rules /etc/udev/rules.d/
sudo udevadm control --reload-rules
sudo udevadm trigger

Пакет deb ставит правило сам, для AppImage его ставят вручную.

На macOS и Windows node-hid работает через системный hidapi, udev-правило не нужно. На macOS система не разрешает запись feature-репортов в клавиатуру: IOHIDDeviceSetReport возвращает not permitted, потому что интерфейс 0 описан как клавиатура. Поэтому окно показывает состояние и живые кадры, но менять подсветку и назначения нельзя. Для записи нужен Linux.

usb-reset на этих платформах не гарантируется: он рассчитан на Linux.

Сборка пакетов¶

npm run dist

Результат — dist/katana-studio-<версия>-amd64.deb и dist/katana-studio-<версия>-x86_64.AppImage. Конфигурация electron-builder лежит в разделе build файла package.json.

70-ganss-katana.rules кладётся в resources/;
build/linux/after-install.sh устанавливает правило в /etc/udev/rules.d/;
after-remove.sh удаляет правило;
нативные модули распаковываются из asar (asarUnpack), пересборка не нужна (npmRebuild: false).

Приложение упаковывается только под Linux, но npm run dev работает и на macOS, и на Windows.

Тесты¶

Тесты офлайновые: железо и Python не нужны. Всё необходимое лежит в tests/fixtures/ и закоммичено.

npm test

Состав фикстур и обновление эталонов описаны в разделе Тесты и фикстуры.