diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7b39c26..ab30d67 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -86,7 +86,7 @@ jobs: - name: Install desktop dependencies run: | sudo apt-get update - sudo apt-get install --no-install-recommends -y python3-venv python3-gi python3-gi-cairo python3-cairo python3-dbus gir1.2-gtk-4.0 gir1.2-adw-1 xvfb xauth dbus-x11 + sudo apt-get install --no-install-recommends -y python3-venv python3-gi python3-gi-cairo python3-cairo python3-dbus gir1.2-gtk-4.0 gir1.2-adw-1 fontconfig xvfb xauth dbus-x11 - name: Install the npm archive, set up its native runtime, and preview GUI env: PYTHON: /usr/bin/python3 diff --git a/MANIFEST.in b/MANIFEST.in index e5d508a..716e637 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -3,5 +3,9 @@ recursive-include bin *.js recursive-include scripts *.sh *.py *.js recursive-include data *.rules recursive-include docs *.md *.png +recursive-include docs/assets *.json recursive-include tests *.py *.js recursive-include .github *.yml *.md + +recursive-include src/mx4_linux/assets *.css *.png *.json *.glb +recursive-include src/mx4_linux/assets/fonts *.ttf *.txt diff --git a/README.md b/README.md index 8fbe043..68da2e9 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,7 @@ Solaar supplies the underlying device protocol implementation. MX4 Linux adds a | **OS** | Linux; verified environment: Arch Linux on Niri / Wayland. Other distributions and architectures are not validated. | | **Runtime** | Python 3.11+; setup uses the distribution's Python GObject bindings. | | **GUI** | GTK 4.12+, Libadwaita 1.4+ and Python GObject. Hardware/configuration CLI commands do not need a graphical session. | +| **Typography** | Fontconfig and JetBrains Mono Regular/Bold. Setup verifies the family and installs the bundled OFL-licensed fonts when missing. | | **Mouse access** | MX Master 4 and read/write access to its hidraw interface, through Bolt or Bluetooth. Live discovery has been verified through Bolt. | | **Desktop features** | Niri and an active Wayland session; `gtk4-layer-shell` library and typelib for the overlay. | | **Optional** | `wtype` for native keyboard input. Setup can build pinned wtype 0.4; `/dev/uinput` is an optional shortcut fallback. | @@ -106,7 +107,7 @@ The second command uses `sudo`, reloads udev rules and reapplies them to matchin ### Updating -Close the application, update your checkout and refresh its environment: +Choose **Quit MX4 Linux** from the application menu, then update your checkout and refresh its environment: ```bash git pull --ff-only @@ -117,7 +118,7 @@ Recreate `.venv` after a system Python version upgrade. Rerun `./scripts/install ### Uninstalling -Close MX4 Linux, then remove its environment and optional launcher from the checkout: +Choose **Quit MX4 Linux** from the application menu, then remove its environment and optional launcher from the checkout: ```bash rm -rf -- .venv .tools @@ -138,7 +139,11 @@ Saved settings remain in `${XDG_CONFIG_HOME:-$HOME/.config}/mx4-linux/`. See [co .venv/bin/mx4-linux # open the control panel ``` -Open the **Actions** tab and click **Enable**, then use the haptic panel from the application you want to control. **Try the ring** previews selection; **Edit actions** opens native forms for routines, eight ring assignments and optional extra-button bindings. Keep MX4 Linux running while using mouse integration; **Disable** or closing the app restores the selected buttons' prior reporting flags. +Open **Actions Ring** and click **Enable** beside **Mouse integration**, then use the haptic panel from the application you want to control. Opening the editor keeps integration enabled; saved changes update its assignments. Closing the settings window keeps enabled integration running in the background by default. Reopen MX4 Linux from your launcher to return to it. **Disable** stops integration; **Quit** (Ctrl+Q) exits the application and restores the selected buttons' prior reporting flags. Application Settings lets you turn off background operation. + +To launch an installed app from the ring, choose **Add application**, select the position under **Replace the action at**, search for the app and select it, then **Save changes**. Choosing or saving an application does not launch it. **Smart Actions** also offers an **Open application** step for longer routines. + +Battery labels refresh automatically. An unavailable reading clears the old percentage; background updates preserve the footer's last operation message. ## Usage @@ -166,6 +171,8 @@ Successful CLI requests return `0`; handled runtime/configuration failures retur ### Keybindings +In the main window, **Escape** closes the current inspector, then returns to the previous page. It does not close the app from Home. Open dropdowns and dialogs handle Escape first. **Ctrl+Q** quits the application, including background integration. In the action editor, **Ctrl+S** saves and **Escape** closes with an unsaved-changes prompt when needed. + These keys apply while the Actions Ring is open: | Key | Action | @@ -382,10 +389,13 @@ The optional shortcut fallback rule is installed with `./scripts/install-input-a | [Installation](docs/install.md) | Dependencies, manual setup, access rules and complete removal | | [Configuration](docs/configuration.md) | Desktop schema, defaults, profiles and environment variables | | [Architecture](docs/architecture.md) | Workers, event lifecycle, focus and action execution | +| [Interface design](docs/design-system.md) | Monospaced typography, warm neutral themes and native motion | +| [UI polish verification](docs/ui-polish-validation.md) | Native captures, motion lifecycle, font installation and package checks | | [Desktop features](docs/desktop-features.md) | Ring interaction, Smart Actions and Niri bindings | | [Validation](docs/validation.md) | Recorded checks and remaining hardware work | | [Linux support research](docs/linux-support-research.md) | Protocol sources and implementation constraints | | [Installer analysis](docs/installer-analysis.md) | Static artifact investigation and evidence limits | +| [Installed Windows Options+ analysis](docs/windows-optionsplus-analysis.md) | MX4 interface/agent protocols, haptics, force sensing and remaining gaps | | [Changelog](CHANGELOG.md) | User-visible changes and release history | ## Contributing diff --git a/bin/mx4-linux.js b/bin/mx4-linux.js index d90449a..1508fe2 100755 --- a/bin/mx4-linux.js +++ b/bin/mx4-linux.js @@ -21,6 +21,7 @@ function run(command, arguments_) { function setup() { if (args.length !== 1) throw new Error('Usage: mx4-linux setup (select the system interpreter with PYTHON=/path/to/python3).'); + run('bash', [join(root, 'scripts', 'setup-font.sh')]); const python = process.env.PYTHON || 'python3'; run(python, ['-c', ` import sys @@ -62,7 +63,7 @@ function launch() { || (existsSync(join(root, '.venv', 'bin', 'python')) ? join(root, '.venv', 'bin', 'python') : null); if (!python) { if (args[0] === '--help' || args[0] === '-h') { - console.log('MX4 Linux — native Linux mouse controls\n\n mx4-linux setup Install the per-user Python runtime\n mx4-linux [gui --demo] Open the control panel\n mx4-linux doctor Check device access\n\nInstall system GTK 4.12+, Libadwaita 1.4+ and Python GObject first.\nAfter setup, mx4-linux --help lists every application command.'); + console.log('MX4 Linux — native Linux mouse controls\n\n mx4-linux setup Install the per-user Python runtime\n mx4-linux [gui --demo] Open the control panel\n mx4-linux doctor Check device access\n\nInstall system GTK 4.12+, Libadwaita 1.4+, Python GObject and fontconfig first.\nSetup installs bundled JetBrains Mono fonts when needed.\nAfter setup, mx4-linux --help lists every application command.'); return; } throw new Error('Run mx4-linux setup first (or npm run setup in a checkout). See docs/install.md for system dependencies.'); diff --git a/docs/3d-interaction-validation.md b/docs/3d-interaction-validation.md new file mode 100644 index 0000000..841b4db --- /dev/null +++ b/docs/3d-interaction-validation.md @@ -0,0 +1,65 @@ +# 3D interaction validation · 2026-10-19 + +The home, Haptic Feedback and Easy-Switch views now use the exact supplied +`mxmaster4mac-whitesilver-ar-360.glb` through native GTK `GLArea`. Its 64,001 +triangles, eight mesh/material groups and embedded texture data are retained; +there is no geometry simplification. The runtime copy has SHA-256 +`305d2b776c0c0d064406253e13c9f222b01b55abf68667bb93ceb588e4e4fd35`, matching the +supplied file byte for byte. + +## Interaction + +- Home: drag in any direction for full rotation, scroll or +/− to zoom, arrow + keys to rotate, Home/0 or Reset view to return. Model manipulation does not + navigate; Customize mouse is a separate button. +- Haptic Feedback: a finite 650 ms turn reveals the thumb-side panel. +- Easy-Switch: a continuous backward turn settles into the upright underside + reference. Switch computer opens the host selector; closing it preserves the + underside. This keeps the animation visible on compact windows. +- Hover: ordinary button contents grow by 3.5%; ring icons grow by 12% while + their circular faces and input targets retain their original size. + +The renderer uses original base-color, normal and material textures, neutral +studio lighting and up to 4× multisampling. Reduced motion skips automatic turns +and hover scaling while preserving direct manipulation. Transitions suspend +when hidden or paused and stop scheduling frames when complete. Static artwork +remains available if OpenGL cannot initialize; the existing finite wheel demo +retains its baked frames. + +## Checks + +The final full suite passed **1,059 tests and 32 subtests**. The focused run +passed 48 model-loader, GPU-renderer and motion tests plus 49 shell-navigation +tests. It exercises all-direction turns, finite backward paths, +interruption and hidden time, reduced motion, zoom limits, projected controls, +GL failures, context recreation, cleanup, and the compact computer-selector flow. +All six npm tests passed, as did Ruff, Python compilation, changed-document +links and whitespace checks. The Python suite reports existing GTK/PyGObject +deprecation warnings. + +Native pixel tests verify that actual model rotation changes the rendered image +and that multisampling produces partial-coverage edges. Independent callback +instrumentation observed no renders during 300 ms after a transition settled, +or while the view was hidden. GTK smoke checks pass without the initial callout +allocation warning: readiness updates now run after the render callback. + +Python/npm packaging includes the runtime GLB and all three new renderer/motion +modules. The wheel and source archive match all 84 runtime modules/assets byte +for byte. The 365-file npm package passes installed-CLI smoke testing. The native checks use simulated +device data and do not write hardware settings or execute user routines. + +## Native visual review + +The final review produced 47 captures at exact 400×740, 620×740 and 1100×800 +window sizes in both themes: 18 page views, 18 explicit hover states, six host +selectors and five frames of the backward turn. All model views initialized +successfully with 4× multisampling. The settled views parked their animations; +hover left input bounds unchanged. Inspected frames showed no clipping or +misplaced controls. The host selector opens through the real callout and closes +back to the underside, including at 400 pixels. + +Representative captures: [home](assets/3d-interaction/home.png), +[Haptic Feedback](assets/3d-interaction/haptics.png), +[Easy-Switch](assets/3d-interaction/easy-switch.png), and +[compact Easy-Switch](assets/3d-interaction/easy-switch-compact.png). +Capture metadata is retained in [results.json](assets/3d-interaction/results.json). diff --git a/docs/architecture.md b/docs/architecture.md index cf093ea..f9270a4 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -13,13 +13,16 @@ MX4 Linux has three boundaries: the native user interface, isolated HID++ worker | `profiles.py` | Manual snapshots, locked atomic saves, profile validation and sequential application. | | `desktop.py` | GUI desktop integration, focus capture/restore, routine lifecycle and listener events. | | `desktop_editor.py` | Ring assignment and Smart Actions editor. | -| `ring.py`, `ring_model.py` | GTK icon overlay, circular pointer geometry, held eight-sector interaction and optional side menus. | -| `ring_icons.py`, `ring_preview.py` | Step-based native icon mapping and the editor’s static assignment diagram. | +| `ring.py`, `ring_model.py`, `ring_motion.py` | GTK icon overlay, circular pointer geometry, held eight-sector interaction, interruptible selection motion and optional side menus. | +| `ring_icons.py`, `ring_preview.py` | Step-based native icon mapping and the editor’s keyboard-accessible, animated assignment diagram. | | `event_session.py` | Nonblocking subprocess lifecycle and session-tagged event delivery. | | `event_worker.py` | Retained HID++ event handle, temporary control reporting and restoration. | | `actions.py` | Desktop schema, defaults, persistence, execution and input backends. | +| `applications.py` | Read-only installed-application discovery and launch through GIO desktop entries. | | `gtk_support.py` | GTK/Adwaita imports and optional layer-shell loading. | -| `motion.py`, `wheel.py` | Frame-time transitions and a finite, illustrative wheel preview without hardware polling. | +| `gltf_model.py`, `model_renderer.py` | Offline loading of the supplied GLB, native GTK `GLArea` rendering and projection of model-space control landmarks. | +| `model_motion.py` | Unrestricted quaternion rotation, bounded zoom and finite, interruptible page-pose transitions without GTK or GPU dependencies. | +| `motion.py`, `mouse_motion.py`, `mouse_view.py` | Native model gestures, frame-time transitions, registered controls, baked-image fallback and finite wheel/haptic previews without hardware polling. | | `bin/mx4-linux.js` | Linux npm entry point, explicit per-user runtime setup, argument/signal forwarding. | ## Hardware requests @@ -30,12 +33,18 @@ Discovery limits itself to supported MX Master 4 settings. Controls and numeric The GUI applies confirmed write values to existing controls instead of running another discovery scan and rebuilding the page. Coupled wheel readbacks update related controls without issuing extra writes. A failed write invalidates uncertain values and refreshes from hardware. Saving a profile uses the existing confirmed snapshot on the background executor and does not rescan the mouse. +Periodic battery reads use the serialized worker without another discovery scan. They update the battery labels and preserve the footer's last operation notice. A failed read clears the previous battery value and observation time; callbacks still require the same device identity and operation epoch. + Profile application validates a full plan before writing. It then makes sequential hardware changes, so it cannot provide a transaction across a disconnect or device failure. Errors state how many changes completed. Profiles never snapshot or replay waveform commands. ## Event listener lifecycle Mouse integration starts only when the user enables it. `EventSession` starts the event worker, sends the selected ring/button controls and relays JSON-line events to the GUI. The worker captures the existing control reporting state, temporarily enables diversion and raw XY for selected supported buttons, and retains its HID handle for input and haptic feedback. +Opening the action editor dismisses any current ring selection while retaining enabled integration. Saving reconciles the configuration with the active worker through its existing control-release boundary; editing does not require disabling and re-enabling integration. The editor exposes the same integration status and Enable/Disable control as the main window. + +Closing the main window hides it while integration is enabled or starting, unless `background` is explicitly false. The registered GTK window keeps the application and controller alive; launcher activation reuses that window without restarting integration. Explicit Quit uses the editor's existing unsaved-changes guard, cancels pending work, waits asynchronously for the listener's stopped/restoration callback, and then releases UI resources and exits. This does not add login autostart or automatically enable integration. + Only nonprimary controls are allowed. The prior reporting flags and mapping are restored on the worker's cleanup path. Stop requests, EOF and termination use this path; a disconnected mouse or forced process loss can prevent immediate hardware restoration and may require reconnecting. The settings worker uses HID++ software ID `0xC`; the event worker uses `0xD`, distinct from Solaar's `0xB`. These IDs separate concurrent replies, but do not prevent other tools from writing conflicting settings. @@ -50,7 +59,17 @@ Held movement keeps the calibrated eight-sector model and center dead zone. Afte Before opening the ring, desktop integration records Niri's focused application/window. Before executing the chosen action, it restores that focus and verifies the original window still exists. A vanished target stops execution. Ring/button dispatch refuses shortcuts and text when an MX4 configuration window is the target; direct CLI `actions run` does not use this GUI focus guard. A preview follows the selection UI but prints steps without action execution or haptic feedback. -Animations use GTK frame callbacks and elapsed time. Wheel motion settles after an impulse; ring callbacks stop when transitions finish or the ring hides. GTK's `gtk-enable-animations` preference disables decorative motion. Labels and buttons are native widgets reused across frames. Opening spreads the icons outward over 180 ms; side menus reveal over 160 ms and labels fade over 100 ms. Hit testing follows the painted positions. Emerging children cannot receive pointer clicks while they overlap their parent, another main button or each other. Ring selection dispatches immediately after hiding; no exit animation delays the action. The wheel illustration previews scrolling visually and does not read or claim to represent physical wheel rotation. +Animations use GTK frame callbacks and elapsed time. Wheel motion settles after an impulse; ring callbacks stop when transitions finish or the ring hides. GTK's `gtk-enable-animations` preference disables decorative motion. Labels and buttons are native widgets reused across frames. Opening traces the orbit over 220 ms while root buttons remain immediately visible at their final hit positions. A short inner selection arc follows the shortest route between actions over 180 ms, retargeting from its current painted angle. Held motion draws a direction tether; captured presses tint the circular face and compress only its icon. Side menus reveal over 160 ms and labels fade over 100 ms. Hit testing follows the painted child positions; root hit regions remain fixed. Emerging children cannot receive pointer clicks while they overlap their parent, another main button or each other. Ring selection dispatches immediately after hiding; no exit animation delays the action. The wheel illustration previews scrolling visually and does not read or claim to represent physical wheel rotation. + +Mouse artwork renders the supplied GLB in a native GTK `GLArea`. The offline loader reads the embedded mesh attributes, materials and textures; no browser, network fetch or third-party 3D engine runs in the application. `ModelPicture` owns the renderer, input controllers, motion state and baked-image fallback. Surface targets, leaders and host indicators use model-space landmarks projected through the current orientation and zoom, while their native callout labels stay parked. Surface overlays hide during page turns and on faces pointing away from the viewer. Easy-Switch initially shows the model; its Switch computer callout opens the host selector, so compact layouts can show the turn without a covering inspector. + +The home model supports drag rotation in every direction, including complete turns and upside-down views. Wheel scrolling and the +/− keys adjust zoom within a bounded range; arrow keys rotate the focused model, and Home or 0 restores its initial pose and magnification. Device pages share a model viewport: Haptic Feedback turns it sideways toward the thumb panel, and Easy-Switch starts a backward flip before settling with the underside upright. `ModelMotion` uses unit quaternions and 650 ms eased interpolation; the underside follows a spherical cubic curve to combine that backward turn with its readable final pose. Navigation interrupts and retargets from the current displayed orientation. The model remains still after settling. Frame callbacks run only during active transitions, capped at 60 fps; unmapping pauses elapsed time, and the toolbar pause control or system reduced-motion setting stops decorative playback. Reduced motion snaps page poses while keeping direct home-model manipulation available. + +If graphics initialization fails, the model retains its baked product illustration and registered controls. Existing image assets also provide the finite wheel demonstration: it temporarily holds the 3D viewport, settles the baked camera, plays the wheel frames and restores the model. The decoded-image LRU cache remains bounded at 16 MiB, plus images retained by visible widgets. Neither the model pose nor the authored wheel/haptic previews represent physical motion telemetry. + +The native shell uses a single monospaced family, flat warm-neutral surfaces and restrained transitions. Button contents and ring icons scale slightly on hover while their layout allocations and pointer hit regions stay fixed. Below 760 pixels, a device-page chooser replaces the wide sidebar; title truncation and bounded dropdowns preserve window sizing. The editor shares theme and motion preferences, supports Ctrl+S and guarded Escape, and exposes field errors beside the relevant details. Ring preview arrows move between assignments; Enter or Space opens the selected assignment. Global settings subscriptions follow mapping or explicit artwork disposal, and ring CSS providers are shared per display. See [design-system.md](design-system.md) for the visual and motion rules. + +Choice rows place their label and help above a full-width control so narrow inspectors do not truncate the selected DPI or assignment. Main-window Back and Escape share route history: close the selected inspector first, then restore the previous page and its selected target. A bubbling key controller leaves native popovers and modal dialogs in control of their dismissal; Escape on Home does not close the application. Optional `ring_groups` references existing routines by slot. Hovering or choosing a grouped position opens its side menu; a held parent release latches the menu, while an explicit child choice dispatches its routine. This does not change direct CLI execution of the parent action. Version 1 documents without groups remain valid. The editor prevalidates group references, preserves ID renames and removes deleted children before saving. @@ -58,7 +77,9 @@ The existing 80 ms compositor focus handoff before input execution remains. It a ## Smart Actions -The whole configuration is validated before saving or executing. Routines contain explicit steps: Niri actions, command argument arrays, keyboard chords, text or delays. Command steps start a process without a shell and do not wait for the application to close. Their processes are reaped in the background. +The whole configuration is validated before saving or executing. Routines contain explicit steps: Niri actions, installed applications, command argument arrays, keyboard chords, text or delays. Command steps start a process without a shell and do not wait for the application to close. Their processes are reaped in the background. + +The ring's **Add application** picker searches visible installed desktop entries, then creates a routine and assigns it to the chosen position in the editor draft. An application step stores `{"type":"application","desktop_id":"org.example.App.desktop"}`. Execution resolves that ID through `GioUnix.DesktopAppInfo` (or the legacy `Gio.DesktopAppInfo`) and calls its launch API, preserving desktop-entry semantics without parsing an `Exec` string. A removed launcher produces an actionable error. Discovery, selection, saving and dry runs do not launch applications. The executor checks cancellation and its two-minute deadline between steps. Delays and native text chunks bound cancellation latency. The GUI permits one active routine and rejects repeated triggers instead of accumulating a queue. Cancellation prevents later steps; completed input and launched applications remain. diff --git a/docs/assets/3d-interaction/easy-switch-compact.png b/docs/assets/3d-interaction/easy-switch-compact.png new file mode 100644 index 0000000..0a4d5f1 Binary files /dev/null and b/docs/assets/3d-interaction/easy-switch-compact.png differ diff --git a/docs/assets/3d-interaction/easy-switch.png b/docs/assets/3d-interaction/easy-switch.png new file mode 100644 index 0000000..003ae97 Binary files /dev/null and b/docs/assets/3d-interaction/easy-switch.png differ diff --git a/docs/assets/3d-interaction/haptics.png b/docs/assets/3d-interaction/haptics.png new file mode 100644 index 0000000..cf47e40 Binary files /dev/null and b/docs/assets/3d-interaction/haptics.png differ diff --git a/docs/assets/3d-interaction/home.png b/docs/assets/3d-interaction/home.png new file mode 100644 index 0000000..bf3829b Binary files /dev/null and b/docs/assets/3d-interaction/home.png differ diff --git a/docs/assets/3d-interaction/results.json b/docs/assets/3d-interaction/results.json new file mode 100644 index 0000000..ec014d9 --- /dev/null +++ b/docs/assets/3d-interaction/results.json @@ -0,0 +1,1130 @@ +[ + { + "name": "home-1100-dark", + "width": 1100, + "height": 800, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 220.0, + 195.0, + 320.0, + 320.0 + ], + "model_samples": 4, + "parked": true + }, + { + "name": "home-1100-dark-hover", + "width": 1100, + "height": 800, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 220.0, + 195.0, + 320.0, + 320.0 + ], + "model_samples": 4, + "parked": true, + "hover_bounds": [ + 287.0, + 677.0, + 186.0, + 34.0 + ] + }, + { + "name": "haptics-1100-dark", + "width": 1100, + "height": 800, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 407.0, + 170.0, + 490.0, + 490.0 + ], + "model_samples": 4, + "parked": true, + "callout_bounds": { + "haptics": [ + 407.74737548828125, + 464.7786560058594, + 167.0, + 40.0 + ] + } + }, + { + "name": "haptics-1100-dark-hover", + "width": 1100, + "height": 800, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 407.0, + 170.0, + 490.0, + 490.0 + ], + "model_samples": 4, + "parked": true, + "hover_bounds": [ + 407.74737548828125, + 464.7786560058594, + 167.0, + 40.0 + ], + "callout_bounds": { + "haptics": [ + 407.74737548828125, + 464.7786560058594, + 167.0, + 40.0 + ] + } + }, + { + "name": "easy-switch-1100-dark", + "width": 1100, + "height": 800, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 407.0, + 171.0, + 490.0, + 490.0 + ], + "model_samples": 4, + "parked": true, + "callout_bounds": { + "hosts": [ + 611.1458740234375, + 493.109375, + 131.0, + 40.0 + ] + } + }, + { + "name": "easy-switch-1100-dark-hover", + "width": 1100, + "height": 800, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 407.0, + 171.0, + 490.0, + 490.0 + ], + "model_samples": 4, + "parked": true, + "hover_bounds": [ + 611.1458740234375, + 493.109375, + 131.0, + 40.0 + ], + "callout_bounds": { + "hosts": [ + 611.1458740234375, + 493.109375, + 131.0, + 40.0 + ] + } + }, + { + "name": "easy-switch-1100-dark-hosts", + "width": 1100, + "height": 800, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 140.0, + 171.0, + 490.0, + 490.0 + ], + "model_samples": 4, + "parked": true, + "callout_bounds": { + "hosts": [ + 343.6458435058594, + 493.109375, + 145.0, + 40.0 + ] + } + }, + { + "name": "flip-0.10", + "width": 1100, + "height": 800, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 407.0, + 171.0, + 490.0, + 490.0 + ], + "model_samples": 4, + "parked": false, + "callout_bounds": { + "hosts": [ + 611.1458740234375, + 493.109375, + 131.0, + 40.0 + ] + }, + "elapsed": 0.15779695399396587, + "orientation": [ + 0.7819521797656067, + 0.5472287566339483, + 0.14780171397723738, + -0.2593185874905042 + ] + }, + { + "name": "flip-0.25", + "width": 1100, + "height": 800, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 407.0, + 171.0, + 490.0, + 490.0 + ], + "model_samples": 4, + "parked": false, + "callout_bounds": { + "hosts": [ + 611.1458740234375, + 493.109375, + 131.0, + 40.0 + ] + }, + "elapsed": 0.30656705499859527, + "orientation": [ + 0.4374171253369691, + 0.7724400601270305, + 0.25039299771418944, + -0.38640129227086434 + ] + }, + { + "name": "flip-0.40", + "width": 1100, + "height": 800, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 407.0, + 171.0, + 490.0, + 490.0 + ], + "model_samples": 4, + "parked": false, + "callout_bounds": { + "hosts": [ + 611.1458740234375, + 493.109375, + 131.0, + 40.0 + ] + }, + "elapsed": 0.4561145899933763, + "orientation": [ + 0.001878683411750383, + 0.45599438552800137, + 0.3575755834070903, + -0.8149879097671683 + ] + }, + { + "name": "flip-0.55", + "width": 1100, + "height": 800, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 407.0, + 171.0, + 490.0, + 490.0 + ], + "model_samples": 4, + "parked": false, + "callout_bounds": { + "hosts": [ + 611.1458740234375, + 493.109375, + 131.0, + 40.0 + ] + }, + "elapsed": 0.6015428200043971, + "orientation": [ + -0.1452360308066348, + 0.21426940453123858, + 0.5511792172289189, + -0.7932191299586004 + ] + }, + { + "name": "flip-0.80", + "width": 1100, + "height": 800, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 407.0, + 171.0, + 490.0, + 490.0 + ], + "model_samples": 4, + "parked": true, + "callout_bounds": { + "hosts": [ + 611.1458740234375, + 493.109375, + 131.0, + 40.0 + ] + }, + "elapsed": 0.855436144003761, + "orientation": [ + 0.15617423847046277, + -0.20368612170676081, + -0.5880841583715886, + 0.766993216224635 + ] + }, + { + "name": "home-1100-light", + "width": 1100, + "height": 800, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 220.0, + 195.0, + 320.0, + 320.0 + ], + "model_samples": 4, + "parked": true + }, + { + "name": "home-1100-light-hover", + "width": 1100, + "height": 800, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 220.0, + 195.0, + 320.0, + 320.0 + ], + "model_samples": 4, + "parked": true, + "hover_bounds": [ + 287.0, + 677.0, + 186.0, + 34.0 + ] + }, + { + "name": "haptics-1100-light", + "width": 1100, + "height": 800, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 407.0, + 170.0, + 490.0, + 490.0 + ], + "model_samples": 4, + "parked": true, + "callout_bounds": { + "haptics": [ + 407.74737548828125, + 464.7786560058594, + 167.0, + 40.0 + ] + } + }, + { + "name": "haptics-1100-light-hover", + "width": 1100, + "height": 800, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 407.0, + 170.0, + 490.0, + 490.0 + ], + "model_samples": 4, + "parked": true, + "hover_bounds": [ + 407.74737548828125, + 464.7786560058594, + 167.0, + 40.0 + ], + "callout_bounds": { + "haptics": [ + 407.74737548828125, + 464.7786560058594, + 167.0, + 40.0 + ] + } + }, + { + "name": "easy-switch-1100-light", + "width": 1100, + "height": 800, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 407.0, + 171.0, + 490.0, + 490.0 + ], + "model_samples": 4, + "parked": true, + "callout_bounds": { + "hosts": [ + 611.1458740234375, + 493.109375, + 131.0, + 40.0 + ] + } + }, + { + "name": "easy-switch-1100-light-hover", + "width": 1100, + "height": 800, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 407.0, + 171.0, + 490.0, + 490.0 + ], + "model_samples": 4, + "parked": true, + "hover_bounds": [ + 611.1458740234375, + 493.109375, + 131.0, + 40.0 + ], + "callout_bounds": { + "hosts": [ + 611.1458740234375, + 493.109375, + 131.0, + 40.0 + ] + } + }, + { + "name": "easy-switch-1100-light-hosts", + "width": 1100, + "height": 800, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 140.0, + 171.0, + 490.0, + 490.0 + ], + "model_samples": 4, + "parked": true, + "callout_bounds": { + "hosts": [ + 343.6458435058594, + 493.109375, + 145.0, + 40.0 + ] + } + }, + { + "name": "home-620-dark", + "width": 620, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 179.0, + 192.0, + 260.0, + 260.0 + ], + "model_samples": 4, + "parked": true + }, + { + "name": "home-620-dark-hover", + "width": 620, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 179.0, + 192.0, + 260.0, + 260.0 + ], + "model_samples": 4, + "parked": true, + "hover_bounds": [ + 216.0, + 614.0, + 186.0, + 34.0 + ] + }, + { + "name": "haptics-620-dark", + "width": 620, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 63.0, + 211.0, + 445.0, + 445.0 + ], + "model_samples": 4, + "parked": true, + "callout_bounds": { + "haptics": [ + 47.57161331176758, + 481.4622497558594, + 167.0, + 40.000030517578125 + ] + } + }, + { + "name": "haptics-620-dark-hover", + "width": 620, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 63.0, + 211.0, + 445.0, + 445.0 + ], + "model_samples": 4, + "parked": true, + "hover_bounds": [ + 47.57161331176758, + 481.4622497558594, + 167.0, + 40.000030517578125 + ], + "callout_bounds": { + "haptics": [ + 47.57161331176758, + 481.4622497558594, + 167.0, + 40.000030517578125 + ] + } + }, + { + "name": "easy-switch-620-dark", + "width": 620, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 40.0, + 162.0, + 490.0, + 490.0 + ], + "model_samples": 4, + "parked": true, + "callout_bounds": { + "hosts": [ + 243.6458282470703, + 484.109375, + 130.99998474121094, + 40.0 + ] + } + }, + { + "name": "easy-switch-620-dark-hover", + "width": 620, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 40.0, + 162.0, + 490.0, + 490.0 + ], + "model_samples": 4, + "parked": true, + "hover_bounds": [ + 243.6458282470703, + 484.109375, + 130.99998474121094, + 40.0 + ], + "callout_bounds": { + "hosts": [ + 243.6458282470703, + 484.109375, + 130.99998474121094, + 40.0 + ] + } + }, + { + "name": "easy-switch-620-dark-hosts", + "width": 620, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 85.0, + 162.0, + 490.0, + 490.0 + ], + "model_samples": 4, + "parked": true, + "callout_bounds": { + "hosts": [ + 288.6458435058594, + 484.109375, + 145.0, + 40.0 + ] + } + }, + { + "name": "home-620-light", + "width": 620, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 179.0, + 192.0, + 260.0, + 260.0 + ], + "model_samples": 4, + "parked": true + }, + { + "name": "home-620-light-hover", + "width": 620, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 179.0, + 192.0, + 260.0, + 260.0 + ], + "model_samples": 4, + "parked": true, + "hover_bounds": [ + 216.0, + 614.0, + 186.0, + 34.0 + ] + }, + { + "name": "haptics-620-light", + "width": 620, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 63.0, + 211.0, + 445.0, + 445.0 + ], + "model_samples": 4, + "parked": true, + "callout_bounds": { + "haptics": [ + 47.57161331176758, + 481.4622497558594, + 167.0, + 40.000030517578125 + ] + } + }, + { + "name": "haptics-620-light-hover", + "width": 620, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 63.0, + 211.0, + 445.0, + 445.0 + ], + "model_samples": 4, + "parked": true, + "hover_bounds": [ + 47.57161331176758, + 481.4622497558594, + 167.0, + 40.000030517578125 + ], + "callout_bounds": { + "haptics": [ + 47.57161331176758, + 481.4622497558594, + 167.0, + 40.000030517578125 + ] + } + }, + { + "name": "easy-switch-620-light", + "width": 620, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 40.0, + 162.0, + 490.0, + 490.0 + ], + "model_samples": 4, + "parked": true, + "callout_bounds": { + "hosts": [ + 243.6458282470703, + 484.109375, + 130.99998474121094, + 40.0 + ] + } + }, + { + "name": "easy-switch-620-light-hover", + "width": 620, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 40.0, + 162.0, + 490.0, + 490.0 + ], + "model_samples": 4, + "parked": true, + "hover_bounds": [ + 243.6458282470703, + 484.109375, + 130.99998474121094, + 40.0 + ], + "callout_bounds": { + "hosts": [ + 243.6458282470703, + 484.109375, + 130.99998474121094, + 40.0 + ] + } + }, + { + "name": "easy-switch-620-light-hosts", + "width": 620, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 85.0, + 162.0, + 490.0, + 490.0 + ], + "model_samples": 4, + "parked": true, + "callout_bounds": { + "hosts": [ + 288.6458435058594, + 484.109375, + 145.0, + 40.0 + ] + } + }, + { + "name": "home-400-dark", + "width": 400, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 70.0, + 192.0, + 260.0, + 260.0 + ], + "model_samples": 4, + "parked": true + }, + { + "name": "home-400-dark-hover", + "width": 400, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 70.0, + 192.0, + 260.0, + 260.0 + ], + "model_samples": 4, + "parked": true, + "hover_bounds": [ + 107.0, + 630.0, + 186.0, + 34.0 + ] + }, + { + "name": "haptics-400-dark", + "width": 400, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + -9.0, + 249.0, + 368.0, + 368.0 + ], + "model_samples": 4, + "parked": true, + "callout_bounds": { + "haptics": [ + 6.0, + 478.3541564941406, + 167.0, + 39.999969482421875 + ] + } + }, + { + "name": "haptics-400-dark-hover", + "width": 400, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + -9.0, + 249.0, + 368.0, + 368.0 + ], + "model_samples": 4, + "parked": true, + "hover_bounds": [ + 6.0, + 478.3541564941406, + 167.0, + 39.999969482421875 + ], + "callout_bounds": { + "haptics": [ + 6.0, + 478.3541564941406, + 167.0, + 39.999969482421875 + ] + } + }, + { + "name": "easy-switch-400-dark", + "width": 400, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + -9.0, + 223.0, + 368.0, + 368.0 + ], + "model_samples": 4, + "parked": true, + "callout_bounds": { + "hosts": [ + 150.1666717529297, + 473.625, + 131.00001525878906, + 40.0 + ] + } + }, + { + "name": "easy-switch-400-dark-hover", + "width": 400, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + -9.0, + 223.0, + 368.0, + 368.0 + ], + "model_samples": 4, + "parked": true, + "hover_bounds": [ + 150.1666717529297, + 473.625, + 131.00001525878906, + 40.0 + ], + "callout_bounds": { + "hosts": [ + 150.1666717529297, + 473.625, + 131.00001525878906, + 40.0 + ] + } + }, + { + "name": "easy-switch-400-dark-hosts", + "width": 400, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 36.0, + 223.0, + 368.0, + 368.0 + ], + "model_samples": 4, + "parked": true, + "callout_bounds": { + "hosts": [ + 195.1666717529297, + 473.625, + 145.00001525878906, + 40.0 + ] + } + }, + { + "name": "home-400-light", + "width": 400, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 70.0, + 192.0, + 260.0, + 260.0 + ], + "model_samples": 4, + "parked": true + }, + { + "name": "home-400-light-hover", + "width": 400, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 70.0, + 192.0, + 260.0, + 260.0 + ], + "model_samples": 4, + "parked": true, + "hover_bounds": [ + 107.0, + 630.0, + 186.0, + 34.0 + ] + }, + { + "name": "haptics-400-light", + "width": 400, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + -9.0, + 249.0, + 368.0, + 368.0 + ], + "model_samples": 4, + "parked": true, + "callout_bounds": { + "haptics": [ + 6.0, + 478.3541564941406, + 167.0, + 39.999969482421875 + ] + } + }, + { + "name": "haptics-400-light-hover", + "width": 400, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + -9.0, + 249.0, + 368.0, + 368.0 + ], + "model_samples": 4, + "parked": true, + "hover_bounds": [ + 6.0, + 478.3541564941406, + 167.0, + 39.999969482421875 + ], + "callout_bounds": { + "haptics": [ + 6.0, + 478.3541564941406, + 167.0, + 39.999969482421875 + ] + } + }, + { + "name": "easy-switch-400-light", + "width": 400, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + -9.0, + 223.0, + 368.0, + 368.0 + ], + "model_samples": 4, + "parked": true, + "callout_bounds": { + "hosts": [ + 150.1666717529297, + 473.625, + 131.00001525878906, + 40.0 + ] + } + }, + { + "name": "easy-switch-400-light-hover", + "width": 400, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + -9.0, + 223.0, + 368.0, + 368.0 + ], + "model_samples": 4, + "parked": true, + "hover_bounds": [ + 150.1666717529297, + 473.625, + 131.00001525878906, + 40.0 + ], + "callout_bounds": { + "hosts": [ + 150.1666717529297, + 473.625, + 131.00001525878906, + 40.0 + ] + } + }, + { + "name": "easy-switch-400-light-hosts", + "width": 400, + "height": 740, + "model_ready": true, + "model_error": null, + "model_bounds": [ + 36.0, + 223.0, + 368.0, + 368.0 + ], + "model_samples": 4, + "parked": true, + "callout_bounds": { + "hosts": [ + 195.1666717529297, + 473.625, + 145.00001525878906, + 40.0 + ] + } + } +] diff --git a/docs/assets/ring-motion/background-settings.png b/docs/assets/ring-motion/background-settings.png new file mode 100644 index 0000000..3a797bf Binary files /dev/null and b/docs/assets/ring-motion/background-settings.png differ diff --git a/docs/assets/ring-motion/group.png b/docs/assets/ring-motion/group.png new file mode 100644 index 0000000..4eb364f Binary files /dev/null and b/docs/assets/ring-motion/group.png differ diff --git a/docs/assets/ring-motion/held.png b/docs/assets/ring-motion/held.png new file mode 100644 index 0000000..d1afa2f Binary files /dev/null and b/docs/assets/ring-motion/held.png differ diff --git a/docs/assets/ring-motion/interactive-ring.mp4 b/docs/assets/ring-motion/interactive-ring.mp4 new file mode 100644 index 0000000..fe4c005 Binary files /dev/null and b/docs/assets/ring-motion/interactive-ring.mp4 differ diff --git a/docs/assets/ring-motion/selected.png b/docs/assets/ring-motion/selected.png new file mode 100644 index 0000000..62f6d35 Binary files /dev/null and b/docs/assets/ring-motion/selected.png differ diff --git a/docs/assets/ui-fixes/application-picker.png b/docs/assets/ui-fixes/application-picker.png new file mode 100644 index 0000000..f035623 Binary files /dev/null and b/docs/assets/ui-fixes/application-picker.png differ diff --git a/docs/assets/ui-fixes/captures.json b/docs/assets/ui-fixes/captures.json new file mode 100644 index 0000000..efa9fd1 --- /dev/null +++ b/docs/assets/ui-fixes/captures.json @@ -0,0 +1,187 @@ +[ + { + "name": "settings-400-dark", + "width": 400, + "height": 740 + }, + { + "name": "point-400-dark", + "width": 400, + "height": 740 + }, + { + "name": "buttons-400-dark", + "width": 400, + "height": 740 + }, + { + "name": "assignment-popup", + "width": 279, + "height": 398 + }, + { + "name": "ring-400-dark", + "width": 400, + "height": 740 + }, + { + "name": "actions-400-dark", + "width": 400, + "height": 740 + }, + { + "name": "picker-400", + "width": 400, + "height": 740 + }, + { + "name": "picker-search-400", + "width": 400, + "height": 740 + }, + { + "name": "picker-empty-400", + "width": 400, + "height": 740 + }, + { + "name": "settings-400-light", + "width": 400, + "height": 740 + }, + { + "name": "point-400-light", + "width": 400, + "height": 740 + }, + { + "name": "buttons-400-light", + "width": 400, + "height": 740 + }, + { + "name": "ring-400-light", + "width": 400, + "height": 740 + }, + { + "name": "actions-400-light", + "width": 400, + "height": 740 + }, + { + "name": "settings-620-dark", + "width": 620, + "height": 740 + }, + { + "name": "point-620-dark", + "width": 620, + "height": 740 + }, + { + "name": "buttons-620-dark", + "width": 620, + "height": 740 + }, + { + "name": "ring-620-dark", + "width": 620, + "height": 740 + }, + { + "name": "actions-620-dark", + "width": 620, + "height": 740 + }, + { + "name": "settings-620-light", + "width": 620, + "height": 740 + }, + { + "name": "point-620-light", + "width": 620, + "height": 740 + }, + { + "name": "buttons-620-light", + "width": 620, + "height": 740 + }, + { + "name": "ring-620-light", + "width": 620, + "height": 740 + }, + { + "name": "actions-620-light", + "width": 620, + "height": 740 + }, + { + "name": "settings-1100-dark", + "width": 1100, + "height": 800 + }, + { + "name": "point-1100-dark", + "width": 1100, + "height": 800 + }, + { + "name": "buttons-1100-dark", + "width": 1100, + "height": 800 + }, + { + "name": "ring-1100-dark", + "width": 1100, + "height": 800 + }, + { + "name": "actions-1100-dark", + "width": 1100, + "height": 800 + }, + { + "name": "picker-1100", + "width": 1100, + "height": 800 + }, + { + "name": "picker-search-1100", + "width": 1100, + "height": 800 + }, + { + "name": "picker-empty-1100", + "width": 1100, + "height": 800 + }, + { + "name": "settings-1100-light", + "width": 1100, + "height": 800 + }, + { + "name": "point-1100-light", + "width": 1100, + "height": 800 + }, + { + "name": "buttons-1100-light", + "width": 1100, + "height": 800 + }, + { + "name": "ring-1100-light", + "width": 1100, + "height": 800 + }, + { + "name": "actions-1100-light", + "width": 1100, + "height": 800 + } +] diff --git a/docs/assets/ui-fixes/pointer-compact.png b/docs/assets/ui-fixes/pointer-compact.png new file mode 100644 index 0000000..d049171 Binary files /dev/null and b/docs/assets/ui-fixes/pointer-compact.png differ diff --git a/docs/assets/ui-fixes/ring-compact.png b/docs/assets/ui-fixes/ring-compact.png new file mode 100644 index 0000000..9a44ee6 Binary files /dev/null and b/docs/assets/ui-fixes/ring-compact.png differ diff --git a/docs/assets/ui-fixes/smart-actions.png b/docs/assets/ui-fixes/smart-actions.png new file mode 100644 index 0000000..efc49c1 Binary files /dev/null and b/docs/assets/ui-fixes/smart-actions.png differ diff --git a/docs/assets/ui-polish/compact-buttons.png b/docs/assets/ui-polish/compact-buttons.png new file mode 100644 index 0000000..bea5ea0 Binary files /dev/null and b/docs/assets/ui-polish/compact-buttons.png differ diff --git a/docs/assets/ui-polish/home-dark.png b/docs/assets/ui-polish/home-dark.png new file mode 100644 index 0000000..ce56b4d Binary files /dev/null and b/docs/assets/ui-polish/home-dark.png differ diff --git a/docs/assets/ui-polish/home-light.png b/docs/assets/ui-polish/home-light.png new file mode 100644 index 0000000..08af8ac Binary files /dev/null and b/docs/assets/ui-polish/home-light.png differ diff --git a/docs/assets/ui-polish/ring-editor.png b/docs/assets/ui-polish/ring-editor.png new file mode 100644 index 0000000..8c7f6e5 Binary files /dev/null and b/docs/assets/ui-polish/ring-editor.png differ diff --git a/docs/assets/ui-polish/ring-group.png b/docs/assets/ui-polish/ring-group.png new file mode 100644 index 0000000..3784440 Binary files /dev/null and b/docs/assets/ui-polish/ring-group.png differ diff --git a/docs/configuration.md b/docs/configuration.md index 05651ca..b4a8b7c 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -12,9 +12,9 @@ MX4 Linux separates hardware profiles from desktop actions. Both use `$XDG_CONFI .venv/bin/mx4-linux actions import desktop.json ``` -`validate` checks without saving or executing. `import` validates then replaces the saved document. Disable and re-enable mouse integration after importing changed button bindings while the GUI is running. Saving in the GUI stops mouse integration; enable it again afterwards. +`validate` checks without saving or executing. `import` validates then replaces the saved document. Disable and re-enable mouse integration after importing changed button bindings while the GUI is running. Saving explicit button/ring assignments in the GUI stops mouse integration; enable it again afterwards. Local preferences, including Adapt to App, reconcile future assignments without stopping an open invocation. -All top-level fields except `ring_groups` are required. Unknown fields are rejected. The file and its serialized configuration are limited to 1 MiB. +The required top-level fields are `version`, `ring`, `actions`, `button_bindings`, `ring_button` and `haptic_feedback`. Additional fields described below are optional. Unknown fields are rejected. The file and its serialized configuration are limited to 1 MiB. | Field | Type and limits | Default when no file exists | | :--- | :--- | :--- | @@ -23,11 +23,28 @@ All top-level fields except `ring_groups` are required. Unknown fields are rejec | `ring_groups` | Optional object mapping decimal ring positions `"0"`–`"7"` to 1–6 distinct existing action IDs in display order | Absent; each position runs its assigned action directly | | `actions` | Object containing 1–128 named routines | Eight built-in routines listed below | | `button_bindings` | Object mapping supported decimal button IDs to existing action IDs | `{}` | -| `ring_button` | Integer: one of `82`, `83`, `86`, `195`, `196`, `416` | `416` (haptic panel) | +| `ring_button` | One of `82`, `83`, `86`, `195`, `196`, `416`, or `null` for manual opening only | `416` (haptic panel) | | `haptic_feedback` | Boolean controlling selection feedback | `true` | +| `adapt_to_app` | Optional boolean: use exact application assignments when enabled | `true` when omitted | `button_bindings` cannot assign the selected `ring_button`. Supported IDs are a configuration allowlist; the listener also verifies that the connected device supports each selected control. Primary left/right click and scrolling are excluded from diversion. +### Application assignments and ring trigger + +Optional `assignment_profiles` maps profile IDs to objects with `label`, exact `app_id` (or `"*"` for General), eight-position `ring`, and `button_bindings`. `ring_groups` and `ring_button` are optional in each profile. `active_profiles` maps exact app IDs and/or `"*"` to an existing profile with the same app ID. Up to 64 profiles are allowed; all profiles, including inactive ones, are validated before saving. + +A profile without `ring_button` inherits the persisted root trigger. Explicit `null` disables its physical ring trigger, while an allowed integer overrides it. Each profile's ordinary bindings must exclude its effective trigger. With no physical trigger, all six supported controls may have ordinary bindings; **Open Actions Ring** and the CLI/desktop shortcut still work. An integration session with no trigger or bindings keeps its ownership/recovery checks and makes no new reporting changes. + +With `adapt_to_app` enabled (the default), the active exact-app profile wins, then active General, then root assignments. Disabled adaptation uses General/root while retaining the actual focused app and window for action conditions and focus safety. Changing this preference preserves an already-open ring and running routine; future assignments become live after the listener acknowledges its safe control transition. + +The device page's context selector edits the selected exact-app/General scope even when adaptation is disabled. Every local button menu offers **Default**, **Show Actions Ring**, and existing actions. Choosing a different trigger releases the old trigger; replacing a trigger with an ordinary action or Default explicitly disables that scope's trigger. Conflicts in any inheriting profile reject the save. The earlier full-window editor labels its default/root scope explicitly; shared routine definitions remain shared. + +Built-in mouse functions are global hardware settings. Replacing a local assignment with a built-in function first waits for confirmed reporting restoration, then saves the local clear before attempting the hardware write. If the hardware request fails, the local clear remains saved and the status reports both results. + +### Adjusting an action + +An action may have an `adjustment` object with nonempty `increase` and `decrease` step arrays, validated with the same limits as its normal `steps`. Scroll over its fully revealed circle to adjust it, or press the primary mouse button on the circle and drag horizontally. Drag capture pins that initial action, including child actions; crossing a gap or another circle does not retarget it. The first detent requires 10 logical pixels of predominantly horizontal motion, followed by 12-pixel detents at every ring size. Small motion preserves a normal click. A recognized drag suppresses the ordinary action on release, including after reversal or a rejected adjustment. One motion callback emits at most 4 steps, and the controller bounds/coalesces pending work. Preview never runs adjustment steps. + ### Action groups Expand **Action groups (optional)** in the Actions Ring editor to make a position open a submenu. Its assigned routine provides the group's label and icon; choosing a child runs that child's existing routine. A group belongs to a ring position, so assigning the same routine elsewhere does not create another group. Calling the parent routine directly, including through a mouse button shortcut, still runs its normal steps. diff --git a/docs/design-system.md b/docs/design-system.md new file mode 100644 index 0000000..7cf6216 --- /dev/null +++ b/docs/design-system.md @@ -0,0 +1,40 @@ +# Interface and motion + +The supplied OpenCode design reference informs the typography, palette and spacing. This remains a native mouse configuration app: the real mouse model, circular action targets and standard keyboard interaction retain their purpose. + +## Typography and surfaces + +- JetBrains Mono is the required free alternative approved by the user. Regular and Bold originals ship with their SIL Open Font License; setup verifies or installs the family for the current user. Body text is 14 px, supporting labels 12 px, native page titles 22 px and the home headline 36 px (28 px in compact layouts). +- Light mode uses warm cream `#fdfcfc`, ink `#201d1d` and secondary text `#646262`. Dark mode reverses the warm neutral hierarchy with secondary text `#b9b5b5`. Existing theme preferences are preserved. +- Layout uses 8/12/16/24/32 px spacing, fine rules, 4 px control corners and square section boundaries. The mouse card provides one dark visual anchor in light mode. ASCII markers identify home links and numbered device sections. No gradients, decorative glow or drop shadows are used. +- Blue identifies keyboard focus and active model landmarks. Errors remain distinguishable through inline text and native invalid-state semantics. Ring buttons stay circular so painted shapes agree with pointer targets. + +## Motion + +| Element | Behavior | Stop condition | +| --- | --- | --- | +| Home mouse model | Direct, unrestricted 3D drag rotation; scroll and +/− zoom; arrows rotate; Home or 0 resets | Direct input ends; reset transition completes | +| Device-page mouse model | 650 ms quaternion transition; Haptic Feedback turns sideways toward the thumb panel, Easy-Switch curves backward into an upright underside view | Transition completes; hidden or paused suspends time; system reduced motion snaps | +| Wheel preview | 140 ms camera settle, 450 ms finite wheel sequence, 140 ms camera return | Completion, route change, hidden, paused or reduced motion | +| Haptic illustration | Three expanding, fading outlines over 800 ms | Completion, route change, hidden, paused or reduced motion | +| Page and inspector changes | Native 180–250 ms fades/slides | Native transition completion; system reduced motion snaps | +| Ring | 220 ms orbit trace, fixed root targets, 180 ms shortest-path selection marker, 160 ms group reveal, 100 ms callout fade, 140 ms selected outline; direct held-direction tether and press feedback | Completion or dismissal; paint updates capped at 60 fps; execution is immediate after hiding | +| Assignment preview | Finite entry and selection transitions; arrows retain keyboard focus | Completion, hidden or reduced motion | +| Buttons and fields | 160 ms color/border easing; button contents grow to 1.035× on hover with unchanged layout and hit regions | Transition completes or pointer leaves; reduced motion disables scaling | +| Ring action icons | 160 ms easing to 1.12× on hover or popup selection; native circular faces and hit regions remain fixed | Transition completes or selection leaves; reduced motion disables scaling | + +Ring pointer and keyboard selection share an interruptible marker that takes the shortest arc. Buttons remain in their final positions during entry; pressing changes only their tint and icon scale. Reduced motion shows the final selection state directly and keeps the held-direction cue. + +Motion never reads the mouse or writes a setting. Preview labels remain still and clickable; surface overlays use model-space landmarks and hide during turns or when their face points away from the viewer. Automatic pose transitions retarget from the displayed pose without jumping. The model stays still when a transition ends; it has no continuous idle rotation. Hiding the viewport excludes hidden time from the animation, and the pause button preserves its choice across workspace rebuilds for the current window. Reduced motion retains direct rotation and zoom while disabling automatic pose interpolation and hover scaling. + +## Runtime and asset boundaries + +The renderer uses native GTK `GLArea` and an offline GLB loader. It loads the supplied mesh, node transforms and embedded textures locally, with no browser, network request or Three.js dependency. The home viewport allows full turns around both axes, including upside-down views, and bounds zoom to 0.7–1.6×. Keyboard focus exposes equivalent rotation, zoom and reset controls. + +The existing baked product images remain available when the graphics context cannot initialize and for the authored wheel demonstration. The 34 baked camera images add 3.31 MB and share a decoded-texture LRU cache limited to 16 MiB (visible widgets also retain the textures they draw). Active transition updates are capped at 60 fps and their callbacks stop after settling; this cap is not a claim of measured performance on every GPU. + +The user-supplied GLB, provenance, camera construction and reproduction tooling are recorded in [reference/model-bake.md](reference/model-bake.md). The model depicts appearance; physical state comes from confirmed device metadata. Font licensing is separate from the application license and is included alongside the bundled fonts. + +## Verification + +Inspect the actual GTK output in both themes at 400, 620 and 1100 px. Confirm complete home-model turns and reset, sideways and backward page transitions, model-marker registration during rotation, stable callout labels, graphics fallback, readable settings, reachable compact navigation, keyboard ring editing, pause/resume and reduced-motion behavior. Include disposal, idle-render and package-asset checks, not only screenshots. Prior interface evidence is recorded in [ui-polish-validation.md](ui-polish-validation.md); 3D interaction checks are tracked separately in [3d-interaction-validation.md](3d-interaction-validation.md). diff --git a/docs/desktop-features.md b/docs/desktop-features.md index d311952..350be89 100644 --- a/docs/desktop-features.md +++ b/docs/desktop-features.md @@ -5,11 +5,13 @@ These features are Linux implementations using the MX4's HID++ event stream and ## Use the ring 1. Open MX4 Linux and wait for your mouse settings to load. -2. Open the **Actions** tab and click **Enable**. +2. Open **Actions Ring** and click **Enable** beside **Mouse integration**. 3. Hold the haptic panel, move the mouse towards a position and release. A short panel click instead leaves the ring open so you can point and click. -4. Use **Edit actions** to change positions, create routines or assign additional mouse buttons. Configuration changes stop mouse integration; enable it again after saving. +4. Change ring positions or open **Smart Actions** to create routines. Opening the editor keeps mouse integration enabled, and **Save changes** updates the active assignments. -The eight circular icon buttons run clockwise from the top. Labels appear beside the hovered or keyboard-selected button; the small center **×** closes the ring. Pointer clicks target the visible circles, so the gaps do not execute actions. Keys **1–8** select them; arrow keys move the selection, Enter confirms, and Escape returns from a group or closes the ring. Moving within the center dead zone does not select an action. A second panel click cancels an open ring. **Try the ring** uses the same interface but prints the chosen steps without executing them or playing feedback. Motion follows the desktop animation preference and stops when the ring settles or closes. +To assign an installed app directly, choose **Add application** in **Actions Ring**, choose the position under **Replace the action at**, search for and select the app, then **Save changes**. The app opens only when you run that ring action. **Open application** is also available as a Smart Actions template and step. + +The eight circular icon buttons run clockwise from the top. Labels appear beside the hovered or keyboard-selected button; the small center **×** closes the ring. Pointer clicks target the visible circles, so the gaps do not execute actions. Keys **1–8** select them; arrow keys move the selection, Enter confirms, and Escape returns from a group or closes the ring. Moving within the center dead zone does not select an action. A second panel click cancels an open ring. **Try the ring** uses the same interface but prints the chosen steps without executing them or playing feedback. The orbit traces into view, a selection marker travels between actions, and held movement shows its direction. Press feedback changes the icon and color while the circular hit area stays fixed. Motion follows the desktop animation preference and stops when the ring settles or closes; selecting an action never waits for an exit animation. In **Edit actions → Actions Ring**, the live diagram shows the assignments with their labels. Click a diagram button to focus its assignment. Expand **Action groups (optional)** to choose up to six different existing routines for a position. Hovering or choosing that position opens a side menu; it does not run the parent routine. Select a child with the pointer, arrows and Enter, or keys **1–6**. When holding the panel, release over a grouped position to leave its submenu open for selection. The center **×** always cancels. Old configurations remain valid, and groups are optional. @@ -17,13 +19,15 @@ In **Edit actions → Actions Ring**, the live diagram shows the assignments wit The ring is a centered layer-shell overlay, not a cursor-position popup. It captures the original application before opening and restores that focus before executing an action. A vanished target stops the action. Shortcuts and text triggered while an MX4 configuration window is focused are refused; use the panel from the application you want to control. -The application must remain running. Disable or close it to restore the selected controls' previous diversion/raw-motion flags. It never diverts primary left/right click or scrolling. On unplug or cancellation, synthetic release events cancel the ring instead of committing its selection. The listener's haptic commands and event reads share one retained handle; separate HID++ software IDs prevent replies being confused with one-shot setting requests or Solaar. +Closing the settings window keeps enabled mouse integration running in the background by default. Reopening MX4 Linux presents the same window and controller. Application Settings lets you disable this behavior. **Disable** stops integration; **Quit** (Ctrl+Q) exits the application and restores the selected controls' previous diversion/raw-motion flags. Closing a window with integration disabled still exits normally. Background operation does not enable integration or add login autostart. + +Integration never diverts primary left/right click or scrolling. On unplug or cancellation, synthetic release events cancel the ring instead of committing its selection. The listener's haptic commands and event reads share one retained handle; separate HID++ software IDs prevent replies being confused with one-shot setting requests or Solaar. Default assignments are Overview, Screenshot, Terminal, Next workspace, Paste, Copy, Undo and Previous workspace. Niri commands use its public IPC. Other compositor support requires adapters; on unsupported layer-shell desktops the ring can appear as a normal window, and Niri actions will report an error. ## Create a Smart Action -Open **Actions → Edit actions → Smart Actions**. Choose an existing routine or create one from a shortcut, launch, text or multiple-step template. Give it a name, expand a step to edit its fields, and use **Add step** plus the move/remove controls to build the sequence. **Edit steps as JSON** exposes the same data for advanced editing; **Advanced routine settings** contains the action ID. An optional application condition requires an exact match with the focused Niri `app_id`. Use `niri msg --json focused-window` to inspect that ID. Editing and saving do not execute the routine. +Open **Smart Actions**. Choose an existing routine or create one from a shortcut, launch, text or multiple-step template. Give it a name, expand a step to edit its fields, and use **Add step** plus the move/remove controls to build the sequence. **Edit steps as JSON** exposes the same data for advanced editing; **Advanced routine settings** contains the action ID. An optional application condition requires an exact match with the focused Niri `app_id`. Use `niri msg --json focused-window` to inspect that ID. Editing and saving do not execute the routine. ![Live Actions Ring assignment preview in the native editor](assets/action-editor-ring.png) diff --git a/docs/install.md b/docs/install.md index f6a81d8..75c0554 100644 --- a/docs/install.md +++ b/docs/install.md @@ -4,14 +4,14 @@ MX4 Linux supports source installation and a self-contained npm package that lau ## System dependencies -The GUI requires Python 3.11+, Python GObject, GTK 4.12+ and Libadwaita 1.4+. Install these through your distribution so the GObject typelib and shared libraries match. Typical base packages are: +The GUI requires Python 3.11+, Python GObject, GTK 4.12+, Libadwaita 1.4+, Fontconfig and JetBrains Mono. Install native libraries through your distribution so the GObject typelib and shared libraries match. Setup installs the bundled fonts automatically when needed. Typical base packages are: ```bash # Arch Linux -sudo pacman -S python python-gobject gtk4 libadwaita python-pip +sudo pacman -S python python-gobject gtk4 libadwaita python-pip fontconfig # Debian / Ubuntu; check that your release meets the GTK and Libadwaita minimums -sudo apt install python3-venv python3-pip python3-gi python3-gi-cairo gir1.2-gtk-4.0 gir1.2-adw-1 +sudo apt install python3-venv python3-pip python3-gi python3-gi-cairo gir1.2-gtk-4.0 gir1.2-adw-1 fontconfig ``` For the Actions Ring overlay, install the system `gtk4-layer-shell` library and its `Gtk4LayerShell-1.0` typelib. Package names vary by distribution. If the library or compositor support is unavailable, the ring can fall back to a normal window. @@ -22,6 +22,21 @@ The local helper build needs `curl`, `sha256sum`, `tar`, Meson, Ninja, `pkg-conf Without wtype, shortcuts can use python-evdev and `/dev/uinput`. Text actions instead call `wl-copy` from `wl-clipboard` and paste with Ctrl+V, replacing the clipboard contents. Niri actions still require Niri. +## Interface font + +The interface uses [JetBrains Mono](https://github.com/JetBrains/JetBrainsMono), a free alternative to Berkeley Mono. Regular and bold font files and the SIL Open Font License 1.1 are bundled in `src/mx4_linux/assets/fonts/`; no paid font, account, external font download or license purchase is required. + +Both setup paths check that Fontconfig exposes the actual JetBrains Mono family in upright regular and bold weights. If either is missing, they verify and install the bundled fonts and their license into `$XDG_DATA_HOME/fonts/mx4-linux-jetbrains-mono/` (default `~/.local/share/fonts/mx4-linux-jetbrains-mono/`) and refresh the user fonts cache, including discovery of the new subdirectory. Setup uses no sudo and leaves other font files untouched. A failed prerequisite check does not disable a previously working installation. + +To check or install the font independently: + +```bash +./scripts/setup-font.sh --check # Read-only; reports missing fonts +./scripts/setup-font.sh # Install bundled fonts only if needed +``` + +Restart an already open application after installing the fonts. An existing launch remains available with a fallback font while the prerequisite is being resolved. + ## Source setup ```bash @@ -32,7 +47,7 @@ cd mx4-linux .venv/bin/mx4-linux doctor --json ``` -`setup.sh` creates `.venv` with `--system-site-packages` so the application can use the distribution's GObject bindings. It installs the editable application, test/lint/build tools and Solaar 1.1.20. If `uv` is installed, setup uses it; otherwise it uses the environment's pip. To select a different compatible interpreter, run `PYTHON=python3.11 ./scripts/setup.sh` with that interpreter's matching system bindings installed. +`setup.sh` verifies or installs JetBrains Mono, then creates `.venv` with `--system-site-packages` so the application can use the distribution's GObject bindings. It installs the editable application, test/lint/build tools and Solaar 1.1.20. If `uv` is installed, setup uses it; otherwise it uses the environment's pip. To select a different compatible interpreter, run `PYTHON=python3.11 ./scripts/setup.sh` with that interpreter's matching system bindings installed. The optional `scripts/setup-wtype.sh` downloads commit `d71be3a7b3f93b534a2823fd68cabd7ac2a02359` from wtype 0.4, verifies its source checksum and installs the built executable, MIT license and man page inside `.venv`. Download/source/build files stay under `.tools`. An existing local helper is reused only when its stored executable checksum matches. @@ -65,7 +80,7 @@ npm install --global --prefix "$HOME/.local" ./mx4-linux-0.2.0.tgz The archive includes the Python application, icon, access-rule installers and documentation. npm installation runs no scripts and installs no Node dependencies. Add `~/.local/bin` to your `PATH` if you want to invoke `mx4-linux` without its full path. -`mx4-linux setup` checks Python 3.11+, GTK 4.12+, Libadwaita 1.4+ and Python GObject, creates a virtual environment with system site packages, and installs the application and Solaar using pip. It writes to `$XDG_DATA_HOME/mx4-linux/runtime/0.2.0/` (default `~/.local/share/mx4-linux/runtime/0.2.0/`); it does not need sudo or change device permissions. `PYTHON=/usr/bin/python3 mx4-linux setup` selects the system interpreter whose GObject bindings match the installed libraries. Install system `wtype` separately for keyboard/text actions; npm setup does not build it automatically. +`mx4-linux setup` verifies or installs JetBrains Mono, checks Python 3.11+, GTK 4.12+, Libadwaita 1.4+ and Python GObject, creates a virtual environment with system site packages, and installs the application and Solaar using pip. The Python runtime is written to `$XDG_DATA_HOME/mx4-linux/runtime/0.2.0/` (default `~/.local/share/mx4-linux/runtime/0.2.0/`); setup does not need sudo or change device permissions. `PYTHON=/usr/bin/python3 mx4-linux setup` selects the system interpreter whose GObject bindings match the installed libraries. Install system `wtype` separately for keyboard/text actions; npm setup does not build it automatically. The launcher first honors `MX4_LINUX_PYTHON=/path/to/environment/bin/python`, then a completed per-user runtime, then a checkout's `.venv`. It always loads the source shipped with the selected npm package. Arguments after `npm start --` reach the native CLI unchanged; for example, `npm start -- doctor --json`. Only `setup` is handled by the launcher. @@ -116,7 +131,7 @@ This writes `$XDG_DATA_HOME/applications/io.github.mx4linux.Control.desktop`, de ## Updating -Close MX4 Linux before updating: +Choose **Quit MX4 Linux** from the application menu before updating: ```bash git pull --ff-only @@ -134,7 +149,7 @@ Profiles and desktop configuration are stored separately and survive environment ## Uninstalling -Close the application first so an active listener can restore the mouse's previous reporting state. From the project directory, remove generated environments and the optional launcher: +Choose **Quit MX4 Linux** from the application menu first so an active listener can restore the mouse's previous reporting state. From the project directory, remove generated environments and the optional launcher: ```bash rm -rf -- .venv .tools @@ -162,6 +177,7 @@ These removal steps do not undo hardware settings already written to the mouse o ## Troubleshooting - **Missing GTK / Adwaita imports:** install the system packages and recreate `.venv` with that system Python. A pip-only PyGObject installation is not the documented setup path. +- **Missing interface font:** install the `fontconfig` package and run `scripts/setup-font.sh`; use `--check` to verify the family without changing files. For a global npm install, rerun `mx4-linux setup`. - **Mouse absent:** wake it, inspect `doctor --json`, verify access, and refresh. A receiver's presence alone does not establish an online MX Master 4. - **Intermittent discovery or writes:** close other mouse configuration tools, including Solaar's UI, to avoid competing settings. Device operations can wait up to 90 seconds before reporting a timeout. - **Helper build failure:** install system wtype, or install the missing build tools printed by `setup-wtype.sh` and rerun it. diff --git a/docs/installer-analysis.md b/docs/installer-analysis.md index 94272c5..fcd52cc 100644 --- a/docs/installer-analysis.md +++ b/docs/installer-analysis.md @@ -77,6 +77,12 @@ For graph projection, create an input JSON object `{"inventory_evidence": [