Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,9 +38,9 @@ Some things can't be tested in CI: applying layouts, switching audio, and talkin

### Conventions

- Use the shared UI vocabulary in `src/ui.rs` (type ramp, spacing, theme brushes, page, section and card builders) instead of raw sizes and colours.
- Use the shared UI vocabulary in `src/gui/ui.rs` (type ramp, spacing, theme brushes, page, section and card builders) instead of raw sizes and colours.
- Don't put tooltips inside a `ContentDialog`: the pinned Reactor closes the window. See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md#winui-rules-worth-knowing).
- Device and settings changes take `windows_audio::OperationLock`, run off the UI thread, verify by reading back, and restore what they changed on failure.
- Device and settings changes take `audio::windows_audio::OperationLock`, run off the UI thread, verify by reading back, and restore what they changed on failure.
- Talk to Windows and TVs directly rather than through helper programs. New dependencies need a reason, and their licenses must be accepted in `packaging/about.toml`; regenerate `THIRD_PARTY_LICENSES.md` when they change.

By contributing, you agree that your contribution is licensed under the [MIT License](LICENSE).
29 changes: 16 additions & 13 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,32 +7,35 @@ Director is one Rust executable, `director.exe`. Started without arguments it op
| Part | Where | What it holds |
| --- | --- | --- |
| Library crate `director` | `src/lib.rs` | Domain models, persistence, the scene and device engines, Windows and TV backends, the CLI |
| Binary | `src/main.rs` and `src/*_ui.rs` | The `DirectorApp` WinUI component (through `windows-reactor` 0.100), pages and dialogs |
| Binary | `src/main.rs` and `src/gui/` | The `DirectorApp` WinUI component (through `windows-reactor` 0.100), its pages and dialogs, and the shared UI vocabulary in `gui/ui.rs` |
| Build script | `build.rs`, `packaging/windows_icon.rs` | Renders `assets/director.svg` into the embedded icon and `director.ico`, embeds `packaging/director.manifest`, stages SVG assets beside the executable |
| Installer | `installer/`, `scripts/package-msi.ps1` | WiX MSI plus a `setup.exe` bundle that installs the Windows App Runtime when missing; see [Windows GUI](INSTALL.md) |
| Installer | `installer/`, `scripts/package-msi.ps1` | WiX MSI plus a `setup.exe` bundle that installs the Windows App Runtime when missing; see [Development](DEVELOPMENT.md#installer) |

## Integration policy

Director talks to Windows and to TVs directly: Win32 and WinRT APIs, Core Audio, the display-configuration (CCD) API, NVIDIA's driver interface, the RTSS shared interface, and each TV's local network protocol. It does not shell out to helper tools such as NirCmd, display-switching utilities or TV CLIs. Launching apps and opening URIs are user-chosen scene actions, not implementation shortcuts.

## Domain modules
## Library modules

| Area | Modules | Notes |
Each folder groups one area; Windows-specific code sits in the `windows_*` module beside the platform-neutral model it implements.

| Folder | Modules | Notes |
| --- | --- | --- |
| Scenes | `scenes`, `scene_session`, `starter`, `windows_scenes` | A scene references a display preset and a TV by ID and holds its own Sound, FPS and action steps. `windows_scenes` runs the ordered transaction: Before → TV → Displays → Sound → FPS → After, with When leaving steps and an optional Return scene. See [Scenes](SCENES.md). |
| Displays | `displays`, `display_apply`, `display_editor`, `display_capabilities`, `display_detection`, `display_mirroring`, `windows_displays`, `windows_display_apply`, `windows_display_modes`, `windows_display_detection`, `windows_hdr` | Capture and apply layouts through CCD with strict readback and an exact restore. `windows_hdr` defines the HDR requests missing from the `windows` bindings. See [Displays](DISPLAYS.md). |
| Sound | `audio`, `audio_control`, `audio_devices`, `windows_audio` | `audio::apply` is the multi-step transaction a scene's Sound step uses; `audio_control` makes one live change at a time for Now and `director audio`. Both sit on one `AudioBackend` (default roles, volume, mute). `audio_devices` remembers endpoints seen before. See [Sound](SOUND.md). |
| TVs | `tvs`, `tv_setup`, `tv_control`, `tv_network`, `tv_input_guard`, `tv_report`, `windows_tv` | Saved TV definitions, the setup guide's state, a brand-neutral control trait, Wake-on-LAN, input protection and compatibility reports. `windows_tv` dispatches by brand. See [TVs](TVS.md). |
| TV brands | `lg_protocol` + `windows_lg`, `samsung` + `windows_samsung`, `android_tv` + `windows_android_tv` | LG webOS and Samsung Tizen over WinHTTP WebSockets; Android TV Remote v2 over in-process TLS (`rustls`) with a per-TV client certificate. |
| FPS | `fps`, `windows_fps` | Global NVIDIA or RTSS frame-rate limit with snapshot, readback and restore. See [FPS](FPS.md). |
| CLI | `cli`, `cli_list`, `cli_name`, `audio_cli`, `display_cli`, `tv_cli` | Argument parsing and output. CLI names are derived from item names, never stored. |
| App services | `storage`, `preferences`, `backup`, `diagnostics`, `crash`, `notifications`, `windows_close` | Settings files, preferences, backup and restore, logs, crash reports, Windows notifications and close protection. See [Diagnostics](TROUBLESHOOTING.md). |
| `src/scene/` | `scenes`, `scene_session`, `starter`, `windows_scenes` | A scene references a display preset and a TV by ID and holds its own Sound, FPS and action steps. `windows_scenes` runs the ordered transaction: Before → TV → Displays → Sound → FPS → After, with When leaving steps and an optional Return scene. See [Scenes](SCENES.md). |
| `src/display/` | `displays`, `display_apply`, `display_editor`, `display_capabilities`, `display_detection`, `display_mirroring`, `display_cli`, `windows_displays`, `windows_display_apply`, `windows_display_modes`, `windows_display_detection`, `windows_hdr` | Capture and apply layouts through CCD with strict readback and an exact restore. `windows_hdr` defines the HDR requests missing from the `windows` bindings. See [Displays](DISPLAYS.md). |
| `src/audio/` | `mod.rs` (`audio::apply`), `audio_control`, `audio_devices`, `audio_cli`, `windows_audio` | `audio::apply` is the multi-step transaction a scene's Sound step uses; `audio_control` makes one live change at a time for Now and `director audio`. Both sit on one `AudioBackend` (default roles, volume, mute). `audio_devices` remembers endpoints seen before. `windows_audio` also holds the cross-process `OperationLock`. See [Sound](SOUND.md). |
| `src/tv/` | `tvs`, `tv_setup`, `tv_control`, `tv_network`, `tv_input_guard`, `tv_report`, `tv_cli`, `windows_tv`, and per brand `lg_protocol` + `windows_lg`, `samsung` + `windows_samsung`, `android_tv` + `windows_android_tv` | Saved TV definitions, the setup guide's state, a brand-neutral control trait, Wake-on-LAN, input protection and compatibility reports. `windows_tv` dispatches by brand. LG and Samsung run over WinHTTP WebSockets; Android TV Remote v2 over in-process TLS (`rustls`) with a per-TV client certificate. See [TVs](TVS.md). |
| `src/fps/` | `mod.rs`, `windows_fps` | Global NVIDIA or RTSS frame-rate limit with snapshot, readback and restore. See [FPS](FPS.md). |
| `src/cli/` | `mod.rs`, `cli_list`, `cli_name` | Argument parsing, `director list` and CLI names, which are derived from item names and never stored. Each area's commands live in its folder (`audio_cli`, `display_cli`, `tv_cli`). |
| `src/` | `storage`, `preferences`, `backup`, `diagnostics`, `crash`, `notifications`, `windows_close` | Settings files, preferences, backup and restore, logs, crash reports, Windows notifications and close protection. See [Troubleshooting](TROUBLESHOOTING.md). |

The window lives in `src/gui/`: one module per page or dialog (`scene_ui`, `scene_editor_ui`, `now_ui`, `display_ui`, `tv_ui`, `options_ui` and others), `editor_flow` for the jumps between pages, and `ui` for the shared layout and theme helpers.

## Threading and locking

WinUI owns the UI thread. Device, network and file work runs in background jobs started with `work(cx, closure)`; each returns plain Rust data as a `Message` to the component's update loop. COM objects never cross threads, and UI callbacks never block, sleep or wait on a worker.

Every device change and every settings write holds `windows_audio::OperationLock`, a named mutex shared by all Director processes, so the window and a CLI scene can't change devices at the same time. While work is pending, a window subclass (`close_guard`) defers normal closing. Native calls can't be cancelled safely, so cancellation is cooperative and recovery from a forced kill is not attempted.
Every device change and every settings write holds `audio::windows_audio::OperationLock`, a named mutex shared by all Director processes, so the window and a CLI scene can't change devices at the same time. While work is pending, a window subclass (`close_guard`) defers normal closing. Native calls can't be cancelled safely, so cancellation is cooperative and recovery from a forced kill is not attempted.

## Transactions and recovery

Expand Down
4 changes: 2 additions & 2 deletions docs/DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Director uses genuine WinUI 3 controls through Microsoft Windows Reactor and fol

## Design system

Every page is built from `src/ui.rs`, so pages line up and follow the theme:
Every page is built from `src/gui/ui.rs`, so pages line up and follow the theme:

- **Type ramp** (Fluent): caption 12, body 14, label 14 semibold, section subtitle 20 semibold, page title 28 semibold. Secondary text uses one opacity (0.72).
- **Spacing** 8/12/16/32 and **radii** 4 (inner panels, controls) and 8 (cards). Page padding and pane widths are constants that width calculations reuse.
Expand Down Expand Up @@ -35,7 +35,7 @@ Scene cards show the scene's main change at the top: the layout miniature when i

The scene editor is a vertical flow of fixed-size step cards in run order (Before, Prepare TV, Displays, Sound, FPS limit, After) joined by small arrows, with When leaving and Return set apart below. A card shows an icon, the title and a one-line summary, with a pencil and a bin. The card opens the step's controls in a dialog: Done keeps the changes and Cancel restores the step. Nothing in the flow expands, and the column has a fixed width (720 DIP, less in a narrow window), so the overview never changes size. Empty steps are dashed outlines of the same size with a hint and an Add button. Failure policy and the device wait live in Options, not in the scene. See [Scenes](SCENES.md).

**No tooltips in dialogs.** The pinned Reactor rejects tooltips inside a ContentDialog and closes the window. Controls in dialogs get an automation name instead, and `scene_editor_ui::tests::dialog_content_has_no_tooltips` guards the step dialogs and the shared helpers they use.
**No tooltips in dialogs.** The pinned Reactor rejects tooltips inside a ContentDialog and closes the window. Controls in dialogs get an automation name instead, and `gui::scene_editor_ui::tests::dialog_content_has_no_tooltips` guards the step dialogs and the shared helpers they use.

## Now

Expand Down
6 changes: 3 additions & 3 deletions docs/DEVELOPMENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,14 +72,14 @@ Back up that folder before running the app against your real settings for testin
- **Unit tests** use fake backends for audio, displays, FPS and scenes, and cover no-op detection, partial failure and recovery, stale writes, and corrupt or unknown-version files.
- **TV transport tests** run against loopback WebSocket and TLS servers in the test process, plus DPAPI tampering checks. They never contact a real TV, so they don't prove compatibility with a particular model.
- **Wake-on-LAN tests** send magic packets only to a loopback receiver.
- **Ignored tests** (`cargo test -- --ignored <name>`) open preview fixtures with in-memory data for visual checks: `preset_cards_preview::cards_fixture`, `fps_ui::fps_fixture`, `tv_ui::native_preview::guide_fixture` and `tv_controls_ui::native_preview::controls_fixture`. They save nothing and contact no device. Some write their state to `target\preview\` for inspection. Production builds have no fixture entry point.
- `windows_samsung::samsung_tls_fixture` needs a hand-started local TLS server and is meant for manual runs only.
- **Ignored tests** (`cargo test -- --ignored <name>`) open preview fixtures with in-memory data for visual checks: `gui::preset_cards_preview::cards_fixture`, `gui::fps_ui::fps_fixture`, `gui::tv_ui::native_preview::guide_fixture` and `gui::tv_controls_ui::native_preview::controls_fixture`. They save nothing and contact no device. Some write their state to `target\preview\` for inspection. Production builds have no fixture entry point.
- `tv::windows_samsung::samsung_tls_fixture` needs a hand-started local TLS server and is meant for manual runs only.

Real hardware checks (applying layouts, switching audio, waking a TV) can't run in CI. Run them by hand, and keep them separate from what automated tests prove.

## WinUI rules worth knowing

- **No tooltips inside a ContentDialog.** The pinned Reactor rejects them with `StructureUnsupported` and closes the window. Give controls in dialogs an automation name instead. `scene_editor_ui::tests::dialog_content_has_no_tooltips` scans the step dialogs, the FPS controls, the relink button, the crash dialog, the command dialog and a checked list of shared helpers; extend it when a dialog hosts something new. Dialogs use `layout_preview_in_dialog` for the same reason.
- **No tooltips inside a ContentDialog.** The pinned Reactor rejects them with `StructureUnsupported` and closes the window. Give controls in dialogs an automation name instead. `gui::scene_editor_ui::tests::dialog_content_has_no_tooltips` scans the step dialogs, the FPS controls, the relink button, the crash dialog, the command dialog and a checked list of shared helpers; extend it when a dialog hosts something new. Dialogs use `layout_preview_in_dialog` for the same reason.
- WinUI controls fire change events when re-rendered with a new value (sliders, combo boxes). Guard handlers so a re-render isn't treated as an edit.
- UI automation: query an open ComboBox's own descendants with a name/type condition rather than walking the whole window; an unrestricted `FindAll` against an open dropdown can stall the provider.
- For screenshots, bring the window to the front and let a frame render first. An occluded window can capture blank.
Expand Down
6 changes: 3 additions & 3 deletions src/audio_cli.rs → src/audio/audio_cli.rs
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
//! `director audio …`: live control of Windows audio devices. Saved sound belongs to scenes
//! (their Sound step); these commands change one thing right away.
use crate::{
audio::audio_control::{self, Level, MuteChange},
audio::windows_audio::{OperationLock, WindowsAudio},
audio::{AudioBackend, Output, Role},
audio_control::{self, Level, MuteChange},
windows_audio::{OperationLock, WindowsAudio},
};

const USAGE: &str = "Use: director audio list | outputs | inputs | status | check
Expand Down Expand Up @@ -114,7 +114,7 @@ fn describe(device: &Output) -> String {
format!(
"{} ({}) · {}{}",
device.name,
crate::cli_name::cli_name(&device.name),
crate::cli::cli_name::cli_name(&device.name),
device
.volume_percent
.map_or("volume unknown".into(), |v| format!("{v}%")),
Expand Down
2 changes: 1 addition & 1 deletion src/audio_control.rs → src/audio/audio_control.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
//! confirm it. Scenes use `audio::apply`, which changes several things as one transaction.
use crate::{
audio::{AudioBackend, DEFAULT_ROLES, Output, Result, Role},
cli_name::cli_name,
cli::cli_name::cli_name,
};

/// A volume change: an absolute percentage, or a step up or down from the current level.
Expand Down
File renamed without changes.
7 changes: 7 additions & 0 deletions src/audio.rs → src/audio/mod.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,11 @@
//! Device-independent audio transaction logic. GUI and COM types do not belong here.
#[cfg(windows)]
pub mod audio_cli;
pub mod audio_control;
#[cfg(windows)]
pub(crate) mod audio_devices;
#[cfg(windows)]
pub mod windows_audio;
use serde::Serialize;

pub type Result<T> = std::result::Result<T, String>;
Expand Down
2 changes: 1 addition & 1 deletion src/windows_audio.rs → src/audio/windows_audio.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
//! Direct Windows Core Audio access. All COM objects stay on their creating worker.
use crate::audio::audio_devices::{Identity, Inventory};
use crate::audio::{AudioBackend, Output, Result, Role};
use crate::audio_devices::{Identity, Inventory};
use std::{ffi::c_void, marker::PhantomData, rc::Rc};
use windows::{
Win32::{
Expand Down
12 changes: 6 additions & 6 deletions src/backup.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@
//! pairing keys stay on the PC.
use crate::{
audio::AudioBackend as _,
displays,
scenes::{self, SoundOutput},
windows_audio::{OperationLock, WindowsAudio},
windows_scenes,
audio::windows_audio::{OperationLock, WindowsAudio},
display::displays,
scene::scenes::{self, SoundOutput},
scene::windows_scenes,
};
use serde::{Deserialize, Serialize};
use std::{
Expand Down Expand Up @@ -145,7 +145,7 @@ pub fn preview(path: &Path) -> Result<Import, String> {
issues.push(format!("{}{} · {error}", scene.name, context));
}
}
if let Ok(live) = crate::windows_displays::capture() {
if let Ok(live) = crate::display::windows_displays::capture() {
for preset in &backup.displays {
for monitor in preset
.layout
Expand Down Expand Up @@ -261,7 +261,7 @@ mod tests {
name: "Desk".into(),
captured_at_unix_seconds: 0,
confirm_changes: false,
layout: crate::display_apply::tests::layout(0),
layout: crate::display::display_apply::tests::layout(0),
};
displays::save(&display_path, &[], std::slice::from_ref(&original)).unwrap();

Expand Down
12 changes: 7 additions & 5 deletions src/cli_list.rs → src/cli/cli_list.rs
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
//! `list` commands: every saved item and device with the CLI name that commands accept.
//! Read-only; nothing here changes a setting.
use crate::{
audio::windows_audio::WindowsAudio,
audio::{AudioBackend, Output},
cli_name::cli_name,
displays, scenes, tvs,
windows_audio::WindowsAudio,
windows_displays,
cli::cli_name::cli_name,
display::displays,
display::windows_displays,
scene::scenes,
tv::tvs,
};
use serde::Serialize;
use serde_json::{Value, json};
Expand Down Expand Up @@ -198,7 +200,7 @@ fn row(name: &str, summary: String) -> Row {
fn collect(category: Category) -> Result<(Vec<Row>, Value), String> {
match category {
Category::Scenes => {
let active = crate::scene_session::active();
let active = crate::scene::scene_session::active();
let all = scenes::load(&scenes::path()?)?;
let rows = all
.iter()
Expand Down
File renamed without changes.
Loading
Loading