Contribute

1. Specification Comes First

• The specification must be read and understood before making changes.
• All work must align with the documented behavior and priorities.
• If implementation and spec conflict, the specification takes precedence.

2. Technology & Architecture Constraints

• The project aims to be TypeScript-only.

• Minimize system-level dependencies:

  • Do not assume OS utilities, background services, or preinstalled binaries.

• Prefer Node-based libraries over low-level or native implementations.

• Avoid unnecessary abstractions and complexity.

Current stack:

• TanStack Start
• Tailwind CSS
• WebSockets
• Nut.js (subject to change)

4. Core Functionality Priority

The following must be implemented and verified before UI polish or optional features:

• Cursor movement
• Mouse clicks
• Scrolling
• Keyboard input

5. Input Injection

5.1 Cursor Position & Indication (High Priority)

• On some systems (notably Wayland), the visible cursor position may not sync.

• Required actions:

  • Investigate methods to sync the actual cursor position.
  • If syncing is not possible, design an alternative cursor indicator.

If absolutely no good options found for node we may resort to ydotool or python.

5.2 Nut.js Evaluation

• Nut.js is currently used, but alternatives should be evaluated.

• Preferred solutions:

  • Work across operating systems
  • Avoid heavy system dependencies
  • Keep complexity low

• Known Nut.js limitations:

  • Cursor desync on Wayland
  • No native virtual gamepad support

5.3 Virtual Input Devices (If Available)

• Libraries providing the following are acceptable alternatives:

  • Virtual keyboard devices
  • Virtual mouse / trackpad devices
  • Virtual gamepad devices

6. Keyboard Input & Keymaps

6.1 System Keyboard Input

• Keyboard input must use the client device’s system keyboard.

• Known issue:

  • Multi-character input (glide typing, voice input) is inconsistent.

• Improving this behavior is encouraged.

6.2 Missing Keymaps (Required)

• Several key mappings are currently missing or incomplete.

• The following must be implemented or verified across platforms:

  • Modifier keys:

    • Ctrl
    • Shift
    • Alt
    • Meta / Windows
    • Fn (where supported)

  • Navigation keys:

    • Arrow keys
    • Home / End
    • Page Up / Page Down

  • Editing keys:

    • Backspace
    • Delete
    • Insert

  • System & utility keys:

    • Tab
    • Escape
    • Function keys (F1–F12)
    • Media keys (play, pause, volume, mute)

• Platform-specific behavior or limitations must be documented.

7. LAN Addressing & mDNS

• The server’s LAN IP may change across sessions.

• To avoid repeated rescanning or reconfiguration:

  • Support mDNS / local hostname resolution (e.g. device.local) if feasible.

• Preferred characteristics:

  • Zero or minimal configuration for the user.
  • Works within a local network.

• If mDNS is not viable on a platform:

  • The limitation must be documented.
  • A fallback approach should be described.

8. Testing Expectations

• Test across:

  • Multiple operating systems
  • Different display protocols (X11, Wayland, etc.)

• Platform-specific limitations must be documented.

9. Autonomy & Decision-Making

• Changes may be made based on intuition when:

  • The specification is silent
  • The change improves usability, stability, or maintainability

• Such changes must:

  • Be documented
  • Be justified in the pull request
  • Respect core principles and constraints

---

10. PRs

• Every pull request must include:

  • A concise summary of changes
  • Justification for design decisions or deviations
  • Notes on platform-specific behavior

• Documentation improvements and video tutorials are encouraged.

---

11. Reference Projects utilizing virtual devices

Useful references for design and input handling:

• https://github.com/Unrud/remote-touchpad
• https://github.com/kitswas/VirtualGamePad