Shade 1.2.4

Full Changelog: v1.2.3...v1.2.4

Shade 1.2.0

Shade 1.2.0

Windows x64 release, 2026-09-26.

Shade dims individual monitors from a compact control window that mirrors your desktop layout, and
exposes the same controls to Home Assistant over MQTT and to the command line.

Changes since 1.1.0

• No console window. Shade was built as a console application, so starting it from Explorer, a
  shortcut or the tray opened a console window that stayed behind the control window for as long as
  Shade ran. It is now a windows-subsystem application and no console is created. This affected every
  earlier release, including 1.0.0 and 1.1.0.
• A second, much smaller download. Shade-1.2.0-win-x64-aot.zip is compiled ahead of time with
  NativeAOT: one 26 MB executable instead of 91 MB, and it starts sooner. The original build is still
  published as Shade-1.2.0-win-x64.zip and remains the recommended download.
• The command line is unchanged from 1.1.0.

Which download

Download	Size	Notes
Shade-1.2.0-win-x64.zip	~91 MB executable	The build every previous release shipped. Choose this one unless you have a reason not to.
Shade-1.2.0-win-x64-aot.zip	~26 MB executable	Compiled ahead of time. Smaller and quicker to start. Newer, and tested on fewer machines.

Both are a single self-contained Shade.exe that needs no .NET installation, both are unsigned, and
both read the same settings, so you can swap between them without losing anything. Verify either
against SHA256SUMS.txt.

The ahead-of-time build restores four bundled libraries to
%LOCALAPPDATA%\Shade\native\<content-hash>\ on first start, because ahead-of-time compilation
cannot hold unmanaged libraries inside the executable. They are verified by SHA-256 on every start
and replaced if altered, and the directory is per user.

Install or upgrade

Download and extract either ZIP, then run Shade.exe. Keep the included license notices with
redistributed copies. Windows SmartScreen may warn on first launch because neither build is signed.

Upgrading from 1.0.0 or 1.1.0 needs no settings migration; the settings format is still 4. Exit the
previous instance from its tray menu, or run Shade --exit, before replacing the executable. Back up
the Shade folder in your local application-data directory (%LOCALAPPDATA%\Shade) first. Windows MQTT
credentials remain protected for the account that saved them.

One behaviour change worth knowing

Because Shade is no longer a console application, a shell does not wait for it. Typing
Shade --status at a prompt still prints — Shade attaches to the terminal it was started from — but
the prompt returns first, and $LASTEXITCODE is not filled in.

Scripts that need Shade's output or exit code should wait explicitly:

$shade = Start-Process Shade.exe -ArgumentList '--status' -RedirectStandardOutput status.txt -Wait -PassThru
$shade.ExitCode
Get-Content status.txt

Output already redirected to a file or a pipe is untouched and behaves as before.

Verified for this release

The tagged build runs the shared checks and the isolated MQTT integration check, verifies the vendored
CupriFace sources, restores from lock files, and packages both Windows archives with bundled license
notices and SHA-256 checksums. The ahead-of-time archive is rejected if it contains more than one
executable, which is what proves its libraries were embedded rather than left beside it.

The ahead-of-time build was additionally checked by hand on two Windows machines: the control window,
dimming, Home Assistant with saved credentials surviving a restart, and forwarded command lines. Its
accessibility and renderer were verified with Shade's live UI Automation smoke — seven sliders
discovered, set and restored, accessible text and password editing, the Home Assistant form, and
native Tab/Shift+Tab — reporting software=False, so hardware OpenGL rather than the software
renderer. Startup to an accessible slider measured 1,369 ms against 1,090 ms for the untrimmed
baseline, so it is smaller and quicker to start as a process without being quicker to reach.

Ahead-of-time compilation reports five warnings from Silk.NET's native-library resolver
(IL3000/IL3002) about APIs that return nothing in a single-file application. They are left visible
in the build log rather than suppressed: they are the standing reason to keep checking that this build
finds its libraries, which the UI Automation smoke above is what confirms.

Known limitations

Unchanged from 1.1.0:

