# Lesavka

<p align="center">
  <img src="client/assets/icons/hicolor/1024x1024/apps/lesavka.png" alt="Lesavka icon" width="220" />
</p>

Lesavka is a remote-control and remote-presence client/server pair built to make a far-away desktop feel as direct and usable as possible. It combines live eye-feed previews, input routing, device staging, capture power control, clipboard send, and operator-focused observability in one launcher.

## What Lesavka Can Do
- Launch and control a live remote relay session from a local desktop app
- Preview the left and right remote eye feeds inline or in broken-out windows
- Stage the local camera, microphone, speaker, keyboard, and mouse before connecting
- Route keyboard and mouse ownership between local and remote on demand
- Send clipboard text into the remote session
- Control relay GPIO/capture power from the launcher
- Show local and remote build versions so we know which code is running on each side
- Install cleanly through idempotent client/server install scripts

## Current Capabilities
- KDE launcher integration for the local client install
- Session console with copy and breakout support
- Adjustable per-eye server-side capture controls for resolution, fps, and bitrate
- Adjustable breakout sizing for each eye feed with standard client-side display profiles
- Automatic redocking of broken-out eye windows when the relay disconnects
- Modifier-aware keyboard relay that now supports `Shift+a -> A`
- Client and server semver visible in the launcher

## Install / Update

### Local Client
```bash
cd /home/brad/Development/lesavka
git pull --ff-only
sudo LESAVKA_REF=master ./scripts/install/client.sh
```

### Server (`theia`)
```bash
ssh theia 'cd /var/src/lesavka && git pull --ff-only && sudo LESAVKA_REF=master ./scripts/install/server.sh'
```

These install scripts are intended to be the trusted, repeatable delivery path. They pull the requested ref, ensure the environment is ready, build the correct binaries, install them into sensible system paths, and refresh the launched application or service.

## Capture / Display Profiles
- Each eye now has separate server-side capture controls for `resolution`, `fps`, and `bitrate`.
- `Source` resolution keeps the HDMI device's own H.264 stream and asks the server to pace it. That is the lowest-overhead path, but its keyframe cadence comes from the capture hardware.
- Standard capture resolutions such as `360p`, `540p`, `720p`, `900p`, and `1080p` force the server to re-encode the eye feed. Once you choose one of those, fps and bitrate become explicit knobs instead of being hidden inside a single preset.
- Breakout display profiles use standard client-side sizes plus `Source Size` and `Display Size`, so the popout window size is explicit instead of implied.

## Versioning
- Lesavka uses semver: `<major>.<minor>.<patch>`.
- Bump `patch` for bug fixes, stability work, profile tuning, and install-script fixes that should not change the operator workflow.
- Bump `minor` for new user-visible features, diagnostics, launcher controls, or protocol additions that remain backward-compatible when client and server are updated together.
- Bump `major` for breaking changes to protocol, install behavior, or operator workflows that require a deliberate upgrade step.

## Operator Workflow
1. Install or update the client and server through the install scripts.
2. Launch `Lesavka` from the KDE application launcher or run `lesavka`.
3. Stage the local devices you want the next relay session to inherit.
4. Connect the relay and confirm the eye previews come online.
5. Route inputs to the remote when you are ready to drive the far-side machine.
6. Use the session console and diagnostics tools to understand what the session is doing.

## Roadmap

### Highest-Impact Next Steps
- Add a real diagnostics panel with breakout/copy support
- Show stream health metrics such as fps, dropped frames, RTT, jitter, and packet loss
- Improve client decoder selection so preview and breakout paths prefer hardware acceleration when possible
- Surface server adaptive-stream stats directly in the launcher

### After That
- Add adaptive bitrate and resolution controls
- Add synthetic motion/input test scenes for objective latency and smoothness measurement
- Add artifact-quality scoring for controlled test patterns
- Keep tightening the “feels local” experience for typing, motion, and conference-style usage

## Philosophy
Lesavka is meant to be practical. The goal is not just to establish a remote session, but to make that session reliable, measurable, and comfortable enough for important real-world work.
