Merge feat/universal-device: universal device support (any mouse/macropad)

ControlId is an open string type, devices are first-class config entities
(schema v3, v2 configs migrate on load), learn-mode adds buttons of any
programmable device via DOM key capture, user devices get an optional photo
with click-to-place hotspots, Razer conveniences are gated to the built-in
Naga device.

Author: danscMax

AGENTS.md

@@ -93,7 +93,7 @@ Windows-first desktop app that remaps a programmable mouse (Razer Naga) and keyb
 - Code comments in English.
 - All user-facing text goes through i18next with matching `en.json` + `ru.json` keys — never hardcode UI strings.
 - No AI/assistant attribution anywhere (commits, PRs, code, docs).
-- Config is the source of truth: schema-first (`schemas/config.v2.schema.json` at the repo root, runtime-validated), atomic writes, rolling + daily backups, corrupt-recovery. The TS `AppConfig` (`src/lib/config.ts`) and Rust structs must stay in sync with the schema.
+- Config is the source of truth: schema-first (`schemas/config.v3.schema.json` at the repo root, runtime-validated), atomic writes, rolling + daily backups, corrupt-recovery. The TS `AppConfig` (`src/lib/config.ts`) and Rust structs must stay in sync with the schema.
 - Adding an `ActionType` touches many mirrored sites — see `src/components/action-picker/AGENTS.md`.
 - Fix root causes, not symptoms. Reuse existing shared primitives/helpers before adding new ones.
 

DESIGN_SYSTEM.md

@@ -13,7 +13,7 @@ all wired into `.github/workflows/ci.yml` (`npm test` + `cargo test`).
 
 | Need | Canon home | Adoption guard |
 |------|-----------|----------------|