• Physical display hotplug/docking, sleep/resume and mixed-DPI identity continuity have not completed
  the full hardware acceptance matrix. Identical monitors without unique serial numbers cannot always
  be distinguished after moving connections.
• Gaming frame-time impact, HDR/VRR and exclusive-fullscreen behavior have not completed acceptance
  testing. The automated tests do not establish gaming performance or physical-monitor compatibility.
• Real Home Assistant reconnect/discovery lifecycle and the trusted-TLS matrix remain incomplete.
• Native screen-reader text-range support remains incomplete.
• Windows x64 only. The Linux backends are implemented and the shared checks pass there, but desktop
  acceptance is unfinished, so no Linux binary is published. Linux credential storage additionally
  needs libsecret and a desktop Secret Service.
• Raising or hiding the control window on request is implemented only on Windows.
• The executables are unsigned, and clean-machine acceptance remains pending.
• The control channel's boundary is the user account. Another program running as the same account can
  send control commands, or claim the channel name while Shade is not running. This crosses no
  boundary that account does not already have, and the channel carries no credential.

New in this release and not yet closed:

• The ahead-of-time build has been exercised on two machines, not on a clean-machine matrix, and not
  with a screen reader attached beyond the automated UI Automation checks. The untrimmed build remains
  the recommended download for that reason.
• A Linux ahead-of-time build has not been attempted. Ahead-of-time compilation cannot cross-compile
  between operating systems, so it would have to be built on Linux, and the embedded-library restore
  that makes the Windows build one file is Windows-only.

Owner: Codex/User for the remaining acceptance items. Next review 2026-10-03.

Shade 1.1.0

Shade 1.1.0

Windows x64 release, 2026-09-25.

Shade dims individual monitors from a compact control window that mirrors your desktop layout, and
exposes the same controls to Home Assistant over MQTT and to the command line.

Changes since 1.0.0

• The command line now sets most of what the interface sets: the global level, per-screen levels,
  enabling and disabling screens, following or leaving the global level, 100% shading, restore-all,
  the saved Home Assistant integration, the Advanced section, and showing, hiding or quitting the
  window. Run Shade --help for the list, or see the command-line reference.
• A second launch updates the instance already running instead of doing nothing. It hands its
  command line to that instance, which applies it immediately, and the existing window comes forward.
  Previously a duplicate launch printed a message and exited without bringing the window back.
• Shade --status prints the running instance's state for scripts, and Shade --exit quits it and
  removes its overlays.
• Exit codes now distinguish success, an unreachable instance, an invalid command line and a rejected
  request. They are listed in --help and in the reference.
• The release workflow marks a stable version as the repository's latest release; this was added for
  1.0.0 and is unchanged here.

Using the command line

Shade --global 40                            # set the global level
Shade --screen 2 --level 60 --screen 3 --off # per-screen, in the order given
Shade --screen all --on
Shade --restore                              # clear every screen
Shade --status                               # print the current state
Shade --exit                                 # quit the running instance

--screen takes the number shown beside each monitor, or all. A screen number that is not
connected refuses the whole command line rather than applying part of it. Startup options
(--settings-directory, --ephemeral, --no-tray) apply only when Shade is not already running and
are refused, not ignored, when it is.

Broker credentials are never accepted on a command line. Other programs running as your account
can read a process command line, so an MQTT username and password belong only in the Home Assistant
section. --home-assistant on re-enables the broker already saved, and refuses when none is saved.

Forwarded command lines travel over a named pipe restricted to your own account and desktop session,
carrying a fixed, length-capped vocabulary that is validated before anything is applied. The
reference describes the access control, the input limits and the trust boundary in full.

Install or upgrade

Download and extract Shade-1.1.0-win-x64.zip, then run Shade.exe. No separate .NET installation
is required. Verify the download against SHA256SUMS.txt. Keep the included license notices with
redistributed copies. The executable is unsigned, so Windows SmartScreen may warn on first launch.

