Roadmap: topology-first MWB-compatible Linux/Windows sharing

[daredoole]

Context

This roadmap builds on PR #9, which adds the beta hardening foundation: health checks, diagnostics bundle export, connection quality view, guided pairing, tray/controller entry points, RPM packaging validation, and beta workflow docs.

This is not a pivot away from the current implementation. It is the next layer on top of it: use the new diagnostics and setup flows to make topology, Wayland/session validation, and safe Windows helper behavior reliable before adding more user-facing features.

Product Contract

InputFlow should be a native Linux peer for the Microsoft PowerToys Mouse Without Borders ecosystem, optimized for trusted-LAN Linux/Windows use and predictable multi-display traversal.

InputFlow should not become a generic Synergy-family protocol clone. Migration docs can help users coming from Barrier, Input Leap, Deskflow, Synergy, Cursr, or Wine/MWB attempts, but the compatibility target remains PowerToys Mouse Without Borders.

Compatibility Requirements

• Preserve PowerToys Mouse Without Borders protocol compatibility.
• Keep shared security-key pairing as the default auth model.
• Keep ports 15101 for input and 15100 for clipboard unless PowerToys compatibility requires otherwise.
• Preserve current beta names and paths: mwb_client, mwb_tray, mwb-client.service, and ~/.config/mwb-client/config.ini.
• Keep Linux input injection based on /dev/uinput where available and permitted.
• Keep user-scoped systemd with config-gated startup.
• Keep trusted-LAN-only positioning; do not market or design this as internet-exposed remote access.
• Do not auto-enable or auto-start remote-control behavior at package install time.
• Do not write Windows helper behavior that stops unrelated processes, kills apps, disables security tools, or edits broad system state.

Phase 0.5: Permission, Session, And Environment Validation

Goal: prevent topology and pairing issues from being misdiagnosed when the actual failure is Wayland policy, /dev/uinput, Secret Service, clipboard manager interference, or network path.

Tasks:

• Detect session type: X11, Wayland, XWayland, unknown.
• Detect desktop/compositor when possible: GNOME, KDE Plasma, wlroots-derived, unknown.
• Verify /dev/uinput exists, permissions are usable, and the current user/session can open it.
• Detect whether the uinput module appears loaded or loadable.
• Detect Secret Service availability and whether the configured secret can be resolved without exposing the key.
• Detect clipboard backend/helper availability and likely clipboard-manager activity where possible.
• Detect active network interface, Wi-Fi versus wired where possible, configured host reachability, and latency hint.
• Surface all of this in mwb_client doctor, the controller health check, and the diagnostics bundle.

Acceptance criteria:

• mwb_client doctor --config PATH --state PATH reports session, compositor, uinput, Secret Service, clipboard helper, service state, host reachability, and network hints in script-friendly lines.
• Diagnostics bundle includes a machine-readable summary.json with these fields.
• The UI health check shows actionable warnings instead of raw failures.
• No secret value is printed or archived.

Phase 1: Supportability Baseline

Goal: make beta reports actionable without hand-copying logs.

Tasks:

• Keep the one-click diagnostics bundle from PR Harden beta setup, diagnostics, and packaging #9.
• Add or update issue templates to request distro, desktop session, compositor, Windows version, PowerToys version, monitor layout, clipboard mode, and diagnostics bundle.
• Include a trust-boundary warning in release notes: trusted LAN only.
• Add known-good integration notes for a specific PowerToys MWB version once tested.

Acceptance criteria:

• A user can attach one diagnostics archive and answer a short issue template instead of pasting terminal output.
• The archive includes redacted config, state, service logs, doctor output, session info, monitor summary, and health summary JSON.

Phase 2: Screen Topology And Wrap Model

Goal: solve the multi-monitor pain users report in Barrier/Input Leap/Deskflow/Synergy-style tools.

Design direction:

• Model machines and individual displays separately.
• Store topology as directed border links between displays, not just relative machine rectangles.
• Keep canvas placement as UI, but resolve runtime behavior through explicit edge-link mappings.
• Define deterministic anchoring for monitor hotplug and resolution changes, likely primary-display top-left plus stable display identifiers where available.

Required layouts/tests:

• AAB
• BAA
• ABA
• BAB
• stacked displays
• asymmetric resolutions
• partial edge overlaps
• wrap off/on
• horizontal wrap
• vertical wrap
• both-direction wrap
• modifier preservation across transitions
• mouse button/drag preservation across transitions
• hotplug/re-anchor behavior
• high-polling-rate or rapid edge-crossing behavior

Acceptance criteria:

