razer-linux-desktop/PROMPT.md

Goal: migrate the existing razerqdhid app into razer-linux-desktop as a native Linux desktop application using Tauri 2 for the shell and Leptos for the UI.

Context:

• Source app: ./razerqdhid
• Target app: ./razer-linux-desktop
• Current target state: the target is still the default Tauri + Leptos template (src/app.rs, src-tauri/src/lib.rs).
• Current source stack: Vue 3 + Vite + WebHID + Pyodide/Python.
• Source device/protocol logic lives mainly under razerqdhid/public/py/.
• This project is Linux-only. The app configures supported Razer mice, currently centered on Basilisk V3 / V3 Pro behavior already implemented in the source project.

Local test hardware (dev machine):

• Connected device: Razer Basilisk V3 Pro (USB)
  • lsusb: 1532:00ab (Razer USA, Ltd)
  • USB sysfs node: /sys/bus/usb/devices/5-2.2.1
  • Exposed HID raw nodes (same VID/PID): /dev/hidraw3, /dev/hidraw5, /dev/hidraw6
    • ID_USB_INTERFACE_NUM: 00 -> /dev/hidraw3 (mouse interface)
    • ID_USB_INTERFACE_NUM: 01 -> /dev/hidraw5
    • ID_USB_INTERFACE_NUM: 02 -> /dev/hidraw6
  • Device serial string currently reports as 000000000000 (do not rely on it for unique identification).

What exists in the source app:

• A connect flow in razerqdhid/src/components/ConnectDevice.vue
• A main device screen in razerqdhid/src/components/DeviceMain.vue
• Configuration sections for:
  • basic settings
  • button mapping
  • LED
  • profiles
  • macros
  • sensor settings
  • device info
• The source app currently relies on browser APIs and Pyodide. The desktop app should replace that with native Tauri/Rust integration.

What I want:

• Port the app into ./razer-linux-desktop.
• Keep the migrated app grounded in the existing source behavior and feature structure instead of inventing a new product.
• Replace WebHID/Pyodide with a native backend that talks to the device on Linux.
• Reuse or carefully reimplement the existing protocol logic from the Python code in Rust where appropriate.
• Keep the app runnable after each meaningful step. Do not leave the target in a half-broken state.

Execution requirements:

1. Inspect the source app and identify the real feature surface before changing architecture.
2. Inspect the Python protocol/device code under razerqdhid/public/py/ and use it as the behavioral reference.
3. Build the migration incrementally, starting with a working vertical slice instead of attempting every feature at once.
4. Preserve the current single-app workflow:
   • connect to device
   • show main configuration UI
   • expose the existing sections progressively
5. Prefer Rust/Tauri-native device access over embedding Python in the final architecture unless there is a concrete blocker.
6. Keep the UI practical and desktop-oriented. Do not ship the default template UI.
7. Do not perform unrelated refactors in the source project unless required for the migration.

Suggested migration order:

1. Replace the default Tauri + Leptos starter UI with a real app shell.
2. Implement backend device discovery/connection for supported Razer devices on Linux.
3. Port the connect screen and basic device info flow.
4. Port the basic settings/profile selection path end to end.
5. Port the remaining sections in descending order of user value: LED, button mapping, profiles, macros, sensor, info/debug tooling.
6. Remove template/demo code once replaced.

Definition of done:

• ./razer-linux-desktop is the active app, not a starter template.
• The app can launch locally as a Tauri desktop app.
• At least one real end-to-end device workflow is implemented natively in the target app.
• The migration status is clear: completed pieces, remaining gaps, and next highest-value steps.
• Any missing source features are called out explicitly instead of being silently dropped.

Faithful Port Checklist (source parity targets):

• App workflow parity:
  • Connect screen: scan/select device, connect, error handling, optional "no hardware" mode for UI-only exploration.
  • Main screen: profile selector + tabs matching the Vue app: Basic, Button, LED, Profile, Macro, Sensor, Info, plus log/debug tooling.
• Backend protocol parity (map to Python razerqdhid/public/py/qdrazer/device.py + qdrazer/protocol.py):
  • Device info:
    • manufacturer/product strings (USB indexed strings)
    • serial number (0x0082)
    • firmware version (0x0081)
    • device mode get/set (0x0084 / 0x0004) as required for sensor calibration flows
  • Basic settings (already partially ported):
    • scroll mode get/set (0x0294 / 0x0214)
    • scroll acceleration get/set (0x0296 / 0x0216)
    • smart reel get/set (0x0297 / 0x0217)
    • polling delay get/set (0x008e / 0x000e)
    • current DPI X/Y get/set (0x0485 / 0x0405)
    • DPI stages get/set (0x0486 / 0x0406) and active stage selection
  • Profile management:
    • available profile count/list (0x0580 / 0x0581)
    • create/delete profile (0x0502 / 0x0503)
    • profile info read/write chunking (0x0588 / 0x0508) for YAML import/export parity (source exports/imports Basic/Button/LED configs)
    • flash usage/readiness helpers (0x068e, 0x0086) as needed for safe writes
  • LED:
    • per-region effect get/set (0x0f82 / 0x0f02) including mode/speed/colors
    • per-region brightness get/set (0x0f84 / 0x0f04)
    • optional static LED write path (0x0f03) if needed for full parity
  • Button mapping + Hypershift:
    • button function get/set (0x028c / 0x020c)
    • full ButtonFunction encoding/decoding parity with qdrazer.protocol.ButtonFunction
      • categories used by UI: disabled, mouse, keyboard, macro, dpi_switch, profile_switch, system, consumer, hypershift_toggle, scroll_mode_toggle, plus "custom/raw"
    • support both Hypershift OFF and ON mappings
  • Macros:
    • macro list/count (get_macro_list/get_macro_count paths in Python) and any required query commands
    • macro info chunked get/set (0x068c / 0x060c)
    • macro size get/set (0x0688 / 0x0608)
    • macro function chunked get/set (0x0689 / 0x0609)
    • delete macro (0x0603)
    • flash reset tooling (0x060a + poll 0x068a) for the source "reset flash" workflow
    • YAML import/export for macro functions (source uses YAML to represent macro op lists)
  • Sensor / lift-off calibration:
    • sensor lift config get/set (0x0b8b / 0x0b0b)
    • lift config blobs get/set (0x0b85 / 0x0b05, 0x0b8c / 0x0b0c, 0x0b8d / 0x0b0d)
    • sensor state + calibration toggles (0x0b83 / 0x0b03, 0x0b09)
    • device mode transitions needed by the calibration workflow (DeviceMode.DRIVER/NORMAL)
  • Logs/debug:
    • source-equivalent log console: show sent/received report frames, status, and raw bytes
    • safe exclusive-access messaging when device replies with "different command" (indicates competing software)
• UI parity notes from Vue components:
  • Basic: includes DPI stages editing (count 1..5), active stage, and a "Y = X" helper.
  • LED: regions wheel/logo/strip; effects off/static/spectrum/wave variants; per-region speed + brightness; apply-to-all.
  • Button: per-button assignments + per-button Hypershift assignments; category editor; custom/raw inspector.
  • Profile: create/delete; YAML export/import for selected profile configs (basic/button/led only in source).
  • Macro: list macros; load/edit/save/delete; YAML export/import all.
  • Sensor: lift config modes; calibration start/stop; parameter calculator + set params.

While working:

• Make concrete code changes, not just a plan.
• Explain architecture decisions briefly when they matter.
• Validate builds/tests when possible.
• If the full migration is too large for one pass, complete the highest-value vertical slice and leave the repo in a clean, runnable state with clear next steps.