-| **ActionType** (3 sources of truth) | Rust `src-tauri/src/config.rs:538` `ActionType::ALL` ⇄ FE `src/lib/constants/ui-copy.ts:56` `ACTION_TYPE_LABELS` → `:73` `ALL_ACTION_TYPES` ⇄ schema `schemas/config.v2.schema.json` `$defs.actionType.enum` | `config.rs` test `action_type_set_matches_schema_enum` (`:4283`, set-equality Rust↔schema) + `:553` compile-exhaustive `match` (no `_` arm) + FE `Record<ActionType, …>` (won't compile without label+icon). A missed schema entry is a **save-breaker** — this is the highest-radius canon. |
+| **ActionType** (3 sources of truth) | Rust `src-tauri/src/config.rs:538` `ActionType::ALL` ⇄ FE `src/lib/constants/ui-copy.ts:56` `ACTION_TYPE_LABELS` → `:73` `ALL_ACTION_TYPES` ⇄ schema `schemas/config.v3.schema.json` `$defs.actionType.enum` | `config.rs` test `action_type_set_matches_schema_enum` (`:4283`, set-equality Rust↔schema) + `:553` compile-exhaustive `match` (no `_` arm) + FE `Record<ActionType, …>` (won't compile without label+icon). A missed schema entry is a **save-breaker** — this is the highest-radius canon. |
 | FE action-type lists | `ui-copy.ts` `editableActionTypes`/`ACTION_CATEGORIES`/`ACTION_TYPE_ICONS` | All derived from `ALL_ACTION_TYPES` — structurally cannot drift from the type set. |
 | **MouseActionKind / MediaKeyKind** (3 SoT, same shape as ActionType) | Rust `config.rs` `MouseActionKind`/`MediaKeyKind` enums ⇄ schema `$defs.mouseActionKind`/`mediaKeyKind` ⇄ FE `ui-copy.ts` `MOUSE_ACTION_LABELS`/`MEDIA_KEY_LABELS` → derived `*_OPTIONS` | `config.rs` tests `mouse_action_kind_set_matches_schema_enum` + `media_key_kind_set_matches_schema_enum` (set-equality Rust↔schema, strings via serde) + per-enum compile-exhaustive `match` (no `_`) + FE `Record<…Kind>` (won't compile without a label). The payload `$ref`s the enum, so a bad value is a clear `schema_violation`, not a deserialize parse-error. |
 | `<select>` dropdown | `src/components/shared.tsx` `SelectField` | `src/lib/canon-guards.test.ts:41` — raw `<select>` fails CI outside `SelectField` + 4 documented exceptions. |
@@ -31,7 +31,7 @@ all wired into `.github/workflows/ci.yml` (`npm test` + `cargo test`).
 
 Touch **all four** or a guard fails (which is the point):
 1. `config.rs` `ActionType` enum + `ActionType::ALL` (`:538`) + the exhaustive `match` (`:553`).
-2. `schemas/config.v2.schema.json` `$defs.actionType.enum`.
+2. `schemas/config.v3.schema.json` `$defs.actionType.enum`.
 3. FE `ui-copy.ts` `ACTION_TYPE_LABELS` + `ACTION_TYPE_ICONS` (compile-guarded `Record`s).
 4. Run `cargo test` (set-equality) + `npm test` (FE compile/derive). See `reference_add_action_type_checklist` in memory.
 

docs/CONFIG-SCHEMA-V2.md

@@ -1,5 +1,8 @@
 # Config Schema V2
 
+> **Superseded by v3** (universal-device support): see `docs/CONFIG-SCHEMA-V3.md`
+> for the delta. The bundled runtime schema is now `schemas/config.v3.schema.json`.
+
 - Status: Working draft aligned with accepted ADRs
 - Date: 2026-03-07
 - Canonical file name: `config.json`

docs/CONFIG-SCHEMA-V3.md

@@ -0,0 +1,65 @@
+# Config Schema V3
+
+- Status: Current
+- Date: 2026-07-05
+- Canonical file name: `config.json`
+- Canonical schema file: `schemas/config.v3.schema.json`
+- Base document: `docs/CONFIG-SCHEMA-V2.md` (v3 is v2 plus the delta below; all
+  v2 rules not listed here still apply)
+
+## Why v3
+
+Sidearm supports any programmable input device, not only the Razer Naga. The
+closed, Naga-specific `controlId` enum became an open token, and devices became
+first-class persisted entities.
+
+## Delta from v2
+
+### `controlId` is open
+
+- v2: closed 27-value enum (`thumb_01` … `top_special_03`).
+- v3: any token matching `^[a-z0-9][a-z0-9_-]*$` (max 64 chars).
+- Referential integrity moved from the schema into application validation
+  (`validate_config` in `src-tauri/src/config.rs`):
+  - every `bindings[].controlId`, `bindings[].chordPartner`,
+    `encoderMappings[].controlId`, and `devices[].hotspots[].controlId` must
+    exist in `physicalControls`
+  - every `physicalControls[].deviceId` must reference a declared device
+
+### New top-level entity: `devices`
+
+```json
+{
+  "id": "razer-naga",
+  "name": "Razer Naga V2 Hyperspeed",
+  "builtin": true,
+  "image": "photo.png",
+  "hotspots": [{ "controlId": "thumb_01", "x": 25.0, "y": 75.5 }]
+}
+```
+
+- `id`, `name` required; `builtin` defaults to false.
+- `image` is a **bare file name** resolved inside the app-data devices
+  directory (path separators and `..` are rejected) — used by user devices.
+  The built-in Naga device renders through frontend-bundled photos instead.
+- `hotspots` place controls on the image in percent (0..=100) of its size.
+- At least one device must be declared.
+- A config declaring the built-in Naga device (`razer-naga`) must contain all
+  27 Naga controls in `physicalControls` — the v2 completeness invariant,
+  scoped to that device.
+
+### `physicalControls[].deviceId`
+
+Each control is tagged with the device it belongs to. Optional in the schema
+(defaults to `razer-naga` in serde) so v2 files stay valid.
+
+### Version and migration
+
+- `version` accepts `2` or `3` at the schema layer; `validate_config` requires
+  the migrated in-memory config to be exactly `3`.
+- A v2 file loads unchanged: `migrate_devices` seeds the built-in Naga device,
+  serde defaults tag legacy controls with `razer-naga`, and the version is
+  bumped to 3 on the next save. Bindings, encoder mappings, and actions are
+  untouched.
+- An app older than v3 refuses a v3 file (its v2 schema pins `version` to 2)
+  and, per the newer-schema guard, never overwrites or "recovers" it.

docs/DEVICE-CATALOG.md

@@ -101,7 +101,7 @@ The control appears remappable in some form, but behavior may be duplicated, uns
 ## Persistence Implications
 
 - Every row in this catalog should correspond to a `physicalControls[]` entry in config v2.
-- The `controlId` set here must remain in sync with `schemas/config.v2.schema.json`.
+- The `controlId` set here must remain in sync with `schemas/config.v3.schema.json`.
 - If a control name improves later, update `defaultName` or `synapseName`, but preserve `controlId`.
 
 ## Known Catalog Debt

schemas/AGENTS.md

@@ -6,12 +6,14 @@ The runtime-validated JSON Schema for `AppConfig` — the single source of truth
 
 ## Ownership
 
-- `config.v2.schema.json` — bundled into `src-tauri/src/config.rs` via `include_str!("../schemas/config.v2.schema.json")`.
+- `config.v3.schema.json` — bundled into `src-tauri/src/config.rs` via `include_str!("../schemas/config.v3.schema.json")`. Accepts `version` 2 or 3: a v2 file (no `devices`/`deviceId`) is schema-valid and migrated in code (`migrate_devices`) on load.
+- `config.v2.schema.json` — historical (v0.x–v0.7.5 contract), no longer bundled. Kept for reference; see `docs/CONFIG-SCHEMA-V3.md` for the v2→v3 delta.
 
 ## Local Contracts
 
 - This schema, the Rust structs (`src-tauri/src/config.rs`), and the TS types (`src/lib/config.ts`) form a three-way contract — a change in any one requires the other two.
 - Enum lists (`$defs.actionType.enum`, `$defs.mouseActionKind.enum`, `$defs.mediaKeyKind.enum`) must match the Rust enums; `config.rs` has schema-sync tests that assert this.
+- `$defs.controlId` is an OPEN pattern since v3 (any device's control token). Referential integrity (control ∈ `physicalControls`, control's `deviceId` ∈ `devices`) is enforced by `validate_config` in Rust, not by the schema.
 - A persisted field rename = `anyOf`(both names) here + `#[serde(alias)]` in Rust, so older configs still load.
 - `version` is pinned to `SCHEMA_VERSION`; bump it deliberately (a newer-version config is never overwritten by an older app).