• Topology validation rejects impossible or ambiguous layouts before save.
• Runtime transition code preserves key/button down state across handoff.
• Tests cover named fixtures for the layouts above.
• Existing absolute cursor movement and reconnect behavior do not regress.

Phase 3: Topology Dry-Run CLI

Goal: let power users and maintainers debug topology before starting the service.

Tasks:

• Add a command that loads config/topology and prints calculated cursor handoff paths for sample movements.
• Include edge name, source display, target display/machine, input coordinate, output coordinate, and wrap decision.
• Provide JSON output mode for tests and diagnostics.

Acceptance criteria:

• Maintainers can reproduce an edge traversal bug from a diagnostics bundle without needing the user’s monitors.
• Topology tests can reuse the dry-run path calculations.

Phase 4: Layout Wizard

Goal: make multi-display setup visible and hard to misconfigure.

Tasks:

• Show Linux and Windows machines as groups of display rectangles.
• Provide presets for side-by-side, stacked, 2x2, AAB, BAA, ABA, and BAB patterns.
• Include a reverse/swap option for common left/right mental-model mistakes.
• Let users adjust edge ratios for asymmetric display sizes.
• Preview wrap and dead zones before enabling service.
• Warn early when a chosen layout cannot be represented safely in the current MWB-compatible path.

Acceptance criteria:

• Wizard writes only validated topology/config.
• Wizard can launch health check and topology dry-run from the final screen.
• User can export the same validated layout into the Windows helper path.

Phase 5: Safe Windows Helper Expansion

Goal: seed or verify PowerToys MWB settings without invasive Windows behavior.

Tasks:

• Add --dry-run mode showing exact planned changes.
• Add --check mode that validates current Windows MWB settings against desired Linux peer/topology.
• Back up the full PowerToys MWB settings file before writing.
• Add a simple restore path, preferably copy-back instructions or a generated restore command.
• Validate schema/version before writing; fail closed if unknown.
• Show before/after diffs for settings changes.
• Keep helper idempotent.

Hard constraints:

• No taskkill.
• No stopping services.
• No disabling VPNs, endpoint security, UPS tools, browsers, or unrelated software.
• No broad registry/system changes.

Acceptance criteria:

• Running helper twice is safe.
• Unknown schema causes a clear error and leaves the original settings untouched.
• Backup and restore path are printed every time the helper writes.

Phase 6: Migration And Positioning Docs

Goal: reduce confusion for users coming from other tools.

Docs to add:

• Coming from Barrier/Input Leap/Deskflow/Synergy/Cursr.
• Wine/MWB attempts versus native InputFlow.
• Server/client terms versus InputFlow peer/machine/display terms.
• Why InputFlow is MWB-compatible, not Synergy-protocol compatible.
• What carries over: edge switching, clipboard expectations, LAN use.
• What does not carry over: Synergy protocol compatibility, generic cloud/account model, internet remote access.

Acceptance criteria:

• Docs distinguish verified facts from product positioning.
• Any claims about competitor maintenance/status are checked against current primary sources before release.

Research Prompt

Research current public evidence before implementing or documenting competitor comparisons.

Questions:

• What does current PowerToys Mouse Without Borders support and document around layout, wrap, clipboard, file transfer, same-subnet mode, service mode, pairing, and settings storage?
• What are the current architecture and maintenance states of Barrier, Input Leap, Deskflow, Synergy, and Cursr?
• Which tools support Linux plus Windows today?
• Which tools model displays individually versus whole-machine rectangles?
• Which tools support bidirectional wrap, loops, or explicit border links?
• What common multi-monitor layouts fail in public reports?
• What common setup or installer behaviors users find unsafe or invasive?
• What clipboard limitations and conflicts are reported?
• What security models are used: shared key, TLS/certs, account/cloud, unauthenticated LAN?
• What does Linux input injection require across X11, Wayland, GNOME, KDE, and wlroots environments?

Deliverables:

• Dated evidence table with links to primary sources.
• Ranked feature candidates with implementation risk.
• Topology requirements document for AAB, BAA, ABA, BAB, stacked, asymmetric, and wrap cases.
• Compatibility risk assessment for protocol, encryption, clipboard, input mapping, and Windows helper changes.

Shipping Gates

• Do not ship topology changes without handoff regression tests.
• Do not ship Windows helper writes without backup, dry-run, schema validation, and restore path.
• Do not broaden the service startup behavior beyond explicit user opt-in.
• Do not claim universal Wayland support; report compositor/session constraints clearly.
• Do not publish competitor state claims without fresh primary-source verification.