diff --git a/.github/ISSUE_TEMPLATE/bug.yml b/.github/ISSUE_TEMPLATE/bug.yml new file mode 100644 index 0000000..8d51da5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug.yml @@ -0,0 +1,45 @@ +name: Bug report +description: Something in Director doesn't work as expected +labels: [bug] +body: + - type: textarea + id: what + attributes: + label: What happened? + description: What you did, what you expected, and what happened instead. + validations: + required: true + - type: textarea + id: steps + attributes: + label: Steps to reproduce + placeholder: | + 1. Open Scenes + 2. Apply "TV Gaming" + 3. ... + - type: input + id: version + attributes: + label: Director version + description: Run `director --version` or see Options → About. + placeholder: "0.12.0" + validations: + required: true + - type: input + id: windows + attributes: + label: Windows version + description: Settings → System → About, for example "Windows 11 24H2 (26100.2605)". + validations: + required: true + - type: input + id: hardware + attributes: + label: Hardware involved + description: GPU, monitors, audio devices or TV model, if the problem involves them. + - type: textarea + id: logs + attributes: + label: Log lines + description: From Options → Open logs folder. Logs contain no pairing keys, but may contain device names; trim anything you'd rather not share. + render: text diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..df66710 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,6 @@ +# Blank issues stay enabled: Director's Report on GitHub button opens issues/new with a pre-filled title and body. +blank_issues_enabled: true +contact_links: + - name: Report a security vulnerability + url: https://github.com/Xarishark/Director/security/advisories/new + about: Please report security problems privately. diff --git a/.github/ISSUE_TEMPLATE/crash.yml b/.github/ISSUE_TEMPLATE/crash.yml new file mode 100644 index 0000000..8faca59 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/crash.yml @@ -0,0 +1,34 @@ +name: Crash report +description: Director closed unexpectedly +labels: [bug, crash] +body: + - type: markdown + attributes: + value: | + Director saves crash reports in `%LOCALAPPDATA%\Director\Logs\Crashes`. Its **Report on GitHub** button opens a pre-filled issue with the summary and backtrace; this form is for reports you file by hand. + - type: textarea + id: doing + attributes: + label: What were you doing? + description: The page you were on and the last thing you clicked or ran. + validations: + required: true + - type: textarea + id: report + attributes: + label: Crash report + description: Paste the contents of the newest crash-….txt file, or attach it. + render: text + - type: input + id: version + attributes: + label: Director version + placeholder: "0.12.0" + validations: + required: true + - type: input + id: windows + attributes: + label: Windows version + validations: + required: true diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..9ad032c --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,15 @@ +## What and why + + + +## Checks + +- [ ] `cargo fmt --all -- --check` +- [ ] `cargo clippy --locked --all-targets -- -D warnings` +- [ ] `cargo test --locked -- --test-threads=1` +- [ ] Docs and README updated where behaviour changed +- [ ] `THIRD_PARTY_LICENSES.md` regenerated if dependencies changed + +## Tested by hand + + diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..42bdb2f --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,22 @@ +# Changelog + +Each release's installer and full notes are on [GitHub Releases](https://github.com/Xarishark/Director/releases). + +## 0.12.0 (2026-11-07) + +- Scenes can **Return** to another saved scene when you end them or run them again. +- The Active dot sits before the scene name, and card names use the space the buttons leave. + +## 0.11.0 (2026-11-07) + +- **Scenes overhaul**: a step-flow editor with Before, When leaving and Close app actions; the active scene and **End**; a first-run "everyday setup" scene; the TV can turn off when you leave a scene. +- **Sound**: live output, volume and mute controls on Now and in `director audio`; scenes hold their own Sound step. +- **CLI names** for every item (`director scene apply tv-gaming`), `director list`, and a `>_` button on cards that copies the command. +- **TV input protection** keeps an LG TV on the scene's input while a streaming box or console tries to take it; `director tv toggle` turns a TV on or off. +- A UI pass with a shared design system, a reworked Now page and a Windows-style display editor; preset cards preview their screens. +- Local crash reports you can file as GitHub issues; Windows 11 24H2 is now the minimum; a new app icon. + +## 0.10.0 (2026-11-05) + +- `Director-x64-setup.exe` installs the Windows App Runtime when it's missing, then Director for all users. +- Every version increase merged into `main` publishes a release with the setup. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5932612 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,46 @@ +# Contributing to Director + +Thanks for helping. Bug reports, TV compatibility reports and pull requests are all welcome. + +## Reporting a problem + +- **Crashes**: Director saves a crash report and offers **Report on GitHub** the next time it starts. That opens a pre-filled issue; attach the crash file from `%LOCALAPPDATA%\Director\Logs\Crashes` if you can. +- **Bugs**: open an issue with your Windows version, your Director version (`director --version` or **Options → About**), the steps that went wrong, and recent log lines from **Options → Open logs folder** if they help. Logs never contain pairing keys, but they can contain device names; trim anything you'd rather not share. +- **TV compatibility**: follow [Test a Samsung or TCL TV](docs/TV_TESTING.md) and attach the exported report. +- **Security issues**: please don't open a public issue; see [SECURITY.md](SECURITY.md). + +## Building + +You need Windows 11 24H2 or newer, Rust 1.95 or newer with the MSVC toolchain, and the Visual Studio C++ Build Tools. Then: + +```powershell +cargo run +``` + +[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) covers the toolchain, the tests and preview fixtures, packaging and CI. + +## Pull requests + +1. Branch from `main`: `feat/` for features, `fix/` for fixes, `docs/`, `chore/` or `refactor/` otherwise. +2. Keep each pull request to one change, and each commit to one step. Commit messages follow [Conventional Commits](https://www.conventionalcommits.org) like the existing history, for example `fix(scenes): keep the Return target after a rename`. +3. Run the same checks as CI before pushing: + + ```powershell + cargo fmt --all -- --check + cargo clippy --locked --all-targets -- -D warnings + cargo test --locked -- --test-threads=1 + ``` + +4. Update the docs in `docs/` and the README when behaviour changes, and explain design choices in the pull request description. +5. Open the pull request against `main`. The **Windows x64 build** check must pass. + +Some things can't be tested in CI: applying layouts, switching audio, and talking to a real TV. Say in the pull request what you checked by hand and on which hardware. Don't change devices on someone else's machine without asking. + +### 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. +- 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. +- 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). diff --git a/Cargo.toml b/Cargo.toml index bf05eff..82f7a17 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -6,6 +6,8 @@ rust-version = "1.95" publish = false description = "Switch displays, audio, and TVs with reusable scenes on Windows." authors = ["Xarishark • Zacharias Xenakis"] +license = "MIT" +repository = "https://github.com/Xarishark/Director" [dependencies] windows-reactor = "=0.100.0" diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..f3cdbc6 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Zacharias Xenakis + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/LICENSE.md b/LICENSE.md deleted file mode 100644 index 0fa29b2..0000000 --- a/LICENSE.md +++ /dev/null @@ -1,5 +0,0 @@ -# Director source and assets - -Director is a private project. All rights are reserved in its original source code and assets. No public license is granted. - -Third-party components remain subject to their respective licenses. diff --git a/README.md b/README.md index e7c7a0d..a1af9a7 100644 --- a/README.md +++ b/README.md @@ -1,82 +1,58 @@

Director icon

Director

Switch your monitors, sound, and TV with one scene.

-

Windows x64 · Private preview

+

Windows x64 · Preview

Download Director for Windows (x64 setup)

-

Latest release · Requires access to this private repo · All releases

+

Latest release · All releases

-Moving from your desk to the living room? A **TV Gaming** scene can wake the TV, switch your picture and sound to HDMI, cap the frame rate, and open Steam Big Picture. Use a **Desk** scene when you come back. For a quick change, open **Now** and adjust the active displays, audio, or FPS limit directly. +Moving from your desk to the living room? A **TV Gaming** scene can wake the TV, switch your picture and sound to HDMI, cap the frame rate, and open Steam Big Picture. A **Desk** scene puts everything back. Every change is checked, and if a step fails Director restores what it changed. -## Presets and scenes +

+ The Scenes page with a sound-only scene and a TV gaming scene + The Displays page with saved monitor layouts +

-Director’s sidebar has four pages, with Options at the bottom: +## What it does -- **Scenes** is where Director opens. Run a scene, or create one. -- **Now** changes what’s active right now without saving anything. Sound changes apply as you make them; display and FPS edits wait until you press **Apply changes** in the corner of the display map. Use **Save as display preset…** or **Save as scene…** to keep what you’ve set up. -- **Displays** and **TVs** hold your saved building blocks: display layouts and paired TVs. +- **Scenes** switch everything together: a display layout, sound, a TV, an FPS limit, and apps or links to run before, after or when you leave. Run one from the window, a shortcut, a script or a Stream Deck. +- **Now** changes what's active right now without saving anything: arrange and switch screens, pick the output and volume, set the FPS limit. +- **Displays** saves monitor layouts: which screens are on, their arrangement, primary, resolution, refresh rate, orientation, mirroring and HDR. +- **TVs** pairs LG webOS TVs (plus Samsung Tizen and TCL Android / Google TV as previews) to wake them, switch inputs and turn them off over your network. -A **scene** is everything you want to switch together: its display preset, its sound, its TV, an FPS limit and actions. Display presets and TVs are saved once and reused across scenes; sound is set in each scene. +## Install -| Building block | What you can save | -| --- | --- | -| **Display preset** | Which screens are enabled, how they’re arranged, which is primary, and their resolution, refresh rate, orientation, and HDR. You can extend or mirror screens. | -| **TV connection** | A paired TV, its PC input, wake settings, and optional links to its Windows display and HDMI audio. | -| **Scene** | Any combination of TV preparation, a display preset, sound (an output or the TV's sound, volume, mute, a calls device and a microphone), a global NVIDIA or RTSS FPS limit, and apps, links or "close app" steps to run before, after, or when you leave the scene. Director remembers audio devices it has seen so you can pick them while they’re offline. | +Director needs **Windows 11, version 24H2 or newer** (x64). Download **Director-x64-setup.exe** with the button above and run it; setup installs the Windows App Runtime if it's missing and adds `director` to PATH. See [Install](docs/INSTALL.md) for details, quiet installs and uninstalling. -Display preset cards show a preview of the layout. A scene card shows its main change: its screens, or for a sound-only scene its output and volume. Use the checkmark to apply a preset or scene. Saving gives you a chance to review it before applying. +## Quick start -## Install the preview +1. Open **Scenes** and choose **Save everyday scene**. It saves your current screens, sound and FPS limit as a scene called Default, so you can always switch back in one click. Nothing on your PC changes. +2. In **TVs**, add your TV and follow its pairing guide. Link its Windows display and HDMI audio output. +3. In **Displays**, create a layout for the TV. If Windows hasn't shown the TV's modes yet, use **Set up this display** to detect them. +4. In **Scenes**, choose **+**, name it **TV Gaming**, and add the TV, the TV layout, **TV's sound** and any apps. Then **Apply** it. -Director needs **Windows 11, version 24H2 or newer** (x64). Setup checks this and stops on older versions. +## Command line -1. Use the **Download for Windows** button above to get **Director-x64-setup.exe** from the latest GitHub Release. You can also get it from the **Director-Windows-x64** artifact of a successful **Windows build** run. Both require access to the private repo. -2. Run setup and click **Install**. Director installs for everyone on the PC, so Windows asks for administrator approval. If Microsoft Windows App Runtime 2.6 is missing, setup downloads it (about 125 MB) and installs it first. Leave **Create a desktop shortcut** selected if you want one. See the [installation and runtime guide](docs/WINDOWS_GUI.md). -3. Click **Launch**, or open **Director** from Start or the desktop. Setup adds Director to PATH. Open a new terminal to use the command line. - -## Set up your first TV scene - -1. The first time you open **Scenes**, save your everyday setup: **Save as my Default scene** stores your current screens, sound and FPS limit as a scene, so you can always switch back in one click. It changes nothing on your PC, and it reuses a display preset you already saved when it matches. Then create a separate display layout for the TV in **Displays**, or from the scene's Displays step. If Windows hasn’t exposed the TV’s modes yet, use **Detect options** to temporarily enable it, read its available settings, and restore your layout. -2. In **TVs**, add the TV, follow its pairing guide, and select the PC input where supported. Link its HDMI audio output so scenes can use **TV's sound**. -3. In **Scenes**, create **TV Gaming**. Select the TV and the TV display preset, and in the Sound step choose **TV's sound** with a volume if you want one. Add a frame-rate cap or an app launch if you want one. If a display preset or TV is missing, choose **New display preset…** or **Add TV…** at the bottom of that list. Director returns to the scene with it selected after you save. Apply the scene when you’re ready. - -Director runs the scene in order: **Before → TV → Displays → Sound → FPS → After.** A Before step can wait for a setup script to finish. Director waits for the selected HDMI audio device after changing displays. If a required step fails, Director stops and restores the previous Windows settings, unless you change that in Options. TV boxes and consoles often grab the TV’s input while it turns on; with TVs that report their current input, such as LG, **TV input protection** in Options keeps switching back to the scene’s input for the first seconds (10 by default) while the rest of the scene carries on. - -Director remembers the scene you applied last until you restart the PC. Applying a different scene first runs the previous scene's **When leaving** steps, for example `steam://close/bigpicture` when you leave a console scene. **End** next to the **+** button (or `director scene end`) runs the exit steps for the active scene. It appears when there is something to do on exit. With the optional **Return** step set to another scene, choosing End or running the active scene again runs its leave steps and applies that scene. Selecting a different scene goes directly there after the leave steps. A scene can also turn its TV off when you leave it: switch it on in the scene's Prepare TV step. - -LG webOS is supported through local control. Samsung Tizen and TCL Android / Google TV are hardware previews. The TV guides explain what to try on each brand and how to send a compatibility report. - -## Use Director from a terminal - -Use `director --version` or **About Director** in Options to check your installed version. - -Run a saved scene from a shortcut, script, or terminal with the window closed. Commands use each item's **CLI name**: its name in lowercase, with dashes instead of spaces and symbols, so "TV Gaming" is `tv-gaming` and needs no quotes. Each scene and preset card has a **>\_** button next to its name that shows the exact command, by CLI name or by ID, with a Copy button, ready to paste into a Stream Deck action or a shortcut. For example: +Every scene, preset, TV, screen and audio device has a CLI name: its name in lowercase with dashes, so "TV Gaming" is `tv-gaming`. The **>\_** button next to a name copies the exact command. ```powershell +director list director scene apply tv-gaming +director scene end director display apply desk-monitors -``` - -`director list` shows every scene, preset, TV, screen and audio device with its CLI name. Each area also has its own list: `scene list`, `display list`, `display screens`, `audio list` (outputs and inputs), `audio outputs`, `audio inputs` and `tv list`. Add `--json` for scripts. Two items of the same kind can't share a CLI name, so Director asks for a different name when saving one that would clash. - -Change sound right away, without a scene. Leaving out the device means the current default, and `--mic` targets the microphone: - -```powershell -director audio status -director audio use soundbar-stage-v2 director audio volume +5 -director audio mute toggle +director tv toggle living-room-tv ``` -## Logs and backups -- **View logs** in Options shows the latest scene result from the app or CLI, followed by recent log entries. If a scene stopped, look there for the failed step and whether recovery succeeded. -- **If Director closes unexpectedly**, it saves a crash report in the logs folder (`Logs\Crashes`) and offers it the next time it starts. **Report on GitHub** opens a new issue in your browser with the error filled in; nothing is sent until you submit it. **Report a problem** in Options does the same for anything else. -- **Notify when CLI scenes fail** lets Windows tell you when an unattended run stops. Click the notification to open that run in Director. -- **Export backup** saves your scenes and display presets to one local file. Backups from older versions still restore; their audio presets move into the scenes that used them. **Restore backup** previews what it will replace and flags device links to review. TV pairing keys stay on the original PC. +`director --help` lists every command. Commands run without opening the window. ## Guides -- [Display setup and detection](docs/DISPLAY_SETUP.md) · [Audio devices and relinking](docs/AUDIO.md) · [Scenes](docs/SCENES.md) -- [TV setup and pairing](docs/TVS.md) · [Samsung test guide](docs/SAMSUNG.md) · [TCL test guide](docs/ANDROID_TV.md) -- [FPS limits](docs/FPS.md) · [Diagnostics](docs/DIAGNOSTICS.md) · [Build, test, and CLI reference](docs/DEVELOPMENT.md) +- **Using Director:** [Scenes](docs/SCENES.md) · [Displays](docs/DISPLAYS.md) · [Sound](docs/SOUND.md) · [FPS limits](docs/FPS.md) · [TVs](docs/TVS.md) +- **Help:** [Install](docs/INSTALL.md) · [Troubleshooting, logs and backups](docs/TROUBLESHOOTING.md) · [Test a Samsung or TCL TV](docs/TV_TESTING.md) +- **Contributing:** [Development](docs/DEVELOPMENT.md) · [Architecture](docs/ARCHITECTURE.md) · [Interface design](docs/DESIGN.md) + +## Contributing + +Bug reports, TV compatibility reports and pull requests are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md). Report security problems privately as described in [SECURITY.md](SECURITY.md). Release notes are in [CHANGELOG.md](CHANGELOG.md). -Director uses Rust and native WinUI 3. See the [rights notice](LICENSE.md). +Director is written in Rust with a native WinUI 3 interface, and licensed under the [MIT License](LICENSE). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..fc334dd --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,21 @@ +# Security policy + +## Reporting a vulnerability + +Please report security problems privately through GitHub: open the repository's **Security** tab and choose **Report a vulnerability**. Don't open a public issue, discussion or pull request for them. + +Include what you found, the Director version, and steps or a proof of concept if you have one. You'll get an answer as soon as possible, and you'll be credited in the fix's release notes unless you'd rather not be. + +Only the [latest release](https://github.com/Xarishark/Director/releases/latest) gets security fixes. + +## What's in scope + +Director runs locally and controls devices on your home network. Areas where a bug could matter: + +- **TV credentials**: pairing keys, tokens, certificate pins and Android TV client keys, encrypted with Windows DPAPI under `%LOCALAPPDATA%\Director`. They must never appear in logs, backups, compatibility reports or CLI output. +- **TV connections**: the TLS connection and certificate checks for Android TV Remote v2, certificate pinning for LG and Samsung, and parsing anything a device on the network sends back. +- **Local data**: settings, backups and reports written to disk, and what crash reports and the **Report on GitHub** link include. +- **The installer**: `setup.exe` downloads the Windows App Runtime from Microsoft and checks its SHA-512 hash before running it. +- **The `director-run:` link handler** that the installer registers. + +Director's own design assumes a trusted home network. Problems that need an attacker who already controls the PC or the Windows account are out of scope. diff --git a/THIRD_PARTY_LICENSES.md b/THIRD_PARTY_LICENSES.md new file mode 100644 index 0000000..73ec648 --- /dev/null +++ b/THIRD_PARTY_LICENSES.md @@ -0,0 +1,2698 @@ +# Third-party licenses + +Director includes the following open-source components. Each is listed with its license text. +Generated by [cargo-about](https://github.com/EmbarkStudios/cargo-about); do not edit by hand. + +## Overview + +- MIT License (95) +- ISC License (23) +- Apache License 2.0 (2) +- BSD 3-Clause "New" or "Revised" License (1) +- Unicode License v3 (1) + +## Apache License 2.0 + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + +Licenses for support code +------------------------- + +Parts of the TLS test suite are under the Go license. This code is not included +in BoringSSL (i.e. libcrypto and libssl) when compiled, however, so +distributing code linked against BoringSSL does not trigger this license: + +Copyright (c) 2009 The Go Authors. All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + + * Redistributions of source code must retain the above copyright +notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above +copyright notice, this list of conditions and the following disclaimer +in the documentation and/or other materials provided with the +distribution. + * Neither the name of Google Inc. nor the names of its +contributors may be used to endorse or promote products derived from +this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + +BoringSSL uses the Chromium test infrastructure to run a continuous build, +trybots etc. The scripts which manage this, and the script for generating build +metadata, are under the Chromium license. Distributing code linked against +BoringSSL does not trigger this license. + +Copyright 2015 The Chromium Authors. All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + + * Redistributions of source code must retain the above copyright +notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above +copyright notice, this list of conditions and the following disclaimer +in the documentation and/or other materials provided with the +distribution. + * Neither the name of Google Inc. nor the names of its +contributors may be used to endorse or promote products derived from +this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +``` + +## Apache License 2.0 + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + +TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + +1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + +2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + +3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + +4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + +5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + +6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + +7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + +8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + +9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + +END OF TERMS AND CONDITIONS + +APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + +Copyright [yyyy] [name of copyright owner] + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +``` + +## BSD 3-Clause "New" or "Revised" License + +Used by: + +- [subtle 2.6.1](https://github.com/dalek-cryptography/subtle) + +```text +Copyright (c) 2016-2017 Isis Agora Lovecruft, Henry de Valence. All rights reserved. +Copyright (c) 2016-2024 Isis Agora Lovecruft. All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + +1. Redistributions of source code must retain the above copyright +notice, this list of conditions and the following disclaimer. + +2. Redistributions in binary form must reproduce the above copyright +notice, this list of conditions and the following disclaimer in the +documentation and/or other materials provided with the distribution. + +3. Neither the name of the copyright holder nor the names of its +contributors may be used to endorse or promote products derived from +this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS +IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A +PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED +TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR +PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF +LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING +NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +``` + +## ISC License + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text +/* Copyright (c) 2014, Intel Corporation. + * + * Permission to use, copy, modify, and/or distribute this software for any + * purpose with or without fee is hereby granted, provided that the above + * copyright notice and this permission notice appear in all copies. + * + * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES + * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF + * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY + * SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES + * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION + * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN + * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */ + +#ifndef OPENSSL_HEADER_EC_ECP_NISTZ384_H +#define OPENSSL_HEADER_EC_ECP_NISTZ384_H + +#include "../../limbs/limbs.h" + +#define P384_LIMBS (384u / LIMB_BITS) + +typedef struct { + Limb X[P384_LIMBS]; + Limb Y[P384_LIMBS]; + Limb Z[P384_LIMBS]; +} P384_POINT; + +typedef struct { + Limb X[P384_LIMBS]; + Limb Y[P384_LIMBS]; +} P384_POINT_AFFINE; + + +#endif // OPENSSL_HEADER_EC_ECP_NISTZ384_H + +``` + +## ISC License + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text +// Copyright 2015-2016 Brian Smith. +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION +// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +//! EdDSA Signatures. + +use super::ops::ELEM_LEN; +use crate::digest; + +pub mod signing; +pub mod verification; + +/// The length of an Ed25519 public key. +pub const ED25519_PUBLIC_KEY_LEN: usize = ELEM_LEN; + +pub fn eddsa_digest(signature_r: &[u8], public_key: &[u8], msg: &[u8]) -> digest::Digest { + let mut ctx = digest::Context::new(&digest::SHA512); + ctx.update(signature_r); + ctx.update(public_key); + ctx.update(msg); + ctx.finish() +} + +``` + +## ISC License + +Used by: + +- [untrusted 0.9.0](https://github.com/briansmith/untrusted) + +```text +// Copyright 2015-2016 Brian Smith. +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES +// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR +// ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +// ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +// OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +``` + +## ISC License + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text +// Copyright 2015-2022 Brian Smith. +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION +// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +use crate::limb::Limb; + +#[derive(Clone, Copy)] +#[repr(transparent)] +pub struct N0([Limb; 2]); + +impl N0 { + #[cfg(feature = "alloc")] + pub(super) const LIMBS_USED: usize = 64 / crate::limb::LIMB_BITS; + + #[inline] + pub const fn precalculated(n0: u64) -> Self { + #[cfg(target_pointer_width = "64")] + { + Self([n0, 0]) + } + + #[cfg(target_pointer_width = "32")] + { + Self([n0 as Limb, (n0 >> crate::limb::LIMB_BITS) as Limb]) + } + } +} + +``` + +## ISC License + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text +// Copyright 2015-2024 Brian Smith. +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION +// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +#[cfg(target_pointer_width = "64")] +type CompilerWord = u64; + +#[cfg(target_pointer_width = "32")] +type CompilerWord = u32; + +/// A native word that isn't secret. +/// +/// `LeakyWord` supports `as` conversions to/from native types. +/// +/// XXX: This isn't the native word size on targets where a pointer isn't the +/// same size as a native word. TODO: Fix this. +pub(crate) type LeakyWord = CompilerWord; + +``` + +## ISC License + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text +// Copyright 2015-2025 Brian Smith. +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION +// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +use crate::{bb, error}; + +#[deprecated( + note = "To be removed. Internal function not intended for external use with no promises regarding side channels." +)] +pub fn verify_slices_are_equal(a: &[u8], b: &[u8]) -> Result<(), error::Unspecified> { + bb::verify_slices_are_equal(a, b) +} + +``` + +## ISC License + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text +// Copyright 2016 Brian Smith. +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION +// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +//! Elliptic curve operations and schemes using Curve25519. + +pub mod ed25519; + +pub mod x25519; + +mod ops; +mod scalar; + +``` + +## ISC License + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text +// Copyright 2016-2024 Brian Smith. +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION +// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +use crate::error::{KeyRejected, Unspecified}; + +impl From for Unspecified { + fn from(source: untrusted::EndOfInput) -> Self { + super::erase(source) + } +} + +impl From for Unspecified { + fn from(source: core::array::TryFromSliceError) -> Self { + super::erase(source) + } +} + +impl From for Unspecified { + fn from(source: KeyRejected) -> Self { + super::erase(source) + } +} + +``` + +## ISC License + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text +// Copyright 2018 Brian Smith. +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION +// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +#[cfg(target_arch = "x86")] +pub fn shift_full_blocks( + in_out: super::overlapping::Overlapping<'_, u8>, + mut transform: impl FnMut(&[u8; BLOCK_LEN]) -> [u8; BLOCK_LEN], +) { + let (in_out, src) = in_out.into_slice_src_mut(); + let in_out_len = in_out[src.clone()].len(); + + for i in (0..in_out_len).step_by(BLOCK_LEN) { + let block = { + let input = + <&[u8; BLOCK_LEN]>::try_from(&in_out[(src.start + i)..][..BLOCK_LEN]).unwrap(); + transform(input) + }; + let output = <&mut [u8; BLOCK_LEN]>::try_from(&mut in_out[i..][..BLOCK_LEN]).unwrap(); + *output = block; + } +} + +``` + +## ISC License + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text +// Copyright 2018 Brian Smith. +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION +// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +//! Serialization and deserialization. + +#[doc(hidden)] +pub mod der; + +#[cfg(feature = "alloc")] +mod writer; + +#[cfg(feature = "alloc")] +pub(crate) mod der_writer; + +pub(crate) mod positive; + +pub use self::positive::Positive; + +#[cfg(feature = "alloc")] +pub(crate) use self::writer::TooLongError; + +``` + +## ISC License + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text +// Copyright 2019-2024 Brian Smith. +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION +// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +use super::BlockLen; + +pub(super) use self::{ + sha2_32::{block_data_order_32, State32, SHA256_BLOCK_LEN}, + sha2_64::{block_data_order_64, State64, SHA512_BLOCK_LEN}, +}; + +pub(super) const CHAINING_WORDS: usize = 8; + +#[cfg(any( + all(target_arch = "aarch64", target_endian = "little"), + all(target_arch = "arm", target_endian = "little"), + target_arch = "x86_64" +))] +#[macro_use] +mod ffi; + +pub(super) mod fallback; +mod sha2_32; +mod sha2_64; + +``` + +## ISC License + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text +// Copyright 2022 Brian Smith. +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION +// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +/// Polyfill for `Option::unwrap()` as a const fn; feature `const_option`. +/// https://github.com/rust-lang/rust/issues/67441. +/// TODO(MSRV): Replace this with `x.unwrap()`. +/// +/// `T: Copy` avoids "constant functions cannot evaluate destructors." +pub const fn unwrap_const(x: Option) -> T +where + T: Copy, +{ + if let Some(x) = x { + x + } else { + panic!("unwrap_const on `None`"); + } +} + +``` + +## ISC License + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text +// Copyright 2024 Brian Smith. +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION +// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +// TODO(MSRV 1.76): Replace with `core::ptr::from_mut`. +#[allow(dead_code)] +#[inline(always)] +pub fn from_mut(r: &mut T) -> *mut T { + r +} + +// TODO(MSRV 1.76): Replace with `core::ptr::from_ref`. +#[allow(dead_code)] +#[inline(always)] +pub const fn from_ref(r: &T) -> *const T { + r +} + +``` + +## ISC License + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text +// Copyright 2024 Brian Smith. +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION +// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +//! Integration tests for non-public APIs. + +mod bits_tests; + +``` + +## ISC License + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text +// Copyright 2024 Brian Smith. +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION +// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +//! Utilities to make dealing with slices less tediuous. + +/// Replaces the first N elements of `a` with the first N elements of `b`, where +/// N is `core::cmp::min(a.len(), b.len())`, leaving the rest unchanged. +pub fn overwrite_at_start(a: &mut [T], b: &[T]) { + a.iter_mut().zip(b).for_each(|(a, b)| { + *a = *b; + }); +} + +``` + +## ISC License + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text +// Copyright 2024 Brian Smith. +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION +// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +pub use self::{ + array::Array, + base::{IndexError, Overlapping}, + partial_block::PartialBlock, +}; + +mod array; +mod base; +mod partial_block; + +``` + +## ISC License + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text +// Copyright 2024 Brian Smith. +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION +// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +use crate::testutil; +use core::{marker::PhantomData, mem::size_of}; + +/// A ZST that can be added to any type to make the type `!Send`. +#[derive(Clone, Copy)] +pub struct NotSend(PhantomData<*mut ()>); + +impl NotSend { + pub const VALUE: Self = Self(PhantomData); +} + +#[allow(deprecated)] +const _: () = testutil::compile_time_assert_clone::(); +#[allow(deprecated)] +const _: () = testutil::compile_time_assert_copy::(); +const _: () = assert!(size_of::() == 0); + +``` + +## ISC License + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text +// Copyright 2025 Brian Smith. +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION +// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +#![cfg(all(target_arch = "aarch64", target_endian = "little"))] + +pub(in super::super) mod mont; + +``` + +## ISC License + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text +// Copyright 2025 Brian Smith. +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION +// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +#![cfg(target_arch = "x86_64")] + +pub(in super::super::super) mod mont; + +``` + +## ISC License + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text +// Copyright 2025 Brian Smith. +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION +// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +mod storage; + +pub(super) use self::storage::{AlignedStorage, LIMBS_PER_CHUNK}; + +``` + +## ISC License + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text +// Copyright 2025 Brian Smith. +// +// Permission to use, copy, modify, and/or distribute this software for any +// purpose with or without fee is hereby granted, provided that the above +// copyright notice and this permission notice appear in all copies. +// +// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +// WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +// MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +// SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +// WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION +// OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +// CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +pub(super) mod aarch64; +pub(super) mod x86_64; + +``` + +## ISC License + +Used by: + +- [ring 0.17.14](https://github.com/briansmith/ring) + +```text +Copyright 2015-2025 Brian Smith. + +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY +SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION +OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN +CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +``` + +## ISC License + +Used by: + +- [rustls-webpki 0.103.16](https://github.com/rustls/webpki) + +```text +Except as otherwise noted, this project is licensed under the following +(ISC-style) terms: + +Copyright 2015 Brian Smith. + +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHORS DISCLAIM ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR +ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +The files under third-party/chromium are licensed as described in +third-party/chromium/LICENSE. + +``` + +## MIT License + +Used by: + +- [sha2 0.10.9](https://github.com/RustCrypto/hashes) + +```text +Copyright (c) 2006-2009 Graydon Hoare +Copyright (c) 2009-2013 Mozilla Foundation +Copyright (c) 2016 Artyom Pavlov + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [cfg-if 1.0.5](https://github.com/rust-lang/cfg-if) + +```text +Copyright (c) 2014 Alex Crichton + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [base64ct 1.8.3](https://github.com/RustCrypto/formats) + +```text +Copyright (c) 2014 Steve "Sc00bz" Thomas (steve at tobtu dot com) +Copyright (c) 2021-2025 The RustCrypto Project Developers + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [num-bigint-dig 0.8.6](https://github.com/dignifiedquire/num-bigint) +- [num-bigint 0.4.8](https://github.com/rust-num/num-bigint) +- [num-integer 0.1.47](https://github.com/rust-num/num-integer) +- [num-iter 0.1.46](https://github.com/rust-num/num-iter) +- [num-traits 0.2.19](https://github.com/rust-num/num-traits) + +```text +Copyright (c) 2014 The Rust Project Developers + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [nom 7.1.3](https://github.com/Geal/nom) + +```text +Copyright (c) 2014-2019 Geoffroy Couprie + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [rustls 0.23.46](https://github.com/rustls/rustls) + +```text +Copyright (c) 2016 Joseph Birr-Pixton + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [digest 0.10.7](https://github.com/RustCrypto/traits) + +```text +Copyright (c) 2017 Artyom Pavlov + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [asn1-rs-derive 0.6.0](https://github.com/rusticata/asn1-rs.git) +- [asn1-rs 0.7.2](https://github.com/rusticata/asn1-rs.git) +- [der-parser 10.0.0](https://github.com/rusticata/der-parser.git) +- [oid-registry 0.8.1](https://github.com/rusticata/oid-registry.git) +- [rusticata-macros 4.1.0](https://github.com/rusticata/rusticata-macros.git) +- [x509-parser 0.18.1](https://github.com/rusticata/x509-parser.git) + +```text +Copyright (c) 2017 Pierre Chifflier + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [smallvec 1.16.4](https://github.com/servo/rust-smallvec) + +```text +Copyright (c) 2018 The Servo Project Developers + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [block-buffer 0.10.4](https://github.com/RustCrypto/utils) + +```text +Copyright (c) 2018-2019 The RustCrypto Project Developers + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [signature 2.2.0](https://github.com/RustCrypto/traits/tree/master/signature) + +```text +Copyright (c) 2018-2023 RustCrypto Developers + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [getrandom 0.2.17](https://github.com/rust-random/getrandom) + +```text +Copyright (c) 2018-2024 The rust-random Project Developers +Copyright (c) 2014 The Rust Project Developers + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [zeroize 1.9.1](https://github.com/RustCrypto/utils) + +```text +Copyright (c) 2018-2026 The RustCrypto Project Developers + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [ppv-lite86 0.2.21](https://github.com/cryptocorrosion/cryptocorrosion) + +```text +Copyright (c) 2019 The CryptoCorrosion Contributors + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [zeroize_derive 1.5.0](https://github.com/RustCrypto/utils) + +```text +Copyright (c) 2019-2026 The RustCrypto Project Developers + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [const-oid 0.9.6](https://github.com/RustCrypto/formats/tree/master/const-oid) + +```text +Copyright (c) 2020-2022 The RustCrypto Project Developers + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [der 0.7.10](https://github.com/RustCrypto/formats/tree/master/der) +- [pkcs8 0.10.2](https://github.com/RustCrypto/formats/tree/master/pkcs8) + +```text +Copyright (c) 2020-2023 The RustCrypto Project Developers + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [cpufeatures 0.2.17](https://github.com/RustCrypto/utils) + +```text +Copyright (c) 2020-2025 The RustCrypto Project Developers + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [crypto-common 0.1.7](https://github.com/RustCrypto/traits) + +```text +Copyright (c) 2021 RustCrypto Developers + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [pem-rfc7468 0.7.0](https://github.com/RustCrypto/formats/tree/master/pem-rfc7468) + +```text +Copyright (c) 2021 The RustCrypto Project Developers + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [pkcs1 0.7.5](https://github.com/RustCrypto/formats/tree/master/pkcs1) +- [spki 0.7.3](https://github.com/RustCrypto/formats/tree/master/spki) + +```text +Copyright (c) 2021-2023 The RustCrypto Project Developers + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [rustls-pki-types 1.15.1](https://github.com/rustls/pki-types) + +```text +Copyright (c) 2023 Dirkjan Ochtman + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [powerfmt 0.2.1](https://github.com/jhpratt/powerfmt) + +```text +Copyright (c) 2023 Jacob Pratt et al. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +``` + +## MIT License + +Used by: + +- [deranged 0.5.9](https://github.com/jhpratt/deranged) + +```text +Copyright (c) 2024 Jacob Pratt et al. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +``` + +## MIT License + +Used by: + +- [num-conv 0.2.2](https://github.com/jhpratt/num-conv) + +```text +Copyright (c) Jacob Pratt + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +``` + +## MIT License + +Used by: + +- [time-core 0.1.9](https://github.com/time-rs/time) +- [time-macros 0.2.32](https://github.com/time-rs/time) +- [time 0.3.55](https://github.com/time-rs/time) + +```text +Copyright (c) Jacob Pratt et al. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +``` + +## MIT License + +Used by: + +- [synstructure 0.13.2](https://github.com/mystor/synstructure) + +```text +Copyright 2016 Nika Layzell + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [rand 0.8.8](https://github.com/rust-random/rand) +- [rand_chacha 0.3.1](https://github.com/rust-random/rand) +- [rand_core 0.6.4](https://github.com/rust-random/rand) + +```text +Copyright 2018 Developers of the Rand project +Copyright (c) 2014 The Rust Project Developers + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [zerocopy 0.8.63](https://github.com/google/zerocopy) + +```text +Copyright 2023 The Fuchsia Authors + +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + + +``` + +## MIT License + +Used by: + +- [director 0.12.0](https://github.com/Xarishark/Director) + +```text +MIT License + +Copyright (c) 2026 Zacharias Xenakis + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +``` + +## MIT License + +Used by: + +- [asn1-rs-impl 0.2.0](https://github.com/rusticata/asn1-rs.git) +- [libm 0.2.16](https://github.com/rust-lang/compiler-builtins) +- [rcgen 0.13.2](https://github.com/rustls/rcgen) +- [windows-collections 0.100.0](https://github.com/microsoft/windows-rs) +- [windows-collections 0.3.2](https://github.com/microsoft/windows-rs) +- [windows-core 0.100.0](https://github.com/microsoft/windows-rs) +- [windows-core 0.62.2](https://github.com/microsoft/windows-rs) +- [windows-future 0.100.0](https://github.com/microsoft/windows-rs) +- [windows-future 0.3.2](https://github.com/microsoft/windows-rs) +- [windows-implement 0.60.2](https://github.com/microsoft/windows-rs) +- [windows-interface 0.59.3](https://github.com/microsoft/windows-rs) +- [windows-link 0.100.0](https://github.com/microsoft/windows-rs) +- [windows-link 0.2.1](https://github.com/microsoft/windows-rs) +- [windows-numerics 0.100.0](https://github.com/microsoft/windows-rs) +- [windows-numerics 0.3.1](https://github.com/microsoft/windows-rs) +- [windows-reactor 0.100.0](https://github.com/microsoft/windows-rs) +- [windows-reference 0.100.0](https://github.com/microsoft/windows-rs) +- [windows-result 0.100.0](https://github.com/microsoft/windows-rs) +- [windows-result 0.4.1](https://github.com/microsoft/windows-rs) +- [windows-strings 0.100.0](https://github.com/microsoft/windows-rs) +- [windows-strings 0.5.1](https://github.com/microsoft/windows-rs) +- [windows-threading 0.100.0](https://github.com/microsoft/windows-rs) +- [windows-threading 0.2.1](https://github.com/microsoft/windows-rs) +- [windows-time 0.100.0](https://github.com/microsoft/windows-rs) +- [windows 0.62.2](https://github.com/microsoft/windows-rs) +- [yasna 0.5.2](https://github.com/qnighy/yasna.rs) + +```text +MIT License + +Copyright (c) + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and +associated documentation files (the "Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the +following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial +portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT +LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO +EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER +IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE +USE OR OTHER DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [rsa 0.9.10](https://github.com/RustCrypto/RSA) +- [rustc-hash 2.1.3](https://github.com/rust-lang/rustc-hash) + +```text +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. +``` + +## MIT License + +Used by: + +- [displaydoc 0.2.7](https://github.com/yaahc/displaydoc) +- [itoa 1.0.18](https://github.com/dtolnay/itoa) +- [lazy_static 1.5.1](https://github.com/rust-lang-nursery/lazy-static.rs) +- [minimal-lexical 0.2.1](https://github.com/Alexhuszagh/minimal-lexical) +- [once_cell 1.21.4](https://github.com/matklad/once_cell) +- [proc-macro2 1.0.107](https://github.com/dtolnay/proc-macro2) +- [quote 1.0.47](https://github.com/dtolnay/quote) +- [serde 1.0.229](https://github.com/serde-rs/serde) +- [serde_core 1.0.229](https://github.com/serde-rs/serde) +- [serde_derive 1.0.229](https://github.com/serde-rs/serde) +- [serde_json 1.0.154](https://github.com/serde-rs/json) +- [syn 2.0.119](https://github.com/dtolnay/syn) +- [syn 3.0.9](https://github.com/dtolnay/syn) +- [thiserror-impl 2.0.21](https://github.com/dtolnay/thiserror) +- [thiserror 2.0.21](https://github.com/dtolnay/thiserror) +- [unicode-ident 1.0.27](https://github.com/dtolnay/unicode-ident) +- [zmij 1.0.23](https://github.com/dtolnay/zmij) + +```text +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [spin 0.9.9](https://github.com/mvdnes/spin-rs.git) + +```text +The MIT License (MIT) + +Copyright (c) 2014 Mathijs van de Nes + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +``` + +## MIT License + +Used by: + +- [typenum 1.20.1](https://github.com/paholg/typenum) + +```text +The MIT License (MIT) + +Copyright (c) 2014 Paho Lurie-Gregg + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +``` + +## MIT License + +Used by: + +- [memchr 2.8.3](https://github.com/BurntSushi/memchr) + +```text +The MIT License (MIT) + +Copyright (c) 2015 Andrew Gallant + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. + +``` + +## MIT License + +Used by: + +- [data-encoding 2.11.1](https://github.com/ia0/data-encoding) + +```text +The MIT License (MIT) + +Copyright (c) 2015-2020 Julien Cretin +Copyright (c) 2017-2020 Google Inc. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + +``` + +## MIT License + +Used by: + +- [generic-array 0.14.7](https://github.com/fizyk20/generic-array.git) + +```text +The MIT License (MIT) + +Copyright (c) 2015 Bartłomiej Kamiński + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +``` + +## Unicode License v3 + +Used by: + +- [unicode-ident 1.0.27](https://github.com/dtolnay/unicode-ident) + +```text +UNICODE LICENSE V3 + +COPYRIGHT AND PERMISSION NOTICE + +Copyright © 1991-2023 Unicode, Inc. + +NOTICE TO USER: Carefully read the following legal agreement. BY +DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING DATA FILES, AND/OR +SOFTWARE, YOU UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE +TERMS AND CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT AGREE, DO NOT +DOWNLOAD, INSTALL, COPY, DISTRIBUTE OR USE THE DATA FILES OR SOFTWARE. + +Permission is hereby granted, free of charge, to any person obtaining a +copy of data files and any associated documentation (the "Data Files") or +software and any associated documentation (the "Software") to deal in the +Data Files or Software without restriction, including without limitation +the rights to use, copy, modify, merge, publish, distribute, and/or sell +copies of the Data Files or Software, and to permit persons to whom the +Data Files or Software are furnished to do so, provided that either (a) +this copyright and permission notice appear with all copies of the Data +Files or Software, or (b) this copyright and permission notice appear in +associated Documentation. + +THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY +KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF +THIRD PARTY RIGHTS. + +IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE +BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES, +OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, +WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, +ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA +FILES OR SOFTWARE. + +Except as contained in this notice, the name of a copyright holder shall +not be used in advertising or otherwise to promote the sale, use or other +dealings in these Data Files or Software without prior written +authorization of the copyright holder. + +``` + diff --git a/build.rs b/build.rs index 344954b..3ae5acd 100644 --- a/build.rs +++ b/build.rs @@ -1,4 +1,4 @@ -#[path = "build/windows_icon.rs"] +#[path = "packaging/windows_icon.rs"] mod windows_icon; fn main() { println!("cargo:rerun-if-changed=assets/director.svg"); diff --git a/docs/ANDROID_TV.md b/docs/ANDROID_TV.md deleted file mode 100644 index cdb0726..0000000 --- a/docs/ANDROID_TV.md +++ /dev/null @@ -1,16 +0,0 @@ -# TCL Android / Google TV: quick test - -This is for a TCL TV running **Android TV or Google TV**. You only need Director, your TV remote and a device connected to HDMI. Keep the TV and PC on the same home network. - -1. **Add the TV.** Turn it on. In Director, open **TVs → + → TCL — Android / Google TV**. Give it any name and enter its IP address, found in the TV’s network settings. -2. **Pair.** Choose **Pair TV**. Enter the six-character code shown on the TV, then click **Confirm code**. If it fails, use **Back** and try pairing again with a new code. -3. **Test HDMI switching.** Choose an HDMI port with something connected. Use the TV remote to switch to a different input or the TV home screen. Tick **The TV is on a different input**, then click **Test HDMI**. Answer **Yes** only if the TV actually switches to the chosen port. Repeat for other ports if wanted, or skip if no HDMI device is connected. -4. **Test power.** Continue through setup, leave the optional Windows display/audio links empty, and **Save TV**. Click the **remote icon**. Check the power status, try **Turn off**, then **Wake**. Allow up to 45 seconds. If wake fails, try enabling **Screenless service / network standby** in the TV’s **Settings → System → Power and energy**, if available, and repeat the test. -5. **Fill in the results.** Close controls and click the TV’s **pencil icon**. Under **Test report**, enter the model and TV software version from **Settings → About**, if available. Select Wi-Fi or Ethernet and answer the three Yes / No / Not tested questions based on what you saw. -6. **Send one file.** Click **Export report…**. A folder opens. Send back the newest **android-tv-compatibility-….json** file. No other files or logs are needed. - -**If pairing fails:** fill in the model/network details under **Test report** on that step and export there. Send the JSON even if nothing worked. If Director itself will not open, tell us that instead. - -The file includes your answers, HDMI results, detected TV information, Director/Windows details and sanitized error history. It excludes pairing codes, keys and IP/MAC addresses. Nothing is sent automatically. - -[Developer details](ANDROID_TV_TECHNICAL.md) diff --git a/docs/ANDROID_TV_TECHNICAL.md b/docs/ANDROID_TV_TECHNICAL.md deleted file mode 100644 index 0dc4b14..0000000 --- a/docs/ANDROID_TV_TECHNICAL.md +++ /dev/null @@ -1,41 +0,0 @@ -# TCL Android / Google TV preview - -Director uses Android TV Remote v2 directly inside the Rust app. No ADB, Python, developer mode, cloud account or companion CLI is needed. This preview targets TCL sets running Android TV or Google TV with Android TV Remote Service. TCL Roku and Fire TV models are not covered. Physical TCL validation is pending. - -## Friend test guide - -1. Keep the TV on, with the PC on the same trusted local network. Make sure the Google TV mobile remote works first; it uses the same service. -2. Open TVs → + → TCL — Android / Google TV. Name the TV and enter its IPv4 address (a DHCP reservation is recommended). -3. Choose Pair TV. Enter the six-character hexadecimal code shown on the television and choose Confirm code. If the code expires or is rejected, use Back and start pairing again. Codes are not saved or logged. Client identity keys are protected by Windows DPAPI for this account. -4. Director reads model and Remote Service version when available. The version is a service version, not necessarily the TV firmware. Input enumeration and selected-input readback are not provided by this protocol. -5. Optional: connect a visible source to the desired HDMI port, start the TV on a different input, select the target port, check the precondition and choose Test HDMI. Answer Yes only if the TV actually switched. Only confirmed direct ports become available to controls/scenes. No source-menu navigation or custom key sequences are used. A failed/rejected retest removes the port. New model/service-version information invalidates old confirmations. -6. Enable Screenless service / network standby under the TV’s power settings if available. This keeps network remote control reachable in standby; Director does not blank the screen. MAC entry is optional and remains behind the advanced switch: this protocol does not provide automatic MAC learning. A saved MAC enables Wake-on-LAN fallback. -7. Optionally link the Windows display and HDMI audio endpoint, then save. Power and input actions are configured separately in scenes. -8. Check status, turn off, then wake. Test each desired HDMI port. Export report in the compatibility section and attach its JSON. Export also works from Edit TV or director tv report "TV name". Nothing uploads automatically. - -Use a second screen for Director during HDMI tests. Testing sends a real input command; Cancel discards unsaved test records but cannot undo that command. Reports can be exported before saving. - -## Controls and boundaries - -- Pairing uses mutually authenticated TLS on port 6467. Control uses port 6466. There is no unencrypted fallback. -- Each TV entry has an RSA client identity. The displayed code is checked against both certificate public keys before accepting the pairing exchange. Later control connections require the same server RSA identity; a changed identity requires explicit re-pairing. TVs using different pairing/control server keys may need additional investigation before compatibility can be established. -- Reported RemoteStart state gives On or Standby. A connected socket alone is not evidence that the panel is on. Timeout/disconnect stays Unknown. -- Wake sends the direct WAKEUP command when the authenticated remote service is reachable. If unreachable and a MAC is saved, Director sends Wake-on-LAN. Deep standby without reachable networking cannot be solved by a remote command alone. -- Turn off uses the direct SLEEP command, never a blind power toggle. Input uses exactly one numbered HDMI key. Sent is not TV acknowledgment or proof that a key had an effect. -- While controls are open, scoped status checks refresh reported state. Closing the controls stops checks/retries. CLI commands require no permanently running process. -- The shared scene and temporary display-detection providers handle TCL too. Scenes prepare the TV before displays/audio, wait for reported awake state, and skip unsupported input readback. -- Unsupported input selectors are hidden until confirmed. Generic remote buttons, volume, app launch, voice, text entry, Roku/Fire TV and custom sequences are outside this preview. - -## Report privacy - -The report allowlists brand, Director/report version, model/service version, pairing status, connection type, direct HDMI test send outcomes and user confirmations. It excludes codes, private keys, certificates, TV names, IP/MAC addresses, display/audio identities, raw responses and arbitrary errors. Reports live under the Windows Local AppData Director/Reports folder. General app logs remain available from Options, but the compatibility JSON is the intended shareable artifact. - -## Implementation references - -- [androidtvremote2](https://github.com/tronikos/androidtvremote2): pairing/protocol reference, Apache-2.0. Director implements the required wire subset independently; no Python runtime or copied generated code. -- [Google Polo pairing protocol](https://android.googlesource.com/platform/external/google-tv-pairing-protocol/): certificate/code exchange. -- [Home Assistant Android TV Remote](https://www.home-assistant.io/integrations/androidtv_remote/): documented TCL standby limitations. - -Rustls, ring, rcgen, rsa, sha2 and x509-parser provide in-process cryptography and certificate handling. Framing is bounded and only the small required protobuf subset is implemented. Existing Windows App Runtime and adjacent app-icon requirements still apply when copying the preview to another PC; this change does not add an installer. - -For the current format-2 report contents, tester result fields and sanitized action history, see DIAGNOSTICS.md. Use ANDROID_TV.md for the short friend instructions. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 1d2822b..3db5274 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,194 +1,74 @@ -# Architecture proposal +# Architecture -Status: the first audio slice implements the shared transaction engine in src/audio.rs, a direct Windows adapter in src/windows_audio.rs, versioned audio-preset persistence in src/presets.rs, and WinUI 3 entry point and headless CLI in src/main.rs. Broader module boundaries and scene/storage design below remain proposals. See IMPLEMENTATION.md for validation. +Director is one Rust executable, `director.exe`. Started without arguments it opens a native WinUI 3 window; with arguments it runs a CLI command and exits without creating any UI. Both paths call the same library code, so a scene behaves the same from the window, a terminal or a Stream Deck shortcut. -## Shared engine +## Crates and entry points -Keep preset capture, persistence, validation, planning, application, verification, and recovery in Rust code independent of the GUI. The GUI and CLI call this same engine so behavior does not drift between entry points. - -The CLI path must not construct the GUI, start its event loop, or require an existing GUI process. The first slice uses one director executable: no arguments open the GUI; audio subcommands run without UI initialization. +| 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 | +| 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) | ## Integration policy -Use direct Windows API calls, device-protocol clients, and linked Rust/native libraries wherever practical. Do not spawn NirCmd, Display Changer II, ColorControl, rtss-cli, frltoggle, or batch files to implement their replacement workflows. A library compiled or linked into Director is different from an independently installed helper application. Keep unavoidable dependencies explicit. User-configured application launches and URI dispatch remain supported scene actions. - -## Proposed boundaries - -| Component | Responsibility | -| --- | --- | -| Domain/model | Display presets, audio presets, scenes, action definitions, device identities, failure policy, operation outcomes | -| Engine | Capture, validate, build an ordered plan, snapshot affected state, apply, verify, and recover | -| Windows displays | Enumerate/query layouts and apply/verify Windows display changes | -| Windows audio | Enumerate endpoints, read identity/name/availability, select defaults, read/set device volume, observe availability changes | -| LG integration | Pairing, Wake-on-LAN, webOS connection, input/power actions, bounded readiness waits | -| Frame-limit providers | Discover supported direct GPU-driver controls and optional RTSS; query limits, snapshot/apply/verify/restore the selected provider | -| Launch integration | Executable launch and URI dispatch; accurate dispatch outcomes | -| Persistence | Versioned presets, remembered inventory, operation results, recovery state, separate credential storage | -| Notifications | Native Windows notifications and activation into result details | -| GUI | Native WinUI 3 views, user input, progress, results; no duplicated device-control policy | -| CLI | Argument parsing, shared engine invocation, output and exit status | - -These are logical boundaries, not a committed crate/package layout. - -## Proposed data relationships - -- Give app presets and scenes stable internal IDs with editable display names. -- Keep app preset IDs distinct from Windows device identities. -- Let a scene reference optional display/audio presets rather than copy their settings. -- Editing a referenced component would affect future applications of every scene that uses it; duplication would create an independent variant. -- Show dependent scenes before deleting a component and prevent dangling references. -- Store optional fields explicitly so an omitted field means leave unchanged. - -Reference/update/deletion semantics need user confirmation before the schema is finalized. - -## Initial creation UI - -Capture current layout reads monitor settings only. Audio presets use independent input/output dropdowns populated from the observed/remembered inventory. Each selected device has an optional Set volume switch and a 0–100% value; disabled means leave volume unchanged. Editing or saving a preset does not apply it. Reading current audio state for status or rollback remains necessary and is separate from a user-facing audio-capture feature. - -## Initial audio role scope - -Output presets map Console, Multimedia and Communications to the selected output by default. An optional separate communications output overrides only that role. An independently optional microphone selection changes all three capture roles; microphone volume is optional. Snapshot every affected render/capture role and requested endpoint volume before the first write, and verify/restore them independently. See AUDIO.md. - -## Device identity - -Audio endpoint identity is separate from its mutable Windows name and current availability. Persist the preferred Stable ID when available, plus the current ordinary endpoint ID and last observed name. Re-query properties when resolving a device; never parse opaque IDs or resolve ambiguity by friendly name alone. - -The display identity strategy needs separate validation. Do not assume transient display numbering or adapter IDs survive hardware/driver changes. - -## Proposed execution lifecycle - -1. Resolve the requested preset/scene and obtain exclusive operation ownership. -2. Validate configuration and dependencies that can be checked without changing hardware. -3. Capture known previous state for affected resources before changing them. -4. Prepare devices needed by later steps, such as waking the TV and selecting its input. -5. Apply/verify display settings, wait for the requested audio endpoint, then apply/verify audio settings. -6. Apply other requested configuration, including the selected frame-limit provider. -7. Dispatch optional final actions if the agreed gating rules permit them. -8. Persist and report the result; notify according to settings. - -On a required failure, use the selected policy. The default recovers affected settings using the captured state, keeps operation ownership during recovery, and reports the recovery result separately from the original failure. - -The accepted scene stage order is Display → Audio → Apps & URIs. Skip omitted stages and constrain user reordering to steps within their stage. TV preparation/readiness is part of the display stage; refresh audio availability after changing displays. Detailed device dependencies must handle both desk and TV transitions without allowing cross-stage reordering. The exact placement of frame-limit configuration remains to be finalized; it must precede final launches. - -## Frame-limit providers - -Keep frame-limit actions independent of the limiting mechanism. A provider reports availability, supported scope/range, and read/apply/restore capabilities. Research direct NVIDIA NVAPI, AMD ADLX FRTC, and Intel IGCL alongside RTSS. Users without RTSS should still be able to use a supported driver provider. GPU vendor alone is insufficient to establish support, and multiple-GPU systems require an explicit target. Do not promise that a saved driver setting takes effect in an already-running game or reproduces RTSS behavior. Preserve previous provider settings for recovery, and do not silently enable multiple limiters or change unrelated driver settings. Driver-based limiting is the primary/default method when supported; RTSS and other future external limiters are optional alternatives. Add a Set FPS limit switch, Method dropdown, and method-validated FPS value in the relevant action editor; off means leave existing limits unchanged. Never silently fall back to an external provider. Provider implementation details/order remain open; audio switching stays the first work item. - -## UI and execution threading - -The UI must remain responsive during discovery, preset/scene application, device readiness waits, verification, and rollback. WinUI owns the main UI/event-loop thread. Run device work on a background Rust worker/executor and send progress/result messages back to the UI; never perform blocking Windows calls, synchronous network/file work, sleeps, or worker joins in UI callbacks. - -The first audio slice uses Reactor background jobs with command/result messages. Serialize mutation requests even when background tasks are asynchronous; separate threads must not permit overlapping preset changes. The operation uses a snapshot of the requested preset so edits do not alter an in-flight plan. - -Reactor background tasks return plain-data messages to the component update loop. Keep UI updates short and exchange no COM objects across threads. Merely marking a callback async does not move blocking work off the UI thread. - -The CLI uses the same execution engine without GUI initialization. Normal closing is deferred while work is active. Forced termination recovery and interruption of an unresponsive native call remain unresolved; do not assume every system call can be safely canceled. - - -## Responsiveness and resource use - -- Keep network and device waits off the UI thread. -- Prefer device notifications and bounded waits over permanent polling. -- Run CLI operations without UI initialization. -- Keep tray residency and startup integration out of the first implementation. -- Measure release-build behavior before selecting rendering options or claiming resource targets. - -## State and local files - -During development, keep repository-local notes, downloaded tools, test credentials/inventories, logs, and other machine-only artifacts inside .localonly/. The machine-wide Git excludes file owns the /.localonly/ rule; do not duplicate broad local-file patterns in the repository .gitignore. This development convention does not select installed-app storage locations. - -Presets, remembered devices, credentials, diagnostic logs, and recovery snapshots have different purposes. Do not treat the last requested/successful scene as proof of the current Windows state. - -Choose storage locations, schema migration, credential protection, and interrupted-operation recovery during implementation planning. Real machine inventories, pairing keys, and runtime results must not be committed to the repository. +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. -## Technical starting points +## Domain modules -- [Rust for Windows](https://learn.microsoft.com/en-us/windows/dev-environment/rust/rust-for-windows) -- [QueryDisplayConfig](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-querydisplayconfig) -- [SetDisplayConfig](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-setdisplayconfig) -- [Audio endpoint Stable ID](https://learn.microsoft.com/en-us/windows/win32/coreaudio/pkey-audioendpoint-stableid) -- [Windows app notifications](https://learn.microsoft.com/en-us/windows/apps/develop/notifications/app-notifications/) +| Area | 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). | -These are research references, not proof of a working integration. Pin dependency/tool versions only when implementation is authorized and they have been validated. +## 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. -## Implemented audio navigation +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. -Audio presets is the main native NavigationView page. A ListView contains selectable rows with visible Apply/Edit/Delete icon buttons. Add/Edit uses the same window with Name, output ComboBox, optional volume NumberBox, failure policy, device-ID Expander, and Save/Cancel. Selection and storage edits never apply audio. InfoBar reports status and errors; ContentDialog confirms deletion. Stable app preset IDs survive renames. Names are unique ignoring case for CLI lookup. +## Transactions and recovery -## Native frontend +Scenes, display Apply, the Sound step, FPS changes and temporary display detection share one pattern: -The root Cargo package builds one director executable. src/main.rs hosts WinUI through pinned windows-reactor 0.100.0; src/close_guard.rs protects pending operations from normal window closure. src/audio.rs, src/windows_audio.rs, src/presets.rs, and src/cli.rs remain shared backend code. CLI arguments are handled before GUI initialization. Reactor WinRT types and the backend Windows bindings remain isolated; worker results are ordinary Rust data. build/windows_icon.rs generates the executable resource and adjacent director.ico from assets/director.svg. The current framework-dependent GUI uses an installed Windows App Runtime; see [runtime notes](WINDOWS_GUI.md). -## Implemented display capture +1. Resolve the request and take the operation lock. +2. Validate everything that can be checked without changing hardware. +3. Snapshot the state that will change. +4. Apply each step, then read the real state back to verify it. +5. On a failed required step, restore the snapshot (unless Options says to keep completed changes) and report the restore result separately from the failure. -The independent domain/storage model is src/displays.rs; src/windows_displays.rs reads CCD paths/modes directly; src/display_ui.rs implements the native capture/list/rename/delete page; src/display_cli.rs handles headless inspection and named capture. Both preset types reuse the known-folder resolution and atomic document write helper, without sharing names or documents. Display jobs use the existing global operation gate and return plain-data messages. src/display_apply.rs provides the shared verified transaction and independent confirmation deadline; src/windows_display_apply.rs resolves current monitor paths/routes and implements native validation, temporary application, persistence, and exact before-state restoration. See [the Apply contract](DISPLAY_APPLY.md). See [display schema and limitations](DISPLAY_PRESETS.md). +TV commands, app launches and URIs can't be undone, so they are reported but not part of automatic recovery. -## Custom display draft editor +## Data and identity -src/display_editor.rs owns pure draft transformations and validation; src/windows_display_modes.rs discovers supported progressive SDR modes through DXGI and a CCD preferred-mode fallback. src/display_editor_ui.rs supplies native controls, the interactive arrangement map, and SVG orientation flyouts. Mode discovery is background-only and returns plain data. Editing never calls a native setter. Saving writes the existing display-preset schema; Apply continues through the shared verified transaction. The build stages four orientation SVGs beside the executable in orientations/. +- Settings live in `%LOCALAPPDATA%\Director`, resolved through the Windows known-folder API. `storage::write_document` validates, checks the file hasn't changed since it was read, writes a temporary file and replaces the original atomically. Corrupt or newer-version files are kept and reported, never overwritten. +- Saved items have stable IDs and editable names. Scenes reference display presets and TVs by ID; deleting an item that a scene still uses is refused and names those scenes. +- Audio endpoints are matched by Windows Stable ID when available, then endpoint ID, never by friendly name alone; offline devices can be relinked. +- Displays are matched by monitor device path, not by transient display numbers or adapter IDs. +- TV pairing keys and client identities are encrypted with Windows DPAPI for the current user and never leave the PC: backups and reports exclude them. -The shared preset heading is src/preset_ui.rs. Display draft pointer gestures use Reactor Border pointer capture, window-relative coordinates, and plain-data Drag/MapTransform domain objects. Layout edits are provisional until release; cancellation restores the pre-drag draft. Dropping snaps edges, resolves overlap, and normalizes the primary origin. No gesture invokes Windows setters. The numeric coordinate UI and separate Customize action have been removed. Edit discovers capabilities in the background immediately. +## References -## Live configuration and HDR +Windows APIs: -src/current_ui.rs holds an independent in-memory Current setup session. The shared display editor routes plain-data events to either the preset or Current draft. The synchronous gesture/change subset reuses the existing handler under a scoped state swap; Current capture-loss timers are routed explicitly to the Current session. Preset persistence/Apply messages are excluded from that bridge. Display and audio Apply call the shared engines directly and reread actual state; preset documents are never accessed. +- [Rust for Windows](https://learn.microsoft.com/en-us/windows/dev-environment/rust/rust-for-windows) and [windows-reactor](https://github.com/microsoft/windows-rs/blob/master/crates/libs/reactor/readme.md) +- [QueryDisplayConfig](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-querydisplayconfig), [SetDisplayConfig](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-setdisplayconfig) and [display device-info types](https://learn.microsoft.com/en-us/windows/win32/api/wingdi/ne-wingdi-displayconfig_device_info_type) (HDR) +- [Audio device roles](https://learn.microsoft.com/en-us/windows/win32/coreaudio/device-roles) and [endpoint Stable ID](https://learn.microsoft.com/en-us/windows/win32/coreaudio/pkey-audioendpoint-stableid) +- [Windows app notifications](https://learn.microsoft.com/en-us/windows/apps/develop/notifications/app-notifications/) and the [WinHTTP status callback](https://learn.microsoft.com/en-us/windows/win32/api/winhttp/nc-winhttp-winhttp_status_callback) (certificate pinning before headers are sent) -src/windows_hdr.rs defines the HDR-specific CCD ABI missing from the pinned Windows bindings. Optional monitor HDR state is captured by windows_displays, exposed via capability options, checked in display_apply verification, and set/restored after topology by windows_display_apply. The previous adapter-LUID dependency in mode-list matching was removed; identity is the monitor interface path, and mode filtering retains unspecified/progressive scan-line modes. +Projects consulted for protocols and design. Director doesn't depend on, bundle or run any of them; its implementations are independent Rust code: -## First TV slice — implemented - -`src/tvs.rs` owns versioned remembered-TV definitions and optional Windows target-path metadata. `src/lg_protocol.rs` validates bounded, correlated SSAP registration/input-list messages. `src/windows_lg.rs` provides native WinHTTP TLS/WebSocket connections, cancellation deadlines, certificate continuity checking, and per-user DPAPI credential protection. `src/tv_ui.rs` and `src/tv_cli.rs` share these modules and the operation lock; no TV helper executable or persistent service is needed. GUI I/O remains on workers. Display links do not apply presets or imply readiness. See [TVs](TVS.md) for the exact first-slice boundaries and proposed MAC/IP identity improvement. - -## Guide and wake update - -The tv_setup module owns progression/gating and invalidation when a new draft’s endpoint changes. The TV UI retains its protected pairing in memory until final save and runs pairing/metadata reads on workers. Defaulted inputs, pc_input, and network fields keep existing paired definitions readable. The Windows LG inspection reads inputs and optional TV-reported wired/Wi-Fi MACs; refused/partial reads do not erase remembered valid addresses. Re-pairing retains a successful key even if subsequent metadata reads fail. - -The tv_network module validates/deduplicates MACs, builds standard magic packets, and dispatches three UDP broadcast rounds. GUI Wake and CLI tv wake share it under the operation lock, without a webOS session or key. Dispatch does not establish physical wake or trigger display/audio/input changes. PC input is connection metadata for later scene actions. Discovery, verified IP migration, input switching, power-off, and scene readiness remain separate work. - -## Shared TV controls - -The tv_control module defines PowerState, explicit PowerAction, snapshots, a backend trait, fresh-state intent handling, input validation/no-op detection, and bounded readback. WindowsTvControls in windows_lg provides a worker-local authenticated WinHTTP session, latched connection errors, TV input/app-ID mapping, and explicit SSAP off/switch calls. It uses the existing wake sender. New status/off/input CLI commands share this engine; wake stays explicit direct packet dispatch. - -The tv_controls_ui module owns ephemeral dialog state, pending target selection, revision-tagged results, and background jobs. It checks the current saved TV definition under the operation lock before connecting or acting, rejecting stale windows. Snapshots are not persisted. A bounded post-action refresh updates the UI, without inferring physical Off from network disappearance or claiming signal readiness from foreground input readback. Main-window close protection remains active during jobs. - - -## Local diagnostics - -The diagnostics module owns a bounded nonblocking producer queue, one process-local writer thread, cross-process file locking, rotation, UTC JSON-line records, operation scopes and timed steps. Both GUI and CLI initialize it and flush briefly before normal exit. Device APIs do not depend on logging success. TV transport logs protocol stages rather than payloads or keys. Audio/display engines record progress and results through the shared logger. The native Options footer opens options_ui; its log-folder action uses the Windows-known Local AppData directory and Windows File Explorer directly on a worker. TV controls keep command details and status details in separate fields. See [diagnostics](DIAGNOSTICS.md) for retention, overload behavior and validation limits. - - - -## Command-aware TV modal transitions - -The root tv_power_state module owns ephemeral Idle/Waking/TurningOff/AssumedOff/WakeExpired states and monotonic retry decisions, independently of reported PowerState. tv_control::Report exposes typed effects; wake_snapshot reads power first and reads input metadata only after an awake response. The GUI updates confirmed input changes directly and marks accepted turn-off as assumed Off without a follow-up timeout. Wake completion schedules revision-tagged read/timer messages through background workers; each callback validates dialog lifetime/revision before starting another attempt. Successful command processing requests reconciliation only when its effect is uncertain or requires wake readiness. Command worker panics/delivery failures return through the same completion path so busy state cannot leave the modal permanently pending. - - -## Optional setup-tip preferences - -preferences.rs stores versioned preferences.json in the Windows-known Local AppData Director directory. It uses the existing atomic document writer and rejects stale, corrupt or future-version overwrites. tv_tip_ui owns asynchronous loading/saving, session dismissal, pending preference state and the saved-TV catalog used for contextual guidance. Preference handlers do not release an unrelated device-operation busy guard. The TV guide supports an add-after-load request; display state stays intact during navigation. The shared monitor editor renders linked-TV context in a width-constrained row. - - -## Temporary display discovery - -display_detection.rs owns the backend-independent snapshot/prepare/enable/read/restore/verify transaction, original-screen comparison, cooperative cancellation/deadline and retained recovery state. windows_display_detection.rs adapts it to the existing WindowsDisplays snapshot, temporary CCD setter and live DXGI/CCD inventory. Optional TV preparation shares native WOL/SSAP control. Restoration uses SDC_APPLY without saving a new database topology. display_capabilities.rs stores validated complete inventories, merges remembered inactive choices and installs learned data into the draft after verified restoration. - -display_setup_ui.rs owns inline review/progress/result/recovery state and sends stage updates through a standard worker channel. Native setters and cache I/O do not run on the UI thread. The shared operation lock and existing close guard cover setup; restoration ignores ordinary work cancellation so it can finish safely. See DISPLAY_SETUP.md for the exact behavior, limits and validation boundary. - - -TV controls own a cancellable PowerWatch. A native worker receives authenticated SSAP power events; the view drains them through its token-checked message path. Read-only reconnects never acquire the mutation lock or wake the TV. Explicit wake retransmissions use the existing operation lock and a bounded per-request retry policy. - -## Scene composition - -scenes.rs owns independent ID references, versioned persistence, validation and the ordered framework-independent transaction. windows_scenes.rs supplies native snapshots, bounded TV/audio readiness, display/audio verification, launch dispatch and restoration under OperationLock. scene_ui.rs keeps drafts/cards/progress on the UI thread, owns cancellation and confirmation channels, and runs I/O on workers. TV audio metadata remains in tvs.json; selecting that source resolves its current saved endpoint ID without duplicating an audio preset. See SCENES.md for recovery boundaries and known limits. - -## Samsung provider boundary - -windows_tv dispatches setup, control, CLI, scene and display-preparation operations by persisted TV brand. Missing brand defaults to LG. samsung owns direct-command schemas, latest confirmed capabilities and the allowlisted report; windows_samsung implements native Tizen transport and guarded power operations. Existing WinHTTP socket/DPAPI helpers in windows_lg are shared, including pre-header TLS pin validation for token-bearing Samsung URLs. LG keeps its subscription; Samsung uses a modal-scoped bounded power poll. tv_setup adds brand selection; samsung_ui presents an optional test and explicit visual confirmation before enabling each port. No sequence fallback or cloud integration is present. - -Android TV Remote v2 uses an independent Rust TLS/protocol implementation (android_tv.rs / windows_android_tv.rs) behind windows_tv. Pending pairing sessions stay in memory while entering the code; account-protected per-TV client identity is persisted only after successful confirmation. Android and Samsung maintain separate compatibility metadata but share the explicit input-test UI/report format. Shared DPAPI document helpers retain the existing LG/Samsung token validation. No new runtime process is introduced. - -Implemented global FPS providers: fps.rs owns requests, snapshots, verification/recovery; windows_fps.rs loads NVIDIA DRS / installed RTSS interfaces. fps_ui.rs shares controls across Current setup and scenes. Scenes snapshot FPS during preflight and apply after audio, before launch actions. Global driver profile is the explicit NVIDIA target; it is not a monitor-specific cap. Blocking calls remain worker-owned and SDK sessions are serialized. - -## Sound — current - -Audio presets are retired (D066). The domain now has display presets, scenes (with an inline Sound step), TVs and the remembered audio-device inventory. `audio::apply` stays the multi-step transaction a scene's Sound step uses; `audio_control` holds the one-change-at-a-time live controls used by Now and `director audio`. Both sit on the same `AudioBackend` (default roles, volume and mute). This supersedes the audio preset page and the preset references described above. +| Project | Used as a reference for | +| --- | --- | +| [lgtvcli](https://github.com/01dnot/lgtvcli), [PyWebOSTV](https://github.com/supersaiyanmode/PyWebOSTV), [lgtv2](https://github.com/hobbyquaker/lgtv2) | LG webOS pairing, inputs, power and network information | +| [samsung-tv-control](https://github.com/timdevlet/samsung-tv-control), [ColorControl](https://github.com/Maassoft/ColorControl) | Samsung Tizen pairing, power state and direct HDMI keys | +| [androidtvremote2](https://github.com/tronikos/androidtvremote2), [Polo pairing protocol](https://android.googlesource.com/platform/external/google-tv-pairing-protocol/) | Android TV Remote v2 pairing and commands | +| [NVAPI](https://github.com/NVIDIA/nvapi), [rtss-cli](https://github.com/xanderfrangos/rtss-cli) | NVIDIA driver profile settings and RTSS profile interfaces | +| [DisplayProfileManager](https://github.com/exytral/DisplayProfileManager), [DisplayHotKeys](https://github.com/jon-mil-92/DisplayHotKeys) | Display editor and mode-switching workflows | diff --git a/docs/AUDIO.md b/docs/AUDIO.md deleted file mode 100644 index 4f445b4..0000000 --- a/docs/AUDIO.md +++ /dev/null @@ -1,49 +0,0 @@ -# Sound - -Director handles sound in two places: - -- **Live controls** change one thing right away: the **Now** page and `director audio` commands. Picking an output or microphone makes it the Windows default, a volume slider or `audio volume` sets the level, and mute buttons or `audio mute` toggle mute. Nothing is saved. -- **A scene's Sound step** saves sound settings in the scene and applies them with the scene's other steps, as one transaction with rollback. - -Audio presets are retired (decision D066). Scenes that used one, and scenes that used a TV's linked audio, migrate into a Sound step when they load. See [scenes](SCENES.md). - -## Now - -The Sound card shows the default output and microphone. Choosing a device makes it the default for all three Windows roles (Console, Multimedia, Communications). Each volume slider sends its level once it rests for 150 ms, so a drag writes once; a slider that moves while a change is running keeps its place and is sent next. The mute buttons toggle the device's mute state. Every change is verified, and the previous value is put back if Windows does not confirm it. **Save as scene…** opens a new scene whose Sound step holds the current output and volume. - -## The scene Sound step - -| Setting | Choices | -| --- | --- | -| Output | Leave as is, a device, or a TV's sound (the output linked to a saved TV) | -| Volume | Leave as is, or 0–100% | -| Mute | Leave as is, unmute, or mute | -| Calls | Optionally a different device for the Communications role | -| Microphone | Optionally a device for all three input roles, with its own volume and mute | - -With the output left as is, volume and mute apply to whichever output is the default when the scene runs. Sound runs after the displays, so a TV's HDMI audio is ready; the scene waits up to the device wait time in Options for the chosen devices to appear. - -All selected devices must be connected and resolve to one endpoint before anything changes. Director snapshots every affected role, volume and mute state, records each change before making it, verifies the result, and on failure restores roles, volumes and mute in reverse order (unless Options keeps completed changes). The cross-process operation lock is held throughout. - -## Command line - -```text -director audio status [--json] -director audio list | outputs | inputs [--json] [--all] -director audio use [--role console|multimedia|communications] -director audio volume [] <0..100 | +N | -N> -director audio mute | unmute | mute toggle [] -director audio check -``` - -Add `--mic` to target the microphone. Leaving out the device means the current default, so `director audio volume +5` turns the current output up, which suits a Stream Deck button. A device is named by its CLI name (its Windows name in lowercase with dashes, so "Speakers (Realtek(R) Audio)" is `speakers-realtek-r-audio`) or its endpoint ID; when two connected devices share a name, use the ID. `audio list` hides endpoints Windows remembers that are not present unless `--all` is passed. - -## Remembered devices and TV audio - -Linking a TV to an audio endpoint is TV metadata. A scene's Sound step can use it as "TV's sound"; linking alone never wakes the TV or switches audio. - -Prefer a verified one-to-one hardware association. Do not infer the link solely from an HDMI label, a matching name, or a shared GPU. Where Windows cannot provide a unique association, offer a one-time selection and remember its endpoint identity and last name. Director remembers Windows input and output endpoints it has seen in a separate local device inventory. - -The Sound step and TV audio pickers include previously seen offline devices. Director resolves a saved reference by endpoint ID, then by a unique Windows Stable ID in the same direction when available. A unique endpoint instance path can also match when known Stable IDs agree or are unavailable. If a reference cannot be resolved, use **Relink device** to choose a replacement and review the scenes and TV links it affects before confirming. - -Windows documents [endpoint roles](https://learn.microsoft.com/en-us/windows/win32/coreaudio/device-roles), [device/container properties](https://learn.microsoft.com/en-us/windows/win32/coreaudio/device-properties), and [endpoint association/Stable ID properties](https://learn.microsoft.com/en-us/windows/win32/coreaudio/audio-endpoint-properties). The association property describes a kernel-streaming pin category; it is not itself a TV-to-monitor mapping. diff --git a/docs/CURRENT_SETUP.md b/docs/CURRENT_SETUP.md deleted file mode 100644 index 5d6432d..0000000 --- a/docs/CURRENT_SETUP.md +++ /dev/null @@ -1,26 +0,0 @@ -# Now - -Now (formerly Current setup) is an alternative workspace for adjusting the active Windows configuration without creating or editing presets. It shares the display editor and backend with saved presets, rather than maintaining a second implementation of monitor controls. - -## Using the view - -Open **Now** in the navigation pane. Displays and FPS limit come first and wait for **Apply changes**, in the bottom-right corner of the display map. Below a divider, Sound applies as you change it: - -- Arrange screens by dragging them in the box; hover for technical details. -- Enable/disable monitors, choose the primary, resolution, refresh rate, HDR, and orientation. -- Sound changes apply right away: choose the default output or microphone, move a volume slider, or press a mute button. Turn on **Use a different device for calls** to send calls to their own output; the main output then sets apps and media only. See [Sound](AUDIO.md). -- **Apply changes** applies everything staged: displays first, then the FPS limit (only if the display change succeeded). Its tooltip says what is staged. No preset name or Save action is involved. -- **Discard** (on only while something is staged) rereads the actual Windows state. -- **Save as display preset…** asks for a name and saves what Now shows, including edits you haven’t applied, then opens the Displays list. Your screens don’t change, and Now keeps its staged edits. **Save as scene…** opens a new scene with its Sound step dialog open, holding the current output and microphone with their volume and mute state. Saving happens in the normal editor, and Cancel discards it. - -Display and FPS controls stage changes until Apply changes is pressed, so a multi-monitor arrangement can be prepared before reconfiguring hardware. Display Apply uses verification/recovery and keeps verified changes without a Keep/Revert prompt. Sound controls don't stage: choosing an output makes it the default for all three roles, a volume slider sends its level once it rests for 150 ms, and mute toggles. Each change is verified and put back if Windows does not confirm it. - -Pending live edits survive page navigation independently of preset drafts. Opening a clean Now page rereads Windows. After display Apply, audio devices are reread so HDMI endpoints can appear. Each page has an independent native control tree to prevent scroll positions leaking between pages. - -## Safety and boundaries - -Display Apply and each sound change run on background workers under the same cross-process operation gate, with normal window-close protection and the shared backend recovery behavior. They are independent operations, not a scene transaction combining both categories. Snapshot/readback errors remain visible. - -HDR requires a supported display and an available HDR-specific Windows API. Unavailable controls are disabled. Clone-group editing, physical Identify, DPI/color-depth/VRR settings, a separate Communications output, and automatic device relinking remain outside this view. - -Now never writes preset or scene files itself; its Save buttons hand a draft to the normal editor. Its temporary display draft is held only in memory; errors and actual state after an attempted application are reread. It does not include appearance/theme controls. diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md deleted file mode 100644 index 1659ecd..0000000 --- a/docs/DECISIONS.md +++ /dev/null @@ -1,236 +0,0 @@ -# Design decision record - -Planning began: 2026-10-30. Implementation authorized: 2026-10-31. "Accepted" means agreed direction, not completed functionality. See IMPLEMENTATION.md for current code and validation. - -## Accepted - -| ID | Decision | Reason/context | -| --- | --- | --- | -| D001 | Rust application logic and CLI; native WinUI 3 GUI through Microsoft Windows Reactor | Native compiled desktop application without a Chromium frontend; prioritize speed and low resource use | -| D002 | Shared execution engine; CLI application without GUI initialization | Identical behavior from the window and automation | -| D003 | Independent display and audio presets, optionally composed into scenes | Users must not need to bind audio and displays at preset creation | -| D004 | Audio input, output, and volume can be controlled independently | Supports input-only, output-only, and volume-only requests | -| D005 | Capture current monitor layouts first; create audio presets with dropdowns and optional volume controls; guided creation later | Audio capture is excluded from the initial workflow; establish basic workflows before expanding creation tools | -| D006 | Remember observed audio devices while unavailable | TV HDMI audio may appear only after the display transition | -| D007 | Prefer Windows Stable ID when available, fall back to endpoint ID, allow explicit relinking | Names are editable/non-unique and device identities can change | -| D008 | A device must be enumerated at least once before selection; show identity and Windows name | Bind presets to real observed devices, not typed names | -| D009 | Ordered optional final executable and URI actions | Support Steam Big Picture and other user-selected apps after configuration | -| D010 | Native Windows system notifications | Report background/CLI results using the system notification experience | -| D011 | Selectable failure policy; default revert, alternative stop and keep completed changes | Recover previous state by default while allowing user choice | -| D012 | Defer tray mode and starting with Windows until after basic functionality | Keep the first implementation focused | -| D013 | Exclude CRU and SpotBye | Explicitly outside the replacement application's scope | -| D014 | Keep the private checklist and repository-local machine files under .localonly/, excluded by the machine-wide Git rule; keep .gitignore limited to build output | Keep the private backlog local while documenting agreed design in repository files | -| D015 | Use Director as the app name and Director as the local repository folder name | User-selected working name; keep documentation and command examples consistent | -| D016 | Scene is the top-level bundle; presets hold saved settings; actions perform commands | Use display/audio presets and TV, frame-limit, executable, or URI actions consistently throughout the app | -| D017 | Fixed scene stages: Display → Audio → Apps & URIs; reorder only within a stage | Displays may introduce audio endpoints, so configure displays before selecting audio; launches come last | -| D018 | Capture current layout applies only to monitors; audio devices are selected in dropdowns with an optional Set volume percentage switch per selected device | Device/volume edits configure a preset; only Apply changes the actual device settings | - -| D019 | Minimize external applications by implementing operations directly through OS APIs, device protocols, or linked libraries wherever practical | Director must replace helper executables rather than wrap them; document unavoidable dependencies separately from intentional user launch actions | - -| D020 | Keep device discovery, preset/scene execution, waits, verification, and recovery off the UI thread | The native window must stay responsive; background execution reports progress/results through the UI event loop and still serializes changes | - -| D021 | GPU-driver frame limiting is primary; RTSS and future external limiters are optional alternatives. Use a Set FPS limit switch, Method dropdown, and FPS value | Prefer supported driver methods, leave settings unchanged when omitted, and validate each provider before claiming support | - -| D022 | Initially change Default audio only: Console and Multimedia together. Defer Communications controls and explicit changes | Present familiar user-facing behavior and keep the first audio feature focused | - -| D023 | User authorized the first audio-output implementation; keep documentation updated and the README clear and user-focused | Start with output dropdown, optional volume, direct Windows Apply, verification/recovery, and a responsive native window | - -| D024 | Audio presets is the main view; Add/Edit uses an editor page with Name and Save/Cancel; saved rows offer Apply/Edit/Delete | The prototype device controls belong in an editor. Saving stores choices without changing audio; only Apply executes them | - -| D025 | Keep machine-specific user settings under the Windows Local AppData known folder, in one Director subfolder | Audio endpoint IDs belong to this PC. Resolve the standard folder through Windows; keep settings out of the repository, Documents, Desktop, and home-folder root | - -| D026 | Replace the prototype layout with a compact workspace shell and selectable preset rows; use plus/Add, green check/Apply, pencil/Edit, and red cross/Delete with hover/focus states | User requested a designed main view with compact actions instead of separate text-button blocks per preset. Preserve the worker, storage, CLI, confirmation, and audio behavior | - -| D027 | Use WinUI 3 through Microsoft Windows Reactor as the only frontend; promote it to the main director executable and remove the previous frontend and parallel package | User compared the native controls and explicitly selected WinUI 3 on 2026-10-31. Keep the shared Rust engine, CLI, settings schema, and background execution | - -| D028 | Implement display presets as capture/save/view/rename/delete first; independent from audio and without a display Apply operation | User authorized capturing the current layout before implementing restoration, confirmation/reversion, or advanced controls. Preserve native UI behavior and existing settings | - -| D029 | Add native display Apply with validation, live snapshot, strict readback, a worker-owned 15-second Keep/Revert deadline, and automatic restoration | User authorized Apply and confirmation/reversion. Persist only verified confirmed changes; headless application uses the same engine and an explicit --yes automation option | - -| D030 | Adopt native per-monitor editor cards/map, visual Identify, explicit clone controls, later DPI scaling, headless scene shortcuts, later launch/restore-on-exit, and optional descriptions/icons | User accepted the comparison-inspired additions as backlog scope; wallpaper remains optional and implementation milestones stay separate | -| D031 | Rotation choices show a rotated display SVG with a top/up marker and a plain-language orientation label; degrees are secondary | User explicitly requested visual rotation choices because degrees alone do not communicate orientation | - -| D032 | Save a per-display-preset Ask to keep display changes preference, default on; CLI follows it with --yes/--confirm overrides | User wants to avoid repeated confirmation for trusted layouts. Opt-out skips only the prompt, preserving verification and failure recovery | -| D033 | Keep LG and Samsung projects as integration research references; Samsung support is deferred | User supplied lgtvcli and samsung-tv-control. No dependency, installation, cloud integration, or current Samsung implementation commitment | - -| D034 | Add Create preset and Customize layout with native per-monitor controls, supported modes, visual orientations, numeric placement, and a read-only preview | User requested custom creation; Save stays separate from Apply. Clone-group editing, drag/Identify, and advanced color/scaling remain deferred | - -| D035 | Use direct display Edit, a boxed draggable map with screen-detail tooltips, cohesive + toolbars/footers, and disabled primary enable control with a reason | User explicitly replaced Customize, numeric placement fields, and mismatched button positions. New GUI/CLI display presets default confirmation off; preserve existing choices. Supersedes the earlier default-on and preview-only parts of D032/D034 | - -| D036 | Remove visible preset Refresh buttons; compact and align orientation choices, remove icon arrows, and fix supported mode discovery | User requested cleanup. Clean page navigation already reloads data; match device paths without stored adapter LUIDs and retain unspecified DXGI scan-line modes | -| D037 | Add optional HDR state through HDR-specific Windows device-info APIs, verification, and recovery | Capability-gate the toggle, preserve legacy leave-unchanged behavior, and reject changes when prior HDR cannot be read | -| D038 | Add Current setup as an alternative combined display/audio page without preset persistence | User clarified active setup only, excluding appearance themes. Stage controls and Apply each category independently; share the editor/backend and preserve preset drafts | - -## Proposed or unresolved - -| Topic | Current proposal or open question | -| --- | --- | -| Scene references | Reference component IDs; edits propagate to dependent scenes; duplicate for independent variants | -| Rename/deletion | Editable names with stable internal IDs; prevent deletion that leaves dangling references | -| CLI | Audio presets now use `director audio apply "Headphones"`; display check/apply now exists; future scene command syntax remains open | -| Final-action gating | Skip launches if required configuration fails; determine behavior on a failure inside the final-action chain | -| Frame-limit implementation | Validate direct NVIDIA/AMD/Intel controls, capabilities, and modern limiter mappings; primary driver selection and optional external providers are already agreed | -| Additional configuration | Exact placement of frame-limit actions within the configuration stages; keep them before final launches | -| Action completion | Dispatch only initially, or optionally wait for executable exit; URI readiness cannot generally be established | -| Policy overrides | Whether failure behavior can be overridden per scene or CLI invocation | -| Notifications | Failure notifications by default, optional success notifications and quiet CLI flag | -| Display confirmation | Implemented 15-second native Keep/Revert deadline and per-preset opt-out; configurable timeout remains open | -| Operation ownership | GUI/CLI coordination, busy-request handling, cancellation, and interrupted operations | -| Reapplication | Reapply all steps versus skip verified unchanged state; optional toggle behavior | -| Additional scope | HDR, color depth, VRR, DDC, other TV brands, hotkeys, triggers, arbitrary scripts, import/export | -| Guided creation milestone | Required before 1.0 or later release | -| Distribution | Windows baseline, portable/installer model, update behavior, executable arrangement | -| Licensing | App license and third-party license notices | -| Performance | Measured budgets for startup, idle CPU, memory, and CLI startup | - -## Working rule - -Update this record when a decision is accepted or changed. Update [requirements](REQUIREMENTS.md) and the [architecture proposal](ARCHITECTURE.md) where affected. Keep unresolved proposals visibly separate from accepted behavior. - -### Proposed next feature: remembered monitor capabilities - -The user clarified that the powered-off LG report was a design question, not authorization to change inactive-TV behavior. The attempted inactive-mode filtering was reverted before release. Proposed handling: learn exact mode pairs and capabilities while the target is active; retain that last verified data while it is unavailable; label remembered choices; never overwrite a complete verified inventory with an off/standby/partial list. On arrival, re-enumerate and validate the selected mode before Apply. Missing or incompatible targets should produce a bounded wait/failure and use the selected recovery policy instead of silently substituting a lower resolution. Identity, cache invalidation, and first-observation behavior need agreement before implementing this feature. - -### D039 — TV setup and optional display association (2026-11-01) - -The user requested a native TV view for adding a controllable TV and asked whether it should link to a Windows monitor. Implement independent remembered LG TV definitions, explicit pairing/checking, and an optional Windows physical-display-path association. The association is metadata for later coordination, not a display-preset reference or current readiness signal. User questioning IP-based identity establishes the need to distinguish remembered TV identity/MACs from current connection IP; verified rediscovery/address migration remains proposed rather than silently guessing another TV. The first conservative endpoint-change pairing reset is documented. See TVS.md for actual implemented scope and unverified physical-device behavior. - -### D040 — Guided TV setup, MAC learning, and wake (2026-11-01) - -The user authorized a step-by-step Add TV guide, automatic MAC learning, and wake. Implement name → IP → pair/read → PC input → wake-address review/manual fallback → optional Windows display → review/save. Pair before saving and retain a successful pairing if later reads fail. Learn only TV-reported wired/Wi-Fi MACs, not a gateway/neighbor MAC. Existing TVs can read/store metadata without recreation. Provide direct GUI/CLI Wake-on-LAN dispatch with truthful results. Store PC/display connections as metadata; action choices, order, and readiness belong to future scenes, independently of pairing. - -### D041 — Advanced manual MAC entry (2026-11-01) - -The user requested an opt-in switch before showing/typing a manual MAC. Implement Enter MAC address manually, off for new setup and on when editing an existing manual address. Preserve draft text while hidden; ignore disabled manual validation and clear its saved target on Save/Next when off. Automatic TV-reported learning remains the default. - -Proposed next UI, not yet implemented: a small TV control modal with fresh status, Wake/Turn off, and input selection. The user asked whether the power control should turn an already-on TV off. Reported state supports this design; the existing Wake-only action is unchanged. Keep scene/CLI power actions explicit rather than toggling on each invocation. - -### D042 — Basic TV control modal and one power button (2026-11-01) - -The user approved a basic status/power/input modal and explicitly requested merging power controls into one state-aware button. Implement a TV-controls opener in the list, fresh status/current input, a single Turn off/Wake button, and explicit input selection plus Switch. On/awake states choose Off; Off/standby/unknown choose Wake with a known MAC. Recheck fresh state while honoring the displayed intent rather than reversing a stale click. Unknown is not Off. CLI/scenes retain separate wake/off/input operations. Setup remains connection metadata, without scene action preferences. Volume and full remote controls remain deferred. Panel-only on/off is not planned; see D049. - - -### D043 — Remote/bin SVGs and fewer TV maintenance buttons (2026-11-01) - -The user requested a remote-control SVG instead of a screen for TV controls, removal of Check connection/Pair again/Read TV details buttons, and a red bin instead of red X across the app. Apply stays unchanged pending a later decision. Share SVG action assets across all relevant views. Keep automatic setup reads; refresh paired-TV editor details in the background and retain offline editability. Changed endpoints continue through pairing setup without prematurely overwriting the stored TV. CLI maintenance commands remain available. - - -### D044 — Immediate, compact TV controls (2026-11-01) - -The user reported an oversized, clipped modal with a scrollbar crossing its controls, duplicated timeout diagnostics, misleading success wording, and a delay when an unreachable TV was checked. Open immediately and check independently in the background. Keep Wake and Close usable during reads; retain mutual exclusion and fresh checks for mutations. Wake dispatch is idempotent and does not need a preliminary network query. Show action completion before the separate status refresh. Ignore old read responses by dialog token/revision. Use compact native controls, hide unavailable input selectors, and disclose technical errors on demand rather than duplicating them on the page. Do not equate unreachable with off or add permanent polling. - - -### D045 — Local operation diagnostics and Options (2026-11-01) - -The user approved persistent rotating logs and requested that Open logs folder live in Options with other settings actions. Add a native Options footer/page and open the known Local AppData log folder through Windows. Share structured logging between GUI and CLI, recording UTC time, process/operation IDs, step outcomes, elapsed durations, and safe diagnostic errors. Use a bounded asynchronous queue and cross-process rotation lock; retain five 1-MiB files. Never record credentials or raw TV payloads. Preserve command diagnostics separately from a later status check so investigating a power failure does not lose its original cause. No remote upload or resident service is added. - - -### D046 — Command-aware TV power transitions (2026-11-01) - -The user approved Waking with a bounded readiness wait, Turning off followed by an explicitly assumed Off after acknowledgment, and selective rather than unconditional refresh. Keep the modal local state distinct from reported TV power. Poll only during wake, initially reading power alone; refresh inputs when awake. Use a 30-second retry window, two-second spacing and existing bounded native request deadlines. Stop retries when closed, superseded, awake or expired; keep Close available. Use typed command effects, update confirmed input selection directly, and reconcile only failures/uncertain results or explicit refresh. Keep command errors intact, do not interpret network failure as confirmed Off, and do not change CLI wake semantics or add resident polling. - - -### D047 — Optional TV setup guidance (2026-11-01) - -The user approved a small dismissible TV reminder during new display-preset creation, with Add TV and Don't show again, and asked for a restrained appearance. This implementation pass is limited to that guidance and draft-preserving TV navigation; temporary display activation/capability discovery remains separate future work. Use an inline neutral native card, not an interrupting dialog or warning. Show it only when preferences/catalog are loaded and no TV is already saved. Close dismisses for this session; Don't show again persists a per-user preference, reversible in Options. Add TV opens/resumes the existing guide without discarding the display draft. Linked monitor cards show the saved TV name and View TV navigation. No action in this guidance changes displays or contacts a TV. - - -### D048 — Inline temporary display detection (2026-11-01) - -The user authorized the complete display-detection workflow after accepting inline progress instead of a loading modal. Explain the temporary change in the selected monitor card and require Detect options before any setter. Provide explicit optional Wake and detect only for a linked, paired TV with wake/PC-input metadata. Snapshot the current layout before TV preparation, preserve existing active screens/primary, temporarily enable the target without persisting the topology, discover active capabilities, then restore and verify before publishing options. Cancellation, deadline, partial setter failure, inspection errors and panics must also pass through recovery. Keep a retryable snapshot when restoration fails and block saving/discarding that draft until restored. Cache only complete results by device path and label remembered offline choices. The retry deadline is cooperative; normal close protection is not a crash/force-kill watchdog. - - - -### D049 — Screen blanking removed from future scope (2026-11-03) - -Screen off/on or panel-only blanking is not a planned or deferred feature. Reconsider it only after an explicit user request. Reading and displaying a TV-reported Screen Off power state remains valid and does not add a blanking control. - - -### D050 — Optional communications output and microphone - -The user superseded the earlier communications deferral: output presets assign all three Windows roles to the main output by default. An optional separate communications output reveals its own picker and overrides only that role. Microphone settings remain untouched unless Change microphone is enabled; selected capture roles follow that input and its volume remains independently optional. Preserve the same semantics in GUI/CLI and full transactional preflight/recovery. TV-to-HDMI-audio association is a metadata proposal requiring verified mapping or explicit confirmation. - -### D051 — Remembered TV audio and scene execution (2026-11-03) - -The user authorized linking and scenes. Implement explicit endpoint selection as optional TV metadata, preserving unavailable links and leaving switching to an audio preset or scene. Do not infer identity from matching names/shared GPU. Scenes compose stable references with optional TV readiness/input, displays, audio and ordered app/URI dispatch. Share one locked GUI/CLI runner, default to actual Windows-state recovery, retain an opt-in keep-completed policy, and clearly exclude TV/app side effects from automatic recovery. Screen blanking remains outside scope. - -### D052 — Samsung direct commands only (2026-11-03) - -The user rejected custom key sequences. Future Samsung integration must use direct supported commands, without menu navigation sequences or silent macro fallback. ColorControl is an additional protocol reference; model-specific support remains to be validated. See INTEGRATION_REFERENCES.md. - -### D053 — Hide unsupported TV controls (2026-11-03) - -The user requires unsupported TV controls to be omitted from the UI, rather than displayed as unavailable/disabled buttons. Apply this to the TV control panel and scene action choices. This differs from a supported action temporarily busy or disconnected, which still needs truthful operation feedback. Samsung remains unimplemented; the proposed initial scope is direct local pairing, remembered authorization, Wake-on-LAN, reported power state and guarded turn-off. Direct input switching requires model-specific verification and no sequence fallback. - -### D054 — Samsung implementation and friend compatibility testing (2026-11-03) - -The user authorized Samsung implementation with the optional setup test/report flow. Pair locally by selected brand, preserve existing LG records, use direct commands only, and expose Samsung HDMI controls only after a sent test and explicit user confirmation for the current model/firmware. Failure or unconfirmed results keep controls hidden; fresh metadata changes invalidate confirmations. Export only an allowlisted redacted report, with no automatic sharing. Samsung remote commands are Sent rather than TV-acknowledged. Report actual power fields, guard KEY_POWER with fresh state and keep Unknown honest. Physical Samsung validation is required before claiming model compatibility. - -### D055 — TCL Android / Google TV friend preview (2026-11-03) - -The user approved TCL as the last additional brand in this round. Support the Android TV Remote v2 platform, code pairing, explicit wake/sleep, reported power, single direct HDMI tests with visual confirmation, redacted reports and existing scene/display/audio integration. No ADB, custom sequences, generic remote panel or screen blanking. Android TV service version must not be presented as confirmed TV firmware. Hardware compatibility remains pending the friend’s test; no claims for TCL Roku/Fire TV. - -### D056 — Readable friend guides and self-contained test reports (2026-11-03) - -The user requested short nontechnical Samsung/TCL instructions and a report with sufficient diagnostic context. Keep the friend guides focused on adding/pairing, direct HDMI, physical power checks and sending one JSON. Move implementation details to separate technical notes. Report explicit tester observations without assuming command success; collect typed sanitized per-TV history, runtime/build context and wake configuration, never raw logs or credentials. Report export must work on failed pairing as well as successful setup/Edit. - -### D057 — NVIDIA/RTSS global FPS controls (2026-11-03) - -The user approved global NVIDIA and optional RTSS providers, scene placement after audio and before launches, and direct Current setup/CLI application. Switch off means unchanged; disabling the global cap is an explicit selected action. Never fall back to another provider or alter competing limiters/game-specific overrides. Use direct installed DLL interfaces, snapshot/readback/restore and the existing scene failure policy. Driver configuration verification is distinct from measuring a game. Per-game targets remain later work. - -### D058 — Scenes / Now / Library navigation (2026-11-06) - -The user found the flat navigation (Scenes, Current setup, Audio presets, Display presets, TVs) disorganized and chose grouping into three areas. Scenes becomes the start page, Current setup is renamed Now, and the presets and TVs sit under an expandable Library item. Now can seed new Library presets, and the scene editor can create a missing preset or TV in place and return with it selected. Storage formats, CLI names and scene execution are unchanged. - -### D059 — Step-flow scene editor, Before/Leave actions and global failure policy (2026-11-06) - -The user found the scene form indistinguishable from Now, the side summary redundant, and per-scene recovery settings out of place. Scenes are now edited as a vertical flow of step blocks. Scenes gain Before actions (apps can wait for completion) and When leaving actions, plus a Close app action. Leave actions run when another scene is applied or the active scene is ended. Director remembers the active scene across the window and the CLI until the PC restarts. "Keep completed changes" and the device wait became one global Options setting shared by scenes and audio presets. The scenes file moved to version 2; version 1 still loads. - -### D060 — VRR-safe FPS cap, linked TV audio volume and a Windows 11 title bar (2026-11-06) - -The user asked for a VRR-safe FPS cap and chose the Reflex-style formula refresh − refresh²/3600, read from the primary display when applied (after a scene's Displays step). The FPS editor shows only the selected method's current value and names its choices "Set a frame rate limit" and "Remove the global limit". A scene's linked TV audio can now set a volume. The app name and pane toggle moved into a WinUI 3 TitleBar, so the navigation pane starts with the pages. - -### D061 — TV off when leaving, End beside +, shortcut commands and Save only on change (2026-11-06) - -The user wanted scenes to switch the TV off, chose a switch in the Prepare TV step that shows a locked "Turn off" card under When leaving, and asked that End appear only when leaving does something, next to + as a global action. Cards gain a ">_" button with copyable commands by name and by ID (for Stream Deck and shortcuts, using `director` on PATH); display and audio CLI commands accept IDs. The audio editor no longer shows the device ID. Save is enabled only for changed, valid drafts. - -### D062 — Local crash reports offered as GitHub issues (2026-11-06) - -Opening a scene step with actions closed the window: the pinned Reactor rejects tooltips inside a ContentDialog, and nothing recorded the failure beyond one log line. The user asked why crashes aren't collected so people can report them. Director now saves a local crash report for panics and fatal window errors and offers it once on the next start. Report on GitHub opens a pre-filled issue in the browser, so nothing is uploaded without the user submitting it; the log lines stay in the file for the user to attach. A test keeps tooltips out of dialog content. - -### D063 — Onboarding starts from the current setup (2026-11-06) - -The first-run checklist sent people to Now and to each Library page before they knew what a scene was, and its buttons were mismatched page names. The user asked for a better start that explains a scene for the everyday setup. The empty Scenes page now saves the current screens, sound and FPS limit as one scene (checkboxes, default name Default), reusing matching presets and changing no device, then shows a dismissible tip for making the next scene in the step editor, which can create presets in place. - -### D064 — Windows 11 24H2 is the minimum (2026-11-06) - -Director declared no Windows support: no app manifest (so version APIs reported 6.2.9200), no installer check and no documented baseline. HDR switching needs display-configuration requests added in Windows 11 24H2, and only current Windows 11 is tested, so the user chose 24H2 (build 26100) as the minimum rather than a partly working Windows 10 install. The executable embeds a manifest (Windows 10/11 supportedOS, maxversiontested 10.0.26100.0, per-monitor v2 DPI), and setup.exe and the MSI refuse older builds. - -### D065 — CLI names, and `list` in every area (2026-11-06) - -Commands found items by name ignoring case, so any name with a space needed quotes, and the shortcut dialog copied commands such as `director scene apply "TV ""Gaming"""`. Lists were also inconsistent: `audio list` printed devices while `scene list` and `tv list` printed saved items, display presets were under `display presets`, and there was no way to see everything at once. - -Every scene, preset, TV, screen and audio device now has a CLI name derived from its name: lowercase letters and digits, with each run of other characters replaced by one dash ("Desk View" is `desk-view`). It is computed rather than stored, so no file format changed and renaming updates it. Lookups accept an exact ID first, then anything that normalizes to the same CLI name, so older quoted commands keep working. Saving a new or renamed item whose CLI name is empty or already used by another item of the same kind is refused (the user chose this over auto-numbering, which would let names shift as items come and go). Existing files with a clash still load; looking up the clashing name reports both IDs. - -`director list` prints every category, and each area has `list` for its saved items: `scene list`, `display list`, `audio list`, `tv list`, plus `display screens`, `audio outputs` and `audio inputs` for devices. All take `--json` with a `cli_name` field. The user accepted that `audio list` now lists audio presets instead of output devices (use `audio outputs`); `audio presets`, `display presets` and `display current` remain as aliases. D066 later retired audio presets: `audio list` prints outputs and inputs, and `audio presets` was removed. - -### D066 — Live sound controls; scenes hold their sound; audio presets retired (2026-11-06) - -Audio mixed two jobs. `audio apply` took either a preset or a raw endpoint ID with `--volume`, Now ran a live change through the full preset transaction behind an Apply button, `audio volume` was the only real live command, and nothing could mute. Scenes pointed at audio presets by ID and also carried a separate `tv_audio` / `tv_audio_volume` special case. - -The user wants to change the active device and volume easily without a preset, and have scenes keep their sound. Sound is now split in two: - -- **Live controls** (`audio_control`) change one thing right away: make a device the default (all roles, or one), set or step the volume (35, +5, -5), and mute, unmute or toggle, for the output or the microphone. No device means the current default. Each change is verified and put back when Windows does not confirm it. Now's Sound card uses them directly (no Apply button; sliders send their level once they rest), and so do `director audio status | use | volume | mute | unmute | mute toggle` with `--mic`. -- **A scene's Sound step** holds its settings inline: an output device or a TV's sound, volume, mute, an optional calls device and an optional microphone with its own volume and mute. It replaces both the audio preset reference and the linked TV audio fields, and runs through `audio::apply` as part of the scene's transaction, which now snapshots and restores mute too. - -The user chose to retire audio presets rather than keep them as an optional choice: a scene with only a Sound step does everything a preset did, including Stream Deck use through `director scene apply`, and sharing one sound setup across scenes was rare. The Library Audio page, `audio apply`, `audio presets` and the scene editor's "New audio preset…" are gone; Now's save button opens a new scene instead. Breaking changes were acceptable because nobody else uses the app yet. - -Scene files move to version 3 and backups to version 2. Version 1–2 scenes migrate when they load: an audio preset reference becomes the preset's output, volume, calls device and microphone (read once from `audio-presets.json` or, for a backup, from the backup's own presets), and linked TV audio becomes the TV's sound with its volume. A preset that can't be found leaves an empty Sound step that the scene card reports. Scene cards show the scene's main change at the top, so a sound-only scene shows its output and volume rather than an empty display box. Settings-file helpers moved from `presets.rs` to `storage.rs`. - -### D067 — TV input protection runs beside the scene (2026-11-06) - -TV boxes on HDMI-CEC take the input while a TV wakes, even when they didn't wake it. The user wanted the scene to win without waiting for the fight to end. After the TV reports the scene's input, a background guard (`tv_input_guard`) polls it for a configurable time (Options, default 10 s, 0–60, 0 off) and switches back, at most every 1.5 s, while displays, sound and apps continue. Only TVs with input readback (LG) get one: without readback a steal can't be seen, and blind resends could fight the user. One guard at a time; every other TV power or input request, a new scene and a restoring scene stop it first, so it never fights the user, including from another process (a Stream Deck `director tv input` while the app guards). Across processes this goes through a marker file holding the guard's token, which any TV request deletes: no new Windows API features were needed, and a guard left behind by a crash costs nothing. The preference is written only when changed, so older builds still read the file. - -### D068 — One page vocabulary and a flat sidebar (2026-11-06) - -A UI pass found pages each rolling their own headings, footers, widths and hardcoded greys, which also looked wrong in Light theme. Pages now share `src/ui.rs` (type ramp, spacing, radii, theme brushes, page, section, card, setting and footer builders). With audio presets retired, Library only held Displays and TVs, so the sidebar lists Scenes, Now, Displays and TVs directly; Options stays a footer button (reactor 0.100 has no footer menu items) drawn with the same selection pill. Now applies its staged display and FPS edits from one footer button, displays first and the FPS limit only after the display change succeeds, instead of two Apply buttons in different places. diff --git a/docs/DESIGN.md b/docs/DESIGN.md index e07c376..ef4db8a 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -1,177 +1,74 @@ # Director interface -## Design system — current +Director uses genuine WinUI 3 controls through Microsoft Windows Reactor and follows the system theme, accent, fonts, focus and scrolling. Custom drawing is limited to layout previews and the display arrangement map. The default client size is 1000 × 700 DIP, minimum 760 × 600. -Every page is built from `src/ui.rs`, so pages line up and follow the system theme: +## Design system + +Every page is built from `src/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. -- **Colour** comes from theme brushes: card fill and stroke, critical red and the accent. Translucent greys mark inner panels, dashed outlines and the arrangement map, so they read on light and dark. Layout previews keep one fixed set of screen colours. +- **Colour** comes from theme brushes: card fill and stroke, critical red and the accent. Translucent greys mark inner panels, dashed outlines and the arrangement map, so they read in Light and Dark. Layout previews keep one fixed set of screen colours. - **Page**: fixed header (title, one-line subtitle, actions at the top right), scrolling body with a scroll-bar gutter, and an optional fixed footer: a hint on the left, Cancel then the accent action on the right. - **Section**: a subtitle with an optional quiet action beside it (Save as…), a one-line description, then the content. Forms stay within 650 DIP; monitor cards use up to three columns of about 400 DIP. - **Settings**: Options uses Windows-Settings-style cards, each with a title and description on the left and its control on the right. -- Empty states use one helper: a subtitle, a line of explanation and at most one button. - -## Navigation — current - -The pane lists Scenes, Now, Displays and TVs, with Options in the pane footer. The Library group was removed once it only held Displays and TVs. Reactor 0.100 has no footer menu items, so Options is a button styled like a navigation item that shows the same selection pill and fill when open. This supersedes "Library is an expanded, non-selectable parent item" below. - -## Display editor — current - -The arrangement map follows Windows Settings › Display: it is centred, spans the editor (up to 1000 DIP) and is 280 DIP tall. Pressing a screen selects it, drawn in the accent colour, and its card below gets an accent outline; dragging still moves it. A display dropped away from the others moves back to share part of an edge with the nearest one, as in Windows. On Now, Discard and **Apply changes** sit in the map's bottom-right corner, where Windows keeps its display actions, in a strip of their own under the screens with a solid backing so no screen is drawn behind them. - -Every display has a card: its name with Primary or Make primary and the On switch, then Resolution beside Refresh rate, Desktop mode beside Orientation, and HDR. A one-display, Windows-style layout was tried side by side and not kept. - -## FPS card — current - -FPS limit is one card, kept to the form width: its title and current state on the left and the switch on the right, then Method beside Limit and Frames per second beside VRR-safe cap, always shown, with one caption. While the switch is off the controls are greyed out and show what turning it on would use, so switching it on never changes the page's height. On Now, a staged change says it waits for Apply changes on the display map. A scene's FPS step uses the same controls without the card. - -## Now — current - -Now has no page title (the sidebar already says Now). It starts with Displays and the FPS card, which stage edits for **Apply changes** in the map's corner; then a divider captioned "Sound changes below apply right away"; then Sound, which applies each change as it is made. At the bottom of Sound, the "Different device for calls" switch enables the calls output picker beside it (always shown, greyed out while off, so nothing moves), which sets only Windows' communications role; it is on when Windows already sends calls elsewhere, and turning it off sends calls back to the main output. Apply changes applies displays and then, if that succeeded, the FPS limit; Discard rereads Windows. Save as display preset… and Save as scene… sit beside their section titles. Save as display preset… asks only for a name in a dialog (errors such as a clashing name show in the dialog, which keeps the name), saves the layout shown, including unapplied edits, and then opens the Displays list with a "Saved" confirmation; Now keeps its staged edits. Save as scene… copies the output and microphone with volume and mute and opens the new scene on its Sound step dialog. Mute buttons read Mute or Unmute with matching icons. This supersedes "Keep separate Apply display changes and Apply audio changes actions, plus Discard edits" below. - -## Information architecture (earlier) - -The navigation pane has three areas. Scenes is the start page (except when opened from a failed-scene notification, which opens Options). Now (formerly Current setup) adjusts the live setup without saving. Library is an expanded, non-selectable parent item with Displays, Audio and TVs. Options stays in the pane footer. Each area has its own icon; Displays and TVs no longer share one. - -Pages connect forward instead of being islands. Now offers Save as display preset… and Save as audio preset…, which open the normal Library editor seeded from the staged state. The last entry of each scene-editor dropdown (New display preset…, New audio preset…, Add TV…) opens the Library editor and, after Save, returns to the scene with the new item selected; Cancel also returns. A sidebar navigation abandons the return. An existing open Library draft is never overwritten: the user is sent to finish or cancel it. The empty Scenes page is a checklist of the building blocks, linking to Now and the Library. This supersedes "Audio presets is the main NavigationView page" below; the page names in older sections refer to Library › Audio, Library › Displays and Now. - -## Leaving a page with unsaved changes — current - -Choosing another category in the navigation pane, or Options, while the current editor has unsaved changes opens a dialog: Save, Discard or Keep editing. Unsaved means the draft differs from how it was when it opened; data that loads into an opened draft (supported display modes, live TV details) doesn't count. Save appears only when the draft can be saved: not in the TV setup guide, and never for Now, whose edits are applied rather than saved, so Now offers Discard or Keep editing. A failed save keeps you on the page with its error. Links inside an editor that return to the draft (Manage presets, View TV, New … preset) don't ask. An unchanged draft stays open when you leave, as before. +- **Empty states** use one helper: a subtitle, a line of explanation and at most one button. +- **Icons**: the green check applies, the pencil edits, the shared red bin deletes, and the remote-control SVG opens TV controls. Every icon button has an accessible name and a tooltip, except inside dialogs (see below). -## Scene editor — current +## Window and navigation -A scene is edited as a vertical flow of fixed-size step cards in run order (Before, Prepare TV, Displays, Audio, FPS limit, After) joined by small down arrows, with When leaving set apart below under its own label. A card shows an icon, the title and a one-line summary, with a pencil and a bin. The card or its pencil opens the step's controls in a dialog: Done keeps the changes and Cancel restores the step as it was when the dialog opened. Nothing in the flow expands, and the column has a fixed width (720 DIP, or less in a narrow window), so the overview never changes size. Empty steps are dashed outlines the same size as filled cards, with the step's muted icon, a one-line hint and an Add button; they open the same dialog. Every card shares one icon column, and the arrows between steps are centred on it. Leaving the page from inside a dialog (New … preset, Manage) closes it and keeps the edits. There is no side summary panel: the flow is the summary. Failure policy and device wait live in Options, not in the scene. Scene cards mark the active scene and offer End beside Apply. See [Scenes](SCENES.md). +The window uses WinUI 3's TitleBar, like Windows 11 Settings: the pane toggle and "Director" sit in the title bar next to the caption buttons. The navigation pane lists **Scenes** (the start page), **Now**, **Displays** and **TVs**, with **Options** in the pane footer. Reactor 0.100 has no footer menu items, so Options is a button styled like a navigation item with the same selection pill. -## Scenes first run — current +Pages connect forward instead of being islands. The last entry of each scene-editor dropdown (New display preset…, Add TV…) opens that editor and, after Save, returns to the scene with the new item selected; Cancel also returns. An open draft is never overwritten: you're asked to finish or cancel it first. -With no scenes, the Scenes page shows one card, "Start with your everyday setup", instead of the old four-step checklist and its page buttons. It reads the current screens, default output and volume, and the global FPS limit, and shows each with a checkbox (all on) and a live summary. A name box defaults to "Default", and one accent button, "Save as my Default scene", saves it; a quiet "Build a scene from scratch instead" link opens the editor. Saving changes no device and reuses a saved preset when the layout, or the output and volume, match exactly. It never sends people to Now: the step editor creates presets in place. While only one scene exists, a slim tip above the cards explains making the next scene, with "Got it" stored in preferences. See [Scenes](SCENES.md). +**Leaving with unsaved changes.** Choosing another page while the current editor has unsaved changes opens a dialog: Save, Discard or Keep editing. Unsaved means the draft differs from how it opened; data that loads into an opened draft (display modes, live TV details) doesn't count. Save appears only when the draft can be saved, so the TV setup guide and Now offer only Discard or Keep editing. -## Status area — current +**Save** is enabled only when the draft is valid and has changed, or is a new item that isn't saved yet. The footer says "No changes to save." meanwhile. Saving never applies anything; only Apply changes devices. -The bottom status area is hidden when nothing needs attention. Work in progress shows one muted line with an indeterminate progress bar. A finished action shows a closable Success InfoBar that hides itself after 5 seconds. Something the user must read (an open draft blocking a flow, a cancelled pairing that left permission on the TV, unavailable live TV data) shows a Warning InfoBar that stays until closed. Errors stay red until closed. Routine hints such as Ready., Draft updated or Edit TV. are recorded for diagnostics but not shown; editor footers already explain save-versus-apply. This supersedes the earlier always-open InfoBar. +**Status area.** Hidden when nothing needs attention. Work in progress shows one muted line with an indeterminate progress bar. A finished action shows a Success InfoBar that hides after 5 seconds. Warnings you need to read stay until closed, and errors stay red until closed. Routine hints are logged, not shown. -## Save and shortcut commands — current +## Scenes -Save is enabled only when the draft can be saved and has changed: it differs from how it opened, or it's a new item that isn't saved yet (a draft seeded from Now counts). Data that loads into an opened draft doesn't count as a change. The scene editor's footer says "No changes to save." meanwhile. +With no scenes, the Scenes page shows one card, "Start with your everyday setup". It reads the current screens, default output and volume, and the global FPS limit, shows each with a checkbox and a live summary, and saves them as a scene named Default. Saving changes no device and reuses a saved display preset when the layout matches. While only one scene exists, a slim tip above the cards explains making the next one. -Scene, display and audio cards have a borderless ">_" (CommandPrompt glyph) button right after the name. It opens a dialog with the command by CLI name (unquoted, for example `director scene apply tv-gaming`) and by ID, each in selectable text with a Copy button and a one-line subtitle, plus `director scene end` for scenes that do something when left. +Scene cards show the scene's main change at the top: the layout miniature when it has a display preset, otherwise a 124 px panel with a large icon and the main value (the output and a volume bar, the TV and its input, the FPS limit, or the number of actions). A fixed slot before the name holds the Active dot. The ">_" button after the name opens a dialog with the command by CLI name and by ID, each with Copy, plus `director scene end` for scenes that do something when left. -## Title bar — current +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). -The window uses WinUI 3's TitleBar, like Windows 11 Settings: the pane toggle (☰) and "Director" sit in the title bar next to the caption buttons, and the navigation pane starts directly with Scenes. NavigationView has no pane title and hides its own toggle. +**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. -## Native Windows workspace +## Now -Use genuine WinUI 3 controls through Microsoft Windows Reactor. Follow the system theme, accent, fonts, hover, focus, scrolling, and control behavior. Keep custom painting and custom interaction machinery out of core controls. +Now changes the live setup without saving anything. It has no page title. It starts with Displays and the FPS card, which stage edits until **Apply changes**; then a divider captioned "Sound changes below apply right away"; then Sound. -Audio presets is the main NavigationView page. Use a compact ListView with one selectable row per preset and an Add/plus control. Each row has visible native icon buttons: green check for Apply, pencil for Edit, red bin for Delete. Accessible names and native tooltips explain each action. Selection alone never applies anything. Deletion uses a native ContentDialog. +- **Apply changes** and **Discard** sit in the arrangement map's bottom-right corner, where Windows keeps its display actions. Apply changes applies the displays and then, only if that succeeded, the FPS limit. Discard rereads Windows. +- **Sound** has an output picker, a Mute/Unmute button and a volume slider, and the same row for the microphone. Each change applies at once. "Different device for calls" enables a calls-output picker beside it (greyed out while off, so nothing moves) that sets only Windows' communications role. +- **Save as display preset…** asks for a name and saves the layout shown, including unapplied edits. **Save as scene…** opens a new scene on its Sound step with the current output and microphone. -Add/Edit stays in the same window: name TextBox, output ComboBox, optional Set volume ToggleSwitch and percentage NumberBox, and Save/Cancel. Saving stores choices only; Cancel discards the draft. The endpoint ID is not shown (it was noise for most people); `director audio outputs` prints it. Failure policy is global in Options. +## Display editor -InfoBar communicates status and errors. Disable mutations while work is active, keeping the UI responsive. Deferred features must not pretend to work. The default client size is 1000 x 700 logical pixels, minimum 760 x 600. Scroll constrained list/editor content, keep actions reachable, and make full device identity available on demand. +The arrangement map follows Windows Settings › Display: centred, up to 1000 DIP wide and 280 DIP tall. Pressing a screen selects it in the accent colour and outlines its card; dragging moves it with pointer capture and a stable scale. A screen dropped away from the others moves back to share part of an edge with the nearest one. Edits stay in the draft until Save or Apply; no gesture calls a Windows setter. -## Validation boundaries +Every display has a card: its name with Primary or Make primary and the On switch, then Resolution beside Refresh rate, Desktop mode (extend or mirror) beside Orientation, and HDR when the display supports it. Mirrored outputs share one map tile. The primary display's On switch is greyed out, with the reason on a hover layer above it. Orientation choices show a monitor SVG rotated to that orientation (the stand marks which way is down) beside Landscape, Portrait, Landscape flipped or Portrait flipped. -Check native accessibility names/actions, dropdowns, disclosure state, optional volume drafts, Add/Edit/Cancel, duplicate errors, delete confirmation, persistence, and default/narrow layouts. Temporary test data must be removed. Record actual results in [implementation status](IMPLEMENTATION.md); do not infer physical audio success or real pointer/keyboard behavior from automation alone. +Each card offers **Detect options** when Windows hasn't exposed a display's modes yet. The card explains the temporary change first, then shows progress, the current phase and Cancel inline, with no popup. Failures stay in the card and offer Restore previous layout when needed. See [Display setup](DISPLAYS.md#screens-that-are-off-or-not-detected-yet). -The user compared the native frontend on 2026-10-31 and explicitly selected WinUI 3 as the only interface. That selects the framework; it does not establish that every feature, accessibility path, or hardware recovery case is verified. -## Display presets +Display preset cards show a miniature of the saved layout with grouped mirror numbers and a legend (resolution, refresh rate, HDR); disabled screens are listed as Display off. Selecting a card never applies it. -Use the same native navigation/list/editor/dialog vocabulary as audio. Use the accent + for creation and the secondary capture icon for quick snapshots. Each saved row exposes the same green Apply checkmark as audio, plus Edit and Delete. New presets keep verified changes automatically. When confirmation is enabled, a native Keep/Revert dialog has a live 15-second countdown; lack of confirmation restores the previous layout. Unchanged layouts report already active without a dialog. Capture initially shows a read-only monitor summary. The + and Edit open native per-monitor cards and the interactive arrangement map directly; Save and Cancel remain fixed below the scrolling editor. Preserve independent drafts across page switches, constrain scrolling, and test default/narrow sizes, empty/error states, cancellation, duplicate names, persistence, and audio isolation. This extension follows the ui-design product/craft guidance using the established native app; no external reference retrieval is needed. +## FPS card -## Per-monitor editor and remaining additions - -Use the established native WinUI vocabulary for an arrangement map plus per-monitor cards. Keep resolution, refresh rate, rotation, enabled state, and primary selection discoverable; use supported-value dropdowns and refresh dependent options when resolution changes. Primary selection is exclusive across enabled desktop sources. Expose Extend/Clone grouping explicitly. Advanced DPI/HDR/color/identity controls must not overwhelm the main task or silently override omitted settings. This editor belongs to display presets; scenes select reusable presets and actions. - -Rotation dropdown entries must show a display SVG rotated to the corresponding orientation, with the monitor stand as the orientation reference. Pair the graphic with Landscape, Portrait, Landscape flipped, or Portrait flipped; degrees are supporting detail. The stand distinguishes flipped orientations; do not add an arrow inside the display. Keep native keyboard/accessibility labels and preserve Save versus Apply semantics. - -The extended-layout editor, draggable map, supported-mode dropdowns, primary/enabled controls, and SVG orientation choices are implemented. Coordinates are screen-tooltip information. Physical Identify, clone-group editing, and DPI/color controls remain deferred; HDR is now capability-gated. -## Cohesion and direct manipulation — current - -Audio and display list pages use one shared heading/toolbar component. Keep the accent + at the top right in the same position. Do not show Refresh buttons; clean pages reload on navigation. Display capture is a secondary camera icon immediately before the display +. Remove duplicate text Add buttons from empty states. Both edit footers place Cancel then Save on the right, with the save-only explanation on the left. - -The display pencil opens the complete editor directly. There is no Customize layout step. A boxed map supports pointer-captured dragging with stable scale during the gesture, edge snapping, and overlap handling on drop. Show technical position details in screen hover tooltips, rather than numeric fields. Keep the primary display's Enabled switch greyed out and put the reason on a transparent, enabled hover layer above it so it can still be hovered. New GUI and CLI presets default to confirmation off; preserve existing choices. - -## Current setup alternative (now "Now") - -Now puts the shared monitor editor and audio output/volume controls into one scrolling page. Keep separate Apply display changes and Apply audio changes actions, plus Discard edits. This view neither edits nor saves preset documents. Stage edits before Apply; preserve pending edits across navigation. New page roots prevent native scroll state from leaking across pages. Theme/appearance switching was explicitly excluded by the user. - -Orientation choices use equally sized compact rows, left-aligned icon/text, stand-only SVGs, and a standard chevron. Re-key the picker after selection so its native flyout closes, including when choosing the current orientation. - -## Proposed overview refinement (deferred) - -The user suggested monitor drawers/expanders that open and close from the overview. Record this for a later layout pass; feature support takes priority now. No overview drawer redesign is authorized by that suggestion alone. - -The HDR availability explanation is tooltip content, not a permanent subtitle. An enabled transparent layer over an unavailable HDR switch owns the reason tooltip so a greyed control can still explain itself. +FPS limit is one card at form width: title and current state on the left, the switch on the right, then Method beside Limit and Frames per second beside VRR-safe cap, always shown. While the switch is off the controls are greyed out and show what turning it on would use, so the page never changes height. A scene's FPS step uses the same controls without the card. See [FPS](FPS.md). ## TVs -Use the same shared page heading, top-right accent +, compact native list, pencil, bin, fixed Cancel/Save footer, and deletion dialog. Pair and connection-check actions have accessible names and native tooltips. Never contact a TV just by navigating, selecting a row, saving, or editing a Windows display link. Pairing is an explicit background operation with an on-TV approval instruction and a bounded wait. Check stays disabled until a pairing is saved. Display links are optional device metadata, independent of presets; disconnected links remain visible. Keep independent TV drafts across navigation. Do not label saved pairing as currently online. Legacy unencrypted mode requires explicit selection and explanation. - -## TV setup guide and wake - -Add TV now uses seven native steps: name, IPv4/connection method, explicit pairing plus automatic input/network reads, PC input, wake-address/manual fallback, optional Windows display, and review/save. Use the shared heading with a step counter, a constrained scroll area, and fixed Back/Cancel/primary controls. Preserve progress across Back/navigation. Pairing runs before saving; successful pairing survives a later input-read failure. Invalid/incomplete steps stay gated. A refused MAC read is a warning with manual entry or skip available. - -Existing TVs retain a compact metadata editor with Read TV details. Add a power-icon Wake action to the list, disabled without a stored MAC. Report Wake request sent rather than physical power state. Setup stores device connections and identities; scene action preferences stay separate. Finishing setup does not switch input, wake, or change displays/audio. - -Manual MAC entry is an advanced opt-in ToggleSwitch, off for new setup. Reveal the field only when enabled; reopen existing manual configurations enabled. Preserve hidden draft text, gate validation only while enabled, and leave learned MACs untouched. The explicit Wake action remains unchanged; status-aware power controls belong to the proposed basic control modal. - -## Basic TV control modal - -The row’s remote-control SVG opens a native ContentDialog, replacing the previous Wake-only icon. Show fresh status and a refresh icon, one power button with explicit action text, current input, a target dropdown, and Switch input. Keep normal state compact; show progress/results/errors only when useful. Do not apply on selection or change stored PC/display mappings. On/Screen off/Screen saver uses Turn off; Off/Standby/Unknown uses Wake with a saved MAC. Never label an unreachable device Off. Preserve the displayed action’s intent if status changes during the fresh check. - -Keep Close controls accessible at the minimum window size. Work runs in the background; while pending, disable action controls and retain window close protection. Closing the modal does not cancel an already-issued command. No permanent polling/tray process. Use native accessible action names (Turn off TV/Wake TV) and explain unavailable wake data. CLI/scenes remain explicit actions rather than alternating power toggles. - - - -## Shared action SVGs and TV action cleanup - -Use one shared red bin SVG for Delete/Remove across audio presets, display presets, and TVs; keep existing accessible names, hover labels, and confirmation dialogs. Apply remains the existing green check, explicitly unchanged by user request. The TV row has three actions: remote-control SVG, pencil, bin. Remove standalone Pair again/Check connection actions and the editor’s Read TV details button. Pairing and initial reads stay in the guide, with Retry only for a failed guide information read. Paired-TV edit refreshes available data automatically, preserving saved choices when unavailable. Connection changes route through the guide before final save. - - -## TV control responsiveness — current - -The modal opens immediately into Checking, without making the whole application busy. Keep Close and Wake (when a MAC is saved) usable during a read. Read-only refresh is separate from mutation progress, and stale responses cannot replace a newer action or reopened dialog. Use a 340-DIP content column, compact power/status row and an input selector beside Switch. Hide empty selectors. No outer scrollbar crosses controls. Keep diagnostic errors behind Technical details; a bounded scroll area belongs only inside that disclosure. Modal progress/results remain local rather than duplicating InfoBars behind the dialog. Mutations still use the shared lock and close protection. This supersedes the earlier instruction to disable all controls for status reads. - - -## Options and diagnostics - -Keep application options separate from device controls. The lower navigation footer exposes Options with a native gear/button; its page contains Diagnostics and Open logs folder. Use the same native typography, accent and constrained/scrollable content conventions as the other views. Show a known logging failure in this area rather than adding diagnostic controls to TV rows or modals. Preserve the original TV command diagnostic when an automatic status refresh completes or times out. - - -## TV power progress — current - -Use Waking… consistently for a pending wake, Turning off… for a pending off, and Off · assumed after an accepted turn-off. Keep one power control; disable repeated commands/refresh during the transition and retain Close. Replace unavailable input controls with a short explanation. Expired wake waits show Not responding yet/Not awake yet with Retry wake. Confirmed input changes update in place; do not flash Checking or clear unrelated controls after every command. Automatic readiness checks belong only to power-on transitions, and one-off recovery checks to uncertain commands. Diagnostic details stay collapsed and command/status causes stay separate. - - -## Optional TV setup tip - -New display presets may show a compact neutral card above the name field: Setting up a TV?, a short optional explanation, Add TV, Don't show again, and an accessible close button. Match existing native typography, muted foreground, border radius and button styles. Avoid warning colors, automatic dialogs or entrance animations. The card is absent while preferences/catalog load, when a TV is already saved, when editing an existing preset, or after dismissal. Show linked TV metadata and a View TV action in the appropriate monitor card instead of another reminder. - -Opening TV setup preserves the complete display draft. Close dismisses the card for this session; Don't show again persists under Windows Local AppData. Options → Show TV setup tips restores it. Existing TV drafts resume rather than being overwritten. Capability detection, temporary activation, remembered modes and automatic wake/input preparation are still proposed display-setup work; the tip does not claim those are implemented. - - -## Inline display detection — implemented - -Each preset monitor card offers Set up this display/Detect display options. Its inline explanation describes temporary enabling, flicker and restoration before the user starts. Linked TV preparation is an explicit alternate action. Progress replaces stale settings and instructions inside the same card, showing a native indeterminate bar, current phase and Cancel detection. No loading popup is introduced. On success, the restored-layout result leads into real detected resolution/rate/HDR controls; remembered choices are labeled when inactive. Failures stay local to the card, retain recovery state and offer Restore previous layout when needed. The page-wide status must not say that screens are unchanged while temporary setup is active. - - -Display cards keep the enable switch in the title row; disabled cards hide mode controls, the primary action and completed-detection copy. The switch remains greyed out for the primary display with its existing explanatory hover tooltip. - -Wide display editors use responsive monitor-card columns rather than a 650-DIP form across a full-screen window. Keep normal mode/HDR controls visible after discovery, hide successful setup copy, and reduce repeat detection to a subtle Detect again action. - -Monitor-card headers align the display name, a Primary indicator or Make primary action, and the enable switch. The primary indicator is a label rather than a disabled action. Disabled displays omit the primary action. - -## Preset preview grids +The TVs page uses the same cards, + button, pencil and bin. Navigating, selecting, saving or editing never contacts a TV; pairing and control are explicit background actions. -Audio and display pages use the same native GridView card vocabulary, title row and apply/edit/delete placement. Display cards show a saved-layout miniature with grouped mirror numbers plus a readable per-monitor legend (resolution, exact-rate label and HDR intent); disabled screens are listed as Display off. Details remain scrollable for larger layouts. Audio cards show the remembered/current device name and either a volume percentage or Keep current device volume. Merely selecting a card does not apply it. Normal native hover/selection/focus behavior is preserved. +**Add TV** is a step-by-step guide: brand, name, IP address, pairing (with an on-TV approval instruction and a bounded wait) plus automatic input and network reads, PC input, the wake address (with an opt-in manual MAC field), an optional Windows display and HDMI audio link, and review. Pairing happens before saving and survives a later read failure. Existing TVs open a compact editor that refreshes details in the background and stays editable offline. -The mirror selector sits in each enabled display card. Mirrored outputs share one draggable desktop tile. Primary means a source group; an individual primary-group member can be disabled while another remains. The final primary output remains protected by the disabled switch and tooltip. The scene editor is described in [Scenes](SCENES.md). +**TV controls** open from the remote-control icon in a dialog that appears immediately in Checking and stays usable while it reads. It shows the status, one power button whose text says what it will do (Turn off when on, Wake when off or unknown and a MAC is saved), the current input and a picker with Switch. Pending states read Waking… and Turning off…; an accepted turn-off shows Off · assumed. An unreachable TV is never labelled Off. Unsupported controls are hidden rather than shown disabled. Technical details stay collapsed. -## Sound — current +New display presets can show a small neutral "Setting up a TV?" card with Add TV and Don't show again (restorable in Options). It's hidden once a TV is saved. -Audio presets and the Library › Audio page are retired; this supersedes the Audio page, audio preset cards and "New audio preset…" above. Sound lives in two places. Now's Sound card has live controls: an output picker, a mute button and a volume slider, and the same row for the microphone; each change applies at once, with no Apply button, and **Save as scene…** opens a scene whose Sound step holds the current output and volume. A scene's **Sound** step dialog holds an Output picker (Leave as is, the devices Director knows, or "TV's sound · TV name"), a Set volume switch with a slider, a Mute choice (Leave as is, Unmute, Mute), "Use a different device for calls" and "Change microphone" checkboxes that reveal their pickers, and Relink device when a saved device is offline. Like every step dialog, it has no tooltips. +## Options -A scene card's top area shows the scene's main change. With a display preset it is the layout miniature; otherwise a 124 px panel shows a large icon and the main value: for sound, the output name with a volume bar (or "Muted") and the calls and mic devices; for a TV, its name and input; then the FPS limit, then the number of actions. +Options holds app-wide settings as setting cards. **Applying scenes**: keep finished changes when a later step fails, the device wait and TV input protection. Then notifications for failed CLI scenes, TV setup tips, **Backup** (export and restore), **Diagnostics** (logs and Report a problem) and **About**. See [Diagnostics](TROUBLESHOOTING.md). diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md index fce0d1b..ece39e2 100644 --- a/docs/DEVELOPMENT.md +++ b/docs/DEVELOPMENT.md @@ -1,118 +1,135 @@ # Development and testing -## Build and run +## Requirements -Director is one Rust application with a native WinUI 3 window through Microsoft Windows Reactor 0.100.0. Running without arguments opens the window; CLI commands use the same backend and return before GUI initialization. +- Windows 11 24H2 or newer, x64. +- [Rust](https://rustup.rs) 1.95 or newer with the MSVC toolchain (`x86_64-pc-windows-msvc`), plus the Visual Studio C++ Build Tools ("Desktop development with C++"). CI uses exactly this setup. +- The [Windows App Runtime 2.6](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/downloads) to run the window. Installing Director once also installs it. -Develop on Windows x64 with Rust 1.95 or newer, a Windows linker/resource compiler, and a compatible Windows App Runtime. The validated local setup uses Rust 1.99.1, x86_64-pc-windows-gnullvm, LLVM-MinGW 20261020 (UCRT), Windows build 26300, and the already installed Windows App Runtime 2.6.4. Other Windows toolchains/builds remain unvalidated. See [runtime and interface notes](WINDOWS_GUI.md). +The `x86_64-pc-windows-gnullvm` target with LLVM-MinGW also works. `.cargo/config.toml` links its CRT statically, so the executable doesn't need the toolchain's `libunwind.dll`. + +## Build, run and check + +Run these from the repository root: ```powershell -.\scripts\dev.ps1 check --locked -.\scripts\dev.ps1 test --locked -.\scripts\dev.ps1 build --locked --release -.\scripts\dev.ps1 run --locked -.\scripts\dev.ps1 -Command clippy -CargoArguments @('--locked', '--all-targets', '--', '-D', 'warnings') -.\scripts\dev.ps1 -Command fmt -CargoArguments @('--all', '--', '--check') +cargo build # debug build: target\debug\director.exe +cargo run # open the window +cargo run -- list # run a CLI command +cargo build --locked --release # optimized build: target\release\director.exe ``` -The script detects existing project-local Rust/Cargo and LLVM tools in .localonly/tools, or uses a suitable toolchain already on PATH. It explicitly sets target as the build output and changes environment variables only for its process. The GNULLVM configuration requests static CRT linking to avoid a toolchain libunwind.dll dependency. The script does not install a runtime or change system PATH. +Before opening a pull request, run the same checks as CI: -Open target/release/director.exe after a release build. Keep the generated director.ico beside the executable for the window icon. The executable also has an embedded icon resource. Cargo.lock is part of the application source; target and globally ignored .localonly are machine-local. No bootstrap or installer is provided yet. +```powershell +cargo fmt --all -- --check +cargo clippy --locked --all-targets -- -D warnings +cargo test --locked -- --test-threads=1 +``` + +The build script stages `director.ico`, `icons\` and `orientations\` beside the executable. Keep them there if you copy the executable somewhere else. `Cargo.lock` is committed and every CI build is `--locked`. + +`scripts/dev.ps1` is an optional wrapper. It finds a project-local Rust and LLVM-MinGW toolchain in `.localonly\tools` (machine-local; keep it out of commits) or falls back to the one on PATH, and changes environment variables only for its own process: + +```powershell +.\scripts\dev.ps1 test --locked +.\scripts\dev.ps1 -Command clippy -CargoArguments @('--locked', '--all-targets', '--', '-D', 'warnings') +``` ## Command-line usage +`director --help` lists every command. The main ones: + ```text -director --help director list +director scene apply tv-gaming +director scene end +director display apply desk-monitors director audio status -director audio list --json -director audio check director audio use soundbar-stage-v2 director audio volume +5 director audio volume --mic 80 director audio mute toggle +director tv input living-room-tv HDMI_2 +director tv toggle living-room-tv ``` -- list, outputs, inputs, status and check read Windows audio and change nothing; check also checks the default-device policy interface. -- use, volume and mute change one thing at once: the device named by CLI name or endpoint ID, or the current default when the device is left out. `--mic` targets the microphone. Each change is verified and put back when Windows does not confirm it. -- Exit 0 means success, including a change that was already in place; 2 means an argument, access or device error. - -Readback verifies Windows settings, not audible playback. Applications explicitly bound to a device can retain it. Director does not change per-application routing. Saved sound belongs to a scene's Sound step; see [Sound](AUDIO.md). -## Backend, worker, and storage - -Core Audio enumeration/default reads and endpoint volume use direct Windows APIs. Default switching uses the undocumented PolicyConfig interface isolated in src/windows_audio.rs. Interface failure is reported without invoking a helper executable. - -Reactor background jobs perform storage and audio work. COM objects are created and released in their worker context; only plain Rust data crosses into UI messages. The UI does not synchronously wait or poll hardware. GUI requests are serialized; a local-session named mutex also protects Apply and preset-file writes across processes. A native window subclass defers normal closure while work is pending. Native calls cannot safely be forcibly canceled; forced-termination recovery is not implemented. Settings files are located and written atomically by `src/storage.rs`. +- Items are found by CLI name (the name in lowercase with dashes) or by ID. Add `--json` to list commands for scripts. +- `audio list`, `outputs`, `inputs`, `status` and `check` change nothing. `use`, `volume` and `mute` change one thing, verify it, and put it back when Windows doesn't confirm it. Leaving out the device means the current default. +- Display Apply follows each preset's **Ask to keep display changes** setting. `--yes` keeps verified changes without asking, and `--confirm` asks in the terminal. +- Exit code 0 means success, including a change that was already in place. 2 means an argument, access or device error. -Settings live in %LOCALAPPDATA%\Director. SHGetKnownFolderPath resolves the real Windows Local AppData folder, including redirection; errors do not fall back to arbitrary folders. Audio presets (`audio-presets.json`) are retired: Director reads that file only to migrate version 1–2 scenes. Director remembers the audio devices it has seen in `audio-devices.json`. See [Audio](AUDIO.md) for identity matching and relinking. +The executable uses the Windows GUI subsystem. To capture CLI output from PowerShell reliably, use `Start-Process director -ArgumentList … -Wait -NoNewWindow -RedirectStandardOutput out.txt`. -Saving validates the document, checks the current on-disk list matches the window snapshot under the mutex, flushes a temporary file, and replaces the original with MoveFileExW replace-existing/write-through. Stale writers must refresh. Corrupt/unsupported files are preserved and reported. Atomic replacement is not a permanent recovery journal or a power-loss guarantee. Saving, cancellation, and deletion never change a device. +## Settings and storage -## Artwork and validation +Settings live in `%LOCALAPPDATA%\Director`, resolved through the Windows known-folder API, with no fallback folder. `storage::write_document` validates a document, checks under the operation lock that the file on disk still matches what was read, writes a temporary file and replaces the original with `MoveFileExW` (replace existing, write through). If the file changed since it was read, the save is refused and the window reloads. Each file carries a `version`; a corrupt file or one with an unknown version is left untouched and reported, never overwritten. When a format changes incompatibly, raise its version and decide whether to convert or refuse older files. -assets/director.svg is the editable source for the README and native icons. build/windows_icon.rs rasterizes seven sizes with build-only resvg and embeds the resource using windres (WINDRES override) or rc.exe. The build stages director.ico beside the binary. MSVC builds remain unvalidated. +Back up that folder before running the app against your real settings for testing. Tests never use it. -Automated audio tests use a fake backend and cover no-op behavior, optional volume, partial failures, prior role assignments, and recovery. Persistence tests cover round trips, duplicate names, stale writes, and corrupt/future files. A hidden native window test checks busy-close protection. +## Tests -Private UI checks use uniquely named fixtures and remove them afterward while preserving original presets. Audio UI checks only Apply a guaranteed nonexistent endpoint, exercising preflight without Windows audio writes. Capture only the owned application window. Real mouse/keyboard behavior and physical switching require separate validation; record observed results in [implementation status](IMPLEMENTATION.md). +- **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 `) 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. -Manual acceptance: create/save a preset without applying; reopen; edit/cancel; edit/save; confirm the CLI lists it; apply without volume, then with optional volume; inspect actual defaults/volume; delete without changing audio; restore your preferred output. Keep read-only/UI evidence distinct from real routing and hardware recovery checks. -## Display capture +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. -See [display presets](DISPLAY_PRESETS.md) for native capture, schema, identities, CLI commands, and limits. Display Apply is implemented separately through direct SetDisplayConfig validation, temporary application, native/CLI confirmation, persistence, and restoration. See [the Apply contract](DISPLAY_APPLY.md). Audio and display drafts, names, and settings files remain independent. +## WinUI rules worth knowing -Display Apply follows the saved **Ask to keep display changes** preference. Override it for one invocation with --yes (keep verified changes automatically) or --confirm (require the terminal confirmation). New presets default to keeping verified changes automatically. Existing preferences are preserved; legacy presets without the field still ask. Both paths retain readback and failure recovery. +- **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. +- 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. -Native UI Automation: query an open ComboBox's own descendants with a name/type condition rather than recursively enumerating the entire window. An unrestricted FindAll against the open live-audio dropdown stalled the provider during testing; the scoped query and selection completed normally. This does not establish full screen-reader compatibility. - -## TV setup checks - -See [TVs](TVS.md) for the setup flow and `director tv list`, `director tv pair `, and `director tv check `. TV commands are dispatched before Windows audio initialization and do not create the WinUI window. Add/edit/remove definitions in the native TVs view. Pairing is explicit, prompts on the TV, and stores only DPAPI-protected credentials. Connection checking is read-only on the TV. No persistent control process is required. - -Offline tests include a loopback WebSocket mock using native WinHTTP, a silent-peer deadline test, and DPAPI tampering checks. They do not contact physical TVs. Firmware/TLS/permissions must still be validated against an on, reachable LG TV with user approval on its screen. There is no discovery or MAC/address migration yet; avoid treating mock success as a hardware compatibility claim. - -## Guided TV and wake validation - -See TVS.md for the new guide and tv learn/wake. Existing TVs can use Edit → Read TV details → Save TV without recreation. Normal tests send wake packets only to a loopback receiver; the headless missing-MAC path rejects before UDP dispatch. A successful wake command means packet dispatch, not verified panel wake. - -The ignored tv_ui::native_preview::guide_fixture application test provides test-only in-memory data for native input/wake/display/review checks. A private owned-window script launches it explicitly, never saves it, and never contacts a TV. Production exposes no fixture flag. Physical validation must separately check firmware network-information permissions, MAC reads, the full on-TV pairing guide, and wake with the TV’s network power-on setting enabled. +## Crash reports -## TV control validation notes +`director::crash::install` sets a panic hook (after `diagnostics::init`), and a fatal Reactor error from `App::run_component` is recorded too. Each report is a text file in `Logs\Crashes` (`crash-.txt`, newest 10 kept) with the summary, version, Windows build, message, a backtrace for panics and the newest 40 log records. On the next start the newest unseen report is offered once; dismissing it renames it to `.seen.txt`. **Report on GitHub** opens `issues/new` with only the summary, version and backtrace in the URL; the log lines stay in the file for the reporter to attach. Panics caught by worker `catch_unwind` safety nets are recorded as well. Native faults that bypass the panic hook (fail-fast, access violations) appear only in Windows' Application event log. See [Diagnostics](TROUBLESHOOTING.md) for the logs. -TV status/off/input CLI commands use the shared control engine; see TVS.md. Ordinary tests exercise the actual native WebSocket power-off/input payloads against a loopback mock, never a physical TV. Power-off acknowledgment is distinct from physical panel state, and foreground input readback is distinct from HDMI/Windows readiness. +## Artwork -The ignored tv_controls_ui::native_preview::controls_fixture test opens the modal after startup with in-memory data. It verifies one power action, pending selection, Unknown handling, Close, and layout; its fake definition fails preflight before any network operation. Production has no fixture entrypoint. Read-only live checks separately exercise fresh status/input reads without pressing Power or Switch. +`assets/director.svg` is the only source for the app icon. `packaging/windows_icon.rs` rasterizes seven sizes with the build-only `resvg` crate, embeds them with `rc.exe` or `windres` (override with `WINDRES`), embeds `packaging/director.manifest`, and stages `director.ico` beside the executable. The installer's 64 px setup logo is copied from that icon. -The pinned Reactor version rejects the tooltip wrapper on Refresh inside ContentDialog with StructureUnsupported. The refresh button retains its accessible name without that wrapper. No dependency/cache modification was made. Keep this native regression check when changing dialog content. +## Installer -The same rule applies to everything a dialog hosts: the scene step dialogs once had tooltips on their action rows (Move up, Move down, Remove) and on the chosen app's name, and opening a step with actions closed the window. Give those controls an automation name instead. `scene_editor_ui::tests::dialog_content_has_no_tooltips` scans the step dialogs, the FPS controls, the relink button used by the Sound step, the crash dialog and the command dialog; extend it when a new dialog hosts shared controls. Shared helpers can hide a tooltip too: the display preview put one on each screen and crashed the Displays step dialog, so dialogs use `layout_preview_in_dialog`, and the test only lets the step dialogs call helpers on its checked list. +`scripts/package-msi.ps1` builds both installer files with WiX 6.0.2 into `target\installer`: -## Crash reports +```powershell +.\scripts\package-msi.ps1 # release build, then package +.\scripts\package-msi.ps1 -UseExistingRelease # package the existing release build +.\scripts\package-msi.ps1 -Wix C:\tools\wix.exe +``` -`director::crash::install` sets a panic hook (after `diagnostics::init`), and a fatal Reactor error from `App::run_component` is recorded too. Each report is a text file in `Logs\Crashes` (`crash-.txt`, newest 10 kept) with the summary, version, Windows build, message, backtrace for panics and the newest 40 log records. On the next start the newest unoffered report is shown once; dismissing it renames it to `.seen.txt`. Report on GitHub opens `issues/new` with only the summary, version and backtrace in the URL: the log lines stay in the file for the user to attach. Panics caught by worker `catch_unwind` safety nets are recorded as well, since each one is a bug. Native faults that bypass the panic hook (fail-fast, access violations) still appear only in Windows' Application event log. +It adds the pinned WiX Util and bootstrapper extensions to the global WiX cache when missing. +- `Director--x64.msi` comes from [installer/Director.wxs](../installer/Director.wxs): a per-machine package with no dialogs of its own. It installs to `%ProgramFiles%\Director`, adds shortcuts, the `director-run:` handler and the PATH entry, and refuses Windows builds below 26100 through a launch condition. +- `Director--x64-setup.exe` is a WiX Burn bundle from [installer/DirectorSetup.wxs](../installer/DirectorSetup.wxs) with the [Director theme](../installer/theme). It embeds the MSI, checks the Windows build, and installs the Windows App Runtime first when the pinned package isn't registered. Releases publish only this file. -## Action SVG assets +The runtime is pinned in two places. To move to a newer one, update the version, download URL, SHA-512 hash and size in `DirectorSetup.wxs` (`wix burn remotepayload` generates them), and `$runtimeVersion` and `$runtimePackage` in the packaging script. Users see what setup does in [Install](INSTALL.md). -Build stages assets/icons/remote.svg and delete.svg into each Cargo profile’s icons directory. Keep that directory beside director.exe when copying the preview, alongside the existing icon/orientation assets. The shared icons module uses the profile folder for test executables in deps. No image-generation dependency or helper executable was added. Native checks should retain accessible action labels, verify SVG rendering, and confirm Apply is unchanged. +`windows-reactor` is a preview crate, pinned to `=0.100.0` with `Cargo.lock`; its published API differs from current upstream examples, so check the matching source before using a new API. It needs the framework-dependent Windows App Runtime 2.4 or newer and shows a download prompt when it's missing; the CLI doesn't need the runtime. The executable embeds `packaging/director.manifest` (Windows 10/11 supported OS, `maxversiontested` 10.0.26100.0, per-monitor v2 DPI). Raise `maxversiontested` after testing on a newer Windows release. -For visual captures, foreground the owned test window and allow a frame to render. An occluded-window run produced a blank captured client despite valid native accessibility controls; foreground recapture verified the actual UI. +## GitHub Actions +The [Windows build workflow](../.github/workflows/windows-build.yml) runs for pull requests and pushes to `main`, and can be run by hand from the Actions tab. On the hosted Windows runner with the MSVC toolchain it checks formatting, runs Clippy and the tests, builds the release executable, packages the MSI and the `setup.exe` that embeds it, and uploads the setup as the **Director-Windows-x64** artifact (GitHub zips artifacts; release assets download as the plain file). When a merge into `main` raises the version, the workflow publishes a GitHub Release with that setup. A manual run on `main` with `publish_release` enabled publishes the current version. See [Setup and MSI](#installer). -## Runtime diagnostics +## Versioning -Use **Options → Open logs folder** to inspect the automatically rotating local logs. [Diagnostics](DIAGNOSTICS.md) describes file retention, operation correlation, covered stages, excluded secrets, and best-effort/queue limits. Reproduce a failure with the current build before reading its log; older attempts made before logging existed cannot be reconstructed. +Set the version in the root [Cargo.toml](../Cargo.toml) under `[package]`, as three numbers such as `0.12.1`, which the MSI needs. Run `cargo check` afterwards to update the root package entry in `Cargo.lock` before a `--locked` build. The [packaging script](../scripts/package-msi.ps1) reads the version for the MSI and setup versions and file names. Add a line to [CHANGELOG.md](../CHANGELOG.md) for each release. +## Third-party notices -## GitHub Actions +`THIRD_PARTY_LICENSES.md` lists the license of every crate compiled into `director.exe`, and the installer copies it beside the executable with `LICENSE.txt`. Regenerate it after adding or updating a dependency: -The [Windows build workflow](../.github/workflows/windows-build.yml) runs for pull requests and pushes to main. You can also run it manually from the Actions tab. It uses the hosted Windows runner and the MSVC Rust toolchain, runs formatting, Clippy and tests, then builds the x64 MSI and the setup.exe that embeds it, and uploads the setup.exe. Find the unsigned installer under the run’s **Director-Windows-x64** artifact. GitHub zips Actions artifacts; release assets download as the plain file. A version increase merged into main publishes a GitHub Release with the verified setup.exe after the build succeeds. See [setup and MSI](WINDOWS_GUI.md#setup-and-msi). A manual main-branch run can also publish the current version by enabling publish_release. GUI and physical-device checks remain separate from CI. -## Versioning +```powershell +cargo install cargo-about --locked --features cli +cargo about generate -c packaging/about.toml packaging/about.hbs -o THIRD_PARTY_LICENSES.md +``` -Set the app version in the root [Cargo.toml](../Cargo.toml) under `[package]`. Keep it in three-part numeric form, such as `0.9.1`, for MSI packaging. After changing it, refresh the root package entry in `Cargo.lock` with a normal Cargo check before running the locked build. The [MSI packaging script](../scripts/package-msi.ps1) reads the version from Cargo.toml and uses it for the MSI and setup.exe versions and filenames. +`packaging/about.toml` lists the accepted licenses. Generation fails if a new crate uses one that isn't listed, so review that license before adding it there. ## Protecting main -The build check is named **Windows x64 build**. Configure it as a required check with an up-to-date branch and require pull requests for main, including administrators. Private repository branch protection requires GitHub Pro or an eligible paid organization plan. GitHub rejected protection on the repository’s current plan. - -For local protection, run git config --local core.hooksPath .githooks after cloning. This checkout has the same guard installed in its local Git hooks directory so it survives switching branches. The pre-push hook blocks updates and deletion of main. GitHub-side rules are needed to enforce PR-only changes and required checks for all clients. +`main` only changes through pull requests that pass the **Windows x64 build** check. Locally, run `git config --local core.hooksPath .githooks` after cloning: the pre-push hook refuses direct pushes to `main`. diff --git a/docs/DIAGNOSTICS.md b/docs/DIAGNOSTICS.md deleted file mode 100644 index e63c034..0000000 --- a/docs/DIAGNOSTICS.md +++ /dev/null @@ -1,40 +0,0 @@ -# Diagnostics - -Director records local diagnostics automatically for the desktop app and CLI. In the window, choose **Options → Open logs folder**. This opens the Windows-known Local AppData location, normally `%LOCALAPPDATA%\Director\Logs`. - -## Files and retention - -`director.log` is the current file. Up to four older files, `director.1.log` through `director.4.log`, are retained. Each file is capped at approximately 1 MiB (records are bounded); oldest records are replaced on rotation. Each line is a JSON object with readable UTC timestamp, Unix milliseconds, process ID, operation ID, step, outcome, and diagnostic detail. Read the files in a text editor or parse them as JSON lines. Operation IDs are process-local; use timestamp and process ID with them. - -A worker writes logs through a bounded 512-record queue. Ordinary UI/event logging never waits for disk access or another process. A separate file lock coordinates writers/rotation across app and CLI instances. If the queue fills, records may be dropped and the next available event reports the dropped count. Exit flush waits at most two seconds. Logging is best effort: a disk error must not stop a device operation. Options reports a known logging failure, updated when that view renders. Logs can contain device IDs, input IDs, device names in audio reports, and Windows error information; pairing keys, protected credentials, certificate bytes, MAC addresses, and raw TV messages are not deliberately recorded. - -## Coverage - -- Application startup, CLI exit, GUI shutdown, background jobs, and global operation failures. -- Audio apply progress, verification/recovery progress, and final report. -- Display snapshot, preparation, validation, temporary apply, verification, keep/revert, commit, restoration, and final report. -- TV connection, registration, authenticated session, request sent, reply/timeout, parsed power state, command acknowledgment, fresh turn-off/input checks, wake dispatch, and command result. -- TV dialog token/read revision connects an action to its separate follow-up check. An unavailable status snapshot records its notes even though snapshot collection itself returned successfully. - -A request-sent event means bytes were handed to the transport, not that the TV accepted the command. Look for command acknowledgment and the final action result separately. A finished span records elapsed time; it does not imply success. Physical panel state, HDMI signal, and network disappearance must not be inferred from acknowledgment alone. - -The modal also preserves the original command diagnostic independently of follow-up status errors. A later timeout cannot erase why an action failed. - -## Development checks - -Unit tests exercise rotation limits, complete concurrent records, Unicode-safe detail limits, and JSON escaping. Native fixtures verify Options/folder-open acceptance and retention/correlation of a blocked TV command followed by an unavailable status response. Fixtures do not send power/input commands to the physical TV. Windows accepted the folder-open request; inspecting Explorer's folder through Shell automation was unavailable in the test environment. - - -Folder opening starts Windows' own explorer.exe from the Windows installation directory and passes the log folder as a separate argument. This avoids the folder-association handoff that returned success without opening a visible window. The status reports a completed request rather than asserting that a window appeared, and includes the runtime log location and writer state. - -Final checks: the release CLI writes and flushes startup/operation/exit records without opening a window. Native TV fixtures verify that the original preflight failure and later timeout notes both remain visible and have correlated diagnostic records. The test environment exposes no Explorer windows to UI Automation and denies Shell window enumeration, so it cannot independently verify a visible Explorer folder. The user confirmed that the final direct Explorer invocation visibly opened Logs after the button was invoked through UI Automation. Process-start success alone is not treated as proof that a folder is displayed. - - - -## Samsung compatibility sharing - -Samsung setup/Edit TV provides Export report, and CLI provides director tv report . The report in the Local AppData Director/Reports folder is a separate allowlisted JSON document, not a copy of raw application logs. It includes observed model/firmware, paired state, tested direct ports and user confirmations; it omits credentials, certificate bytes, addresses, MACs, aliases, TV/device IDs, raw responses and arbitrary errors. Nothing is uploaded automatically. See SAMSUNG.md for the friend-testing procedure and current physical-validation limit. - -## Friend reports (format 2) - -Samsung/TCL reports now include explicit Not tested/Yes/No feedback for displayed status, physical turn-off and physical wake; optional TV model/software and Wi-Fi/Ethernet information; export timestamp, Windows version/build, architecture, executable SHA-256, and wake-address-presence/count flags. Selected-TV structured history is read from bounded rotated logs, with action, outcome, timing, reported power, coarse failure category and an optional numeric system code. No raw error strings or full log records are exported. Missing/unreadable history is reported explicitly. Only actions run with this build are captured; reproduce the failure before exporting. Pairing steps expose the same export action even before authorization succeeds. User observations are distinct from command send results. diff --git a/docs/DISPLAYS.md b/docs/DISPLAYS.md new file mode 100644 index 0000000..0cbb89d --- /dev/null +++ b/docs/DISPLAYS.md @@ -0,0 +1,71 @@ +# Displays + +A display preset saves which screens are on, how they're arranged, which is primary, and each screen's resolution, refresh rate, orientation, desktop mode (extend or mirror) and HDR. Scenes use presets, and you can apply one on its own from **Displays** or the command line. + +## Save a layout + +- **Capture current layout** (the camera button) saves your screens exactly as they are now under a name. +- **+** opens the editor starting from your current layout, so you only change what's different. +- The pencil on a preset opens the same editor for that preset. + +Saving only saves. Nothing changes on your screens until you apply a preset. + +## The editor + +The arrangement map works like Windows Settings › Display. Select a screen to highlight its card; drag it to move it. A screen dropped away from the others moves back to touch the nearest one, and overlaps are resolved when you let go. Hover a screen for its size, refresh rate and position. + +Each display has a card: + +- **On** switch and **Make primary**. The primary display can't be switched off; make another one primary first. +- **Resolution** and **Refresh rate**. Only modes Windows reports for that screen are listed, with exact rates (59.94 Hz stays 59.94). Rates that Windows marks with an asterisk belong to a different resolution and appear when you pick that resolution. +- **Desktop mode**: **Extend desktop** or mirror another enabled display. Mirrored screens share one tile on the map and one resolution. +- **Orientation**: Landscape, Portrait, Landscape flipped or Portrait flipped, each shown with a rotated monitor icon. +- **HDR**, when the screen supports it. Leaving it unset keeps whatever HDR state the screen has when the preset is applied. + +**Ask to keep display changes** decides whether applying this preset shows a 15-second Keep/Revert prompt. It's off for new presets. + +## Screens that are off or not detected yet + +Windows only reports the modes of a screen while it's active. For a TV or monitor that's off, its card offers **Set up this display**: + +1. Turn the display on and select the PC's input, then choose **Detect options**. +2. Director temporarily turns that screen on (your other screens stay as they are), reads its resolutions, refresh rates and HDR support, then restores your layout and checks it. The card shows each phase, and **Cancel detection** stops it at any point before restoring. +3. The detected options fill the card. Director remembers them, so you can build presets for that screen while it's off; they're marked **Previously detected** and checked again when applied. + +If the screen belongs to a paired TV with a saved wake address and PC input, **Wake and detect** also wakes the TV and switches it to that input first. The TV stays on afterwards. + +If restoring your layout fails, the card keeps what it needs and offers **Restore previous layout**. You can't save or discard that preset until it succeeds. Use **Detect again** after changing a cable, port or driver. + +## Applying a preset + +Choose **Apply** on a preset card, or run `director display apply `. + +1. Director finds each screen by its Windows device path, checks the whole layout with Windows, and records your current setup. +2. It applies the layout, then reads it back and compares every screen: on or off, position, size, primary, orientation, exact refresh rate, mirroring and HDR. +3. With **Ask to keep display changes** on, you get **Keep these display settings?** for 15 seconds. **Revert**, closing the prompt or letting it time out restores your previous layout. +4. Only a verified (and, if asked, confirmed) layout is saved to Windows' display settings. + +If anything fails along the way, Director restores your previous layout and checks it, and tells you if the restore didn't fully succeed. A preset that already matches your screens reports that and changes nothing. A preset that needs a screen that isn't connected fails before changing anything. + +## Command line + +```text +director display screens [--json] +director display list [--json] +director display capture "Desk monitors" +director display check desk-monitors +director display apply desk-monitors [--yes | --confirm] +``` + +- `screens` shows the live layout; `list` shows saved presets; `capture` saves the current layout. None of them change your screens. +- `check` validates a preset with Windows without applying it. +- `apply` follows the preset's **Ask to keep display changes** setting and asks in the terminal when it's on. `--yes` keeps a verified layout without asking; `--confirm` always asks. Neither skips verification or the restore on failure. +- Exit codes: 0 applied or already active, 1 reverted or failed, 2 bad arguments, missing preset or access error. + +## How it works + +Presets live in `display-presets.json` and detected options in `display-capabilities.json`, both in `%LOCALAPPDATA%\Director`. Screens are identified by their Windows device interface path, never by display number, friendly name or adapter ID, which can change between sessions. If a device path changes after a driver or hardware change, recapture or edit the preset. + +Director talks to the Windows display configuration API directly (`QueryDisplayConfig`, `SetDisplayConfig`) and lists modes through DXGI. Changes are first applied without saving them to Windows, then saved only after verification. HDR uses Windows 11 24H2's HDR-specific display requests and is restored with the rest of the layout on failure; a requested HDR change is refused up front if the screen's current HDR state can't be read. + +Not supported: interlaced and virtual modes, DPI scaling, colour depth, VRR settings and identifying screens with on-screen numbers. Recovery happens inside Director, so a crash or forced shutdown during a change can leave the temporary layout in place; Windows' own display settings can fix that. diff --git a/docs/DISPLAY_APPLY.md b/docs/DISPLAY_APPLY.md deleted file mode 100644 index 278ddaa..0000000 --- a/docs/DISPLAY_APPLY.md +++ /dev/null @@ -1,51 +0,0 @@ -# Applying display presets - -## Native workflow - -The green check on a display-preset row applies that saved layout. Director resolves monitor device paths against current Windows targets, validates the requested configuration, and snapshots the actual active setup before changing it. It does not reuse saved adapter/target locators as hardware identities or guess by friendly name. - -Changes are temporary until readback matches the requested enabled monitors, positions, desktop dimensions, primary source, rotations, exact equivalent refresh fractions, and mirrored/extended grouping. When confirmation is enabled for the preset, a native **Keep these display settings?** dialog then gives 15 seconds to choose **Keep settings** or **Revert**. Escape/closing the dialog, a missing confirmation, or a lost confirmation channel chooses reversion. An already-matching layout reports that it is active without changing hardware or asking for confirmation. - -Each preset has an **Ask to keep display changes** switch, off for newly created or captured presets. Existing saved preferences are preserved; legacy presets without the field retain their previous confirmation-on behavior. Turning it off automatically keeps verified changes. Validation, strict readback, persistence checks, and failure recovery always run. Editing or cancelling this preference does not change the captured layout or apply it. The CLI follows this saved preference unless explicitly overridden with --yes or --confirm. There is no deadline when confirmation is disabled. - -The monotonic deadline belongs to the background worker, not a UI timer. A stalled UI cannot extend it. The worker owns the cross-process operation lock through application, confirmation, and any restoration. Other preset writes or device changes cannot overlap it. Normal window closure stays blocked while the transaction is pending; Revert or the timeout returns to the previous layout. - -Requested changes are saved to the Windows display database only after verification and confirmation. Restoration also saves the actual pre-operation snapshot, including after an attempted persistence failure. A failed setter may already have changed the desktop, so setter errors, verification failures, persistence failures, and Rust panics after an attempted write all trigger restoration and readback. Failed restoration is reported as incomplete recovery rather than success. - -## Direct Windows implementation - -src/display_apply.rs contains the shared transaction, semantic verifier, and confirmation deadline. src/windows_display_apply.rs resolves current routes, assigns unique sources to independent desktops while preserving clone groups, calls SetDisplayConfig with VALIDATE before mutation, applies without SAVE_TO_DATABASE initially, and persists after confirmation. Exact current target timings are retained when only arrangement changes. CCD source dimensions are supplied as reported by Windows, while GDI desktop dimensions remain the readback/UI geometry. Cold-enabled progressive targets use a progressive scan-line value with a specified refresh fraction; an unspecified scan-line value was rejected by the validation host and is covered by a regression test. Windows best-mode completion may be used after a bad-configuration validation result, but strict readback still decides whether the requested layout was achieved. - -The rollback snapshot contains native active paths and mode tables, including target timings, alongside the actual user-visible layout. Recovery reapplies that snapshot and verifies the observed layout. Known disabled monitors may be absent; required enabled monitors must be available and identifiable. Ambiguous identities, unsupported routing, and active monitors not represented in a saved preset fail before mutation. Recapture when hardware membership or driver identities change. - -The GUI uses ordinary Rust channels and supported Reactor background-task messages to bridge countdown progress to the native dialog. UI objects never cross to the worker. Confirmation messages carry a transaction token so an old dialog cannot keep a later operation. - -## CLI - -```text -director display check desk-monitors -director display apply desk-monitors -director display apply desk-monitors --yes -``` - -check resolves and validates through Windows without applying. apply follows the saved preference. When confirmation is enabled, it asks the terminal for yes/y with the same 15-second deadline; EOF, another answer, or no answer reverts. --yes explicitly keeps a verified layout without prompting, for automation without a window. --confirm forces confirmation even for an automatic preset. Neither option skips verification or recovery. Success/already-matching exits 0; a reverted/failed application exits 1; bad arguments, missing presets, or access/initialization errors exit 2. - -## Current boundaries - -This supports ordinary captured desktop layouts. Virtual-mode topologies, cold-enabling interlaced modes, advanced VRR/DPI/color settings, automatic identity relinking, and driver-specific changes are outside the modeled feature. Windows may create/remove HDMI audio endpoints as displays change; Director does not explicitly change audio settings during a display transaction. - -The deadline cannot rescue a process that has been forcibly terminated, a crashed/restarted process, or a synchronous driver call that never returns. There is no external watchdog or durable interruption-recovery journal yet. Restoration can also fail after unplugging hardware or a driver failure; the result includes those errors. These are limits, not claims of tested recovery on every monitor/driver combination. - -## Reference - -- [Microsoft SetDisplayConfig contract, validation, temporary application, and persistence](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-setdisplayconfig) -- [Target refresh and target-mode precedence](https://learn.microsoft.com/en-us/windows/win32/api/wingdi/ns-wingdi-displayconfig_path_target_info) -## Validation — 2026-10-31 - -All 31 tests pass, including transaction failures/partial writes, panic recovery, cancel/timeout/channel loss, incomplete recovery, clone/identity verification, source assignment, snapshot mode changes, and cold-enable timing parameters. Release build, strict all-target Clippy, and formatting pass. - -Native validate-only and same-layout Apply left the desktop unchanged. A controlled live test temporarily enabled the known secondary monitor with a small offset while preserving the primary, held stdin open without confirming, and verified automatic restoration after 15 seconds. A concurrent operation was rejected while confirmation was pending. Native accessibility checks then verified the updating dialog, guarded window close, explicit Revert, Keep/persistence, and normal/narrow rendering. A verified headless Apply restored the original single-screen setup. Required-missing-monitor preflight failed without mutation. Owned fixtures were removed and the existing user display preset was preserved; audio CLI checks passed. - -This is validation on the local desktop configuration, not every TV, GPU, refresh/resolution change, or hot-plug failure. Forced-termination recovery, full physical failure injection, and clean-PC distribution remain unverified. - -HDR now participates in explicit preset verification and restoration when requested and readable. See [HDR application and limits](HDR.md). Legacy presets without an HDR field leave it unchanged. The same transaction also drives the independent [Current setup](CURRENT_SETUP.md) display Apply operation. diff --git a/docs/DISPLAY_PRESETS.md b/docs/DISPLAY_PRESETS.md deleted file mode 100644 index 328ee2e..0000000 --- a/docs/DISPLAY_PRESETS.md +++ /dev/null @@ -1,63 +0,0 @@ -# Display presets - -## Working scope - -Capture the current Windows desktop configuration, give it a name, and save an independent display preset. View/rename and confirmed deletion manage the saved snapshot. None of these operations enable, disable, move, or reconfigure a monitor. The green check applies the saved layout with native confirmation and automatic reversion; see [applying display presets](DISPLAY_APPLY.md). The + button and preset pencil now open the custom extended-layout editor directly. HDR now has a capability-gated toggle; clone-group editing, color depth, VRR, and DPI scaling remain deferred. - -From **Displays**, choose **Capture current layout**, review the monitor details, enter a name, and choose **Save display preset**. The pencil opens the full saved preset editor directly; renaming preserves its captured layout and timestamp. Cancel discards the draft. Switching between audio and display pages preserves unsaved drafts independently. The cross removes only the chosen saved display preset after native confirmation. - -Capture reads Windows again at that moment, rather than copying the last page refresh. Monitor positions and displayed dimensions are current desktop pixels. Optional HDR state is captured when available; see [HDR support](HDR.md). Current GDI dimensions are checked against the CCD source position, avoiding incorrect portrait dimensions on drivers that report an unrotated CCD source size. Raw CCD source dimensions are retained separately; refresh rates still come from the exact CCD fraction. The primary source is the one at (0, 0); mirrored targets can share that primary source. Refresh rates retain the exact numerator/denominator in storage and show two decimals in the UI. Mirroring retains shared source identity while keeping per-target refresh/orientation. - -## Create and customize - -Choose **+** to read the current monitors and open a configurable draft. The current arrangement is the starting point, so you do not have to rebuild it from scratch. **Capture current layout** remains a separate, quick snapshot flow. An existing preset's pencil opens all per-monitor controls directly. - -Each monitor card includes enabled state, exclusive primary selection, resolution, dependent refresh-rate choices, visual orientation choices, and a boxed arrangement map. Drag screens in the map to reposition them, with edge snapping and overlap handling. Hover over a screen to see its size, refresh rate, primary status, and pixel position; there are no raw position fields. Selecting a new primary translates all enabled monitors to keep their relative positions, with the primary at 0, 0. Enabling a monitor places it to the right. The primary display's Enabled switch is disabled; hovering its enabled overlay explains that another primary must be selected first. - -The compact orientation dropdown shows four rotated SVG monitor icons with the stand as its orientation reference and plain-language labels. Choices are left-aligned and selecting one closes the menu. Dropping a moved primary normalizes all positions around its new origin, preserving primary status. Pointer cancellation restores the pre-drag draft. Invalid coordinates, additional displays at the primary origin, and overlapping extended layouts are rejected. Captured clone groups remain supported by capture/Apply, but editing their shared settings is deferred. - -**Save display preset** stores the draft; **Cancel** discards it. Neither changes the live setup. To switch, use the saved row's green Apply check. Windows validates the final topology at Apply time, so a mode being listed is not a guarantee that every combination of outputs works. - -## Supported-mode discovery - -The background worker queries DXGI Output1 mode lists for ordinary progressive SDR modes, mapped to the monitor device-interface path rather than its editable name. Resolution changes rebuild the refresh list, retaining exact rational rates. The current captured mode is preserved, including its raw CCD source dimensions. Match output device paths without requiring a historical adapter LUID. Accept unspecified scan-line ordering from the DXGI list as well as progressive ordering, while excluding explicit interlaced/stereo entries. DXGI enumeration retries mode-list changes with bounded buffers. - -A connected disabled output may expose no DXGI mode list. In that case, only its exact CCD preferred mode is offered, with a visible explanation. If no mode is available, enabling it is disabled. Connect/enable the output in Windows and reopen the editor for more choices. Disconnected monitors remain visible, but cannot be newly enabled through the custom editor. This does not add remembered-monitor identity relinking or advanced color modes. - -## Storage and identity - -Display presets use schema version 1 in the Windows Local AppData known folder at %LOCALAPPDATA%\Director\display-presets.json. Sound settings live in each scene's Sound step, not in a preset file. A display preset has an internal ID, editable name, capture timestamp, and layout. Each monitor stores a Windows device path when available, current adapter/target locators, name, availability, enabled state, and an active desktop mode when enabled. A mode includes source identity, desktop position/dimensions, raw CCD source dimensions, exact refresh fraction, and orientation. - -Names are nonblank, unique ignoring case within display presets, have a CLI name (lowercase with dashes) that no other display preset uses, and at most 160 UTF-8 bytes. Audio and display presets may use the same name. Shared atomic write and operation-lock mechanisms preserve corrupt/future files and reject stale writers. Capture errors never save partial layouts. - -Adapter LUIDs, source IDs, and target IDs are current-session locators, not durable hardware identities. Device paths can change after hardware/driver changes; missing paths remain explicit. Apply re-enumerates, resolves device paths, and reports missing/ambiguous targets rather than applying these locators blindly or matching friendly names alone. This first schema is a captured desktop description, not a complete serialized driver configuration. - -## Direct Windows capture - -src/windows_displays.rs calls GetDisplayConfigBufferSizes, QueryDisplayConfig, DisplayConfigGetDeviceInfo, and EnumDisplaySettingsExW directly. Capture invokes no display-changing API or external executable. The separate Apply adapter uses SetDisplayConfig directly after validation and snapshotting. ALL_PATHS is needed to discover disabled targets; it can be expensive, so capture/refresh runs on background jobs only when requested. Possible routes are deduplicated by target; an active route takes priority. Unidentifiable unused ports are omitted. Named disconnected targets are retained when Windows reports them; the list is not a permanent monitor inventory. - -Buffer sizing/query races retry up to four times. Active source-mode indices, types, and identities are checked before reading native unions. Invalid/incomplete active modes or refresh data are reported rather than silently filled in. Virtual-refresh-rate distinctions, headset displays, remote-session/legacy-driver compatibility, and stable hardware relinking are outside this slice. Hardware failures and hot-plug races still need wider physical validation. - -## Headless commands - -```text -director display screens -director display screens --json -director display list -director display list --json -director display capture "Desk monitors" -``` - -current reads the live layout; presets reads saved layouts; capture saves a new named snapshot. These inspection/capture commands do not change displays or audio. Commands run before GUI or audio-COM initialization. Exit codes follow the existing CLI contract. Display check and apply use the same model and transaction engine; see [confirmation and automation options](DISPLAY_APPLY.md#cli). - -## Sources - -- [QueryDisplayConfig](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-querydisplayconfig) -- [Desktop source mode and primary origin](https://learn.microsoft.com/en-us/windows/win32/api/wingdi/ns-wingdi-displayconfig_source_mode) -- [Current desktop display settings](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-enumdisplaysettingsexw) -- [Monitor names and device paths](https://learn.microsoft.com/en-us/windows/win32/api/wingdi/ns-wingdi-displayconfig_target_device_name) -## Windows starred refresh choices - -Windows Advanced display can show rates with an asterisk that require changing the selected resolution. Director's refresh dropdown currently filters to the selected resolution, so a starred Windows alternative need not appear in that specific list. Do not insert such a rate into the native-resolution pair unless Windows actually reports that pair. [Microsoft explains the asterisk](https://support.microsoft.com/en-us/windows/hardware/display-graphics/change-the-refresh-rate-on-your-monitor-in-windows). - -The user's P27 screenshot shows 59.95 Hz and 50 Hz*. The earlier explanation that the monitor had only one refresh option was too broad: it referred only to the selected-resolution list and omitted the cross-resolution distinction. diff --git a/docs/DISPLAY_SETUP.md b/docs/DISPLAY_SETUP.md deleted file mode 100644 index 99c4a19..0000000 --- a/docs/DISPLAY_SETUP.md +++ /dev/null @@ -1,50 +0,0 @@ -# Display option detection - -In a display preset, choose **Set up this display** (or **Detect display options** for an already-active display). The explanation stays inside that display's card; nothing changes until **Detect options** is pressed. Turn the display on and select the PC input first. - -When a paired TV is linked to that Windows display and has a saved wake address and PC input, **Wake and detect** is also available. It wakes that TV and selects the saved PC input. The TV stays on afterward; restoration applies to the Windows display layout, not the TV's power or selected input. - -## Progress and cancellation - -The card shows preparing, optional TV preparation, temporary enabling, reading, restoring and verification. An indeterminate native progress bar avoids inventing percentage estimates. Unrelated controls and Save are disabled while setup runs. Cancel detection is available until restoration starts; cancellation waits for the current native/network call to finish, then restores the captured layout. Normal window closing is protected while the operation runs. - -Detection has a cooperative 30-second work deadline checked between steps. In-flight native calls use their existing behavior/timeouts and cannot be forcibly interrupted safely. Restoration runs even after cancellation/deadline and is not skipped merely because that deadline has elapsed. - -The current primary/active displays are retained. Temporary activation is validated by Windows, and the original enabled displays are checked for changes before capabilities are accepted. Any attempted activation, including a setter that fails after a partial change, goes through restoration and readback verification. TV wake/arrival is also treated as potentially changing Windows topology. No temporary topology is committed to Windows' persistent display database. Existing HDR state is restored; the discovery action does not explicitly enable HDR on its target. - -If restoration fails, the card keeps its recovery snapshot and offers **Restore previous layout**. Saving/canceling that draft is blocked until recovery succeeds. Recovery exists in memory; force termination, process crashes and reboot are outside this in-process restoration guarantee. A persistent recovery watchdog is not part of this implementation. - -## Remembered choices - -Only complete, active display inventories are remembered after successful restoration. Exact resolution/rational-refresh pairs and HDR availability are stored by Windows device-interface path in the known Local AppData Director directory, in versioned display-capabilities.json. Inactive fallback reports never replace a complete inventory. Corrupt/future cache files are preserved. - -Inactive/disconnected cached displays show **Previously detected · checked again when applied**. These choices can be used to author a preset while the screen is off. A display without learned capabilities offers setup instead of a misleading fallback resolution dropdown. Newly detected displays are enabled in the draft only; the live layout is already restored. Existing draft positions/orientation are preserved when learned modes are installed. - -Save still stores a preset without applying it. Apply uses the existing fresh Windows validation and exact post-apply verification; unsupported modes are not silently substituted. A changed driver, port, cable or display identity can require detection again. - -## Native implementation - -Windows selects the target timing using documented [unspecified refresh/scan-line rules](https://learn.microsoft.com/en-us/windows/win32/api/wingdi/ns-wingdi-displayconfig_path_target_info) and [SetDisplayConfig validation/best-mode completion](https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-setdisplayconfig). Existing screens retain supplied modes and are checked afterward. Device/probe work runs on workers under the shared operation lock, with thread-safe progress messages to WinUI. - -## Validation boundary - -79 regular tests plus native in-memory UI checks cover success, partial writes, read failure, panic, cancellation, failed TV preparation, recovery retry, original-screen preservation, cache precision/corruption, explanation/progress and learned 4K/120 Hz/HDR controls. The UI fixture never activates a physical display, sends a TV command or writes a fake capability cache. Original settings/cache hashes and live display topology remain unchanged. Actual LG/driver activation and restoration require hardware validation; the simulated 4K/120 Hz/HDR inventory does not establish the capabilities of the user's live connection. - - -Detection selects Windows' preferred resolution and the highest freshly reported refresh rate at that resolution in the draft. It does not guess native resolution from the largest driver mode (which could be virtual/supersampled). If Windows does not report a preferred resolution present in the inventory, the observed mode is retained. Explicit detection replaces even a supported fallback draft mode, preserving arrangement and orientation; it does not apply the chosen mode to the live desktop. - -Monitor cards put the include switch beside the name. Disabled cards omit mode fields, the primary-display action, and the completed-detection message; warnings and recovery errors remain visible. - -## Cold-display HDR and wide-window correction - -Detection enables an inactive target at the preferred pixel dimensions reported by CCD, rather than probing a 640x480 desktop that may suppress HDR availability. It logs the actual probe dimensions, draft recommendation, inventory size and HDR result. Existing displays remain checked and the original layout is restored afterward. - -Apply permits a previously disabled display whose HDR state is unreadable while inactive. After enabling its requested mode it waits up to three seconds for a fresh HDR reading, records its retained HDR preference before any HDR setter, and then changes HDR. On rollback that preference is restored while the target is still enabled, before restoring the original topology. Already-active displays with unreadable HDR still fail preflight. Cached capability data never bypasses live HDR validation. - -The editor uses one to three monitor-card columns according to window width. Detected settings remain editable; completed setup copy disappears and detection becomes a subtle Detect again action. Initial setup, errors and recovery controls remain available. - -## Mirror editing - -Desktop mode offers Extend desktop or Mirror with another enabled display. Joining chooses a reported common resolution, keeps each output's reported refresh rate when available, and shares source size, orientation and position. Changing a shared resolution updates all group members. Detaching places the selected output to the right as a separate desktop. One arrangement tile represents the group and moves all members together. Save changes only the preset; applying still uses fresh CCD routes and exact verification. - -HDR remains an explicit per-target request. Windows can restrict HDR in duplicated layouts; Director does not silently discard an HDR-on request. Select HDR off or use an extended layout when validation reports it unavailable. A successful unsupported-HDR API result is distinguished from a failed query. See [Microsoft's HDR guidance](https://support.microsoft.com/en-us/windows/hardware/display-graphics/hdr-settings-in-windows). diff --git a/docs/FPS.md b/docs/FPS.md index f7b0a9c..414ae43 100644 --- a/docs/FPS.md +++ b/docs/FPS.md @@ -1,52 +1,51 @@ # FPS limits -Director can change the global FPS setting through the NVIDIA driver or an installed, running RTSS. Both work directly from the app; no rtss-cli, Profile Inspector or helper executable is required. Director does not need to stay open after applying. RTSS must stay running when its limiter is selected. +Director sets the global frame rate limit in the NVIDIA driver or in RivaTuner Statistics Server (RTSS). It talks to both directly, so no extra tools are needed, and Director doesn't need to stay open afterwards. RTSS must be installed and running to use its limit. ## Use it -- In **Now → FPS limit**, turn on **Change FPS limit**, choose NVIDIA or RTSS, choose **Set a frame rate limit** (a number, or **VRR-safe cap**) or **Remove the global limit**, and click **Apply changes** at the bottom of the page. -- In a **scene**, use the same controls. Saving does not apply anything. The scene applies TV preparation → displays → audio → FPS → final apps/URIs. A scene containing only FPS is supported. -- **Change FPS limit off means leave all FPS settings unchanged.** To remove the selected provider’s global cap, turn the switch on and choose **Disable global limit**. -- Only available methods appear in the dropdown. Open RTSS first if using it. Check available methods can rediscover unavailable providers. Unavailable saved methods remain saved but fail preflight before scene device changes; there is no automatic provider fallback. +On **Now** or in a scene's **FPS limit** step: -Headless commands: +1. Turn on **Change FPS limit**. With it off, Director leaves all FPS settings as they are. +2. Choose the method: NVIDIA or RTSS. Only methods available on this PC are listed; open RTSS first, then use **Check available methods**. +3. Choose **Set a frame rate limit** with a number or **VRR-safe cap**, or **Remove the global limit**. - director fps status - director fps set nvidia 117 - director fps set nvidia off - director fps set rtss 120 - director fps set rtss off +On Now, the change waits for **Apply changes** on the display map. In a scene, it runs after the Sound step and before the After actions. A scene can contain only an FPS step. If a scene's method isn't available when it runs, the scene fails before changing anything; Director never switches to the other method. -Existing director scene apply commands use the saved FPS choice without opening the window. +```text +director fps status +director fps set nvidia 117 +director fps set rtss vrr +director fps set nvidia off +``` ## VRR-safe cap -Turn on **VRR-safe cap** under Set a frame rate limit to cap a little below the primary display's refresh rate, so a VRR display stays in its variable-refresh range. Director uses the curve NVIDIA Reflex uses, refresh − refresh²/3600 (rounded down): 240 Hz → 224 FPS, 165 Hz → 157, 144 Hz → 138, 120 Hz → 116, 60 Hz → 59. +**VRR-safe cap** limits frames a little below the primary display's refresh rate, so a variable refresh rate display stays in its VRR range. Director uses the curve NVIDIA Reflex uses, refresh − refresh²/3600, rounded down: -The refresh rate is read when the cap is applied, not when it's saved. A scene reads it after its Displays step, so switching to a 120 Hz TV gives 116. Now and the CLI (`director fps set rtss vrr`) read the current primary display. If the refresh rate can't be read, the step fails before anything changes. The dialog previews the value from the scene's display preset, or the current layout. +| Refresh rate | Cap | +| --- | --- | +| 240 Hz | 224 FPS | +| 165 Hz | 157 FPS | +| 144 Hz | 138 FPS | +| 120 Hz | 116 FPS | +| 60 Hz | 59 FPS | -The editor shows the current value of the selected method only. "Remove the global limit" turns off a cap that's already set; turning off **Change FPS limit** leaves the current setting alone. +The refresh rate is read when the cap is applied. In a scene that's after its Displays step, so switching to a 120 Hz TV gives 116. If the refresh rate can't be read, the step fails before changing anything. The step's dialog previews the value from the scene's display preset or your current layout. -## What the setting means +## What the limit affects -NVIDIA changes FRL_FPS in the driver’s global/base profile, not a particular monitor/GPU or a game-specific profile. RTSS changes its global profile. Game-specific overrides, in-game limits, other limiters, V-Sync and frame generation can affect the FPS you actually see. Selecting one method leaves the other unchanged. A running game may need restarting, particularly for driver settings. Readback verifies configuration, not measured game frame rate. +- **NVIDIA** sets the frame rate limit in the driver's global profile, for every GPU and display. Game-specific profiles override it. +- **RTSS** sets its global profile's limit. Per-game RTSS profiles override it. +- Setting one method leaves the other alone. In-game limits, V-Sync and frame generation also affect the frame rate you see. A running game may need a restart to pick up a driver change. +- Limits: NVIDIA 1–1023 FPS; RTSS 1–1000 FPS. RTSS fractional and frame-time limits are left untouched. -The first implementation supports NVIDIA integer caps 1–1023 through the documented setting domain (the installed driver can still reject values), and a conservative Director RTSS range of 1–1000. RTSS fractional or time-based global modes are rejected and left unchanged. Per-game targets, AMD/Intel providers and automatic refresh-rate offsets are outside this slice. +Director reads the setting back after writing it, which confirms the configuration, not the frame rate a game reaches. If a later scene step fails, the previous limit is restored. -## Verification and recovery +## How it works -The GUI and CLI share the same Rust providers and execution policy. FPS calls run on workers under the existing mutation guard. Provider discovery is read-only and serialized with SDK calls. A scene snapshots the selected provider before any TV/display/audio changes and validates availability up front. It writes and reads back FPS after audio, before any launches. Default failure/cancel recovery restores the original cap; NVIDIA predefined/inherited state and RTSS limiter-disable state are preserved. Stop and keep completed changes honors the existing scene policy. +NVIDIA uses the driver settings API (`nvapi64.dll` from System32) to change the global profile's frame rate limiter. RTSS is found through its installation registry entry and controlled through `RTSSHooks64.dll` from that folder; DLLs load only from the install folder and System32. Removing the RTSS limit writes 0 without disabling per-game limits. If RTSS runs elevated and Director doesn't, RTSS may refuse the change; Director reports that instead of elevating. -RTSS has separate saved-cap and limiter-disabled states. Applying a cap clears only the limiter-disable bit when necessary; unrelated flags are preserved. Disabling its global cap writes zero without disabling game-specific limits globally. Save/reload and a separate disk check verify persistence. RTSS and Director may need matching privileges for settings notifications; Director reports blocked operations and never silently elevates or changes ACLs. +Per-game limits and AMD or Intel drivers aren't supported. -NVIDIA uses installed System32 nvapi64.dll and versioned DRS structures. RTSS is discovered from its machine installation registry entry and loads RTSSHooks64.dll from that installation. DLL dependency lookup is restricted to the installed directory and System32. Native interfaces are serialized; no resident Director service or automatic RTSS launch is added. - -## Manual trial - -Apply a cap such as 60 in Now, then check the saved setting in NVIDIA Control Panel / RTSS and test a game that can normally exceed 60. Try Disable global limit, then restore your preferred cap. Repeat through an FPS-only scene and CLI. Check that selecting a method or saving a scene alone changes nothing. A configured game profile can override a global limit, so choose a game without such an override for the first test. - -## References - -- [NVIDIA driver settings API](https://docs.nvidia.com/nvapi/group__drsapi.html), [setting definitions](https://github.com/NVIDIA/nvapi/blob/main/NvApiDriverSettings.h), [interface IDs / ABI](https://github.com/NVIDIA/nvapi). -- [rtss-cli source](https://github.com/xanderfrangos/rtss-cli), used as a protocol/interface reference. Implementation is independent Rust code; the CLI is not bundled or invoked. -- Installed RTSS SDK RTSSProfileInterface.h and RTSSHooksInterface.h are the local interface reference. RTSS itself is not redistributed. +References: [NVIDIA driver settings API](https://docs.nvidia.com/nvapi/group__drsapi.html), [NVAPI headers](https://github.com/NVIDIA/nvapi), [rtss-cli](https://github.com/xanderfrangos/rtss-cli) (protocol reference; not bundled or run). diff --git a/docs/HDR.md b/docs/HDR.md deleted file mode 100644 index f8a3273..0000000 --- a/docs/HDR.md +++ /dev/null @@ -1,17 +0,0 @@ -# HDR control - -HDR is an optional per-monitor setting in display presets and Now. New captures include Windows' reported HDR preference when the display/API supports it. The toggle is disabled with an explanation when that state is unavailable. - -## Storage and application - -The optional monitor hdr field is a boolean. Missing/null means leave HDR unchanged, preserving legacy presets. Opening a legacy preset in the editor initializes an unspecified HDR choice from the fresh Windows state; merely opening/cancelling never writes the file. - -Display Apply validates topology, snapshots the actual configuration and known HDR state, applies topology first, then changes HDR by freshly resolved monitor identity. Readback verifies the requested HDR setting as well as geometry/modes. Commit retains the verified configuration; recovery restores known prior HDR states as well as the topology. A requested HDR change is rejected before mutation when its prior state cannot be read for recovery. - -The adapter uses HDR-specific device-info types GET_ADVANCED_COLOR_INFO_2 (15) and SET_HDR_STATE (16), with checked WinSDK-compatible C layouts. It does not use the generic Advanced Color/WCG setter. Unsupported API versions or devices remain unavailable; there is no guessed fallback that could toggle WCG instead of HDR. See [Windows device-info types](https://learn.microsoft.com/en-us/windows/win32/api/wingdi/ne-wingdi-displayconfig_device_info_type). - -The captured value/readback concerns Windows' user HDR setting, not a measurement of emitted light or game HDR rendering. Changing HDR can affect available mode combinations; strict post-apply readback and recovery still apply. No durable process-crash recovery is added by this slice. - -## Validation scope - -Tests cover HDR readback requirements, legacy leave-unchanged behavior, commit failure recovery, and ABI sizes. Native UI checks cover supported/unsupported toggle state, draft persistence, and cancellation without changing live HDR. Physical HDR flips and HDR-specific native setter failures have not been injected on hardware. diff --git a/docs/IMPLEMENTATION.md b/docs/IMPLEMENTATION.md deleted file mode 100644 index 26e7692..0000000 --- a/docs/IMPLEMENTATION.md +++ /dev/null @@ -1,234 +0,0 @@ -# Current implementation - -Updated: 2026-11-03. This covers the current setup view, audio/display presets, and guided LG/Samsung TV setup, MAC learning, and basic status/power/input controls, not the full pre-1.0 plan. - -The leading summary reflects the current build; dated implementation notes below retain historical validation limits. See [Scenes](SCENES.md) for the current composition scope. - -## Implemented - -- Native Samsung Tizen provider and brand selection, optional direct HDMI compatibility tests with explicit user confirmations, hidden unsupported controls and redacted JSON report export. GUI, CLI, display preparation and scenes share provider dispatch. Physical Samsung validation is pending. See [Samsung preview](SAMSUNG.md). - -- Native Scenes cards/editor and shared headless runner, independent preset/TV references, optional TV preparation, bounded HDMI audio readiness, native executable/folder pickers and ordered app/URI dispatch. Progress, cancellation, display confirmation and scene-wide Windows recovery are included. [Current scene scope](SCENES.md). -- Explicit remembered TV audio endpoint metadata in setup/editing. No name-based automatic pairing. - - -- One native WinUI 3 frontend through Microsoft Windows Reactor 0.100.0, selected by the user after comparing interactions. The root package builds director.exe; there is no separate frontend package or alternate GUI feature. -- Native Audio presets main view, compact selectable rows with visible Apply/Edit/Delete icon buttons and tooltips, Add/Edit page, Save/Cancel, native deletion dialog, and InfoBar results. -- Name, output dropdown, optional volume, failure policy, retained unavailable output identity, and device-ID disclosure/Copy. Navigation and disclosure state survive form updates. -- Shared versioned persistence in the Windows Local AppData known folder, stable preset IDs, case-insensitive unique names, stale-writer detection, and corrupt-file preservation. -- Direct Core Audio reads and volume control, isolated PolicyConfig default switching, all three output roles with an optional separate communications device, optional microphone/capture roles, snapshot/readback/recovery, and keep-changes alternative. Mute is preserved. -- Background work, message-based UI updates, cross-process operation mutex, and native close protection while work is active. -- Headless presets/list/check/apply commands in the same executable, using the same backend without creating a window. -- SVG source artwork, embedded executable icon, adjacent window icon, and machine-local Director desktop shortcut. - -## Display capture - -- Native Display presets navigation/list with capture, name/save, view/rename, Cancel, and confirmed deletion. Audio and display drafts survive page switches independently; saving never changes hardware. -- Direct Windows CCD enumeration for active and named inactive targets; exact refresh fractions, source/target identities, names/device paths, enabled state, position, primary source, and orientation. Current GDI settings supply actual desktop extents; raw CCD sizes are retained separately to handle portrait driver differences correctly. -- Independent versioned display-presets.json in the existing Local AppData folder, with the same atomic writes, operation ownership, stale-writer checks, and corrupt/future-file preservation. -- Headless display current/presets inspection and named capture, without GUI or audio initialization. Native Apply and timed confirmation/recovery are implemented; see [Apply behavior and validation](DISPLAY_APPLY.md). See [display capture scope](DISPLAY_PRESETS.md). - -## Validation - -Before promotion, the native frontend passed its release build, strict linting, formatting, and hidden-window close-guard test. The backend passed 13 tests for transactions, recovery, persistence, validation, and concurrency. - -Native accessibility automation covered Add/Save, optional volume persistence, Edit/Cancel, duplicate-name errors, deletion cancellation/confirmation, restart persistence, pane state, output dropdown, and device-ID disclosure. Owned-window captures were inspected at 1000 x 700 and 760 x 600 logical client sizes. Temporary fixtures were removed and original preset data preserved. The only automated Apply targeted a guaranteed nonexistent endpoint and returned No changes made before any Windows audio write. - -Headless checks covered help, preset listing, read-only Windows audio access, missing names, and invalid volume. Earlier user reports accepted the shared backend workflow for real output switching, optional volume, saved presets, and terminal application. The user subsequently reported that native WinUI interactions are substantially better and selected this frontend; that is not a separate claim of observed physical Apply or recovery through every new UI path. - -After promotion, the canonical director.exe passed the optimized release build, all 14 tests (13 backend plus one native close-guard test), strict all-target Clippy, and formatting. Its native UI automation again passed preset CRUD, optional volume, dialogs, persistence, pane/dropdown/device-ID state, default/narrow captures, and guaranteed-missing-endpoint Apply. Original presets were preserved; the unsaved-form check left the settings file byte-for-byte unchanged. Headless checks passed, the main Director shortcut was verified against the new executable, and the obsolete comparison shortcut was removed. Source/configuration/docs/lockfile scans found no removed frontend dependencies or references. Machine-specific logs, captures, fixtures, and resource samples remain under globally ignored .localonly. - -Display-capture validation on 2026-10-31: the optimized release build, strict all-target Clippy, and formatting pass. All 20 tests pass (19 backend/model/storage/native-parsing tests plus the native close-guard test). Added coverage includes negative positions, cloned sources, fractional rates, invalid mode indices/types/identity, captured-data preservation during rename, and portrait desktop extents while retaining raw CCD sizes. - -Live read-only Windows capture found two enabled monitors and one named disabled TV. Independently read Windows desktop bounds confirmed the primary monitor and the portrait monitor position/dimensions. Native UI automation exercised navigation, independent drafts, capture/save, view/rename/cancel, duplicate errors, deletion confirmation/cancellation, restart persistence, and default/narrow layouts. CLI capture/listing and duplicate rejection passed; duplicate capture preserved file bytes. Captures of the native editor/list/error/dialog were inspected at 1000 x 700 and 760 x 600 logical client sizes. These were native accessibility checks, not a claim of full real mouse/keyboard or assistive-technology testing. - -Temporary display fixtures were removed, original display data/absence was restored, audio presets were unchanged, and live display snapshots before/after matched. Existing audio UI regression checks passed again, including a guaranteed-missing endpoint preflight without audio writes. No physical monitor change was performed. Machine-specific evidence stays in ignored .localonly. - -Display Apply validation: all 31 tests, strict lint/format, and the optimized release build pass. Native identity/routing validation and no-op checks passed. Real secondary-monitor enable/offset, 15-second automatic reversion, native Revert, Keep/persistence, guarded close, cross-process exclusion, and headless verified restoration were exercised; the original single-screen desktop was restored. The native confirmation dialog was captured and inspected at default/narrow sizes. Missing-monitor rejection made no changes. Owned test presets were cleaned while preserving the existing user preset. See [detailed scope and limits](DISPLAY_APPLY.md). - -## Deferred and limited - -Remaining work includes physical display Identify, DPI/color editing, scenes, scene-level TV orchestration, driver/FPS control, system notifications, guided creation, installer/updater, tray, and startup integration. Mirror editing and standalone TV power/input controls are implemented as detailed below. Drag arrangement, capability-gated HDR, and initial TV setup/pairing are implemented as detailed below. See [Audio](AUDIO.md) for remembered endpoint identities and relinking. - -PolicyConfig is undocumented. Readback does not prove audible playback or force explicitly routed applications to migrate. Forced termination has no recovery journal; stalled display/audio native calls cannot safely be canceled. TV WebSocket receives have their own bounded cancellation. Hardware failure/recovery and deliberately slow device calls need physical validation. Runtime packaging, clean-PC testing, and release licensing remain outstanding; see [runtime notes](WINDOWS_GUI.md). - -## Repository state - -Work remains local and uncommitted. Commit/push only with explicit authorization and retain the existing signing configuration. Desktop shortcuts and machine-specific development material are not repository source. -### Initial confirmation preference — 2026-10-31 (default superseded below) - -Display presets now store an Ask to keep display changes switch. New and legacy presets default to on. GUI and CLI may keep verified changes automatically when it is off; CLI --yes and --confirm override the saved preference for one invocation. Verification, persistence checks, busy-close protection, and failure recovery remain active. - -All 33 tests, strict all-target Clippy, formatting, and the release build pass. Native accessibility checks verified default-on, opt-out saving, restart persistence, Cancel, re-enabling, CLI listing, and conflicting-flag rejection. Default/narrow window captures were inspected. Test presets were removed; the existing preset identity, name, timestamp, and exact layout were preserved, with only the explicit default-on field added during serialization. Audio preset bytes and the live display layout were unchanged. These preference checks did not apply a layout; previous live Apply validation above predates this preference change. - -### Initial custom display creation — 2026-10-31 (interaction revised below) - -Create preset, separate from Capture current layout, opens native per-monitor controls. Existing presets can use Customize layout. Background mode discovery uses DXGI exact refresh fractions and physical interface paths, with an explained CCD preferred-mode fallback for disabled outputs. The editor provides enabled/primary selection, dependent resolution/refresh dropdowns, SVG orientation choices, numeric positions, and a read-only arrangement preview. Pure draft validation protects primary selection, invalid positions, and overlapping extended layouts. Saving never applies hardware changes. - -All 36 tests, strict all-target Clippy, formatting, and release build pass. Native accessibility checks exercised Create, supported resolution selection, the rendered SVG orientation flyout, secondary-disable editing, navigation draft preservation, Save, restart, Customize, and Cancel. Windows validate-only accepted the saved 1920x1080/180-degree custom fixture without applying it. Toolbar, editor/preview, flyout, scrolling controls, and minimum-width window states were inspected using captures of owned windows. Fixture cleanup preserved existing presets, audio file bytes, and the exact live layout. - -The first native run exposed an unsupported Reactor rich-flyout target; it now uses the supported native Button/flyout combination. Checks above cover the corrected build. Creation changes were not physically applied during this slice; earlier display Apply/recovery hardware validation remains separately recorded. Broader monitor/GPU mode changes, disabled-output combinations, and actual assistive-technology/physical input validation remain outstanding. - -### Cohesive direct display editor — 2026-10-31 - -Both preset lists now share the same heading/toolbar component, with aligned top-right refresh and accent + buttons. Display capture is a secondary camera icon before that pair. The display pencil loads all controls directly; Customize is removed. Audio and display edit footers both put Cancel then Save on the right. New GUI, quick-captured, and CLI-captured display presets default confirmation off; existing explicit preferences and legacy presets are preserved. - -The arrangement box supports pointer-captured dragging. A fixed transform during each gesture avoids rescaling under the cursor; dropping snaps nearby edges, resolves overlaps, and normalizes the primary origin. Coordinates are screen-hover details, not editable form fields. The primary Enabled switch is disabled and greyed out; a transparent enabled overlay provides its hover explanation. - -All 38 tests, strict all-target Clippy, formatting, and release build pass. Native accessibility checks verified plus-button alignment, direct Edit, absent Customize/position fields, disabled primary state, GUI/CLI default-off persistence, restart/Cancel, and default/minimum-width layouts. A real pointer press/move/release changed and saved a draft monitor position. Real hover exposed screen resolution/refresh/coordinates and the disabled-primary explanation. Owned-window captures were inspected. Tests did not Apply live displays; test presets were removed, original presets and audio settings were preserved, and the actual Windows layout remained unchanged. - -A native release-order issue was found: Reactor calls ReleasePointerCapture before enqueuing PointerReleased, so CaptureLost may arrive first. Capture-loss cancellation now waits 25 ms on a worker and checks a gesture token, allowing the queued release to finish and preventing stale cancellation of a later drag. PointerCanceled still restores the pre-drag draft immediately. Temporary tracing used to verify the ordering was removed. Full touch/pen/keyboard-only map interaction and deliberate mid-gesture focus/capture failures remain unverified. - -### Current setup, HDR, mode lists, and picker polish — 2026-10-31 - -Current setup is a separate navigation page combining the shared display editor with default audio output/volume controls. Its display and audio Apply operations use the existing engines independently and never write preset documents. Pending edits survive navigation; Discard rereads actual Windows state. Native page roots are keyed separately so scrolling does not leak between pages. Audio choices are reread after display application, preserving pending audio edits. - -Visible Refresh buttons were removed from preset lists; clean page entry still reads the current data. Orientation choices now have compact equal-height rows, aligned stand-only SVGs/text, a standard chevron, and dismissal after selection. The extra icon arrow was removed at the user's request. - -Mode discovery no longer requires a historical adapter LUID to match a physical device path. It accepts unspecified as well as progressive DXGI scan-line ordering, while rejecting explicit interlaced/stereo modes. Native UI enumeration exposed multiple resolutions on both monitors and multiple refresh choices on AW3225QF. P27h-20 exposed one refresh choice at its native resolution, as reported by Windows. - -HDR is an optional per-monitor setting, capability-gated using the HDR-specific Windows API. Missing legacy fields leave HDR unchanged. Explicit HDR settings participate in preflight availability/recovery checks, readback, persistence, and restoration. The native toggle was available on AW3225QF and disabled on P27h-20. See HDR.md for the API contract and hardware-test limits. - -All 43 tests, strict all-target Clippy, formatting, and release build pass. Native checks covered refresh-button removal, expanded mode choices, compact orientation selection/dismissal, HDR draft save, Current setup pending state/navigation/discard, and default/minimum-width views. A guarded Current setup audio Apply targeted the already-active Console+Multimedia output without requesting volume, returned Already set, and preserved both defaults and volume. Preset files remained byte-identical during that live-view check; earlier owned HDR fixtures were cleaned while preserving the existing user preset. Display/HDR state was not changed by these checks. - -An unrestricted whole-window UI Automation FindAll while an audio dropdown was open stalled the provider/test window. Those exact owned test processes were terminated after confirming no device operation held the operation gate. Searching only the dropdown's own items completed correctly, including selection and the no-op Apply. Test helpers now scope that query. No temporary event tracing remains in source. Full assistive-technology stress, native HDR toggles/failure injection, and wider hardware combinations remain unverified. - -### HDR explanation tooltip — 2026-11-01 - -Rebuilt the desktop executable after Director was closed. The permanent unavailable-HDR subtitle has been replaced with a tooltip on an enabled transparent hover layer above the disabled switch. Supported HDR controls also have a short hover description. Native hover verified the reason appears only on hover; the unsupported toggle remains disabled. The unsaved test draft was cancelled, preset/audio files were preserved, and live display/HDR state did not change. - -LG inactive-TV behavior remains unchanged. The attempted inactive-mode filtering was reverted before this build; remembered monitor capabilities are a proposal, and overview monitor drawers remain deferred. The P27 50 Hz* explanation is documented as a Windows cross-resolution choice, not an additional native-resolution pair. - - -## TVs setup/pairing — 2026-11-01 - -Added a native TVs navigation page and consistent +, edit, removal dialog, and fixed Cancel/Save TV footer. Manual IPv4 setup can optionally remember a Windows physical display path/name, independent of presets. Drafts survive navigation. Pairing and authenticated connection/input-list checks run on background workers through native WinHTTP, sharing the operation lock and protected storage. Pairing key/certificate continuity data uses per-user DPAPI. Default TLS 3001 and explicitly selected legacy 3000 are separate modes; no silent downgrade. Name/display-link edits retain pairing; an endpoint change clears it in this first slice. `tv list`, `tv pair`, and `tv check` work headlessly. See [TVs](TVS.md). - -Validation: 52 Rust tests passed (49 library, 3 application), strict all-target Clippy, formatting, and offline release build. New tests cover TV endpoint validation/uniqueness, stale/corrupt storage preservation, metadata-versus-endpoint credential retention, correlated pairing/error responses, protected credential round-trip/tampering, native WinHTTP registration against a loopback mock, and cancellation of a silent WebSocket. Native owned-window checks passed: empty state, add validation, optional real Windows display metadata selection (no display change), draft retention across navigation, default/minimum-size editor and fixed footer, save/reopen/rename, duplicate rejection, disabled check before pairing, and removal cancellation/confirmation. Original TV storage was restored; audio/display preset bytes and live display layout stayed unchanged. Test entries were temporary offline documentation addresses; no real TV was contacted. - -Not validated: physical LG TLS certificate compatibility, unsigned permission manifest acceptance, on-TV approval/denial, or actual LG input responses. Not implemented: discovery/MAC learning, verified IP migration, Wake-on-LAN, input switching/power-off, configurable retry/timing, or scene readiness. MAC/TV identity must eventually be separate from the current connection IP; the user explicitly raised this during implementation. Existing monitor capability-cache and overview-drawer proposals remain unimplemented. - - -User hardware feedback (2026-11-01): the user reports successfully pairing the LG TV and seeing its input list. This establishes a reported successful pairing/input-enumeration path on that TV. The connection mode was not specified, so it does not independently establish encrypted-versus-legacy compatibility. Input switching, wake, power-off, and failure/reconnect behavior remain untested. - - -## Guided TV setup, MAC learning, and wake — 2026-11-01 - -This update supersedes the earlier manual-add and MAC/wake deferrals. Add TV now has seven native steps: name, address, pair/read, PC input, wake addresses, optional Windows display, and review/save. Pairing precedes final saving; successful pairing stays in the draft when input reads fail. Refused MAC reads permit manual entry or skipping wake. Back/navigation retain choices, while changing a new draft’s endpoint invalidates its pairing/read results. Existing TV editors can read and save input/MAC metadata without recreation. Old definitions retain their protected pairing through defaulted optional fields. - -Wake sends standard magic packets directly through Rust UDP IPv4 broadcast in three rounds, using each distinct Ethernet/Wi-Fi/manual MAC. Results describe dispatch, not verified power. No input/display/audio action is applied by setup. Added shared tv learn and tv wake commands; CLI pair also attempts metadata learning while retaining successful pairing if later reads fail. Scenes, input switching, power-off, discovery, and verified IP migration remain unimplemented. - -Validation: 58 passing Rust tests (55 library, 3 application), strict all-target Clippy, and offline release build. Tests cover guide gating/invalidation, MAC validation, partial/denied network data, old paired-definition compatibility, exact 102-byte packet contents, and three actual UDP sends to a loopback receiver. Existing WebSocket, DPAPI, storage, display, and audio checks pass. An additional ignored test-only in-memory WinUI fixture is explicitly launched for post-pairing visual checks; production has no fixture entrypoint. - -Native release checks passed for name/IP/pair screens, Back/navigation/cancel, minimum-size footer, PC/MAC/display metadata save/reopen/remove, disabled Wake without MAC, and headless missing-MAC rejection before dispatch. The fixture exercised input choice, MAC entry/validation, optional display, review, and Back/Cancel at default/minimum sizes. Captures were inspected. Original TV file bytes were restored, original audio/display preset bytes and live display layout stayed unchanged, and no real TV was contacted or woken. Physical MAC reads, the complete revised guide with on-TV approval, and actual LG wake remain user validation work; earlier pairing/input-list success was user-reported. - -## Manual MAC opt-in and read-only LG status — 2026-11-01 - -Added the native Enter MAC address manually switch in setup/editing, default off for new TV setup. Hidden draft text is preserved but does not block progress; saving while off removes only the manual target. Existing manual values reopen enabled. User reports the TV functionality works. An explicitly run read-only hardware test returned Active and two valid TV-reported network addresses (Ethernet and Wi-Fi), without any power/input/settings write. This test is ignored by normal runs and requires exactly one paired TV, with explicit user authorization to perform the check. - -The normal 58 tests and strict Clippy passed, and the release build was updated. Native checks exercise initial hidden state, showing/hiding the field, retained draft text, disabled invalid validation while hidden, re-enabled validation, and existing manual-value persistence. Settings fixtures are restored; no physical power command was sent. A basic status/power/input modal is a recommendation, not implemented in this patch. The current power icon still dispatches Wake only. - - -## Basic TV control modal — 2026-11-01 - -Implemented native TV controls with fresh status/current external input, a single state-aware Turn off/Wake button, refresh, and an explicit Switch input action. The list’s Wake-only icon is replaced by a TV-controls opener. On, screen-off, and screen-saver states select Turn off; off, standby, and unknown select Wake, disabled without a saved MAC. Fresh state is checked before acting, while preserving the action shown to the user: stale Wake never turns off an already-on TV, and stale Off never wakes a TV that became off/standby. Unreachable/unknown does not authorize an off request. - -The shared tv_control engine validates fresh inputs, avoids confirmed no-ops, sends explicit SSAP commands, and attempts bounded foreground-input readback. Accepted-but-unverified and ambiguous acknowledgment failures are reported honestly. Worker jobs check TV-definition freshness under the operation lock; snapshots/pending selections do not modify settings. A bounded post-action refresh updates the dialog. Close dismisses the dialog without canceling an issued operation; root window close protection continues until completion. Added CLI status/off/input; existing wake remains explicit dispatch. - -Validation: 64 regular Rust tests (61 library, 3 application), strict all-target Clippy, format, and offline release build. New tests cover stale intent races, unknown/unreachable power, wake with unavailable status, fresh input validation/no-ops, accepted-versus-confirmed readback, exact command acknowledgments, and actual native WinHTTP power/input requests against a loopback mock. Ignored native fixtures are explicitly launched for visual checks and do not send real commands. - -Native checks passed for default/minimum modal size, one power control, pending selection without automatic application, Unknown → Wake, stale-input disabling, refresh/error/Close, guide/editor metadata regression checks, and preservation of original TV/audio/display bytes and live Windows layout. A separate read-only hardware check via CLI and the release modal returned On, current PC, and all four HDMI inputs from the user’s LG; refresh worked. No real power-off/input-switch request was sent. Those physical command transitions remain user validation, while wire-level commands were mock-tested. - - -## Action icon and TV UI cleanup — 2026-11-01 - -Added shared remote/delete SVG assets staged beside the executable. The TV row now contains only remote controls, edit, and red-bin remove. Audio and display preset delete actions use the same red bin. Existing action names/tooltips/deletion confirmations are retained, and Apply’s green check/callbacks are unchanged. Removed redundant TV GUI Pair/Check handlers and the editor’s manual Read TV details button; backend/CLI commands remain available. - -Paired-TV editing automatically reads available inputs/MACs on a worker, leaving pending metadata unsaved until Save. Unavailable data falls back to editable saved choices. Changing a saved address/method opens the existing setup guide at Pair; final guided saving retains the newly obtained credential for that endpoint. Duplicate checks exclude the record being reconfigured. Cancel preserves the original TV definition. - -Validation: 64 existing tests, strict all-target Clippy, format, and offline release build pass. Native checks verified SVG images on audio/display/TV actions, absence of removed TV buttons, unchanged Apply controls, default/minimum layouts, metadata save/reopen/delete, and changed-connection Back/Next/Cancel without an early write. TV controls and setup fixtures still pass. Original settings were restored; no preset Apply or TV power/input write was performed. Foreground-owned recapture was used for final visual inspection after an occluded-window capture produced blank client pixels. - - -## Responsive TV controls — 2026-11-01 - -Replaced the outer modal scroll panel with a compact 340-DIP column and a shared input/Switch row. Unavailable inputs use a short placeholder. Local status replaces duplicated global InfoBars; diagnostics use a collapsed disclosure with bounded scrolling. Status reads no longer hold the mutation lock or global busy guard. Dialog tokens/read revisions ignore results superseded by commands, refresh, or closing/reopening. Wake dispatch is immediate and action reports arrive before the follow-up status read; fresh turn-off validation remains intact. - -Validation: 65 regular tests pass, including wake-without-query and stale-read rejection. Strict all-target Clippy and formatting pass. Native in-memory fixtures cover On, pending input selection, a delayed unavailable response, Wake during checking, expanded diagnostics, default/minimum layouts, Close, and a late response after reopening. Original settings hashes and live display layout were preserved. No command was sent to the physical TV during this work. Release build updated for the existing desktop shortcut. - - -## Persistent diagnostics and Options — 2026-11-01 - -Added local rotating JSON-line logs for GUI/CLI startup/exit, background work, audio/display apply stages/results, and TV connection/authentication/request/acknowledgment/power/input/wake stages. UTC timestamps, process and operation IDs, elapsed times, and dialog token/read revision aid correlation. The bounded asynchronous writer coordinates rotation across processes; five files retain roughly 5 MiB total. Keys, credentials and raw TV payloads are excluded by logging only selected stage/result data. Logging errors are isolated from device operations. - -A native Options footer/page contains Open logs folder. It uses Windows Local AppData and native folder opening. Command errors now remain separate from follow-up status notes in the TV modal. - -Validation: 67 regular tests, strict all-target Clippy and format checks pass. Rotation/concurrent-write/escaping tests are included. The native TV fixture preserved an original blocked-command diagnostic across a later unavailable-status response and confirmed correlated log entries with no TV request sent. Default/minimum Options checks and native folder-open acceptance are exercised separately. Settings hashes and live display layout remain unchanged. No real TV power/input command was issued. Explorer's folder could not be independently inspected through Shell automation in this environment; folder-open verification is limited to Windows accepting the native request. - - -Folder-open follow-up: the user reported that dispatch-only success did not reliably open Explorer. Replaced the call with an explicitly COM-initialized STA worker and ShellExecuteEx/SEE_MASK_NOASYNC, returning its native failure rather than assuming that an asynchronous dispatch finished. Known folder existence and user permissions were checked without changing ACLs. Direct Explorer verification remains a separate check. - -The final release passed 67 regular tests, strict Clippy, formatting and offline build. Headless CLI log/flush checks passed. The desktop shortcut was verified to point to the updated release executable. Options layout and shell-return handling passed native checks; the corrected folder action still requires the user's visible-Explorer confirmation because neither Shell enumeration nor UI Automation exposes Explorer in this test environment. No access-control permissions were changed. - -The native shell handoff was not confirmed by the user. The current implementation instead starts Windows explorer.exe directly with the folder argument; status wording describes the request and includes the exact runtime folder/writer state. Windows file-service metadata confirmed that the desktop app and test tools were seeing different log contents at the same nominal path, explaining the apparent absence of desktop-process events in the agent's view. Do not treat the tool-side log as the user's live log without checking this boundary. The final executable update requires Director to be closed. - -Final folder verification: the release was updated after Director closed. The agent opened the updated app, navigated to Options and invoked Open logs folder through UI Automation without moving the mouse. The runtime showed the expected Windows Local AppData log location, initialized logger and written records. The user explicitly confirmed that Explorer opened Logs. The final direct-Explorer implementation is therefore visibly confirmed; earlier shell handoff failures remain historical investigation notes. Director was left open on Options for review. - -## TV power transitions and selective refresh — 2026-11-01 - -Added typed command effects, a separate GUI power-progress state machine, bounded wake retry scheduling, and power-first wake snapshots. Acknowledged Off is explicitly assumed and never inferred from a lost connection. Confirmed input changes update in place without a full modal read. Errors and unconfirmed input results reconcile once, preserving the original diagnostic. Close/reopen invalidates both queued timers and completed reads. Command worker panic/delivery handling returns through normal completion. - -Validation: 70 regular tests, strict all-target Clippy and formatting pass. Core tests cover no input queries before awake, monotonic retry/expiry, manual recovery and assumed-Off semantics. Native in-memory fixtures exercise confirmed input without status reload, Turning off, assumed Off, Waking through an unavailable response, confirmed awake, expiry, retry, minimum-size layout and stopping checks after close/reopen. Settings hashes and live display layout remain unchanged. No power/input request was sent to the physical TV. The retry window is 30 seconds; an already-running native request remains subject to its own bounded timeouts. - - -## Optional TV tip in new display presets — 2026-11-01 - -Added a restrained inline card with Add TV, session dismissal and persistent Don't show again. It waits for preferences/catalog loading and is suppressed for existing TVs and existing-preset edits. Add TV opens/resumes the guide while keeping the unsaved display draft. Shared monitor cards show linked TV names and View TV. Options contains Show TV setup tips; the preference lives in versioned per-user preferences.json with atomic/stale-safe writes. - -Validation: 71 regular tests, strict all-target Clippy, formatting and offline release build pass. A native release check covers the default/minimum layouts, dismissal, persistent hide/restart, Options restoration, guide navigation, preserved draft name and linked-TV navigation. Final screenshots were recaptured with the owned window visible after an occluded capture returned black client pixels. Original TV/preferences bytes were restored; preset files and live display layout stayed unchanged. No TV was contacted and no display was enabled/disabled. Temporary capability-detection setup is not implemented in this pass. - - -## Inline temporary display detection — 2026-11-01 - -Implemented the previously deferred setup flow in display presets. Detection is explicit, uses inline explanation/progress/cancel, and optionally prepares a linked TV. A backend-independent transaction restores and verifies the original desktop after success, cancellation or failure, including partial writes/panics and TV arrival. Failed restoration retains a retryable snapshot and blocks draft Save/Cancel. Confirmed active capabilities are remembered by physical device path and become draft choices only after restoration. The target is enabled in the draft, not left enabled on the live desktop. Inactive fallback selectors are hidden until a usable inventory is available; cached offline choices retain exact refresh fractions and are revalidated on Apply. - -Validation: 78 regular tests, strict all-target Clippy and formatting pass. Native simulated-display checks cover explanation, optional wake stage, reading/restoring progress, cancellation and resulting 4K/120 Hz/HDR controls at default/minimum window sizes. Unit coverage includes failed/partial activation, inspection failure/panic, cancellation before setters, failed TV preparation, restoration retry and cache corruption/precision. All original settings/cache bytes and the live Windows layout stayed unchanged. No physical TV/display was activated during these checks. Real LG/driver activation remains hardware validation. See DISPLAY_SETUP.md for cancellation/deadline/crash boundaries. - - -Display detection now uses CCD preferred dimensions and the highest exact reported refresh at those dimensions for the draft, rather than copying the temporary fallback desktop. Explicit detection replaces supported fallback selections while preserving position/orientation. A regression test covers virtual larger modes, fractional refresh and a supported 640x480 fallback. - -Cold HDR preflight now defers unreadable inactive targets until after activation, records their live retained HDR state before writes, and restores it before disabling during rollback. Detection seeds the native pixel dimensions, and logs its actual active probe. Native plan regression covers inactive HDR vs unreadable active HDR; physical LG/driver verification remains necessary. - -Scoped TV power subscriptions use the existing WinHTTP transport and pinned authentication, cancellation-aware WebSocket watchdog, and worker-to-WinUI event queue. Wake retransmissions are capped and guarded, stale events/readbacks are invalidated, and closing controls cancels listeners and queued retransmissions. CLI semantics and Screen off/on control scope are unchanged. - -Live-TV validation attempt: the TV entry visible to the tool session had no wake address and its endpoint did not answer. No wake packets were sent; the cleanup turn-off request could not pass fresh-status preflight. This is not a successful hardware test. Mock transport and native event/transition fixtures passed. - -Physical LG C1 follow-up passed: Windows' file provider exposed the desktop TV record with verified wake addresses, while ordinary reads in the tool context saw an older record lacking them. Temporary wake metadata was used without changing either saved record. The real native SSAP subscription reported On, acknowledged shutdown produced a reported Standby transition, and the subscription recovered to On after spaced external WOL dispatches. The final explicit Turn off command was acknowledged by the TV. Temporary protected settings copies were removed. This validates real authentication/subscription/reconnection; GUI wake-retry scheduling remains covered separately by unit/native fixtures because the tool-visible saved entry lacks wake metadata. - -Preset list rows were replaced with shared native preview cards. Mirroring supports join/detach, reported common resolutions, shared orientation/position and group dragging, independent reported target refresh rates/HDR intent, group-aware primary handling, and atomic rejection of incompatible changes. Detaching/re-enabling allocates unused logical source keys so outputs cannot accidentally become clones. The existing native apply planner validates source routing and verifies the applied grouping, restoring on failure. Successful unsupported-HDR readings can satisfy an explicit HDR-off request; API errors and requested HDR-on remain strict. - -Validation includes draft/group/drag/source-allocation regressions, native clone-path planning and missing-route rejection, and owned-window fixtures for gallery layout, metadata previews, mirroring, detach, primary changes and wide/narrow presentation. No real monitor topology was changed in these checks; driver-specific mirror combinations require hardware validation. - - -Optional audio routing is implemented in the shared GUI/CLI transaction engine: default three-role output, optional communications override, optional microphone and input volume. Legacy presets deserialize with both optional fields disabled; applying them now follows the user-approved three-role default. No existing preset file was rewritten during implementation. Tests cover missing optional-device preflight, untouched capture when disabled, six-role/two-volume rollback, and serialization compatibility. Native fixtures exercise hidden/revealed fields and cancellation without live audio writes. Automatic TV/audio association remains a proposal, not implemented by this change. - -## Scene/link validation — 2026-11-03 - -The current build passes 103 regular tests (94 library and 9 native-state tests), strict Clippy and formatting. The owned-window scene/link fixture passed create/edit/delete, TV/display/audio selections, action reordering, draft preservation and unavailable audio-link recall at wide/narrow sizes. Inspected actual native captures. It did not write real settings, mutate audio/displays, contact the TV or dispatch apps/URIs. The release build completed and director scene list exited successfully without opening a window or leaving a process running. Physical end-to-end HDMI readiness and recovery remain unvalidated. No commit or push was performed. - -## Samsung preview validation — 2026-11-03 - -111 regular tests pass (102 library, 9 native state), plus owned native UI and loopback TLS fixtures. Strict Clippy and formatting pass. Native checks cover brand/setup/pairing, required different-input precondition, No/Yes confirmation, failed-retest invalidation, saved PC input, redacted report content, and capability filtering in the modal and scene editor at wide/narrow sizes. Synthetic WebSocket tests cover direct frames and denial; TLS tests prove matching-pin command success and zero authorization-bearing headers reaching a mismatched-certificate server. These fixtures do not contact a real TV or mutate live Windows audio/display state/settings. Physical Samsung pairing/wake/off/HDMI compatibility awaits the friend’s report. LG protocol/storage regression tests pass; no physical LG commands were sent. - -## TCL Android / Google TV preview validation — 2026-11-03 - -119 regular tests pass (110 library and 9 native state), strict Clippy passes, and owned native TCL/Samsung guide fixtures pass. Loopback mutual-TLS checks cover complete code pairing, DPAPI round-trip, feature negotiation, keepalive, reported power, one direct HDMI frame, changed-server-identity refusal before commands, incorrect code rejection, and partial-frame deadline enforcement. Native UI checks cover brand choice, blank/invalid code gating, Back/restart clearing the code, HDMI preconditions, Yes/No confirmation, failed-retest invalidation, saved PC input, report privacy and modal/scene capability filtering at wide/narrow sizes. Inspected native captures. No physical TV was contacted; fixtures do not change real settings or Windows audio/displays. Physical TCL compatibility, standby networking and clean-PC distribution remain for the friend to validate. No commit or push performed. - -## Friend guides and report validation — 2026-11-03 - -Samsung/TCL guides now contain six nontechnical steps and name the single JSON file to send. Developer detail was preserved in SAMSUNG_TECHNICAL.md and ANDROID_TV_TECHNICAL.md. Compatibility format 2 adds explicit tester observations, optional model/software/network information, export time, Windows build, architecture, executable SHA-256, wake configuration flags/counts and typed per-TV action history. Pairing pages permit report export before pairing succeeds. History omits raw text, credentials and device addresses; retention/unavailable data are explicit. 121 regular tests (112 library, 9 native state) and strict Clippy pass. Owned Samsung/TCL native fixtures cover failed-pairing export, sanitized timeout/system code, input checks, manual feedback, runtime fields, saved selection and hidden unsupported controls at wide/narrow sizes. No real TV was contacted and fixture settings/audio/display state remain unchanged. - -## NVIDIA/RTSS FPS validation — 2026-11-03 - -126 regular tests pass (117 library, 9 native state), strict Clippy and formatting pass. Pure tests cover partial-write recovery, preserved RTSS enabled state, explicit keep-on-failure, disable versus unchanged semantics, legacy scene loading, FPS-only scenes and launch ordering/recovery. Native read-only discovery finds both installed methods. An explicit 61 FPS native round trip passed on NVIDIA and RTSS; each actual configuration was read back and the exact original snapshot restored and verified: NVIDIA inherited/default zero, RTSS 115 with limiter enabled. The owned native UI fixture passed FPS-only scene create/edit, NVIDIA-first selection, disable/unchanged distinction, direct RTSS Current setup application, and wide/narrow layouts. It performs no real writes and preserves settings/layout. Physical game FPS enforcement, app-specific overrides and running-game restart behavior remain manual validation. No TV, audio or display change was performed. - -Release build completed. Headless fps status and --help passed with explicit process exit checks and no window. Final release readback confirms NVIDIA 0/inherited and RTSS 115/enabled remain restored. Canonical desktop executable updated; actual game FPS validation remains for the user. diff --git a/docs/INSTALL.md b/docs/INSTALL.md new file mode 100644 index 0000000..f206ea5 --- /dev/null +++ b/docs/INSTALL.md @@ -0,0 +1,42 @@ +# Install Director + +## Requirements + +- **Windows 11, version 24H2 (build 26100) or newer**, x64. HDR switching relies on display requests added in 24H2, so setup refuses older versions and points you to Windows Update. +- The **Microsoft Windows App Runtime 2.6**. Setup installs it for you when it's missing. + +## Install + +1. Download **Director-x64-setup.exe** from the [latest release](https://github.com/Xarishark/Director/releases/latest). +2. Run it and choose **Install**. Director installs for everyone on the PC, so Windows asks for administrator approval once. Leave **Create a desktop shortcut** ticked if you want one. +3. Choose **Launch**, or open **Director** from Start. + +Setup and the app aren't code-signed, so Windows SmartScreen may warn before setup runs. Choose **More info → Run anyway** if you trust the download. + +What setup does: + +- Installs Director to `%ProgramFiles%\Director` with its license files, and adds Start menu and (optionally) desktop shortcuts. +- Adds the install folder to the system PATH, so `director` works in any **new** terminal. +- Registers the `director-run:` link that CLI failure notifications use to open their result. +- If the Windows App Runtime 2.6 is missing, downloads Microsoft's signed installer (about 125 MB) from Microsoft, checks its SHA-512 hash, installs it for all users and deletes the download. An offline PC needs the runtime installed beforehand. + +### Quiet install + +From an elevated terminal: + +```powershell +.\Director-x64-setup.exe /quiet +.\Director-x64-setup.exe /quiet DesktopShortcut=0 +``` + +## Update + +Download and run the newer setup. It replaces the installed version and keeps your settings. `director --version` or **Options → About** shows the installed version. + +## Uninstall + +Uninstall **Director** from **Settings → Apps → Installed apps**. This removes the program, shortcuts and PATH entry. Your scenes, presets, TV pairings and logs stay in `%LOCALAPPDATA%\Director`; delete that folder to remove them too. The Windows App Runtime stays installed, since other apps can use it. + +## Build from source + +See [Development](DEVELOPMENT.md). diff --git a/docs/INTEGRATION_REFERENCES.md b/docs/INTEGRATION_REFERENCES.md deleted file mode 100644 index 159108d..0000000 --- a/docs/INTEGRATION_REFERENCES.md +++ /dev/null @@ -1,35 +0,0 @@ -# Integration references - -Projects to consult for design and protocol research. Listing a project does not make it a Director dependency. The first LG setup/pairing slice is implemented; physical TV compatibility is awaiting validation (see TVS.md). Review the relevant source, API limitations, and license before reusing code. - -| Project | Useful research | Director scope | -| --- | --- | --- | -| [DisplayProfileManager](https://github.com/exytral/DisplayProfileManager) | Per-monitor editor controls and display-profile workflows | Inspiration for the planned native monitor editor; preserve Director's independent presets and scenes | -| [DisplayHotKeys](https://github.com/jon-mil-92/DisplayHotKeys) | Display mode, refresh-rate, scaling, and hot-plug workflows | Display capability and usability research | -| [lgtvcli](https://github.com/01dnot/lgtvcli) | LG webOS discovery, pairing, Wake-on-LAN, power, input selection, and remote commands | Research for the planned direct LG integration; do not require this Python CLI | -| [samsung-tv-control](https://github.com/timdevlet/samsung-tv-control) | Local Samsung discovery/pairing, Wake-on-LAN, and remote WebSocket commands | Protocol reference for the implemented native Samsung preview; no Node/CLI dependency, no sequences or SmartThings | - -Samsung's optional SmartThings cloud integration is not an accepted Director feature. Local protocol capabilities, input selection, and state reporting need device-specific validation before making support claims. - -References reviewed on 2026-10-31. These are implementation references, not endorsements or compatibility guarantees. - - -## Samsung direct-command policy — 2026-11-03 - -The user explicitly rejected custom remote-key sequences and menu navigation fallbacks. The implemented Samsung preview offers only tested direct commands; hide unsupported controls rather than substituting a sequence. SmartThings remains optional/unapproved research. - -ColorControl's SamsungDevice.cs uses the local samsung.remote.control WebSocket, Wake-on-LAN, individual ms.remote.control key commands and preset sequences. It does not supply a universal confirmed HDMI-port selection API. Its built-in SamsungButtons list contains KEY_HDMI and KEY_SOURCE, not numbered HDMI1–4 entries. Direct numbered HDMI keys still require model-specific testing. An individual discrete HDMI command is distinct from a menu-navigation sequence; no sequence fallback is accepted. - -Its GetPowerStateAsync reads device.PowerState from http://:8001/api/v2/ when provided. This is more informative than treating every HTTP response as On; transport failure must still remain Unknown in Director. Its PowerOffAsync sends KEY_POWER, tolerates a timeout and then marks local state off; that does not independently verify physical shutdown. - -Sources: https://github.com/Maassoft/ColorControl/blob/master/ColorControl/Services/Samsung/SamsungDevice.cs and https://github.com/Maassoft/ColorControl/blob/master/Shared/Contracts/Samsung/SamsungButtons.cs. This source review adds no Samsung implementation or compatibility guarantee. - -Samsung local pairing/control and explicit compatibility testing are now implemented; SAMSUNG.md documents current behavior and physical-validation limits. This supersedes the earlier deferred implementation status above. - -## TCL Android / Google TV reference - -[tronikos/androidtvremote2](https://github.com/tronikos/androidtvremote2) and the Google Polo protocol are references for the local code-pairing and Remote v2 wire subset. Director implements control in Rust; neither Python nor an external TV CLI is a runtime dependency. See ANDROID_TV.md for scope and physical testing limitations. - -## NVIDIA and RTSS FPS references - -NVIDIA’s official NVAPI DRS headers and interface table define the FRL_FPS setting and ABI. xanderfrangos/rtss-cli and the installed RTSS SDK identify the profile/flag interfaces. Director implements independent Rust native calls and does not redistribute the driver/RTSS or invoke either CLI. See FPS.md for supported global scope and validation limitations. diff --git a/docs/REQUIREMENTS.md b/docs/REQUIREMENTS.md deleted file mode 100644 index 8ada874..0000000 --- a/docs/REQUIREMENTS.md +++ /dev/null @@ -1,203 +0,0 @@ -# Requirements and implementation order - -Status: planned product scope. The audio-output slice now includes named presets and a main view; see [current implementation and validation](IMPLEMENTATION.md) for what works. Requirements below are not a claim that every feature is implemented. - -## 1. Scenes, presets, and actions - -### Display presets - -Capture and apply enabled displays, primary display, resolution, refresh rate, rotation, and desktop positions. Preserve fractional refresh rates where supported. Report missing or ambiguous displays rather than selecting an unintended one. - -A display-only operation makes no explicit audio, TV, Steam, or RTSS changes. Windows may naturally change HDMI audio availability when displays are enabled or disabled. - -### Audio presets - -Create audio presets by selecting input/output devices from dropdowns, not by capturing the current audio configuration. For each selected device, offer a separate Set volume switch with a percentage value from 0 to 100. With the switch off, leave that device volume unchanged. Apply input selection, output selection, and device volume independently. A preset can change only an input, only an output, only an explicit device's volume, or a combination. Omitted settings remain unchanged. An audio-only operation makes no display, TV, Steam, or RTSS changes. - -For the initial implementation, switching Default audio sets the Windows Console and Multimedia roles together. Do not expose Communications controls or explicitly change the Communications assignment. Communications support is deferred. Snapshot, verify, and restore each affected role independently, even if their prior endpoints differ. - -### Scenes - -A scene can select a display preset, an audio preset, either independently, and optional TV/RTSS/final actions. Components can be created independently in any order and reused by multiple scenes. - -A scene is the agreed top-level bundle. Presets hold saved settings; actions perform operations such as TV commands, frame-limit changes, executable launches, or URI dispatch. TV preparation actions can run before presets; app/URI launches belong to the optional final chain. - -Scene stages have a fixed order: **Display → Audio → Apps & URIs**. Omitted stages are skipped. Users may reorder applicable steps within a stage, but cannot move audio before display changes or launches before configuration. TV wake/input preparation belongs to the display stage when required. After display changes, refresh endpoint availability and wait for the selected audio device before applying audio settings. - -References to saved components, update propagation, and deletion behavior remain design proposals; see [the decision record](DECISIONS.md). - -## 2. Creation and management - -The first implementation captures the current monitor layout into a display preset. Audio presets are created separately with input/output device dropdowns and optional Set volume switches/percentage values. Use remembered devices in these dropdowns, including unavailable devices with clear status. Review, name, and save the result. Capturing, choosing a device, toggling Set volume, and saving configure the preset only; they must not change hardware settings or apply the result. - -Provide preset editing, duplication, deletion, and a readable summary. As basic workflows become available, allow independently created presets to be assembled into scenes. - -Add step-by-step custom preset creation later while keeping monitor-layout capture available. Its exact release milestone, including whether it blocks 1.0, is undecided. Capture does not infer desired TV power actions, launch actions, or timings from current state. - -## 3. Remembered audio devices - -- A device must be enumerated at least once before it can be chosen for a preset. -- Retain remembered devices when unavailable and show availability clearly. -- Display the Windows-friendly name and expose a copyable identity in device details. -- Names can change and are not unique. Renaming an endpoint must not change a preset's intended target. -- Prefer `PKEY_AudioEndpoint_StableId` when available on Windows 11 24H2 or later. Fall back to the ordinary endpoint ID when unavailable. -- Treat both IDs as opaque values. Stable IDs are case-sensitive and are not guaranteed permanent. -- Refresh mutable properties after resolving a remembered device. Retain the last observed name while unavailable. -- If the identity can no longer be resolved, allow explicit user relinking. Do not silently substitute an endpoint based on its name. -- Remembering a device does not itself enable automatic switching. - -When a scene enables the TV, wait a bounded, configurable period for its remembered HDMI audio endpoint before applying audio settings. A timeout must not cause selection or volume changes on another device. - -Technical references: [endpoint IDs](https://learn.microsoft.com/en-us/windows/win32/coreaudio/endpoint-id-strings), [Stable ID](https://learn.microsoft.com/en-us/windows/win32/coreaudio/pkey-audioendpoint-stableid), [friendly name](https://learn.microsoft.com/en-us/windows/win32/coreaudio/pkey-device-friendlyname). - -## 4. Integrations - -Project-wide requirement: perform supported operations directly in Director using Windows APIs, device protocols, or libraries linked into the app wherever practical. Do not wrap existing batch scripts or require separately launched helper executables for functionality Director can implement directly. Launching a user-selected application or URI is an intentional scene action, not an implementation dependency. Document unavoidable dependencies explicitly; RTSS remains necessary for the currently planned RTSS-based frame limiting. - -### Windows display and audio - -Control Windows directly instead of requiring Display Changer II or NirCmd. Verify applied state where APIs permit it. API selection and compatibility details need validation during implementation. - -### LG webOS - -Configure/pair a TV, retain pairing credentials locally, wake it using Wake-on-LAN, select HDMI inputs, and turn it off. Support bounded retries and configurable settling delays. Implement these operations without ColorControl. - -Coordinate TV readiness, display selection, and HDMI audio availability. Do not assume that successfully sending a command proves the final physical TV state. - -### Frame-limit providers - -GPU-driver-based limiting is the primary frame-limit method. RTSS is an optional alternative; other external limiter integrations can be added later. The UI exposes a Set FPS limit switch, a Method dropdown (supported NVIDIA/AMD/Intel driver or optional RTSS), and an FPS value. Use Method as the user-facing name for the provider/protocol. With the switch off, this scene leaves frame-limit settings unchanged, matching optional audio volume behavior. Switching this control off does not disable an existing driver/RTSS limit. - -When enabling the action, prefer a supported driver method for the selected GPU; show unsupported/unavailable options clearly and never silently fall back to RTSS. With multiple compatible GPUs, require an unambiguous target. Validate numeric input against the selected method's reported range and step. Choosing a method or editing an FPS value configures the scene only; applying executes the change. Driver support is an accepted product direction, but each vendor integration still requires implementation and validation; it is not a promise of support on every GPU/driver. - -Candidate direct integrations: NVIDIA NVAPI driver settings, AMD ADLX Frame Rate Target Control, and Intel IGCL frame-limit control. Validate the exact setting (including NVIDIA modern Max Frame Rate versus legacy limiter settings), supported GPU/driver combinations, FPS range/step, privileges, global versus per-application scope, and whether running games require restarting. Query support instead of assuming vendor-wide availability. - -Read/set RTSS directly without rtss-cli or frltoggle. Let the user select a supported provider; do not silently apply a different limiter or alter competing limits. Save and restore the chosen provider's actual previous state, including enabled/inherited state where applicable. Reading back a setting confirms configuration, not actual frame pacing inside a game. - -Research references: [NVIDIA driver settings](https://docs.nvidia.com/nvapi/group__drsapi.html), [AMD ADLX FRTC](https://gpuopen.com/manuals/adlx/adlx-sdk-references/adlx-interfaces/3d-graphics/iadlx3dframeratetargetcontrol/), [Intel IGCL](https://intel.github.io/drivers.gpu.control-library/Control/api.html). - -### Ordered final actions - -Allow optional ordered executable launches and URI dispatch, including Steam Big Picture. Executable actions support separate arguments and an optional working directory. Basic actions must not require batch files or a shell. Users can add, edit, remove, reorder, and enable/disable actions. - -Run final actions after configuration. Define their gating after a failed required step and whether executable actions can wait for exit before implementation. URI dispatch cannot generally prove application readiness or completion. Arbitrary scripting is not an agreed initial requirement. - -## 5. Execution and recovery - -Prevent overlapping applications from the GUI and CLI, including during recovery. Report per-step progress and distinguish success, failure, partial application, and recovery results. Never report partial application as full success. - -Failure behavior is user-selectable: - -1. **Revert to previous settings** — the default. -2. **Stop and keep completed changes** — stop further scene actions and report partial application. - -For recovery, snapshot the actual relevant pre-operation state rather than the last saved preset. Include each affected audio role and target device's volume. Track attempted changes, because a failed API operation may already have changed some state. - -Restore reversible changes in an order that respects device dependencies. Verify restoration, continue independent recovery steps after a recovery error, and report incomplete recovery honestly. App launches and URI side effects may be irreversible. TV recovery requires known prior state and a reachable device. - -Display Apply uses an agreed native Keep/Revert confirmation countdown with automatic restoration; the initial timeout is 15 seconds. Per-scene and per-command failure-policy overrides are also undecided. - -## 6. GUI, CLI, and notifications - -- Provide a proper WinUI 3 desktop window for managing presets and devices. -- Keep the window responsive while discovering devices, applying settings, waiting for devices, verifying results, and reverting changes. Perform blocking work outside the UI thread and dispatch progress/results back safely. -- Serialize setting changes and retain a stable operation snapshot; a background worker must not introduce concurrent preset mutations. -- Share application behavior and saved presets between GUI and CLI. -- CLI application works with the GUI closed and does not initialize a window. -- Provide preset listing, status, monitor-layout capture, application, help, and meaningful error/exit reporting. Exact syntax remains proposed. -- Define how simultaneous GUI/CLI requests are handled before implementation. -- Use native Windows notifications rather than custom notification popups. -- Notifications should identify the scene and outcome and allow opening the relevant result details. -- Respect Windows notification preferences. Preserve local results and CLI output even when notifications are suppressed. -- Failure/success notification defaults and an explicit quiet option still need confirmation. - -## 7. Implementation sequence - -This sequence is a planning proposal, not authorization to start development. - -1. Establish the Rust/WinUI 3 shell and shared model; enumerate displays/audio, capture monitor layouts, and configure audio presets through dropdowns without changing settings. -2. Save, review, and apply independent presets with state verification and recovery. -3. Compose scenes and coordinate TV/display/audio readiness, frame limiting, and final actions. -4. Validate notification activation, headless CLI behavior, packaging, and real hardware workflows. -5. Add guided creation and other later features according to agreed release scope. - -System tray mode and starting with Windows are explicitly deferred until after basic functionality. CRU and SpotBye are excluded. - -## 8. Before 1.0 - -Validate display/audio-only isolation, actual desk and TV transitions, fractional refresh/rotation, remembered device reappearance, renamed/relinked endpoints, missing devices, timeouts, partial failures, both failure policies, incomplete recovery, RTSS, ordered launches/URIs, notification suppression, and CLI use with the GUI open and closed. - -Verify UI responsiveness during deliberately slow device operations, timeouts, and recovery, and verify duplicate Apply requests cannot overlap. - -Measure cold startup, idle CPU, memory, and CLI startup on representative release builds. No performance budgets or comparative framework benchmarks have been agreed yet. - -Set the supported Windows baseline, distribution/update model, app/WinUI 3 licensing, and release-blocking feature scope. Validate the packaged app without development tools installed and document working setup/build/test instructions and limitations. - - -## Accepted initial audio navigation - -Start on Audio presets with Add preset and inline Apply/Edit/Delete actions. Add/Edit opens a separate editor page with a name, output dropdown, optional volume, failure policy, and Save/Cancel. Saving must not apply settings. Store named presets between launches and allow applying one through director audio apply with its name. Delete confirms removal and leaves current audio unchanged. Scenes and display navigation are added when those features are implemented. - -## Accepted compact workspace - -Use an overarching app shell with Audio presets as the working view. Presets use compact selectable rows, a plus control to add, and right-aligned SVG actions: green checkmark to apply, pencil to edit, red cross to delete. Hover, selection, and keyboard focus reveal actions; narrow windows keep them visible. All icon controls need accessible names and keyboard activation. Selection must not apply audio, deletion still requires confirmation, and future sections must be visibly unavailable until implemented. See [interface design](DESIGN.md). - -## Accepted editor and convenience additions - -These additions were accepted after reviewing Display Profile Manager; they are backlog scope, not claims of implementation or an immediate instruction to implement every item. - -- Add a visual monitor arrangement preview/map and a distinct Identify action that labels physical screens. Provide direct arrangement editing when the custom editor is implemented. -- Use native per-monitor editor cards with supported-mode resolution/refresh dropdowns, enabled state, exclusive primary-source selection, rotation, and explicit Extend/Clone group controls. Collapse inactive/unselected cards when useful; keep audio presets independent. -- Every rotation choice pairs a rotated display SVG with a plain-language orientation label. Include an asymmetric top-edge/up marker so 0 versus 180 degrees and 90 versus 270 degrees remain visually distinct. Degrees are secondary detail, never the sole explanation. -- Add per-monitor DPI scaling in later display work. Keep Windows UI/text scaling distinct from image/aspect-ratio scaling; hide advanced controls behind an Advanced section and offer Leave unchanged where supported. -- Add stable-identity desktop/Start Menu shortcuts for scenes, using headless application without requiring a resident process. -- Later, allow launching an app/game with a scene and restoring the actual previous setup on exit. Specify launcher/process tracking and abnormal-exit behavior before implementation. -- Add optional preset/scene descriptions and icons as later polish. - -Wallpaper switching remains lower-priority optional scope. Tray, startup, global hotkeys, HDR/advanced display controls, and the guided creator keep their existing deferred/proposed status unless separately agreed. Basic scene composition, TV power/input orchestration and HDMI-audio readiness are now implemented (SCENES.md). See [Audio](AUDIO.md) for audio Stable ID resolution and relinking; initial manual TV setup/pairing is now implemented (TVS.md); accepting this editor design does not make them implemented. -### Display confirmation preference - -Display presets allow users to disable the Keep/Revert prompt for trusted layouts. New presets default off; existing explicit choices and legacy confirmation-on behavior are preserved. Confirmation-off keeps verified changes automatically; failures still recover. CLI follows the preset with explicit --yes and --confirm overrides. - -### TV integration references - -Consult [integration references](INTEGRATION_REFERENCES.md) for the LG and Samsung projects supplied during planning. A native Samsung Tizen preview is now implemented with explicit direct-command testing and report export; physical validation remains pending (SAMSUNG.md). No external TV CLI is required by this decision. - -### Custom display creation milestone - -Create preset starts a new configurable draft from a fresh Windows layout. Keep Capture current layout as a separate quick snapshot action. Existing saved presets offer Customize layout. The first editor includes enabled/primary selection, supported resolution and exact refresh choices, visual orientation choices, numeric positions, a read-only arrangement preview, and draft-only Save/Cancel behavior. Detect invalid coordinates, an extra primary origin, and overlapping extended outputs. New clone grouping, drag placement, physical Identify, DPI/HDR/color controls remain later work. - -### Cohesive direct display editing - -The accepted UI now uses a consistent top-right + on audio and display pages, with matching toolbar and editor-action placement. The display pencil opens layout editing directly. Provide a boxed draggable arrangement map and screen hover details instead of raw pixel inputs. Disable the primary display's Enabled switch with a hover explanation. New GUI/captured/CLI display presets default to confirmation off, preserving existing explicit settings and legacy confirmation behavior. This supersedes the earlier default-on and separate Customize/read-only preview decisions. - -### Current setup and display refinement - -The user requested an alternative combined active-configuration view, explicitly excluding app appearance themes. Provide displays and audio output/volume on one page with independent Apply actions and no preset writes. Preserve staged edits across navigation and read actual state on clean entry/discard. Read audio outputs again after display changes. - -Remove Refresh buttons from preset lists. Use compact left-aligned orientation rows with stand-only SVGs and automatic dismissal after selection. Expose supported resolution/refresh lists independently of stale saved adapter IDs; keep valid unspecified/progressive DXGI modes. HDR is now an explicit capability-gated toggle with verified application/recovery, superseding its deferred status; other advanced color/DPI/VRR controls remain deferred. - -### TV setup and identity — first slice - -Provide a TVs view to add/edit/remove LG webOS devices, explicitly pair with on-TV approval, and check authenticated connectivity without changing TV settings. Store protected local credentials, separate from presets. An optional physical Windows display-path association is device metadata; TV control remains independent of it and of presets. Preserve unavailable links and require explicit relinking when identity changes. IP is a connection address, not durable TV identity. TV-reported MAC learning is now implemented; stable TV identity and verified address migration remain follow-up work; avoid treating a certificate shared by LG models as unique identity. Discovery, power/input actions, and scene readiness remain subsequent slices. - - - -### Guided TV setup and wake — implemented - -New TV setup asks for name, IPv4/connection mode, on-TV pairing, automatically read inputs/network information, an explicit PC-input choice, wake addresses/manual fallback, optional physical Windows display, and final review/save. Keep completed choices across Back/navigation. Retain a successful pairing when an input read fails so it can be retried. Network-info refusal must allow manual entry or skipping wake. Cancel writes no new definition; previously granted TV permission must be revoked on the TV separately. - -Remember Ethernet/Wi-Fi/manual MACs independently of IP/pairing. Reject invalid/zero/multicast/broadcast MACs, preserve remembered values on missing reads, and deduplicate wake targets. GUI/CLI wake uses direct bounded packet dispatch and reports that result without claiming verified TV power. Setup stores PC/display connections; scene-specific wake/input/power/timing preferences remain outside pairing. - -### Basic TV controls — implemented - -Provide a native control modal with fresh power/current-input status, manual refresh, one Turn off/Wake button, and target selection requiring an explicit Switch action. Honor the displayed power intent after fresh status verification; never reverse it because the state changed. A failed status query must not imply Off or authorize an off request. Missing MACs disable wake; explicit wake can run without an authenticated control session. Validate input IDs freshly, skip confirmed unchanged inputs, and distinguish accepted commands from confirmed readback/physical state. - -Keep CLI and future scene power actions explicit and idempotent in intent. Modal interaction must not change TV connection metadata or saved presets. Perform I/O on workers, serialize operations, reject stale TV definitions, and handle closed dialogs without stale UI updates or unguarded window exit. Volume, full remote controls, and scene readiness remain future work. - - -TCL Android / Google TV preview: local code pairing, protected client identity, reported state, direct wake/sleep, confirmed-only HDMI inputs, report export, shared scenes and display preparation. No other TCL platform or physical model compatibility is assumed. - -## Audio presets superseded - -Audio presets were retired in D066. Requirements above that mention audio presets now apply to a scene's Sound step (saved sound) and to the live controls on Now and `director audio` (immediate changes). Saving or editing a Sound step still never changes a device. diff --git a/docs/SAMSUNG.md b/docs/SAMSUNG.md deleted file mode 100644 index 822f483..0000000 --- a/docs/SAMSUNG.md +++ /dev/null @@ -1,16 +0,0 @@ -# Samsung TV: quick test - -You only need Director, your TV remote and a device connected to an HDMI port. Keep the TV and PC on the same home network. - -1. **Add the TV.** Turn it on. In Director, open **TVs → + → Samsung Tizen**. Give it any name and enter its IP address, found in the TV’s network settings. -2. **Pair.** Choose **Pair TV** and accept Director’s connection request on the TV. -3. **Test HDMI switching.** Choose an HDMI port with something connected. Use the TV remote to switch to a different input or the TV home screen. In Director, tick **The TV is on a different input**, then click **Test HDMI**. Answer **Yes** only if the TV actually switches to the chosen port. Repeat for any other ports you want to test. You can skip this if you have no HDMI device connected. -4. **Test power.** Continue through setup, leave the optional Windows display/audio links empty, and **Save TV**. Click the **remote icon** beside the TV. Check its power status, try **Turn off**, then try **Wake**. Give it up to 45 seconds to come on. If Wake is missing or fails, leave that result as No / Not tested as appropriate; you do not need to configure advanced settings to send a useful report. -5. **Fill in the results.** Close controls and click the TV’s **pencil icon**. Under **Test report**, enter the TV model and software version from **Settings → About / Support** if available. Select Wi-Fi or Ethernet and answer the three Yes / No / Not tested questions based on what you actually saw. -6. **Send one file.** Click **Export report…**. A folder opens. Send back the newest **samsung-compatibility-….json** file. No other files or logs are needed. - -**If pairing fails:** stay on that step, fill in the model/network details under **Test report**, and click **Export report…** there. Send the JSON even if nothing worked. If Director itself will not open, tell us that instead. - -The file includes your answers, HDMI results, detected TV information, Director/Windows details and sanitized error history. It excludes pairing secrets and IP/MAC addresses. Nothing is sent automatically. - -[Developer details](SAMSUNG_TECHNICAL.md) diff --git a/docs/SAMSUNG_TECHNICAL.md b/docs/SAMSUNG_TECHNICAL.md deleted file mode 100644 index d21ae04..0000000 --- a/docs/SAMSUNG_TECHNICAL.md +++ /dev/null @@ -1,44 +0,0 @@ -# Samsung Tizen preview - -Director now has a native local Samsung provider. No Samsung account, SmartThings cloud, external CLI or custom remote sequence is required. Physical Samsung compatibility remains unvalidated: this is ready for a friend’s controlled hardware test, not a promise for every model. - -## Setup and compatibility test - -1. Open TVs → + and select Samsung Tizen. Enter its name and static/reserved IPv4 address. Keep the TV on. -2. Pair and accept Director in the TV’s on-screen connection prompt. The token, or the fact that a tokenless TV authorized the client, is protected by Windows for this account. -3. Director reads model/firmware and network addresses when the TV reports them. Missing fields remain Not reported; failure to read optional information does not discard successful pairing. -4. Optional HDMI test: choose a connected HDMI 1–4 port, use the physical remote to start on a different input, and check that precondition. Keep Director visible on another screen while testing. Test HDMI sends exactly one KEY_HDMI command. There is no SOURCE/menu-navigation fallback. -5. Answer Did the TV switch to HDMI n? Yes enables that direct command; No leaves it hidden. Sending successfully by itself never enables the feature. Each port is tested separately. The latest test for a port controls availability, and stored model/firmware changes invalidate prior confirmations. A failed retest removes the port and clears it as the PC input. Next can skip input control entirely. -6. Optionally choose a confirmed port as the PC input used by scenes. Configure wake addresses (Samsung’s network standby must be enabled), Windows links, then save. Missing wake addresses hide Wake rather than presenting an unsupported button. - -Testing changes the TV input only after the explicit test action. Saving/canceling does not undo a sent command. Cancel discards the TV draft and its unsaved tests; export first if those results should be retained separately. Editing a saved Samsung TV exposes the same test/export form. Changing its connection requires pairing again before a test can send saved authorization to it. Explicit CLI re-pairing clears prior test confirmations. - -## Send us the report - -Choose Export report in the compatibility section of setup or Edit TV. Director saves JSON in the Windows Local AppData Director/Reports folder and opens that folder. The report captures the current draft, including tests before Save. Your friend can attach that JSON to the chat. Nothing is uploaded automatically. - -Reports contain Director/report versions, Samsung brand, model/firmware when reported, paired status, connection mode, reported token-auth capability, timestamps, port test send outcomes and explicit confirmations. They omit pairing tokens, certificates, IP/MAC addresses, names/aliases, TV IDs, display/audio links, raw responses and arbitrary error messages. They are built from an allowlist, rather than redacting a full catalog or application log. A successful user-confirmed test applies only to that saved entry and observed model/firmware; it does not establish universal Samsung support. - -Headless export: director tv report "TV name". For logs of general app operations, Options → Open logs folder remains available; the compatibility JSON is the intended shareable Samsung report. - -## Implemented control and scene behavior - -- Local pairing and saved authorization over Tizen’s remote WebSocket. Encrypted port 8002 is the default; legacy unencrypted 8001 is an explicit opt-in, with no automatic downgrade. -- Wake-on-LAN uses the existing bounded dispatch/retry behavior and requires a learned/manual MAC plus TV network standby. -- Power reads device.PowerState from the local /api/v2/ information endpoint. HTTP success alone never becomes On, and a timeout never becomes Off. On/Standby/Off are reported only when present; otherwise Unknown. -- Turn off requires a fresh On/awake report. The provider authenticates, checks again immediately before sending one KEY_POWER, then reports Sent / Off assumed. It cannot guarantee atomic idempotence against somebody pressing the physical remote at the same moment. It never sends a blind toggle for Unknown/unreachable state. -- Normal input controls and scene input choices exist only for confirmed direct ports. Input readback is not supported and its UI is omitted. Commands are reported as Sent, not Accepted/Confirmed by the TV. -- A modal-scoped four-second polling interval plus bounded requests updates Samsung power; LG retains its scoped subscription. Poll results are timestamped before the request so pre-command reads cannot overwrite newer state. No resident daemon is required. -- Scenes and temporary display preparation use the same provider dispatcher as the GUI/CLI. A scene waits for reported awake state, sends an optional confirmed direct input command, then uses existing display/audio verification. Samsung input readback is not invented or waited on forever. Models that do not report usable power state cannot complete automatic TV readiness yet; omit TV preparation and turn the TV on manually for those models until validated support is added. - -Older non-Tizen Samsung protocols, automatic discovery, volume/remote panels, screen blanking and SmartThings are outside this slice. Unsupported buttons are hidden. Supported controls may still be temporarily busy or disconnected, with truthful progress/error feedback. - -## Transport and validation - -Native WinHTTP is shared with the existing LG integration. First-pairing TLS certificates are remembered inside DPAPI data. Samsung puts its token in the upgrade URL, so a synchronous SENDING_REQUEST callback checks the exact remembered certificate before authorization-bearing headers are sent; mismatch aborts the request. Redirects are disabled and requests/frames/responses are bounded. No token or full URL is logged. A certificate pin is not proof of a globally unique TV identity. - -Validation covers legacy LG loading, brand-change invalidation, strict command generation, token/tokenless handshakes and denial, state parsing, latest-confirmation/firmware gating, redacted reports and truthful unacknowledged outcomes. Native loopback tests exercise Samsung WebSocket frames. Owned TLS fixtures verify matching-pin command success and zero HTTP headers reaching a mismatched-certificate server. Native UI Automation covers brand/setup/pairing, test preconditions, No/Yes results, saved PC input, report content and hidden modal/scene controls at wide/narrow sizes without moving the mouse or changing real devices. Physical Samsung pairing/wake/off/HDMI testing remains pending. - -Protocol references: [samsung-tv-control](https://github.com/timdevlet/samsung-tv-control/blob/main/src/api/local-tv.ts), [ColorControl SamsungDevice](https://github.com/Maassoft/ColorControl/blob/master/ColorControl/Services/Samsung/SamsungDevice.cs), and [Microsoft WinHTTP callback documentation](https://learn.microsoft.com/en-us/windows/win32/api/winhttp/nc-winhttp-winhttp_status_callback). These are references, not runtime dependencies. To copy the preview to another PC, keep its icons folder and director.ico beside director.exe; the compatible Windows App Runtime requirement in WINDOWS_GUI.md still applies. No installer/runtime bootstrap is provided by this change. - -For the current format-2 report contents, tester result fields and sanitized action history, see DIAGNOSTICS.md. Use SAMSUNG.md for the short friend instructions. diff --git a/docs/SCENES.md b/docs/SCENES.md index c3d7e46..953d79a 100644 --- a/docs/SCENES.md +++ b/docs/SCENES.md @@ -1,88 +1,69 @@ # Scenes -Scenes are saved in the Windows Local AppData Director folder as versioned scenes.json. They reference display presets and remembered TVs by ID, and hold their sound settings inline (the Sound step); display layouts and pairing credentials are not copied into scenes. Unique names are case insensitive. Stale writers and malformed/future-version files are rejected without overwriting them. Removal of a referenced preset or TV is blocked with the scene names; edit those scenes first. Missing references from external file edits remain visible and must be relinked explicitly. +A scene is everything you want to switch together: a display layout, sound, a TV, an FPS limit, and apps or links to open. Applying it changes everything in one go, checks that each change took effect, and puts things back if a step fails. -## Native editor +## Your first scene -Scenes uses the existing + button and rectangular preview-card vocabulary, with Apply/Edit/Delete in the same position as presets. The editor has optional TV preparation, Displays, Audio, and ordered After setup sections. Wide windows show an execution summary beside the form; narrow windows stack it. Manage preset buttons preserve the scene draft across navigation and reload available presets on return. Save only saves. Sound-only, display-only and action-only scenes are supported. +With no scenes yet, the Scenes page shows **Start with your everyday setup**. It reads your current screens, default output and volume, and global FPS limit; untick anything you don't want, name it (Default unless you change it) and choose **Save everyday scene**. Saving doesn't change anything on your PC. If one of your saved display presets has the same layout, the scene uses it; otherwise Director saves the layout as a new preset too. **Build a scene from scratch instead** opens an empty editor. -TV preparation selects one saved TV, wake-if-needed and optionally a reported input (initially its saved PC input). The Sound step can use a TV's linked output ("TV's sound"); it does not implicitly wake or switch the TV: TV preparation is a separate explicit choice. See the Sound step section below. +## Steps -App actions use the native executable/folder pickers, separate arguments (one per line, spaces preserved) and an optional working directory. URI actions dispatch through the Windows registered handler. Add, edit, reorder and remove final actions. No scripts or shell command parsing are involved. Dispatch is reported honestly; app readiness, process exit and URI completion are not tracked. Disabled per-action drafts and per-action icons remain follow-up polish. +The editor shows a scene's steps as cards in the order they run. Choose a card (or its pencil) to edit that step in a dialog: **Done** keeps the changes and **Cancel** puts the step back as it was. The bin clears a step. Empty steps show an **Add** button. -## Shared execution +| Step | What it does | +| --- | --- | +| **Before** | Runs apps or opens links first. An app can wait until it finishes; the scene stops if it fails or runs longer than the device wait in Options. | +| **Prepare TV** | Wakes a saved TV if needed and switches it to an input, usually your PC's. Optionally turns the TV off when you leave the scene. See [TVs](TVS.md). | +| **Displays** | Applies a saved display preset. See [Displays](DISPLAYS.md). | +| **Sound** | Sets the output, volume, mute, a separate calls device and a microphone. See [Sound](SOUND.md). | +| **FPS limit** | Sets or removes the global NVIDIA or RTSS frame rate limit. See [FPS](FPS.md). | +| **After** | Runs apps or opens links once everything else has succeeded. | +| **When leaving** | Runs when you switch to another scene or end this one, for example `steam://close/bigpicture`. | +| **Return** | Optional: the scene to go back to when you end this one. | -GUI and CLI resolve fresh catalogs under the existing cross-process operation lock. They use the same runner. All scene I/O runs away from the UI thread. Progress and final results use structured rotating logs; raw TV credentials are excluded. The runner validates references and app paths before any device changes, then snapshots the actual relevant Windows state, not a previous preset. +Every step is optional, so a scene can be sound only, displays only, or just a set of apps. Actions are **Run app**, **Open link** and **Close app**. Close app asks every running copy of the program to close, waits up to 10 seconds, and ends it only if you turned that on; a program that isn't running counts as closed. App arguments go one per line, and nothing passes through a shell. -Order is fixed: TV readiness/input → Displays → Sound readiness/apply → final apps/URIs. Omitted stages are skipped. TV and audio readiness waits are individually bounded by the scene timeout (default 30 seconds, 1–120 allowed); individual transport calls still have their own existing timeout and cancellation is checked between them. Wake dispatch is capped at five attempts, spaced at least five seconds apart, and only occurs when an awake state has not been reported. Input selection must be read back before display application continues; while waiting, the input is requested again (at most every 1.5 seconds) if the TV reports another one. Once it is read back, TV input protection (Options, default 10 seconds, 0–60, 0 off) keeps the TV on that input on a background thread while the scene continues: it polls every 0.5 seconds and switches back when a TV box or console has taken the input over (another input or an app in front). Only TVs that report their current input (LG) get it. Any other TV power or input request, a new scene and a scene that stops and restores end the guard first, from any Director process: the guard keeps its token in `tv-input-guard.txt` in the settings folder, every TV power or input request deletes that file, and a guard whose token is gone stops at its next poll. A CLI run waits for its guard before exiting. No display detection probe runs automatically: a scene uses a previously configured/verified display preset. +The last entry in the display preset and TV lists (**New display preset…**, **Add TV…**) opens that editor and brings you back to the scene with the new item selected. -After displays, enumerate fresh audio devices until every selected output/communications output/input is active and resolves exactly by endpoint ID. A timeout never substitutes another device. Apply the shared audio request, including optional microphone and volume semantics. Display presets retain their saved Keep/Revert preference; the GUI uses a native 15-second dialog and CLI accepts an explicit override. +## Applying a scene -On failure/cancel, stop subsequent stages and final actions. Default recovery restores requested device levels while newly enabled endpoints are still available, then restores the Windows display snapshot and original render/capture role IDs. It verifies restoration and reports incomplete recovery if needed. TV preparation is included in Windows snapshots because waking a TV can itself change Windows topology/defaults; an unchanged display snapshot needs no restoration write. Audio role snapshots precede TV/display preparation; a newly appearing device’s volume can only be captured once it becomes available, immediately before its audio writes. Input roles are never read or written unless the Sound step picks a microphone. A display-only scene also snapshots render defaults for failed-display recovery. Display application retains its own safety recovery even when the scene keeps earlier completed stages. TV power/input and dispatched app/URI effects are explicitly not rolled back. No screen blanking is implemented or planned. +Choose **Apply** on a scene card, or run `director scene apply `. Steps run in a fixed order: **Before → Prepare TV → Displays → Sound → FPS limit → After.** -## Headless commands +- Before anything changes, Director checks the scene's references and app paths and records the current Windows settings it might change. +- The TV step waits until the TV reports it's awake and on the right input. With [TV input protection](TVS.md#tvs-in-scenes) on, Director keeps it there for the first seconds while the rest of the scene carries on. +- After the displays change, the Sound step waits for the chosen devices to appear (a TV's HDMI audio often appears only now), up to the device wait in Options. It never picks a different device instead. +- A display preset that asks to keep changes shows the Keep/Revert prompt as usual. -- director scene list -- director scene check tv-gaming -- director scene apply tv-gaming [--yes | --confirm] +**If a step fails** or you cancel, the remaining steps and the After actions don't run, and Director restores the displays, default devices, volumes, mute and FPS limit it changed, then checks the restore worked. To keep the steps that already finished instead, turn on **Keep changes that finished if a later step fails** in Options. TV commands and apps you launched can't be undone, so they're never part of the restore. -CLI names (the scene name in lowercase with dashes, as `director scene list` shows) or IDs are accepted; a quoted name such as "TV gaming" still works. Check validates saved references and executable paths only, without device mutation or live readiness claims. Apply does not start the GUI or require Director to remain resident. --yes skips display confirmation; --confirm requires it. Exit code is zero only on complete success. +## The active scene, End and Return -## Validation and remaining work +The scene you applied last stays active until you apply another or restart the PC, in the window and the CLI alike. Its card shows a dot before the name. -Model/runner tests cover stable reference resolution, direct TV audio, stage order, early failure gating, cancellation, both recovery policies, stale/corrupt storage and legacy TV compatibility. Native fixture tests cover creation/editing/deletion, action reordering, draft navigation and remembered links at wide/narrow sizes without real settings writes, audio/display mutations, TV commands or launches. Physical end-to-end HDMI arrival and restoration still need a hardware run. See [Audio](AUDIO.md) for the shared remembered-device inventory and relinking. Automatic TV-to-audio correlation, notifications, app-exit tracking and import/export are outside this slice. +- **Applying a different scene** first runs the active scene's **When leaving** steps, then turns its TV off if the scene says so. A leave step that fails is reported as a warning and never blocks the next scene. +- **End **, next to the **+** button, appears when the active scene has something to do on exit. It runs the leave steps and then applies the **Return** scene, if one is set. `director scene end` does the same. +- **Running the active scene again** also ends it and goes to its Return scene, when it has one. -## FPS stage +Before running any leave steps, Director checks that the Return scene still exists and is valid; if not, it keeps the current scene active and runs nothing. End doesn't restore any settings by itself; use a Return scene such as your Default for that. -A scene may optionally set a global NVIDIA/RTSS FPS limit. Order is TV → displays → sound → FPS → final launches. Unsupported providers fail preflight before device changes; default failure/cancel recovery includes the selected FPS configuration. FPS-only scenes are supported. Off means unchanged; Disable global limit is an explicit operation. See FPS.md. +## Shortcuts and the command line -## Before, After and When leaving — version 2 +The **>\_** button after a scene's name shows the commands for it, each with **Copy**: by CLI name (`director scene apply tv-gaming`, easy to read) and by ID (keeps working after a rename). Paste either into a Stream Deck action, a shortcut or a script. Setup adds `director` to PATH. -Scenes are stored as `version: 2`. Version 1 files still load; their per-scene `keep_on_failure` and `wait_seconds` are read and dropped, and are no longer written. Older Director builds refuse a version 2 file instead of rewriting it. +```text +director scene list +director scene check tv-gaming +director scene apply tv-gaming [--yes | --confirm] +director scene end +``` -Each scene has three action lists. **Before** runs first, after the settings snapshot and before any device change. **After** (the old final actions) runs once every device step has succeeded. **When leaving** runs when a different scene is applied, from the window or the CLI, or when the active scene is ended. Order is Before → TV → Displays → Sound → FPS → After. +- A scene's CLI name is its name in lowercase with dashes ("TV Gaming" is `tv-gaming`). Two scenes can't share one. +- `check` validates references and app paths without changing anything. +- `apply` runs without opening the window. `--yes` keeps verified display changes without asking; `--confirm` asks in the terminal. +- The exit code is 0 only when the whole scene succeeded. With **Notify when CLI scenes fail** on in Options, a failed run shows a Windows notification that opens its result in Director. -Actions are Run app, Open link (URI) and Close app. An app can **wait until it finishes**: it then fails the step on a non-zero exit code or when it runs longer than the device wait from Options, and the process is left running on timeout. New Before apps wait by default; After and leave apps don't. Close app asks every running copy of a program (by `name.exe` or full path) to close through its windows, waits up to 10 seconds, and ends it only when "End it if it doesn't close" is on. A program that isn't running counts as closed. Steam Big Picture is best closed with the link `steam://close/bigpicture`. +## How it works -The active scene is stored in `active-scene.json` with the time Windows started, so it survives closing Director and is shared with the CLI, but is forgotten after a restart. A successful apply records the scene; a failed apply clears it. Leave actions never block the next scene: each failure is reported as a warning and the remaining actions still run. End runs the leave actions and forgets the active scene; it doesn't restore any settings. `director scene list` marks the active scene and `director scene end` ends it. +Scenes are stored in `scenes.json` in `%LOCALAPPDATA%\Director`. A scene refers to display presets and TVs by ID, so editing a preset changes every scene that uses it; sound settings live in the scene itself. Deleting a preset or TV that a scene still uses is refused and names those scenes. The active scene is kept in `active-scene.json` together with the time Windows started. -## Sound step — version 3 - -Scenes are stored as `version: 3`. The Sound step (`sound`) replaces the audio preset reference (`audio`) and the linked TV audio fields (`tv_audio`, `tv_audio_volume`). It holds: - -- `output`: a device (`{"kind":"device","id","name"}`) or a TV's sound (`{"kind":"tv","id"}`, the output linked to that TV); absent leaves the default output as is. -- `volume` (0–100) and `mute` (true or false); absent leaves them as they are. With no output, they apply to whichever output is the default when the scene runs. -- `calls`: an optional separate Communications output. -- `mic`: an optional microphone with its own `volume` and `mute`; it takes all three input roles. - -Version 1 and 2 files still load. A scene that referred to an audio preset gets that preset's output, volume, calls device and microphone, read once from `audio-presets.json`; a scene that used a TV's linked audio gets `output: tv` with its volume. A preset that can't be found leaves an empty Sound step, which the scene card reports so the scene can be edited. The next save writes version 3 and Director no longer reads or writes `audio-presets.json` otherwise. - -The runner snapshots volume and mute for every endpoint the step changes (a device that appears late is snapshotted just before its writes) and restores them, with the default roles, on failure. A scene card shows the scene's main change at the top: its display layout, else a sound panel (output, volume bar or Muted, calls and mic), else its TV, FPS limit or actions. - -## Turning the TV off when leaving - -The Prepare TV step has **Turn off the TV when you leave this scene** (`off_when_leaving` on the scene's TV preparation). When it's on, a locked "Turn off C1" card sits under When leaving; its pencil opens Prepare TV and its bin turns the setting off. Removing the TV step clears it, and choosing another TV keeps it. Leaving runs the leave actions first and then turns the TV off through the same path as `director tv off`. A TV that doesn't answer is reported as a warning and never blocks the next scene. - -**End** appears next to the Scenes page's **+** only while the active scene has leave actions or turns its TV off; its tooltip lists what will run. The active card shows a green dot before its name (tooltip "Active", or where Return goes); every scene card reserves that slot, so names never shift. A scene with Return lists "Return: " last in its card summary. - -## Return - -Return is an optional final step. In its dialog, turn the switch on and choose another saved scene. End and running the active scene again check the destination before running any leave steps, then apply it once. Selecting a different scene always goes there after the usual leave steps. End is also available when Return is the only exit action. - -If the destination was removed or its settings fail validation, Director keeps the current scene active and runs nothing. Scene file version 4 stores the optional destination by ID, so renaming it works. Older scenes load with Return off. - -## Commands for shortcuts - -The **>\_** button next to a scene's or preset's name opens "Run … from a shortcut" with two commands, each with a Copy button: by CLI name (`director scene apply console`, readable, but copy it again after a rename) and by ID (keeps working after a rename). A scene with leave work also shows `director scene end`. Display presets accept their ID in `director display apply`, as scenes do. The by-name command uses the CLI name, unquoted (`director scene apply console`). Setup puts `director` on PATH, so the commands don't include a full path. - -## First scene - -An empty Scenes page offers to save the current setup as the everyday scene (named "Default" unless changed). It reads the layout with the display capture, the console default output (else any active one) with its volume, and the global FPS limit from the FPS survey: a provider with a limit wins, RTSS wins when both have one, and a zero value saves "no global limit". Each part can be unticked; a part that couldn't be read is disabled. Saving holds the operation lock, reuses a display preset with an identical layout, otherwise adds "Default screens" (made unique), and puts the output and volume in the scene's Sound step. The display preset is saved before the scene, so a scene never points at a preset that wasn't saved. No device changes. The logic is `director::starter`. - -## Global failure policy - -"Keep changes that finished if a later step fails" and the device wait (1–120 seconds, default 30) are Options settings in `preferences.json`, shared by scenes and waited apps. Live sound changes (Now and `director audio`) change one thing at a time and always put it back when Windows does not confirm it. - -## Step-flow editor - -The editor is one fixed-width column of step cards in run order, joined by down arrows, with When leaving set apart below. A card shows its title and a one-line summary, with edit and remove buttons; remove resets that step. Editing opens the step's controls in a Done/Cancel dialog, and Cancel restores the step as it was when the dialog opened. Empty steps are dashed outlines with a hint and an Add button that open the same dialog. App actions show Choose app and the chosen app's name; arguments, working folder and the editable path are under Advanced options. The former right-hand summary panel and the per-scene "Readiness and recovery" section were removed. This supersedes the editor layout described under "Native editor" above. +The window and the CLI share one runner and one cross-process lock, so two scenes never change devices at the same time. While Director waits for a TV, it resends wake at most five times and the input request at most every 1.5 seconds, within the device wait. diff --git a/docs/SOUND.md b/docs/SOUND.md new file mode 100644 index 0000000..b9f832c --- /dev/null +++ b/docs/SOUND.md @@ -0,0 +1,56 @@ +# Sound + +Director changes Windows sound in two ways: + +- **Live**, from the **Now** page or `director audio`: each change applies right away and nothing is saved. +- **In a scene**, from its **Sound** step: the settings are saved with the scene and applied with its other steps, and undone if a later step fails. + +## Now + +The Sound section shows your default output and microphone: + +- Pick an output or microphone to make it the Windows default for apps, media and calls. +- Move a volume slider; the level is sent once the slider rests, so a drag writes once. +- Use **Mute** / **Unmute**. +- Turn on **Different device for calls** and pick a calls output to send calls (Windows' communications role) somewhere else. Turning it off sends calls back to the main output. + +Each change is checked, and put back if Windows doesn't confirm it. **Save as scene…** opens a new scene with its Sound step holding the current output and microphone, with their volume and mute. + +## The scene Sound step + +| Setting | Choices | +| --- | --- | +| Output | Leave as is, a device Director has seen, or **TV's sound** (the output linked to a saved TV) | +| Volume | Leave as is, or 0–100% | +| Mute | Leave as is, Unmute or Mute | +| Calls | **Use a different device for calls**: a separate output for calls | +| Microphone | **Change microphone**: a device, with its own volume and mute | + +With the output left as is, volume and mute apply to whichever output is the default when the scene runs. + +Sound runs after the Displays step, because a TV's HDMI audio often only appears once its screen is on. The scene waits for the chosen devices, up to the device wait in Options, and never switches to a different device instead. If a later step fails, Director restores the default devices, volumes and mute it changed (unless Options keeps finished changes). + +## Offline devices and Relink + +Director remembers every output and microphone it has seen, so you can pick a device that's unplugged right now, such as a TV's HDMI audio. If a saved device can't be found any more, for example after a driver update gave it a new ID, the step shows **Relink device…**: choose the replacement, review the scenes and TV links that will change, and confirm. + +## Command line + +```text +director audio status [--json] +director audio list | outputs | inputs [--json] [--all] +director audio use [--role console|multimedia|communications] +director audio volume [] <0..100 | +N | -N> +director audio mute | unmute | mute toggle [] +director audio check +``` + +- Add `--mic` to target the microphone instead of the output. +- Leaving out the device means the current default, so `director audio volume +5` suits a Stream Deck button. +- A device is named by its CLI name (its Windows name in lowercase with dashes: "Speakers (Realtek(R) Audio)" is `speakers-realtek-r-audio`) or its endpoint ID. Use the ID when two devices share a name. +- `use` makes the device the default for all three Windows roles unless `--role` picks one. +- `list` hides devices Windows remembers but that aren't present, unless you add `--all`. `check` also tests the default-device interface Director uses. + +## How it works + +Director uses Windows Core Audio directly. A device is matched by its endpoint ID, then by its Windows Stable ID, never by its name alone. Remembered devices are kept in `audio-devices.json` in `%LOCALAPPDATA%\Director`. Linking a TV to an audio output only stores that link; it never wakes the TV or switches audio by itself. Director changes the Windows defaults and endpoint volume; apps that are set to a specific device keep using it. diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md new file mode 100644 index 0000000..ce847e9 --- /dev/null +++ b/docs/TROUBLESHOOTING.md @@ -0,0 +1,46 @@ +# Troubleshooting, logs and backups + +## When a scene fails + +**Options → View logs** shows the result of the latest scene run, from the window or the CLI, followed by recent log entries. Look for the step that failed and whether the restore of your previous settings succeeded. + +Turn on **Notify when CLI scenes fail** in Options to get a Windows notification when a scene started from a shortcut, script or Stream Deck fails. Choosing the notification opens that run's result in Director. + +Common causes: + +- **A device didn't appear in time.** A TV's HDMI audio, or a screen that's slow to wake, can take longer than the device wait. Raise **Device wait (seconds)** in Options (up to 120 seconds). +- **A display preset no longer matches your hardware.** A new cable, port or driver can change a screen's Windows device path. Edit the preset, or capture it again. +- **A saved audio device has a new ID.** Use **Relink device…** in the scene's Sound step. See [Sound](SOUND.md). +- **The TV didn't respond.** Check that it's on the same network, has the same IP address, and has network standby or mobile power-on enabled for Wake. See [TVs](TVS.md). + +## Logs + +**Options → Open logs folder** opens `%LOCALAPPDATA%\Director\Logs`. The app and the CLI both write there. + +- `director.log` is the current file; up to four older files (`director.1.log` to `director.4.log`) are kept, each about 1 MiB. +- Each line is a JSON record with the time (UTC), process ID, operation ID, step, outcome and details. Open them in a text editor, or parse them as JSON lines. +- Logs contain device names and IDs, TV input IDs and Windows error codes. They never contain pairing keys, tokens, certificates, MAC addresses or raw TV messages. +- Logging never holds up a device change: if the disk is busy or full, records can be dropped, and the next record says how many. + +A "request sent" record only means the command left Director; look for the acknowledgment and the final result separately. For TV controls, the original command error is kept apart from any later status check, so a timeout afterwards doesn't hide why the command failed. + +## Crash reports + +If Director closes unexpectedly, it saves a report in `Logs\Crashes` with the error, a backtrace, the Director and Windows versions and the last 40 log records. The next time it starts, it offers the report once: + +- **Report on GitHub** opens a new issue in your browser with the summary, version and backtrace filled in. Nothing is sent until you submit it. The log lines stay in the file; attach it if you're happy to share them. +- **Report a problem** in Options opens a new issue for anything else. + +Native crashes that bypass Rust's error handling appear only in Windows' Event Viewer, under Windows Logs → Application. + +## TV compatibility reports + +For Samsung and TCL TVs, **Export report…** in the TV editor (or `director tv report `) saves an allowlisted JSON report to `%LOCALAPPDATA%\Director\Reports`. It contains no keys, addresses or raw logs. See [Test a Samsung or TCL TV](TV_TESTING.md). + +## Backups + +**Options → Export backup** saves your scenes and display presets to one `.director-backup` file. **Restore backup** shows what it will replace before you confirm, and flags device links to review afterwards. + +TV pairing keys are encrypted for your Windows account on this PC, so they're never included: after restoring on another PC, pair each TV again. Scene app paths and links come back as they were saved; review them before applying a scene. + +To back up everything by hand, copy the `%LOCALAPPDATA%\Director` folder while Director is closed. TV pairings in that copy only work for the same Windows account on the same PC. diff --git a/docs/TVS.md b/docs/TVS.md index 2ffc70b..266a5cb 100644 --- a/docs/TVS.md +++ b/docs/TVS.md @@ -1,55 +1,57 @@ # TVs -## Add a TV - -Open **TVs → +**. The native guide walks through: - -1. **Brand** — LG webOS or Samsung Tizen. Existing saved TVs default to LG. -2. **Name** the TV. -3. **IP address** — enter its IPv4 address from its network settings; keep it on. -4. **Pair** — accept the TV’s connection prompt. LG reads available inputs and network addresses. Samsung reads model/firmware, reported power and network information when available. -5. **PC input / compatibility** — LG selects from reported inputs. Samsung offers an optional single-command HDMI test, followed by explicit user confirmation; unconfirmed/failed inputs remain hidden. See [Samsung testing](SAMSUNG.md). -6. **Set up wake** — review learned addresses; enable the advanced manual MAC field if needed, or skip. -7. **Windows connections** — optionally link its display and audio output. -8. **Review and save**. +Director controls TVs over your home network: it pairs once, then can wake the TV, switch it to your PC's input and turn it off, from the window, a scene or the command line. Supported platforms: -The guide saves after the final step. Choosing an input records its identity for future scenes. Saving does not switch inputs, wake the TV, or apply a Windows layout. The explicit Samsung compatibility test does send one direct input command; choosing a port alone does not. Back preserves completed choices; changing the IP/connection method during setup clears the draft’s pairing and learned information. Cancel writes no TV definition. Permission already granted on the TV remains until revoked in the TV’s settings. A successful pairing remains in the draft if reading inputs fails, so **Retry** can read the details again without repeating pairing. +| Platform | Status | Control | +| --- | --- | --- | +| LG webOS | Supported | Pairing, wake, power status, turn off, input list and switching with readback, live power updates, TV input protection | +| Samsung Tizen | Hardware preview | Pairing, wake, power status, turn off, HDMI inputs you've tested and confirmed | +| TCL Android / Google TV | Hardware preview | Code pairing, wake and sleep, power status, HDMI inputs you've tested and confirmed | -An unavailable network-info request is a warning, not a setup failure. Missing input information can be retried; a successfully read empty input list can proceed with an explicit **No PC input** choice. Invalid names, IPs, MACs, duplicate definitions, and incomplete steps cannot be saved. +Other TCL platforms (Roku, Fire TV) and cloud services such as SmartThings aren't supported. Have a Samsung or TCL TV? [Testing it](TV_TESTING.md) and sending a report helps. -## Existing TVs - -The pencil opens the compact editor. For a paired TV, available inputs and wake addresses load automatically in the background; **Save TV** remembers the pending details. If the TV cannot be reached, saved choices remain editable. Select or correct the PC input, add a manual MAC, or change the Windows display link independently. Name/connection-metadata edits retain pairing. An IP or connection-method change shows **Continue setup** and returns to guided pairing; the original definition stays saved until the guide finishes. +## Add a TV -The TV row contains just a **remote-control SVG**, **pencil**, and **red bin**. The remote opens live TV controls; the pencil edits connection metadata; the bin asks to remove the definition. Standalone Pair again, Check connection, and Read TV details buttons are removed. Pairing and initial information reads belong to setup; metadata refresh on edit is automatic. Removing a TV deletes Director’s local definition/credential; revoke permission on the TV separately if needed. Saved pairing is not a live-status indicator. Advanced headless pair/check/learn commands remain available. +Open **TVs → +**. The guide walks through: -## Wake-on-LAN +1. **Brand.** +2. **Name** the TV. +3. **IP address**: the TV's IPv4 address from its network settings. Keep the TV on. +4. **Pair**: accept the prompt on the TV (or, for Android TV, type the code it shows). Director then reads what the TV reports: inputs, network addresses, model. +5. **PC input**: choose the input your PC is connected to. LG lists its inputs. Samsung and TCL offer a test that sends one direct HDMI command; you confirm on screen whether it switched, and only confirmed inputs become available. +6. **Wake**: review the network (MAC) addresses Director learned. If none could be read, turn on **Enter MAC address manually**, or skip. +7. **Windows connections** (optional): link the TV's Windows display and its HDMI audio output, so scenes can wait for them. +8. **Review and save.** -Director reads `wiredInfo.macAddress` and `wifiInfo.macAddress` from the authenticated TV’s local connection-manager service. It validates individual, nonzero 48-bit addresses and stores Ethernet, Wi-Fi, and an optional manual address separately. Colon, hyphen, and compact manual forms normalize to uppercase colon-separated addresses. Invalid, zero, broadcast, and multicast addresses are rejected. A failed or partial read does not erase previously learned addresses. No ARP/gateway inference is used. +Nothing is saved until the last step, and saving never switches inputs, wakes the TV or changes Windows. Back keeps your choices; changing the IP address clears the pairing so you pair again. If reading details fails after pairing, **Retry** reads them again without re-pairing. Permission granted on the TV stays there until you revoke it in the TV's settings, even if you cancel. -Wake sends standard 102-byte magic packets directly through Rust UDP: IPv4 local broadcast `255.255.255.255:9`, three rounds 100 ms apart, one packet per distinct saved MAC per round. A two-second socket write timeout bounds individual writes. It works without an open control connection or pairing key, including while the TV is off. **Wake request sent** means UDP dispatch succeeded; it does not prove the TV/panel has awakened. No follow-up polling, automatic input switch, display change, or audio change runs. +## Edit or remove a TV -The TV must remain network-connected and support/enable the relevant network/mobile power-on feature. Wake behavior over Wi-Fi and deep standby is model/firmware-dependent. This first sender uses the system’s broadcast routing; multiple interfaces, routed subnets, and explicit interface/directed-broadcast selection need future work. It does not discover a changed IP. +The pencil opens a compact editor. For a paired TV, inputs and wake addresses refresh in the background; if the TV can't be reached, saved choices stay editable. Changing the IP address or connection method sends you back through pairing, and the old definition stays saved until you finish. -MACs are device metadata and wake destinations, not cryptographic identity or replacements for the current connection IP. Verified rediscovery/address migration remains unimplemented. A Windows display path, TV pairing key, and TV network addresses are distinct identities. +The bin removes Director's copy of the TV and its pairing key. To revoke Director's access completely, also remove it from the TV's device-connection settings. -## Optional Windows display link and scene boundary +## TV controls -A TV is independent of display presets and scenes. Its optional Windows link stores the physical target device path and last-known name. An unreported link remains selectable as unavailable. Director does not guess from friendly names, display numbers, IPs, or transient adapter/target numbers. A Windows path change requires manual relinking; multiple PC connections may eventually need multiple associations. +The remote-control icon on a TV card opens its controls. They appear immediately and check the TV in the background: -The PC input is also a connection mapping. Which TV actions to perform—wake, select the PC input, power off, timing/readiness—belongs to the scene, not pairing/setup preferences. Scene composition is still unimplemented; manual input switching and power-off are available in TV controls. TV readiness alone must not imply Windows display/HDMI-audio readiness. +- **One power button.** It reads **Turn off** when the TV reports On, Screen off or Screen saver, and **Wake** when it reports Off or Standby or can't be reached (Wake needs a saved MAC address). Director rechecks the state before turning off, so a stale click never does the opposite. +- **Waking…** sends Wake-on-LAN and watches for the TV to report it's awake, resending a few times within 30 seconds. If it doesn't wake, you get **Retry wake**. +- **Turning off…** becomes **Off · assumed** once the TV accepts the command; Director doesn't ping a TV it just turned off. +- **Input**: pick an input and choose **Switch input**. LG reads the input back to confirm it; Samsung and TCL report the command as sent. +- An LG TV pushes power changes while the controls are open, so the dialog updates when someone uses the remote. -## Connection and credential protection +A TV that can't be reached is shown as unknown, never as Off. Controls a TV doesn't support are hidden rather than greyed out. Technical details stay collapsed unless something fails. -Encrypted WebSocket on port 3001 remains the default. Director permits the local LG TLS handshake, then compares exact remembered certificate bytes **before sending a saved key**. Initial certificate trust accompanies explicit pairing and on-TV approval. Changed certificates require explicit re-pairing. LG may share certificates across TVs; continuity checking does not uniquely identify hardware. +## TVs in scenes -**Use legacy connection** explicitly selects unencrypted WebSocket port 3000 for older TVs. The guide/editor explains the consequence; there is no silent downgrade. Pairing key and certificate pin are protected together with Windows per-user DPAPI under Director’s Local AppData known folder. They are not included in presets, CLI listings, application errors, or logs. Copying credentials to another Windows account/machine is not supported. +A scene's **Prepare TV** step can wake the TV and switch it to the saved PC input before the display step, and optionally turn it off when you leave the scene. If the TV is linked to a Windows display and HDMI audio output, the scene waits for them after changing displays. See [Scenes](SCENES.md). -TV definitions remain a versioned `tvs.json`. New input/PC/network fields default empty when reading existing definitions, preserving existing protected pairing bytes. Storage uses the operation lock, atomic writes, and stale-window detection; corrupt or future-version files are preserved. Device/storage/network work runs off the UI thread. Initial native connection phases use 2.5-second timeouts; WebSocket pairing has a 45-second deadline and inspection/checking an 8-second deadline, with bounded cancellation. Pairing and the subsequent inspection are separate connections. Wake uses the same cross-process operation lock. +**TV input protection.** Streaming boxes and consoles on HDMI-CEC often grab the TV's input while it wakes. For TVs that report their current input (LG), Director keeps switching back to the scene's input for the first seconds after it reports it (Options, default 10 seconds, 0 turns it off) while the rest of the scene carries on. Any other TV command from the app or the CLI, a new scene or a restore stops the guard first. -No Python, Node, ColorControl, downloaded TV helper, persistent service, or tray process is required. +**Display detection.** A linked, paired TV with a saved PC input offers **Wake and detect** in its monitor card, so Director can wake it, select the input and read its display modes. See [Display setup](DISPLAYS.md#screens-that-are-off-or-not-detected-yet). -## CLI +## Command line ```text director tv list @@ -61,105 +63,29 @@ director tv status living-room-tv director tv off living-room-tv director tv toggle living-room-tv director tv input living-room-tv HDMI_1 +director tv report living-room-tv ``` -Each TV is named by its CLI name (its name in lowercase with dashes, as `director tv list` shows) or its ID. Pair stores protected pairing and attempts metadata learning. Check authenticates and reads inputs without changing the TV or saving metadata. Learn refreshes and saves input/wake information without changing the selected PC mapping or TV state. Wake dispatches packets only; exit zero does not establish physical wake. Toggle reads the power state first: it turns the TV off when it reports on, wakes it when it reports off or standby or can't be reached (a fully-off TV often drops off the network), and sends nothing when the TV answers with an unknown state. Add/edit/remove and PC/display mapping are configured in the window. - -## Validation and remaining work - -The user reported successful LG pairing/input enumeration on 2026-11-01 with the earlier slice; connection mode was unspecified. That feedback does not establish MAC-reading or wake behavior. - -Current automated checks cover guide progression/gating, optional/manual MAC validation, packet bytes and three actual UDP sends to a loopback receiver, TV-reported Ethernet/Wi-Fi parsing and denial, preservation of old paired definitions, credential protection, storage failures, and mock native WebSocket registration/timeouts. Native owned-window tests cover real release guide name/IP/pair screens, Back/navigation/cancel, PC/MAC/display metadata save/reopen/remove, and the remaining guide screens through a test-only in-memory fixture. Settings and live displays are preserved; no real TV is contacted or woken by these tests. - -The user reports the revised guide/MAC/wake flow works. A subsequent read-only hardware check independently verified Active state and Ethernet/Wi-Fi MAC reads. Standby/off transitions and power-off have not been exercised. Discovery/verified IP migration, scene readiness/orchestration, configurable wake timing, and per-interface broadcast selection remain later work. - -Protocol research: [lgtvcli](https://github.com/01dnot/lgtvcli), [PyWebOSTV](https://github.com/supersaiyanmode/PyWebOSTV), and [lgtv2](https://github.com/hobbyquaker/lgtv2) (TV-reported wired/Wi-Fi fields and local wake protocol). These are references, not dependencies; no signed application manifest was imported. - - - -### Manual MAC opt-in and hardware status check — 2026-11-01 - -Manual entry now sits behind **Enter MAC address manually** in both setup and editing. New setup defaults off and hides the field. An existing saved manual address reopens with the switch on. Toggling off retains draft text during editing, ignores its validation, and clears the manual address only when saving/advancing; learned Ethernet/Wi-Fi addresses remain intact. Toggling back on restores the draft. - -The user reports the TV setup/wake work is functioning. With the TV explicitly turned on by the user, a separate read-only authenticated check independently returned power state **Active** and valid TV-reported MAC addresses for both Ethernet and Wi-Fi. No power, input, or settings change was sent. At that earlier slice, the list power icon meant Wake only. The control-modal update below supersedes that UI. A proposed small control modal would use fresh reported state and explicit Wake/Turn off/input actions. Unreachable/unknown must not be interpreted as off. Standby/off transitions and Turn off have not been exercised by this check. - - - -## Basic TV controls — current - -Choose the **remote-control** SVG beside a TV. The native modal reads fresh power status, external inputs, and the current foreground input when the TV reports enough information. Use the refresh icon to reread; no background process or continuous polling is added. - -There is one power button: -- **On**, **Screen off**, or **Screen saver** → **Turn off**. -- **Off** or **Standby** → **Wake**. -- **Unknown/unreachable** → **Wake**, enabled only with a saved MAC. - -A failed connection is never proof of Off. Before turning off, Director checks fresh state; a stale Turn off click on a TV reporting standby/off cannot wake it. Wake dispatches idempotent Wake-on-LAN packets immediately, without waiting for an unreachable TV to answer, and never turns an already-awake TV off. Unrecognized/unreachable fresh state blocks a turn-off request. Wake can still dispatch to saved MACs without an authenticated connection. - -Selecting an input changes only the pending choice. **Switch input** validates the target against a freshly read input list, sends the explicit input ID, and attempts bounded foreground-app readback. An unchanged input is a no-op. Readback confirms the TV-selected input/app, not HDMI signal or Windows/audio readiness. If acknowledgment succeeds but readback is unavailable/late, the result says accepted without claiming verification. - -Control mutations run on workers under the shared operation lock and reject stale TV definitions. Status reads run independently without that mutation lock. Wake readiness and uncertain results use separate status checks; confirmed input changes and acknowledged off update directly. Closing the modal does not cancel a command already in flight; the window’s existing close protection remains active until work finishes. Errors/uncertain acknowledgments remain visible. Refresh again after wake/input settling when needed. A successful turn-off acknowledgment is not independent proof that the physical panel powered off. - -The modal never edits pairing, PC-input mappings, display presets, or saved scene choices. Status/input reads do not save TV metadata. CLI and future scenes use explicit wake/off/input intents, not an alternating toggle. CLI status reads fresh state; off rechecks it; input takes the exact input ID listed by status/check. Wake remains explicit packet dispatch. - -Validation: 64 regular tests pass, including explicit power intent/state races, Unknown handling, input freshness/no-op/readback, strict acknowledgments, and native WinHTTP requests against a loopback mock. Native default/minimum-size modal checks confirm one power button, pending input selection, unknown-state behavior, Close, and guide/editor regression behavior. A read-only check on the user’s LG returned On/current PC and four external inputs; the live modal showed the same values and refreshed correctly. Original settings files and live Windows layout stayed unchanged. Physical turn-off/input-switch commands were tested only against the mock, not sent to the user’s TV. - - - - -## Responsive controls and unavailable TVs - -Opening the modal immediately shows Checking while a worker contacts the TV. These are authenticated TV requests, not ICMP pings. Read-only checks do not set global busy or hold the mutation lock, so Close and Wake remain usable. An ordinary refresh disables another refresh and input selection until its response arrives; power transitions additionally disable repeated commands until completion or expiry. Turn-off and input changes retain mutation exclusion and fresh validation. Wake dispatch does not require an authenticated connection, and action completion does not wait for a follow-up status read. Wake uses the bounded readiness monitor described below; manual refresh remains available after completion or expiry. There is no permanent monitor. - -Each dialog has a lifetime token and read revision. Starting an action invalidates an older read; closing/reopening or refreshing ignores superseded responses. Read completion never releases a mutation guard. Network timeouts remain bounded by the transport; they no longer gate opening or closing controls. - -A compact fixed-width body replaces the outer scrolling panel. Unknown status never means Off. Hide empty input controls until available. Short local messages replace duplicated page/modal errors and misleading status-updated banners. Technical diagnostics are collapsed by default, with a bounded scroll area inside that disclosure only. No user settings or TV state are changed by status reads. - - -## Power transitions and selective refresh — current - -Wake immediately shows **Waking…**, dispatches Wake-on-LAN once, and polls authenticated power status until the TV reports an awake state. Failed/unavailable checks remain part of waking rather than flashing Unknown. Polls are spaced two seconds after each completed attempt, within a 30-second retry window starting after dispatch. A request already in flight can finish after that window, subject to existing native transport timeouts. Inputs are queried only once the TV reports awake. A responding TV still in standby is not treated as awake. - -On expiry, show **Not responding yet** (or **Not awake yet** when the TV has reported a non-awake state), with **Retry wake**. A retry starts a new wake request/window. Close stays available; closing/reopening invalidates reads and queued polls through the dialog token/revision. No permanent polling continues after success, expiry or closing. - -Turn off shows **Turning off…** while the command runs. A positive acknowledgment changes the modal to **Off · assumed**, with Wake available; Director does not immediately query an intentionally unreachable TV. This describes accepted intent rather than independently verified physical state. A fresh response saying already Off/Standby is shown as reported, without the assumed qualifier. An unacknowledged/failed command is never marked assumed Off. - -Confirmed input changes update the current input in place and preserve the rest of the modal. No additional full status refresh follows a confirmed change or confirmed no-op. Failed/uncertain commands and accepted-but-unconfirmed input readback get one reconciliation read, retaining the original command details separately. Manual refresh remains available outside pending transitions. - -The core engine returns typed effects (WakeSent, OffAccepted, AlreadyOff, InputConfirmed, InputAccepted), so the GUI never infers results from message text. CLI commands remain explicit and headless; GUI wake waiting does not change CLI wake's dispatch-only contract. - - - -## Optional reminder in display presets - -When creating a new display preset without a saved TV, Director offers a quiet Setting up a TV? card. Adding a TV is optional; ordinary displays and manually controlled TVs remain supported. Add TV opens the existing guide and keeps the display draft intact. Close hides the tip for the session; Don't show again remembers the choice. Restore it under Options → Show TV setup tips. Already-saved TVs suppress the generic reminder, and linked monitor cards show their TV name with View TV. This guidance does not enable a display, wake a TV, change its input or learn monitor capabilities. - - -## TV preparation during display detection - -A linked TV with protected pairing, wake addresses and a saved PC input offers Wake and detect inside its monitor's setup card. This is an explicit runtime preparation action, not a stored scene preference. Director snapshots Windows first, wakes the TV, waits for an awake report, selects the saved input, then learns display options through Windows. The display layout is restored afterward; the TV stays on with that input. TV metadata is not changed. Manual Detect options remains available without adding/pairing a TV. - - -## Live power updates while controls are open - -Opening a TV's controls starts a read-only, authenticated SSAP power subscription on a worker. It reuses the existing account-protected pairing and certificate pin; it never silently pairs. Command requests retain their existing explicit intents and shared mutation lock. Power updates change the current modal in place. An external power-on triggers one input/status reconciliation; ordinary input changes do not continuously reload the view. - -A lost connection is unknown, not proof of shutdown. An acknowledged Director turn-off retains Off · assumed until a fresh reported state is available. Original command errors remain separate from subscription/connection errors. Late events are rejected across dialog/action boundaries. Reconnect attempts back off from two seconds to a maximum fifteen seconds while controls remain open; reconnecting never sends Wake-on-LAN. +TVs are named by CLI name (the name in lowercase with dashes) or ID. -An explicit GUI Wake allows up to five wake dispatches total (the initial dispatch and four retransmissions, at least two seconds apart) within the existing thirty-second readiness deadline. Each dispatch may send packets for multiple saved MAC addresses. Stop retries when the TV reports awake, the controls close, or the deadline expires. No sleeping worker holds the mutation lock. Closing the modal signals cancellation; an idle WebSocket receive is interrupted and its handles are released on the worker. An already-started HTTP handshake remains bounded by transport timeouts. +- `check` authenticates and reads inputs without changing anything; `learn` refreshes and saves inputs and wake addresses. +- `wake` only sends the packets: success means they were sent, not that the TV woke. +- `toggle` reads the power state first: it turns the TV off when it reports on, and wakes it when it reports off or standby or can't be reached. +- `input` takes an input ID exactly as `status` or `check` lists it. +- `report` exports a compatibility report for Samsung and TCL; see [Test a Samsung or TCL TV](TV_TESTING.md). -CLI Wake remains dispatch-only and does not create a listener or require Director to stay running. No tray/startup service was introduced. Screen off/on controls are not planned unless explicitly requested; existing reported Screen Off status can still be displayed. +## How it works -Validation: 84 regular tests, a local mock WebSocket for pushed states and cancellation, native in-memory remote-power/disconnect/recovery/close tests, and the existing native wake/off/input/timeout fixture. Physical-TV validation is recorded separately when performed. +**Wake-on-LAN.** Director stores the Ethernet and Wi-Fi MAC addresses the TV reports, plus an optional manual one; invalid, zero, broadcast and multicast addresses are rejected, and a failed read never erases known addresses. Wake sends standard magic packets to the local broadcast address (`255.255.255.255:9`), three rounds 100 ms apart, one per saved address. It needs no pairing or open connection. The TV must stay on the network and have its network or mobile power-on setting enabled; Wi-Fi and deep-standby behaviour depends on the model. Multiple network interfaces, routed subnets and finding a TV whose IP address changed aren't handled. -## Remembered HDMI audio link +**LG connection.** Director uses the encrypted WebSocket on port 3001 by default and pins the TV's certificate at pairing: the exact certificate is compared before a saved key is sent, and a changed certificate requires pairing again. **Use legacy connection** selects the unencrypted port 3000 for older TVs, only when you choose it. -TV setup’s optional Windows connection step and Edit TV now include a TV audio output dropdown. First-time choices are active Windows outputs; existing saved TV links remain selectable when unavailable. Selection records endpoint ID and last name, not a name-based guess, and never changes audio or pairing. Scenes can explicitly select the link and wait for that endpoint after displays apply. Automatic TV/display/audio correlation is not implemented. See [Scenes](SCENES.md). +**Samsung.** Director uses the TV's local remote-control WebSocket on the encrypted port 8002; **Use legacy connection** selects the unencrypted port 8001 only when you choose it. The TV's certificate is pinned at pairing and checked before the authorization token is sent. Power status comes from the TV's local information endpoint, and only a reported On, Standby or Off counts; a timeout stays unknown. **Turn off** needs a fresh On report and sends one power key, never a blind toggle. HDMI inputs use one direct `KEY_HDMI` command each, never menu navigation or key sequences, and each port is offered only after you've tested it and confirmed that the TV switched. A new model or firmware reading clears earlier confirmations. Samsung doesn't acknowledge individual keys, so commands are reported as sent. While the controls are open, Director checks the power state every four seconds. -## Provider capabilities +**Android TV.** Director implements Google's Android TV Remote v2 protocol in Rust, the same service the Google TV phone remote uses: pairing on port 6467 and control on port 6466, both over mutually authenticated TLS with no unencrypted fallback. Pairing creates an RSA client certificate for that TV; the code shown on screen is checked against both certificates, and later connections require the same TV certificate (a changed one needs pairing again). The TV reports On or Standby; a connection alone doesn't count as On. **Wake** sends the protocol's wake command, falling back to Wake-on-LAN with a saved MAC address when the TV can't be reached; **Turn off** sends its sleep command. This protocol can't list inputs or read the current one, so HDMI inputs work like Samsung's: one direct key each, offered only after a confirmed test. Android TV reports a Remote Service version rather than the TV's firmware version. -LG uses its existing direct webOS provider. Samsung uses its separate native Tizen provider, with DPAPI-protected authorization, direct Wake-on-LAN, reported power and guarded KEY_POWER turn-off. Samsung controls have no per-key acknowledgment. Unsupported features are omitted from the modal and scene editor. A manually confirmed HDMI command is exposed for that entry/model/firmware; it is reported as sent, not read back. Local status polling runs only while its modal is open. SmartThings, discovery and custom sequences are not implemented. See SAMSUNG.md. +**Credentials.** Pairing keys, tokens, certificate pins and client keys are encrypted with Windows DPAPI for the current user under `%LOCALAPPDATA%\Director`. They never appear in CLI output, errors, logs, backups or reports, and can't be moved to another PC or Windows account. -## TCL Android / Google TV +**Identity.** A TV's Windows display link stores the monitor device path and last name, never a guess from names or display numbers. Its audio link stores the endpoint ID. If Windows changes the path or ID, relink it in the editor. -Choose the TCL Android / Google TV platform, request a code and confirm it in Director. The remaining input-test, optional wake/display/audio links and save steps use the existing guide. Direct input controls require an explicit successful test. See [TCL setup and friend test guide](ANDROID_TV.md); other TCL platforms are not included. +**Storage.** TV definitions live in versioned `tvs.json`, written atomically under the shared operation lock like other settings. Connections use bounded timeouts (2.5 s per connection phase, 45 s for pairing, 8 s for checks), and all TV I/O runs off the UI thread. No helper program, service or tray process is involved. diff --git a/docs/TV_TESTING.md b/docs/TV_TESTING.md new file mode 100644 index 0000000..8ffa833 --- /dev/null +++ b/docs/TV_TESTING.md @@ -0,0 +1,24 @@ +# Test a Samsung or TCL TV + +Samsung Tizen and TCL Android / Google TV support is a preview: it works on the protocol level, but every model behaves a little differently. If you have one of these TVs, a test report tells us what works on yours. It takes about ten minutes. + +You need Director, your TV remote, and a device connected to one of the TV's HDMI ports. Keep the TV and the PC on the same home network. + +1. **Add the TV.** Turn it on. In Director, open **TVs → +** and choose **Samsung Tizen** or **TCL — Android / Google TV**. Give it any name and enter its IP address, from the TV's network settings. +2. **Pair.** Choose **Pair TV**. + - Samsung: accept Director's connection request on the TV. + - TCL: type the six-character code the TV shows, then choose **Confirm code**. If it fails, use **Back** and pair again for a new code. +3. **Test HDMI switching.** Choose an HDMI port with something connected. With the remote, switch the TV to a different input or its home screen. In Director, tick **The TV is on a different input** and choose **Test HDMI**. Answer **Yes** only if the TV actually switched to that port. Repeat for other ports if you like, or skip this step if nothing is connected. +4. **Test power.** Continue through setup, leave the optional Windows display and audio links empty, and save the TV. Choose the **remote icon** on the TV's card: check that the power status is right, try **Turn off**, then **Wake**. Give it up to 45 seconds to come on. + - Samsung: Wake needs the TV's network standby setting. + - TCL: if Wake fails, turn on **Screenless service** or **network standby** under the TV's **Settings → System → Power and energy**, if it has one, and try again. +5. **Fill in the results.** Close the controls and choose the TV's **pencil**. Under **Test report**, enter the TV model and software version from the TV's **Settings → About** (or **Support**), choose Wi-Fi or Ethernet, and answer the three Yes / No / Not tested questions with what you actually saw. +6. **Send the report.** Choose **Export report…**. A folder opens. Attach the newest `samsung-compatibility-….json` or `android-tv-compatibility-….json` file to a [new GitHub issue](https://github.com/Xarishark/Director/issues/new) with your TV model in the title. + +**If pairing fails**, stay on that step, fill in the model and network details under **Test report**, and choose **Export report…** there. A report from a failed pairing helps just as much. If Director itself won't open, say so in the issue instead. + +## What the report contains + +The report holds your answers, the HDMI test results, what the TV reported (model, software version, power state), the Director version, the Windows version and build, a fingerprint of `director.exe`, and a cleaned-up history of the TV actions you tried with this build: what was tried, the outcome, timing and a coarse failure reason. + +It never contains pairing codes, keys, tokens, certificates, IP or MAC addresses, TV or device names, raw TV messages or log lines. Director builds it from an allowlist instead of filtering a log, and never sends it anywhere by itself. You can also export it with `director tv report `. diff --git a/docs/WINDOWS_GUI.md b/docs/WINDOWS_GUI.md deleted file mode 100644 index 8514d8b..0000000 --- a/docs/WINDOWS_GUI.md +++ /dev/null @@ -1,48 +0,0 @@ -# Native Windows interface and runtime - -Status: WinUI 3 is the selected, sole Director frontend as of 2026-10-31. - -## Application layout - -The root Cargo package produces target/release/director.exe. Its WinUI 3 controls are provided through pinned Microsoft windows-reactor 0.100.0. The library modules implement the shared audio engine, Windows adapter, preset persistence, and CLI. There is one frontend, build script, package lockfile, and executable name. CLI arguments are handled before GUI startup. - -The GUI uses native NavigationView, ListView, Button, TextBox, ComboBox, NumberBox, ToggleSwitch, Expander, InfoBar, and ContentDialog controls. Rust background jobs return plain-data messages; Windows/COM objects stay in their creating context. A native close guard protects pending work from normal window closure. - -## Deployment - -The GUI is framework-dependent. windows-reactor 0.100.0 requires the x64 Microsoft.WindowsAppRuntime.2 framework package, version 2.4 or newer. If it is missing, it shows a download prompt at startup. The CLI does not need the runtime. Setup installs the pinned 2.6.5 runtime when needed (see below). This is not a portable self-contained distribution. Licensing notices and validation on a clean PC are still required. - -## Supported Windows - -Director supports **Windows 11, version 24H2 (build 26100) or newer**, x64. HDR switching uses the display-configuration requests for advanced colour info and HDR state that Windows added in 24H2, and only current Windows 11 is tested. Most other features (layouts, audio, FPS, TVs, apps) use long-standing APIs, but older Windows isn't supported or tested. setup.exe (Burn `WindowsBuildNumber`) and the MSI (a launch condition on the registry `CurrentBuildNumber`) both refuse older builds with a message pointing to Windows Update. The executable embeds `build/director.manifest`, which declares Windows 10/11 support (so version APIs report the real build), `maxversiontested` 10.0.26100.0 and per-monitor v2 DPI awareness (WinUI sets the same at startup; the manifest makes CLI runs match). Raise `maxversiontested` when testing on a newer Windows release. - -Keep director.ico beside director.exe for the title-bar icon; the executable also embeds the same artwork. The requested local Director desktop shortcut points to this main executable. Build instructions are in [development](DEVELOPMENT.md). - -Reactor is a preview API. Published 0.100.0 differs from current upstream examples; keep the version and Cargo.lock pinned and consult the matching source before changing APIs. The backend uses Windows bindings 0.62 while Reactor supplies its own WinRT types. Never exchange those framework objects across the boundary. - -## Initial observations - -The native release comparison, before promotion into the main package, used about 106 MiB working set and 143.5 MiB private committed memory after settling, with a 3.31 MiB executable excluding the shared runtime. Idle CPU time was zero in a two-second sample. These warm local observations are not benchmarks, installed-size totals, startup guarantees, or budgets for later versions. Detailed machine-specific results remain under ignored .localonly. - -The user preferred the native interactions and authorized removing the alternate frontend. Keep optimizing measured costs while preserving native behavior. - -## Upstream references - -- [Microsoft Reactor](https://github.com/microsoft/windows-rs/blob/master/crates/libs/reactor/readme.md) -- [Runtime staging and deployment](https://github.com/microsoft/windows-rs/blob/master/crates/libs/reactor-setup/readme.md) -## Setup and MSI - -Build with WiX 6.0.2 using `./scripts/package-msi.ps1` from the repository root. Pass `-Wix` with the path to the WiX CLI if it is outside PATH. Pass `-UseExistingRelease` to package an existing release build. The script adds the pinned WiX Util and bootstrapper extensions to the global WiX cache if they are missing. It writes two files to `target/installer`: - -- `Director--x64-setup.exe` is the file users run. It is a WiX Burn bundle built from [DirectorSetup.wxs](../installer/DirectorSetup.wxs), using the standard WiX bootstrapper UI with a [Director theme](../installer/theme). It has a welcome page with a desktop shortcut checkbox, a progress bar, and a finish page with **Launch**. Releases publish only this file. -- `Director--x64.msi` is the application package from [Director.wxs](../installer/Director.wxs). setup.exe embeds and installs it. It has no dialogs of its own, and CI and releases do not publish it separately. Build it locally for managed deployment on PCs that already have the runtime. - -Director installs for everyone in `%ProgramFiles%\Director` and asks for administrator approval once. Setup adds Start menu and optional desktop shortcuts, registers the `director-run` link handler, and appends the install folder to the system PATH. Open a new terminal to use `director` from any folder. Director appears once in **Installed apps**. Uninstalling removes the files, shortcuts and PATH entry. Presets, TV pairing data and logs stay in `%LOCALAPPDATA%\Director`. - -setup.exe checks the current user's registration for the pinned runtime, `Microsoft.WindowsAppRuntime.2_2.6.5.0_x64__8wekyb3d8bbwe`. If the runtime is missing, setup downloads Microsoft's signed `windowsappruntimeinstall-x64.exe` 2.6.5 (about 125 MB) from the version-pinned aka.ms link and checks its SHA-512 hash. It then runs the installer elevated with `--quiet`, which provisions the runtime for all users, and removes the download afterwards. The runtime stays installed when Director is uninstalled. To move to a newer runtime, update the version, URL, hash and size in DirectorSetup.wxs (`wix burn remotepayload` generates them) along with `$runtimeVersion` and `$runtimePackage` in the packaging script. Offline installation needs the runtime installed beforehand. - -Director 0.9.1 and earlier offered a per-user install. Windows Installer cannot upgrade that copy from a machine-wide install, so setup stops with a message asking you to uninstall it first. Your presets are not affected. - -For a quiet install, run `Director--x64-setup.exe /quiet` from an elevated shell. Add `DesktopShortcut=0` to skip the desktop shortcut. - -setup.exe and the MSI are unsigned, so SmartScreen may warn before running setup. Bundle build and manifest checks passed. Clean-PC installation including the runtime download, standard-account launch, upgrade and uninstall tests remain open. diff --git a/docs/images/displays.png b/docs/images/displays.png new file mode 100644 index 0000000..05b504b Binary files /dev/null and b/docs/images/displays.png differ diff --git a/docs/images/scenes.png b/docs/images/scenes.png new file mode 100644 index 0000000..5d8029f Binary files /dev/null and b/docs/images/scenes.png differ diff --git a/installer/Director.wxs b/installer/Director.wxs index dcf5578..7717a87 100644 --- a/installer/Director.wxs +++ b/installer/Director.wxs @@ -44,6 +44,8 @@ + + @@ -71,6 +73,8 @@ + + diff --git a/packaging/about.hbs b/packaging/about.hbs new file mode 100644 index 0000000..7da6fe9 --- /dev/null +++ b/packaging/about.hbs @@ -0,0 +1,25 @@ +# Third-party licenses + +Director includes the following open-source components. Each is listed with its license text. +Generated by [cargo-about](https://github.com/EmbarkStudios/cargo-about); do not edit by hand. + +## Overview + +{{#each overview}} +- {{{name}}} ({{count}}) +{{/each}} + +{{#each licenses}} +## {{{name}}} + +Used by: + +{{#each used_by}} +- [{{crate.name}} {{crate.version}}]({{#if crate.repository}}{{crate.repository}}{{else}}https://crates.io/crates/{{crate.name}}{{/if}}) +{{/each}} + +```text +{{{text}}} +``` + +{{/each}} diff --git a/packaging/about.toml b/packaging/about.toml new file mode 100644 index 0000000..bc9bcab --- /dev/null +++ b/packaging/about.toml @@ -0,0 +1,18 @@ +# cargo-about configuration for THIRD_PARTY_LICENSES.md. See docs/DEVELOPMENT.md. +accepted = [ + "MIT", + "Apache-2.0", + "Apache-2.0 WITH LLVM-exception", + "BSD-2-Clause", + "BSD-3-Clause", + "ISC", + "Zlib", + "Unicode-3.0", + "Unicode-DFS-2016", + "CDLA-Permissive-2.0", + "MPL-2.0", + "OpenSSL", +] +targets = ["x86_64-pc-windows-msvc", "x86_64-pc-windows-gnullvm"] +ignore-build-dependencies = true +ignore-dev-dependencies = true diff --git a/build/director.manifest b/packaging/director.manifest similarity index 100% rename from build/director.manifest rename to packaging/director.manifest diff --git a/build/windows_icon.rs b/packaging/windows_icon.rs similarity index 97% rename from build/windows_icon.rs rename to packaging/windows_icon.rs index 6cb6000..71bac9a 100644 --- a/build/windows_icon.rs +++ b/packaging/windows_icon.rs @@ -53,10 +53,10 @@ pub fn embed(svg: &[u8], binary: &str) { let description = rc_text(&env::var("CARGO_PKG_DESCRIPTION").expect("package description")); let icon_path = icon.display().to_string().replace('\\', "/"); // RT_MANIFEST (24), resource 1: declares Windows 11 support and DPI awareness. - println!("cargo:rerun-if-changed=build/director.manifest"); + println!("cargo:rerun-if-changed=packaging/director.manifest"); let manifest = std::path::Path::new(&env::var_os("CARGO_MANIFEST_DIR").expect("crate directory")) - .join("build/director.manifest") + .join("packaging/director.manifest") .display() .to_string() .replace('\\', "/"); diff --git a/scripts/package-msi.ps1 b/scripts/package-msi.ps1 index 9647eb6..6386d81 100644 --- a/scripts/package-msi.ps1 +++ b/scripts/package-msi.ps1 @@ -50,11 +50,11 @@ $setup = Join-Path $outputDir "Director-$version-x64-setup.exe" New-Item -ItemType Directory -Force $outputDir | Out-Null Invoke-Wix @('build', '-arch', 'x64', '-d', "Version=$version", '-d', "ReleaseDir=$release", - '-d', "Publisher=$publisher", '-d', "Description=$description", + '-d', "Publisher=$publisher", '-d', "Description=$description", '-d', "SourceDir=$root", '-o', $msi, (Join-Path $installerDir 'Director.wxs')) if ($LASTEXITCODE -ne 0) { throw 'WiX could not build the Director MSI.' } -# The setup window shows a 64 px logo. build/windows_icon.rs stores every icon frame as a PNG, so copy that frame. +# The setup window shows a 64 px logo. packaging/windows_icon.rs stores every icon frame as a PNG, so copy that frame. $ico = [IO.File]::ReadAllBytes((Join-Path $release 'director.ico')) $logoBytes = $null for ($entry = 0; $entry -lt [BitConverter]::ToUInt16($ico, 4); $entry++) { diff --git a/src/android_tv.rs b/src/android_tv.rs index e4de47d..2680cd0 100644 --- a/src/android_tv.rs +++ b/src/android_tv.rs @@ -1,4 +1,4 @@ -//! Android TV Remote v2 wire subset. Protocol references: docs/ANDROID_TV.md. +//! Android TV Remote v2 wire subset. See docs/TVS.md for the protocol scope and references. //! Deliberately excludes generic keys, text injection and menu sequences. use std::io::{Read, Write}; pub const LIMIT: usize = 65536; diff --git a/src/preset_cards_preview.rs b/src/preset_cards_preview.rs index 89d4fa4..c0a0e25 100644 --- a/src/preset_cards_preview.rs +++ b/src/preset_cards_preview.rs @@ -7,6 +7,13 @@ use director::{ }; use std::sync::atomic::{AtomicBool, Ordering}; pub(crate) static ENABLED: AtomicBool = AtomicBool::new(false); + +/// Where preview fixtures write state for inspection: `target/preview/`. +pub(crate) fn output(name: &str) -> std::path::PathBuf { + let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("target/preview"); + std::fs::create_dir_all(&dir).unwrap(); + dir.join(name) +} fn layout() -> Layout { let mut monitors = vec![]; for (i, name) in ["Desk monitor", "Portrait monitor", "Living room TV"] @@ -362,11 +369,11 @@ impl DirectorApp { if let Some(tv) = &self.tv.draft { let data = director::samsung::report(tv).unwrap(); std::fs::write( - if tv.brand == director::tvs::Brand::TclAndroid { - ".localonly/android-fixture-report.json" + output(if tv.brand == director::tvs::Brand::TclAndroid { + "android-fixture-report.json" } else { - ".localonly/samsung-fixture-report.json" - }, + "samsung-fixture-report.json" + }), serde_json::to_vec_pretty(&data).unwrap(), ) .unwrap(); diff --git a/src/scene_ui.rs b/src/scene_ui.rs index 3b5056f..d32838d 100644 --- a/src/scene_ui.rs +++ b/src/scene_ui.rs @@ -281,7 +281,7 @@ impl DirectorApp { self.scene.scenes = next; if crate::fps_ui::PREVIEW.load(Ordering::Acquire) { std::fs::write( - ".localonly/fps-scenes-fixture.json", + crate::preset_cards_preview::output("fps-scenes-fixture.json"), serde_json::to_vec_pretty(&self.scene.scenes).unwrap(), ) .unwrap(); diff --git a/src/windows_samsung.rs b/src/windows_samsung.rs index c513068..2684733 100644 --- a/src/windows_samsung.rs +++ b/src/windows_samsung.rs @@ -127,11 +127,16 @@ impl Backend for Controls<'_> { #[cfg(test)] #[test] -#[ignore = "Synthetic loopback TLS test driven by local owned .NET server; no real TV or settings"] +#[ignore = "Manual: needs a hand-started local TLS server that writes target/preview/samsung-tls-case.json; no real TV or settings"] fn samsung_tls_fixture() { - let value: serde_json::Value = - serde_json::from_slice(&std::fs::read(".localonly/samsung-tls-case.json").unwrap()) - .unwrap(); + let value: serde_json::Value = serde_json::from_slice( + &std::fs::read(concat!( + env!("CARGO_MANIFEST_DIR"), + "/target/preview/samsung-tls-case.json" + )) + .unwrap(), + ) + .unwrap(); let port = value["port"].as_u64().unwrap() as u16; let certificate = serde_json::from_value::>(value["certificate"].clone()).unwrap(); let result = Socket::open_path(