daredoole · daredoole · May 1, 2026 · Apr 28, 2026 · Apr 29, 2026 · Apr 30, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,97 @@
+name: Beta bug report
+description: Report an InputFlow Linux beta problem with PowerToys Mouse Without Borders.
+title: "[Beta Bug]: "
+labels: ["bug", "beta"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Attach the diagnostics bundle from `scripts/inputflow-diagnostics-bundle.sh` when possible. Review it before posting publicly; the bundle redacts secrets by best effort.
+  - type: textarea
+    id: summary
+    attributes:
+      label: Problem summary
+      description: What failed, and what did you expect instead?
+    validations:
+      required: true
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Diagnostics bundle
+      description: Attach the generated archive or paste the path/name if sharing privately.
+      placeholder: inputflow-diagnostics-YYYYMMDD-HHMMSS-PID.tar.gz
+    validations:
+      required: true
+  - type: input
+    id: linux-distro
+    attributes:
+      label: Linux distro and version
+      placeholder: Fedora 40, Ubuntu 24.04, Arch, etc.
+    validations:
+      required: true
+  - type: dropdown
+    id: session-type
+    attributes:
+      label: Linux session type
+      options:
+        - X11
+        - Wayland
+        - XWayland/mixed
+        - Unknown
+    validations:
+      required: true
+  - type: input
+    id: desktop
+    attributes:
+      label: Desktop/compositor
+      placeholder: GNOME, KDE Plasma, Sway, Hyprland, etc.
+  - type: input
+    id: windows-version
+    attributes:
+      label: Windows version
+      placeholder: Windows 11 24H2
+    validations:
+      required: true
+  - type: input
+    id: powertoys-version
+    attributes:
+      label: PowerToys version
+      placeholder: v0.xx.x
+    validations:
+      required: true
+  - type: textarea
+    id: monitor-layout
+    attributes:
+      label: Monitor and machine layout
+      description: Include machine order and display layout, for example AAB, BAA, ABA, stacked, mixed DPI/resolution, wrap on/off.
+    validations:
+      required: true
+  - type: dropdown
+    id: auth-source
+    attributes:
+      label: Linux key source
+      options:
+        - key_file
+        - key_secret_id
+        - inline key
+        - not configured
+        - unknown
+  - type: dropdown
+    id: clipboard
+    attributes:
+      label: Clipboard mode
+      options:
+        - enabled send/receive
+        - enabled receive-only
+        - disabled
+        - unknown
+  - type: textarea
+    id: steps
+    attributes:
+      label: Reproduction steps
+      placeholder: |
+        1. Start PowerToys Mouse Without Borders on Windows.
+        2. Start InputFlow on Linux.
+        3. Move cursor from ...
+    validations:
+      required: true
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,7 @@
 # Build artifacts
 build/
 build-*/
+.rpmbuild-local/
 
 # Working/research files not for public release
 gemini/

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -46,6 +46,7 @@ add_executable(mwb_client
     src/main.cpp
     src/PeerRecovery.cpp
     src/SecretStore.cpp
+    src/TopologyModel.cpp
     src/ClipboardManager.cpp
     src/CryptoHelper.cpp
     src/InputManager.cpp
@@ -85,6 +86,8 @@ include(CTest)
 find_package(PkgConfig QUIET)
 
 if (BUILD_TESTING)
+    find_program(PYTHON3_EXECUTABLE python3)
+
     add_executable(mwb_client_unit_tests
         tests/test_main.cpp
         src/AppConfig.cpp
@@ -125,6 +128,14 @@ if (BUILD_TESTING)
     target_compile_options(mwb_input_latency_tests PRIVATE -Wall -Wextra -Wpedantic)
     mwb_apply_sanitizers(mwb_input_latency_tests)
 
+    add_executable(mwb_topology_model_tests
+        tests/test_topology_model.cpp
+        src/TopologyModel.cpp
+    )
+    target_include_directories(mwb_topology_model_tests PRIVATE src)
+    target_compile_options(mwb_topology_model_tests PRIVATE -Wall -Wextra -Wpedantic)
+    mwb_apply_sanitizers(mwb_topology_model_tests)
+
     add_executable(mwb_mouse_trace_tests
         tests/test_mouse_trace.cpp
         src/InputManager.cpp
@@ -175,18 +186,35 @@ if (BUILD_TESTING)
     add_test(NAME mwb_inject_mouse_abs_tests COMMAND mwb_inject_mouse_abs_tests)
     add_test(NAME mwb_input_device_capability_tests COMMAND mwb_input_device_capability_tests)
     add_test(NAME mwb_input_latency_tests COMMAND mwb_input_latency_tests)
+    add_test(NAME mwb_topology_model_tests COMMAND mwb_topology_model_tests)
+    if (PYTHON3_EXECUTABLE)
+        add_test(NAME mwb_topology_config_docs
+            COMMAND "${PYTHON3_EXECUTABLE}"
+                "${CMAKE_CURRENT_SOURCE_DIR}/tests/topology_config_docs_test.py"
+                "${CMAKE_CURRENT_SOURCE_DIR}/docs/topology.md"
+        )
+    endif()
     add_test(NAME mwb_mouse_trace_tests COMMAND mwb_mouse_trace_tests)
     add_test(NAME mwb_media_key_bridge_tests COMMAND mwb_media_key_bridge_tests)
     add_test(NAME mwb_protocol_security_tests COMMAND mwb_protocol_security_tests)
     add_test(NAME mwb_clipboard_socket_security_tests COMMAND mwb_clipboard_socket_security_tests)
     add_test(NAME mwb_client_help COMMAND mwb_client --help)
     add_test(NAME mwb_client_doctor COMMAND mwb_client doctor --config "${CMAKE_CURRENT_BINARY_DIR}/missing-doctor-config.ini")
+    add_test(NAME mwb_client_topology_explain
+        COMMAND mwb_client topology explain "${CMAKE_CURRENT_SOURCE_DIR}/tests/simple.topology"
+    )
     add_test(NAME mwb_client_doctor_categories
         COMMAND ${CMAKE_COMMAND}
             "-DMWB_CLIENT=$<TARGET_FILE:mwb_client>"
             "-DCONFIG_PATH=${CMAKE_CURRENT_BINARY_DIR}/missing-doctor-config.ini"
             -P "${CMAKE_CURRENT_SOURCE_DIR}/tests/doctor_categories.cmake"
     )
+    add_test(NAME mwb_export_windows_pair_helper
+        COMMAND ${CMAKE_COMMAND}
+            "-DMWB_CLIENT=$<TARGET_FILE:mwb_client>"
+            "-DTEST_DIR=${CMAKE_CURRENT_BINARY_DIR}/export_windows_pair"
+            -P "${CMAKE_CURRENT_SOURCE_DIR}/tests/export_windows_pair_helper.cmake"
+    )
     add_test(NAME mwb_client_doctor_invalid_config COMMAND mwb_client doctor --config "${CMAKE_CURRENT_SOURCE_DIR}/tests/invalid_config.ini")
     set_tests_properties(mwb_client_doctor_invalid_config PROPERTIES WILL_FAIL TRUE)
 endif()

diff --git a/README.md b/README.md
@@ -15,10 +15,14 @@ Recommended first-run flow for most users:
 2. **Launch Setup UI:** Run `./mwb-desktop-ui.sh menu`
 3. **Configure:**
    - Go to **Settings** -> Enter your Windows Host IP and Security Key.
-4. **Pair with Windows:**
+4. **Use PowerToys layout for normal setups:**
+   - If this Linux/Fedora machine has one monitor, do not configure topology. Let Windows PowerToys Mouse Without Borders own the Linux/Windows machine placement.
+   - If topology was enabled while testing, choose **Use PowerToys Layout Only** to set `topology_enabled=false`.
+5. **Pair with Windows:**
    - In the same UI, use the **Export Helper** option.
    - Run the exported `.ps1` script on your Windows machine to register the Linux peer.
-5. **Start:** Choose **Start Service** or launch the tray with `./build/mwb_tray`.
+6. **Start:** Choose **Start Service** or launch the tray with `./build/mwb_tray`.
+7. **Advanced layouts only:** Open **Advanced Topology/Layout** if you have multiple Linux monitors, stacked/asymmetric edges, wrap behavior, or wrong-edge handoff problems.
 
 For the full beta setup, health-check, diagnostics, connection-quality, and packaging-verification workflow, see [docs/beta-workflow.md](docs/beta-workflow.md).
 
@@ -98,9 +102,13 @@ See the full [documentation section](#detailed-documentation) for environment va
 User-facing beta operations:
 
 - [Guided Windows pairing and export helper](docs/beta-workflow.md#guided-pairing-and-export-helper)
+- [Topology/layout wizard](docs/beta-workflow.md#topologylayout-wizard)
 - [Health checks and diagnostics bundle](docs/beta-workflow.md#health-check)
 - [Connection quality and latency reporting](docs/beta-workflow.md#connection-quality)
 - [Packaging verification](docs/beta-workflow.md#packaging-verification)
+- [Topology config contract and layout wizard expectations](docs/topology.md)
+- [Migration from other keyboard/mouse sharing tools](docs/migration.md)
+- [Compatibility matrix and platform caveats](docs/compatibility.md)
 
 <a name="detailed-documentation"></a>
 ## Detailed Documentation
@@ -109,7 +117,11 @@ User-facing beta operations:
 This repository started as a fork of [chrischip/mwb-client-linux](https://github.com/chrischip/mwb-client-linux) and has been substantially expanded with service management, rich clipboard support, and recovery tooling.
 
 ### Configuration (`config.ini`)
-Supports `key_file`, `key_secret_id` (keyring), `screen_width/height` overrides, and more. Default path: `~/.config/mwb-client/config.ini`.
+Supports `key_file`, `key_secret_id` (keyring), `screen_width/height` overrides, `topology_enabled`, `topology_file`, and more. Default path: `~/.config/mwb-client/config.ini`.
+
+Display-level topology is a separate opt-in contract. The default runtime remains MWB-compatible machine placement unless topology is explicitly enabled; see [docs/topology.md](docs/topology.md) for examples, wrap policies, validation, and cross-machine handoff behavior.
+
+Windows PowerToys still owns the Windows-side machine layout. InputFlow topology does not edit PowerToys per-display geometry; it only tells Linux which local display edge should hand off back to Windows. Keep the PowerToys machine position and the InputFlow topology links consistent.
 
 ### Screen Sizing
 The client detects screen size in this order:

diff --git a/docs/beta-workflow.md b/docs/beta-workflow.md
@@ -12,7 +12,9 @@ Use the desktop controller for the guided path:
 
 1. Open **Settings** and enter the Windows host IP, local machine name, port, and exactly one authentication source: inline key, `key_file`, or Secret Service key ID.
 2. Use **Connection Behavior** to choose automatic reconnect behavior before starting the service.
-3. Export a Windows helper from Linux when the UI exposes the action, or use the CLI fallback:
+3. For one Linux/Fedora monitor, leave topology disabled and use the normal PowerToys layout path.
+4. Optionally run **Advanced Topology/Layout** only if you have multiple Linux displays, stacked/asymmetric edges, wrap behavior, or wrong-edge handoff problems.
+5. Export a Windows helper from Linux when the UI exposes the action, or use the CLI fallback:
 
 ```bash
 ./build/mwb_client export-windows-pair \
@@ -31,6 +33,27 @@ Keep the exported `.ps1` private because it contains pairing material. Delete it
 
 ![Pairing helper walkthrough](screenshots/pairing-helper.svg)
 
+## Advanced Topology/Layout Wizard
+
+Open the wizard from the desktop controller only when the normal PowerToys layout is not enough:
+
+```bash
+./mwb-desktop-ui.sh layout-wizard
+```
+
+The wizard asks for a plain-language layout, Linux/Windows machine names, display size, wrap policy, and output file name. It shows a preview of the exact topology file before making changes. For one Linux monitor, prefer **Use PowerToys Layout Only** instead.
+
+Only after confirmation, the wizard writes the topology file under `~/.config/mwb-client/` and updates `config.ini`:
+
+```ini
+topology_enabled=true
+topology_file=/home/example/.config/mwb-client/topology-side-by-side.topology
+```
+
+When topology is enabled, configured cross-machine edge transitions are enforced at runtime. Same-machine transitions remain local, and invalid topology falls back to the existing behavior with a warning.
+
+Use **Explain Current Topology** after saving. It translates the topology into English and reminds users that Windows PowerToys still owns the Windows-side machine layout. Keep the PowerToys machine placement and the InputFlow topology edges consistent.
+
 ## Health Check
 
 Run the built-in doctor before filing a beta issue or after changing package/service setup:
@@ -45,19 +68,20 @@ The desktop controller shows the same health check together with the user servic
 ./mwb-desktop-ui.sh status
 ```
 
-Review warnings for missing `/dev/uinput` access, missing `inputflow` group membership, missing packaged files, unavailable clipboard helpers, or invalid authentication configuration.
+Review warnings for missing `/dev/uinput` access, Wayland input-gating, missing `inputflow` group membership, missing packaged files, unavailable clipboard helpers, unavailable Secret Service/session bus, or invalid authentication configuration.
 
 ## Diagnostics Bundle
 
-Until a one-click diagnostics bundle command is available, collect this minimal bundle for beta reports:
+Create a redacted support bundle before filing beta reports:
 
 ```bash
-./build/mwb_client doctor --config ~/.config/mwb-client/config.ini > inputflow-doctor.txt
-systemctl --user status --no-pager mwb-client.service > inputflow-service-status.txt
-journalctl --user -u mwb-client.service --since "30 minutes ago" --no-pager > inputflow-service-log.txt
+./scripts/inputflow-diagnostics-bundle.sh \
+  --config ~/.config/mwb-client/config.ini \
+  --state ~/.local/state/mwb-client/state.ini \
+  --output .
 ```
 
-Also include `~/.config/mwb-client/config.ini` with `key`, `key_file`, `key_secret_id`, Windows IPs, and hostnames redacted as needed. Do not attach exported Windows helper scripts or unredacted Secret Service identifiers to public issues.
+The archive includes `summary.json` for machine-readable triage, redacted config/state summaries, session and `/dev/uinput` checks, package/build details, service status, recent user-service journal lines, and `mwb_client doctor` output. Review the archive before posting publicly. Do not attach exported Windows helper scripts or unredacted Secret Service identifiers to public issues.
 
 ## Connection Quality
 

diff --git a/docs/compatibility.md b/docs/compatibility.md
@@ -0,0 +1,59 @@
+# Compatibility Guide
+
+InputFlow is a native Linux peer for Microsoft PowerToys Mouse Without Borders (MWB). It targets PowerToys MWB interoperability with Linux input, clipboard, service, and configuration integration. It is not a Barrier, Synergy, Input Leap, Deskflow, or Cursr protocol implementation.
+
+## Compatibility Matrix
+
+| Area | Status | Notes |
+| --- | --- | --- |
+| Linux on X11 | Supported beta path | Input delivery uses `/dev/uinput`. Clipboard sync needs `xclip` or `xsel` when clipboard features are enabled. |
+| Linux on Wayland | Supported with caveats | Input delivery still needs writable `/dev/uinput`. Some compositors may apply extra policy, prompts, or restrictions for synthetic input. Clipboard sync needs `wl-clipboard`, and polling may be needed in some sessions. |
+| `/dev/uinput` | Required for input injection | Load the `uinput` module and grant the user access, usually through the packaged `inputflow` group and udev rule. |
+| PowerToys MWB on Windows | Target peer | Pair InputFlow with the PowerToys Mouse Without Borders feature on Windows. Exported helpers seed `MachinePool`, `MachineMatrixString`, `Name2IP`, peer name, address, layout, and key material. |
+| Barrier / Synergy / Input Leap / Deskflow | Not protocol compatible | Use the migration guide to translate concepts, not configuration files. |
+| Cursr | Not protocol compatible | InputFlow does not join Cursr groups. Use MWB peer placement instead. |
+| Authentication: Secret Service | Supported when available | Use `key_secret_id=` when a session bus and keyring are available. Headless sessions may not provide this. |
+| Authentication: `key_file` | Supported | Good default for service usage when file permissions are managed carefully. |
+| Authentication: inline `key` | Supported | Useful for quick setup, but avoid sharing configs because the key is stored directly. |
+| Clipboard receive/send | Supported beta path | Requires local helpers: `wl-clipboard` on Wayland or `xclip`/`xsel` on X11. Availability is reported by `doctor`. |
+| systemd user service | Opt-in | Packaging includes a user unit, but users should enable/start it only after validating config, key source, and `/dev/uinput` access. |
+| Network trust model | Trusted LAN/subnet | Use on a trusted local network. Do not expose MWB ports to untrusted networks or the public internet. |
+| Display-level topology config | Opt-in | The contract is documented in [Topology Config Contract](topology.md), and the default runtime remains MWB-compatible machine placement unless topology is enabled. |
+
+## Linux Session Details
+
+X11 is the simpler path because clipboard helpers and desktop automation policy are more predictable. Wayland can work, but compositor policy matters: even with `/dev/uinput` access, the compositor or desktop environment may restrict, gate, or prompt around synthetic input behavior.
+
+Run the health check after setup:
+
+```bash
+./build/mwb_client doctor --config ~/.config/mwb-client/config.ini
+```
+
+Review warnings for session type, `/dev/uinput`, group membership, clipboard helpers, Secret Service availability, and authentication conflicts.
+
+## Windows PowerToys MWB
+
+InputFlow is intended to pair with the Windows PowerToys MWB implementation. Use the exported Windows helper when possible because it writes the MWB settings that are easy to mistype by hand: peer name, address, shared key, `MachinePool`, `MachineMatrixString`, and `Name2IP`.
+
+InputFlow is independent and not affiliated with Microsoft. Compatibility is based on the open-source PowerToys MWB behavior.
+
+## Network Assumptions
+
+InputFlow assumes a trusted local network where peers can reach each other directly by IP or resolvable host name. Keep MWB traffic on a private LAN, VPN, or otherwise trusted subnet.
+
+Avoid:
+
+- Forwarding MWB ports from the internet.
+- Pairing across networks you do not control.
+- Publishing configs or exported helper scripts that include keys or private addresses.
+
+## Service Expectations
+
+The systemd user service is a convenience, not a required first step. During migration or first setup, run the desktop UI or CLI manually, confirm `doctor` output, and verify Windows pairing. Enable the user service only after those checks pass.
+
+## Topology Expectations
+
+Current default compatibility is machine-level MWB placement. Display-level topology is intentionally gated and opt-in so InputFlow can remain compatible with PowerToys MWB unless the user enables explicit machine/display links.
+
+The topology contract separates machines from displays and supports configurable wrap policies, AAB/BAA/ABA layouts, stacked layouts, asymmetric layouts, and cross-machine edge handoff. See [Topology Config Contract](topology.md) for the file format and validation expectations.