Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
90 commits
Select commit Hold shift + click to select a range
700e3d7
feat: add contextual assignments and Linux action catalog
Dijo-404 Oct 18, 2026
909f8ed
fix: keep catalog file paths literal for xdg-open
Dijo-404 Oct 18, 2026
7e18718
feat: resolve live application profiles and restore native controls
Dijo-404 Oct 18, 2026
a055794
fix: keep application profiles active after feedback warnings
Dijo-404 Oct 18, 2026
80924b8
feat: add scalable ring and pinned scroll adjustments
Dijo-404 Oct 18, 2026
d9ebcb4
fix: cancel standalone ring adjustments on focus loss
Dijo-404 Oct 18, 2026
c9d2a75
fix: distinguish ring popup from application settings focus
Dijo-404 Oct 18, 2026
1f98f0e
fix: avoid delayed GTK activation after popup focus return
Dijo-404 Oct 18, 2026
578a246
feat: recover per-unit reporting and remembered mouse settings
Dijo-404 Oct 18, 2026
553b499
fix: gate device writes and resume on confirmed reporting
Dijo-404 Oct 18, 2026
a8519bd
fix: inhibit automatic acquisition after reporting conflicts
Dijo-404 Oct 18, 2026
49dc6f4
fix: preserve reporting ownership through recovery identity checks
Dijo-404 Oct 18, 2026
371d76e
feat: rebuild native mouse workspace from reference model and GUI
Dijo-404 Oct 18, 2026
ba5cd40
fix: preserve shell destinations and confirmed device displays
Dijo-404 Oct 18, 2026
4637a21
fix: reconcile local commits across device cancellation
Dijo-404 Oct 18, 2026
b97eff8
feat: add contextual ring triggers and horizontal adjustments
Dijo-404 Oct 18, 2026
cf2247e
fix: gate asynchronous ring opening on acknowledged context
Dijo-404 Oct 18, 2026
e35024e
feat: implement finite local catalog utilities and session toggles
Dijo-404 Oct 18, 2026
9300dd7
fix: pin utility execution branches and guard cycle commits
Dijo-404 Oct 18, 2026
1aea054
fix: synchronize toggle selection reset and success commit
Dijo-404 Oct 18, 2026
83a2607
fix: clean failed helper groups and reject obsolete cycle tokens
Dijo-404 Oct 18, 2026
de2097f
docs(plan): Record the native reference rebuild sequence
Dijo-404 Oct 18, 2026
a21e80b
docs(reference): Preserve video workflow frames and notes
Dijo-404 Oct 18, 2026
b99f1d8
docs(reference): Capture Home and device discovery states
Dijo-404 Oct 18, 2026
46d8de8
docs(reference): Capture button assignment inspectors
Dijo-404 Oct 18, 2026
d7146c0
docs(reference): Capture pointer and scrolling controls
Dijo-404 Oct 18, 2026
8725ea7
docs(reference): Capture haptic feedback controls
Dijo-404 Oct 18, 2026
044bbd3
docs(reference): Capture Easy-Switch and Flow workflows
Dijo-404 Oct 18, 2026
e1d7b48
docs(reference): Capture device settings and feature tours
Dijo-404 Oct 18, 2026
a645027
docs(reference): Capture Smart Actions editing workflows
Dijo-404 Oct 18, 2026
81a8b84
docs(reference): Capture Actions Ring customization workflows
Dijo-404 Oct 18, 2026
012b8e6
docs(reference): Capture Marketplace navigation and settings
Dijo-404 Oct 18, 2026
866278b
docs(reference): Capture account and application preferences
Dijo-404 Oct 18, 2026
20152b8
docs(reference): Map the supplied native interface inventory
Dijo-404 Oct 18, 2026
31652dd
docs(reference): Record observed motion and animation timing
Dijo-404 Oct 18, 2026
1097079
docs(reference): Document artwork provenance and usage
Dijo-404 Oct 18, 2026
559a62a
docs(research): Inventory installed Windows components
Dijo-404 Oct 18, 2026
f3bc4d5
docs(research): Preserve agent schema inspection tooling
Dijo-404 Oct 18, 2026
eb0bd7c
docs(research): Decode interface resources and findings
Dijo-404 Oct 18, 2026
d07443a
docs(research): Preserve recovered animation metadata
Dijo-404 Oct 18, 2026
eac3305
docs(research): Record native and JavaScript inspection results
Dijo-404 Oct 18, 2026
0ed334b
docs(research): Record plugin service architecture findings
Dijo-404 Oct 18, 2026
249fbd0
docs(research): Record Download Assistant component findings
Dijo-404 Oct 18, 2026
2ddeff6
docs(research): Explain Windows components and Linux boundaries
Dijo-404 Oct 18, 2026
e98e7ba
docs(model): Preserve the supplied GLB and mesh inventory
Dijo-404 Oct 18, 2026
2fd92b7
build(model): Preserve wheel geometry extraction tools
Dijo-404 Oct 18, 2026
0e1d9ba
build(model): Preserve reproducible rendering and bake tooling
Dijo-404 Oct 18, 2026
d434a8f
test(pointer): Archive the native gesture verification tools
Dijo-404 Oct 18, 2026
4debc7e
docs(validation): Record contained native drag verification
Dijo-404 Oct 18, 2026
204835d
test(hardware): Preserve physical panel verification records
Dijo-404 Oct 18, 2026
135fe64
test(settings): Preserve isolated settings verification records
Dijo-404 Oct 18, 2026
be069a9
test(session): Preserve transition and restoration proof
Dijo-404 Oct 18, 2026
a5f11ef
docs(validation): Record native utility window behavior
Dijo-404 Oct 18, 2026
ddf190a
docs(validation): Record bounded haptic pulse verification
Dijo-404 Oct 18, 2026
ce3177b
feat(model): Bundle source geometry and registered orbit views
Dijo-404 Oct 18, 2026
fc6f7ee
build(fonts): Bundle licensed JetBrains Mono font weights
Dijo-404 Oct 18, 2026
cc99455
feat(setup): Install and verify bundled fonts offline
Dijo-404 Oct 18, 2026
d4590c2
fix(hidpp): Format structured device errors clearly
Dijo-404 Oct 18, 2026
7249adc
feat(apps): Discover and launch installed desktop applications
Dijo-404 Oct 18, 2026
22c3716
feat(pointer): Add an optional bounded Wayland input helper
Dijo-404 Oct 18, 2026
256b373
feat(pointer): Validate and supervise current cursor operations
Dijo-404 Oct 18, 2026
0d52162
feat(actions): Add pointer and desktop launcher assignments
Dijo-404 Oct 18, 2026
69117f3
fix(input): Restore thumb ownership and isolate haptic failures
Dijo-404 Oct 18, 2026
04bb22c
feat(model): Load embedded geometry and project control anchors
Dijo-404 Oct 18, 2026
84d3c5a
feat(model): Add bounded rotation zoom and camera transitions
Dijo-404 Oct 18, 2026
d44ff3a
feat(model): Render textured geometry with native OpenGL
Dijo-404 Oct 18, 2026
4beebe6
feat(mouse): Add finite registered camera playback
Dijo-404 Oct 18, 2026
bc3da9a
feat(mouse): Integrate interactive model views and controls
Dijo-404 Oct 18, 2026
6ada1f7
feat(ring): Add icons for pointer assignment actions
Dijo-404 Oct 18, 2026
6330bd5
feat(ring): Model finite orbit and directional feedback
Dijo-404 Oct 18, 2026
9a21435
feat(ring): Animate selection press and held direction feedback
Dijo-404 Oct 18, 2026
048c6a7
fix(desktop): Preserve integration while editing assignments
Dijo-404 Oct 18, 2026
0520b74
feat(controls): Share accessible full width inspector choice rows
Dijo-404 Oct 18, 2026
36e46d3
feat(editor): Add responsive launchers and accessible previews
Dijo-404 Oct 18, 2026
4f59dc5
fix(icon): Refresh the native application launcher artwork
Dijo-404 Oct 18, 2026
2e77a01
feat(gui): Refine native controls and background integration
Dijo-404 Oct 18, 2026
1ca116b
build(setup): Check fonts before creating the native runtime
Dijo-404 Oct 18, 2026
74e768b
build(npm): Include native model and font assets
Dijo-404 Oct 18, 2026
2e04b67
build(python): Include model fonts and validation assets
Dijo-404 Oct 18, 2026
2125984
test(package): Verify the complete runtime asset tree
Dijo-404 Oct 18, 2026
8d2e447
ci(gtk): Install fontconfig for native package smoke checks
Dijo-404 Oct 18, 2026
c5a376f
docs(design): Define native typography motion and controls
Dijo-404 Oct 18, 2026
2a6ad17
docs(architecture): Describe native rendering and lifecycle
Dijo-404 Oct 18, 2026
69cdb8c
docs(desktop): Explain launching input and background behavior
Dijo-404 Oct 18, 2026
f391ea4
docs(install): Explain font setup and optional pointer support
Dijo-404 Oct 18, 2026
ae6dc36
docs(readme): Describe the updated native desktop experience
Dijo-404 Oct 18, 2026
dd346fe
docs(validation): Record native model interaction checks
Dijo-404 Oct 18, 2026
bcfd7ae
docs(validation): Record interface and typography polish
Dijo-404 Oct 18, 2026
e5d73ed
docs(validation): Record responsive editor and integration fixes
Dijo-404 Oct 18, 2026
c02270e
docs(validation): Record ring motion and background lifecycle
Dijo-404 Oct 18, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions MANIFEST.in
Original file line number Diff line number Diff line change
Expand Up @@ -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
16 changes: 13 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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 |
Expand Down Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion bin/mx4-linux.js
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.');
Expand Down
65 changes: 65 additions & 0 deletions docs/3d-interaction-validation.md
Original file line number Diff line number Diff line change
@@ -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).
Loading
Loading