Upgrading from 1.0.0 needs no settings migration; the settings format is still 4. Exit the previous
instance from its tray menu, or run Shade --exit, before replacing the executable. Back up the
Shade folder in your local application-data directory (%LOCALAPPDATA%\Shade) first. Windows MQTT
credentials remain protected for the account that saved them.

Verified for this release

The tagged build runs the shared checks and the isolated MQTT integration check on Windows, verifies
the vendored CupriFace sources, restores from lock files, and packages a self-contained single-file
executable with bundled license notices and SHA-256 checksums.

The 36 shared checks also pass on a self-contained linux-x64 build executed under WSL Ubuntu 24.04,
which exercises the forwarded-command-line channel over Unix domain sockets. A trimmed Windows
publish completes without warnings, though trimming remains off for the release as before.

New automated coverage: command-line parsing and its refusals, every operation's forwarded form,
29 malformed protocol lines, a live model driven through a real pipe, untrusted channel input refused
without changing state, and a quit request whose reply reaches the caller before shutdown.

Known limitations

Unchanged from 1.0.0 and not closed by this release:

• Physical display hotplug/docking, sleep/resume and mixed-DPI identity continuity have not completed
  the full hardware acceptance matrix. Identical monitors without unique serial numbers cannot always
  be distinguished after moving connections.
• Gaming frame-time impact, HDR/VRR and exclusive-fullscreen behavior have not completed acceptance
  testing. The automated tests do not establish gaming performance or physical-monitor compatibility.
• Real Home Assistant reconnect/discovery lifecycle and the trusted-TLS matrix remain incomplete.
• Native screen-reader text-range support remains incomplete.
• Windows x64 only. The Linux backends are implemented and the shared checks pass there, but desktop
  acceptance is unfinished, so no Linux binary is published. Linux credential storage additionally
  needs libsecret and a desktop Secret Service.
• Trimming and NativeAOT remain experimental; this release uses the untrimmed, self-contained
  single-file baseline.
• The executable is unsigned, and clean-machine acceptance remains pending.

New in this release and not yet closed:

• Raising or hiding the control window on request is implemented only on Windows. On Linux a
  forwarded command line still applies its controls, and --show and --hide report that the
  window cannot be moved.
• The live path of a second launch raising a real window has not been exercised by an automated test;
  the channel and the applied controls are covered on both platforms, but window activation against
  a running interface has only been reasoned about from the Windows foreground rules.
• The control channel's boundary is the user account. Another program running as the same account can
  send control commands, or claim the channel name while Shade is not running. This crosses no
  boundary that account does not already have, and the channel carries no credential.

Owner: Codex/User for the remaining acceptance items. Next review 2026-10-02.

Shade 1.0.0

Shade 1.0.0

Windows x64 stable release, 2026-09-25.

Shade dims individual monitors from a compact control window that mirrors your desktop layout, and exposes the same controls to Home Assistant over MQTT.

Changes since 1.0.0-rc.2

• First stable release. The application code is unchanged from 1.0.0-rc.2; this release promotes that candidate to a stable version after the candidate period passed without new defect reports.
• Version metadata moved from 1.0.0-rc.2 to 1.0.0, so the release is published as a normal release rather than a prerelease.
• The release workflow now marks stable versions as the repository's latest release and continues to leave prereleases unmarked.
• README and release documentation updated for the stable version.

Features

• Monitor-shaped controls that match your desktop arrangement; click a monitor to enable or disable its shading.
• Global slider with 0 / 20 / 40 / 60 / 80% quick presets. Global changes preserve disabled screens and independent levels.
• Advanced controls for individual screen levels, Use global, and Allow 100% shading, which switches the presets to 0 / 25 / 50 / 75 / 100%.
• Automatic display-layout reconciliation, with saved settings for trusted display identities and manual identity assignment for ambiguous hardware.
• Home Assistant MQTT 5 integration: a device named PCNAME Shade, per-screen controls using the numbers shown in Shade, TLS through the system certificate trust store, and credentials protected for the Windows account that saved them.
• Tray controls, Restore all displays, and Ctrl+Alt+Shift+R recovery.
• Single-instance protection with recovery after an abnormal exit, an application icon, and an About dialog.

