AGENTS.md

1# RustDesk Guide
2 
3## Project Layout
4 
5### Directory Structure
6* `src/` Rust app
7* `src/server/` audio / clipboard / input / video / network
8* `src/platform/` platform-specific code
9* `src/ui/` legacy Sciter UI (deprecated)
10* `flutter/` current UI
11* `libs/hbb_common/` config / proto / shared utils
12* `libs/scrap/` screen capture
13* `libs/enigo/` input control
14* `libs/clipboard/` clipboard
15* `libs/hbb_common/src/config.rs` all options
16 
17### Key Components
18- **Remote Desktop Protocol**: Custom protocol implemented in `src/rendezvous_mediator.rs` for communicating with rustdesk-server
19- **Screen Capture**: Platform-specific screen capture in `libs/scrap/`
20- **Input Handling**: Cross-platform input simulation in `libs/enigo/`
21- **Audio/Video Services**: Real-time audio/video streaming in `src/server/`
22- **File Transfer**: Secure file transfer implementation in `libs/hbb_common/`
23 
24### UI Architecture
25- **Legacy UI**: Sciter-based (deprecated) - files in `src/ui/`
26- **Modern UI**: Flutter-based - files in `flutter/`
27  - Desktop: `flutter/lib/desktop/`
28  - Mobile: `flutter/lib/mobile/`
29  - Shared: `flutter/lib/common/` and `flutter/lib/models/`
30 
31## Rust Rules
32 
33* Avoid `unwrap()` / `expect()` in production code.
34* Exceptions:
35 
36  * tests;
37  * lock acquisition where failure means poisoning, not normal control flow.
38* Otherwise prefer `Result` + `?` or explicit handling.
39* Do not ignore errors silently.
40* Avoid unnecessary `.clone()`.
41* Prefer borrowing when practical.
42* Do not add dependencies unless needed.
43* Keep code simple and idiomatic.
44 
45## Tokio Rules
46 
47* Assume a Tokio runtime already exists.
48* Never create nested runtimes.
49* Never call `Runtime::block_on()` inside Tokio / async code.
50* Do not hide runtime creation inside helpers or libraries.
51* Do not hold locks across `.await`.
52* Prefer `.await`, `tokio::spawn`, channels.
53* Use `spawn_blocking` or dedicated threads for blocking work.
54* Do not use `std::thread::sleep()` in async code.
55 
56## Editing Hygiene
57 
58* Change only what is required.
59* Prefer the smallest valid diff.
60* Do not refactor unrelated code.
61* Do not make formatting-only changes.
62* Keep naming/style consistent with nearby code.
63 
64### Comments
65 
66* Keep them short: one line by default, three at most.
67* Say **why**, never what. If the code already says it, delete the comment.
68* A comment must never be longer than the code it describes.
69* Applies to YAML, shell and Python too, not just Rust.
70 
71### Be minimally invasive
72 
73* Prefer purely additive changes: layer new (`#[cfg]`-gated) blocks or new functions around existing code instead of restructuring it. The ideal diff for a fix adds lines and modifies/deletes none.
74* Do not extract or reshape existing code just to enable your new code; look for a mechanism that leaves existing lines untouched (e.g. hide/show an existing object instead of refactoring its construction into a helper for rebuilding).
75* Put new logic in self-contained functions in the module it belongs to (platform-specific logic in `src/platform/`, with `use` inside the function body to avoid churning shared import blocks). Call sites in shared files (`src/tray.rs`, `src/core_main.rs`, `src/server/connection.rs`, …) should be thin one-line hooks.
76 
77## Localization (`src/lang/*.rs`)
78 
79Each file is a `HashMap<key, translation>`. Layout:
80 
81* `template.rs` is the master list of every key. **Never edit it** as part of translation work.
82* `en.rs` holds only the keys whose English display text differs from the key itself.
83* Every other file (`de.rs`, `fr.rs`, …) carries the full key set; an untranslated entry has an empty value: `("key", "")`.
84 
85### Finding the English source for a key
86 
87When filling an empty entry, determine the source English text with this rule:
88 
89* If `key` exists in `en.rs` **with a non-empty value**, that value is the source text (look it up in `en.rs`).
90* Otherwise the **key string itself is the source text** (the key is already plain English).
91 
92Then translate that source into the file's target language (infer the language from the file's existing non-empty entries / filename).
93 
94### Translation hygiene
95 
96* Only fill empty values. Never change keys, and never touch existing non-empty translations.
97* Preserve placeholders (`{}`) and escape sequences (`\n`, `\"`) exactly as in the source.
98* Do not translate brand or technical tokens: `RustDesk`, `Socks5`, `TLS`, `UAC`, `Wayland`, `X11`, `TCP`, `UDP`, `2FA`, `RDP`, `D3D`, etc.
99* Copy URL values (e.g. `doc_*` keys) verbatim from `en.rs`.
100 
101### Adding new keys (feature work)
102 
103* New English-text keys use sentence case, not Title Case: `Use ID whitelisting`, **not** `Use ID Whitelisting`. Acronyms (ID, IP, 2FA…) stay uppercase. Legacy Title-Case keys (e.g. `Use IP Whitelisting`) stay as-is — do not rename them.
104* Since the key itself is the English display text, a sentence-case key usually needs **no** `en.rs` entry; add one only when the display text must differ from the key (e.g. `*_tip` keys).
105* Append each new key to `template.rs` (with `""`) and to every `src/lang/*.rs` file (translated, or `""` if unsure), at the end of the list.
106