Install or upgrade

Download and extract Shade-1.0.0-win-x64.zip, then run Shade.exe. No separate .NET installation is required. Verify the download against SHA256SUMS.txt. Keep the included license notices with redistributed copies. The executable is unsigned, so Windows SmartScreen may warn on first launch.

Upgrading from a release candidate needs no settings migration. Exit the previous instance from its tray menu first, and back up the Shade folder in your local application-data directory (%LOCALAPPDATA%\Shade). Settings use format 4, the same format as 1.0.0-rc.1 and 1.0.0-rc.2; older development builds may refuse newer settings. Windows MQTT credentials remain protected for the account that saved them and are not portable between accounts or machines.

Closing the window keeps Shade in the tray. Exit Shade quits and removes all overlays. Use --ephemeral --no-tray to test without loading or saving your normal settings.

Verified for this release

The tagged build runs the 33 shared checks and the isolated MQTT integration check on Windows, verifies the vendored CupriFace sources, restores from lock files, and packages a self-contained single-file executable with bundled license notices and SHA-256 checksums. Earlier candidate verification, including live UI Automation runs on the GPU and software renderers, is recorded in the 1.0.0-rc.1 notes and validation records.

Known limitations

These items are unchanged from 1.0.0-rc.2 and are not closed by this release:

• Physical display hotplug/docking, sleep/resume and mixed-DPI identity continuity have not completed the full hardware acceptance matrix. Identical monitors without unique serial numbers cannot always be distinguished after moving connections.
• Gaming frame-time impact, HDR/VRR and exclusive-fullscreen behavior have not completed acceptance testing. The automated tests do not establish gaming performance or physical-monitor compatibility.
• Real Home Assistant reconnect/discovery lifecycle and the trusted-TLS matrix remain incomplete.
• Native screen-reader text-range support remains incomplete.
• Windows x64 only. The Linux X11 and Wayland backends are implemented but desktop-session acceptance is unfinished, so no Linux binary is published.
• Trimming and NativeAOT remain experimental; this release uses the untrimmed, self-contained single-file baseline.
• The executable is unsigned, and clean-machine acceptance remains pending.

Owner: Codex/User for the remaining acceptance items, which are tracked for a later release. Next review 2026-10-02.

Shade 1.0.0-rc.2

Shade 1.0.0-rc.2

Windows x64 prerelease, 2026-09-12.

Changes

• Automated tag-based Windows builds, tests and GitHub Releases.
• Self-contained executable with application icon, version information, bundled license notices and SHA-256 checksums.
• Monitor-shaped controls, global presets, independent screen levels and optional 100% shading.
• Home Assistant MQTT integration with numbered screens and a computer-specific device name.
• About dialog, tray controls and single-instance protection with crash recovery.

Install or upgrade

Download and extract the Windows x64 ZIP, then run Shade.exe. No separate .NET installation is required. Keep the included license notices with redistributed copies. The executable is unsigned.

Exit the previous instance from its tray menu before upgrading. Back up the Shade folder in your local application-data directory first. Settings use format 4; older builds may refuse newer settings. Windows MQTT credentials remain protected for the account that saved them.

Closing the window keeps Shade in the tray. Exit Shade quits. Ctrl+Alt+Shift+R restores all screens. Use --ephemeral --no-tray to test without loading or saving normal settings.

Known limitations

This is a release candidate. Physical display hotplug/docking, sleep/resume, mixed-DPI identity continuity, gaming frame-time impact, HDR/VRR and exclusive-fullscreen behavior still need broader acceptance testing. Real Home Assistant reconnect/discovery and trusted-TLS acceptance are incomplete. Native screen-reader text-range support remains incomplete.

Linux backends are in development; this release provides only Windows x64. Trimming and NativeAOT remain experimental; the published candidate uses the untrimmed, self-contained single-file baseline. Clean-machine acceptance remains pending. Automated tests do not establish gaming performance or physical-monitor compatibility.

Owner: Codex/User for remaining acceptance checks. Review before a stable release; next review 2026-09-17.