Merge pull request #20 from chrisuthe/chrisuthe/task/finish-the-reskin-tray-parity-friendly-setting

Finish the reskin: tray parity, friendly picker labels, guarded macOS font, docs sweep

Author: chrisuthe

README.md

@@ -29,16 +29,34 @@ the obvious answer, and each one cost real effort to establish.
 - **Native OS media integration** — the Windows 11 media flyout, MPRIS on Plasma 6 and GNOME, and
   Now Playing / Control Center on macOS — so hardware media keys work without the app being
   focused.
-- **Tray / status item**, start-minimized, single-instance, and notifications with per-event
-  toggles.
+- **Tray / status item** with the transport, Switch Group, mute and a volume readout in its menu;
+  start-minimized, single-instance, and notifications with per-event toggles.
 - **Real measured output latency** per platform, not a constant, plus a per-device manual offset
   for the Bluetooth and AirPlay tail that no API reports.
-- **A diagnostics view** showing sync error, correction band, playback rate in ppm, buffer depth,
-  clock offset and drift, and — the most useful single field — whether the timing source is
-  actually the audio hardware clock.
+- **Stats for Nerds**, a separate window showing sync error, correction band, playback rate in
+  ppm, buffer depth, clock offset and drift, and — the most useful single field — whether the
+  timing source is actually the audio hardware clock. It reopens where it was left.
 - **Native shell, system theme and accent, platform font.** Resizable, with the OS's own
   decorations; follows the desktop's light/dark setting and accent live. The layout inside the
   window comes from Sendspin for Windows; the colours do not.
+- **A living backdrop.** The player advertises the `color@v1` and `visualizer@v1` roles, and the
+  server's palette and loudness/beat frames drive the window: **Ambient Glow** (colour blobs
+  behind the veil), **Breathing Art** (the album art breathes with the music) or **Off**, with an
+  intensity slider. A box drawing without a GPU gets Off automatically, because the effect costs
+  too much in software rendering.
+- **A settings card** over the backdrop rather than a dialog: every control writes through the
+  moment it changes, so there is no Save. Pickers show plain names, not enum members.
+
+## Screenshots
+
+Taken on Fedora / KDE Plasma under Wayland, following the desktop's theme and accent.
+
+| | |
+|---|---|
+| ![Now Playing, narrow, dark](docs/screenshots/reskin/phase3-narrow-dark.png) | ![Now Playing, wide, light](docs/screenshots/reskin/phase3-wide-light.png) |
+| Now Playing, the narrow composition, dark | Now Playing, the wide composition, light |
+| ![Ambient Glow](docs/screenshots/reskin/phase5-glow-dark.png) | ![The settings card](docs/screenshots/reskin/phase4-settings-dark.png) |
+| Ambient Glow, driven by the server's palette and loudness | The settings card |
 
 ## Requirements
 

docs/ARCHITECTURE.md

@@ -582,6 +582,28 @@ the host's and the shell cannot follow a path into it.
 
 ## UI shell
 
+**What shipped, by paragraph.** The measurements below are long; these are the "As shipped"
+paragraphs that say what the player does with them, so a reader after the shell rather than the
+numbers can go straight there:
+
+- **The shell** — [reskin phase 1](#system-font--inter-wins-only-because-fluent-asks-for-it-first)
+  (system theme, accent and font, the "Decided and shipped" paragraph at the end of the font section)
+  and [reskin phase 2](#as-shipped-reskin-phase-2--the-window-shell): the 440×700 native-decorated
+  window, the layer stack, the opaque-root and toolbar-inset rules.
+- **The clock** — the "one timer" paragraph under
+  [reskin phase 2](#as-shipped-reskin-phase-2--the-window-shell): `UiClock`, the hygiene test that
+  keeps `DispatcherTimer` out, and the elapsed-time progress bar.
+- **The compositions** — [reskin phase 3](#as-shipped-reskin-phase-3--now-playing-welcome-the-backdrop-the-prompt):
+  Now Playing's narrow and wide layouts, Welcome, the blurred-art backdrop and the auto-connect prompt.
+- **The settings card** — [reskin phase 4](#as-shipped-reskin-phase-4--the-settings-card-and-the-stats-window),
+  first paragraph: the overlay card, its sections, and write-through with no Save.
+- **The Stats window** — [reskin phase 4](#as-shipped-reskin-phase-4--the-settings-card-and-the-stats-window),
+  "The Stats window": the separate diagnostics window and its refresh clock.
+- **The backdrop** — [reskin phase 5](#as-shipped-reskin-phase-5--the-living-backdrop): the two
+  advertised roles, Ambient Glow, Breathing Art, the software-rendering guard and the measured cost.
+- **The loose ends** — [reskin phase 6](#as-shipped-reskin-phase-6--tray-parity-friendly-labels-the-macos-font):
+  the tray menu at parity with the reference, the friendly picker labels, and the guarded macOS font.
+
 What the windowing layer actually does when asked to follow the desktop, and what the living-backdrop
 effect loop costs. Measured on two dev machines with a throwaway probe kept under
 `scripts/spike/ShellSpike/` so any of it can be re-run:
@@ -889,9 +911,14 @@ already sees, which is what takes the Flatpak from DejaVu Sans to the desktop's
 portal or no key leaves `DefaultFamilyName` null, which is fontconfig's answer as before. The app logs
 what it ended up with at start-up (`UI font: $Default is …, glyphs from …, fallback face …`), which
 is the `font` probe's report without a second binary. Windows leaves the name null on the measurement
-above; macOS leaves it null on the Helvetica measurement; the table above shows `.AppleSystemUIFont` is the
-name that resolves to the system face and that an unresolvable name kills the process, so the macOS
-override is a follow-up that ships with a resolve check (`PlatformSelection.MacOS.cs`).
+above. **macOS: shipped, guarded** (reskin phase 6). The table above shows `.AppleSystemUIFont` is the
+name that resolves to the system face and that an unresolvable name kills the process, so
+`PlatformSelection.MacOS.cs` names it only after `SKFontManager.Default.MatchFamily` has returned a
+typeface for it — the same font manager Avalonia will ask — and leaves the name null, with a line on
+standard error, when it does not. The rule is `Core/Platform/MacSystemFont.Select`, a pure function
+over a resolver, pinned by `Sendspin.Tests/MacSystemFontTests` on both answers without a Mac. The
+start-up `UI font:` line is how the result is read on the machine: `$Default is .AppleSystemUIFont,
+glyphs from System Font` is the guard passing.
 
 
 ### Decorations and client-area extension — the hint does nothing under KWin
@@ -1430,3 +1457,29 @@ spike's, and is exactly why the guard exists. The loop itself held 62.5 fps in e
 `docs/screenshots/reskin/phase5-glow-{light,dark}.png` (the window as the user had it, wide) and
 `phase5-breathing-dark.png`; the settings-card shot `phase5-settings-backdrop.png` needs a hand on
 the gear and is not in this commit.
+
+### As shipped (reskin phase 6) — tray parity, friendly labels, the macOS font
+
+**The tray menu** (`Services/TrayIconController.cs`) carries the Sendspin for Windows items in its
+order, under this app's status line: Play / Pause, Next, Previous, Switch Group, a separator, Mute /
+Unmute, a disabled `Volume: NN %` readout, a separator, Show Sendspin Player, Quit. Switch Group is
+there whether or not the footer shows its button, because the menu is where a hidden button's
+function still lives. The two Avalonia constraints in the file's remarks still hold, so state is
+carried in labels — Play / Pause and Mute / Unmute follow the view model, the readout follows
+`Volume` — and never in `IsChecked`. The transport items bind the view model's commands rather than
+click handlers, which is what greys them all out together while there is no connection
+(`NativeMenuItem` follows `CanExecute`); Mute goes through a new `ToggleMuteCommand` so the footer's
+speaker button and the tray drive the one property. `Sendspin.Ui.Tests/TrayMenuTests` builds the
+menu over the headless platform's null tray and reads the headers in order, then flips mute and
+volume on the view model and reads them back.
+
+**The friendly labels.** `Converters/ConnectionModeLabel.cs` and `AutoConnectPolicyLabel.cs` follow
+`BackdropModeLabel`: the picker binds the enum through to the setting and only the item template
+goes through the converter, so "AdvertiseOnly" reads as "Advertise to servers, and let a server
+connect" and "JustOnce" as "Just once". `Sendspin.Ui.Tests/SettingLabelTests` pins every member of
+both enums, so a new member fails a test rather than showing raw; `ConnectionMode.Auto`, obsolete
+on this SDK line and removed on the next, is the one member allowed to fall through, and the test
+says so. `EverySettingsComboBoxIsGuarded` still counts five.
+
+**The macOS font** is the "shipped, guarded" paragraph at the end of the System font section
+above. The one thing this phase could not verify from Linux is that line on a Mac.

docs/NEXT_STEPS.md

@@ -261,3 +261,19 @@ Recorded so the reasoning is not relitigated from scratch:
   complete first-party Swift SDK; SwiftUI plus SendspinKit is the answer there.
 - **No native C audio shim yet.** See `docs/ARCHITECTURE.md` for the per-platform realtime story and
   where the macOS one is knowingly short.
+- **The native shell.** The window follows the system theme, accent and font, with the OS's own
+  decorations; the composition — the layer stack, Now Playing's two layouts, the settings card, the
+  Stats window, the living backdrop — comes from Sendspin for Windows, and the colours do not. Every
+  colour is a theme or accent token; the hygiene test in `Sendspin.Ui.Tests` keeps literal colours
+  out of the axaml. The reasoning and the measurements are the *UI shell* section of
+  `docs/ARCHITECTURE.md`.
+- **The `UiClock` rule.** No `DispatcherTimer`, `RequestAnimationFrame` or Avalonia `Animation` in
+  the app: the Wayland backend quantises the first and runs the other two at tens of kilohertz with
+  no frame between (item 8). Everything periodic goes through `Player/Threading/UiClock.cs`, and a
+  hygiene test keeps `DispatcherTimer` out of every other file. Re-measure the backend on every
+  `Avalonia.Wayland` bump before relaxing this; do not relax it on the strength of a reading.
+- **The two backdrop roles are advertised.** `client/hello` lists `color@v1` and `visualizer@v1`
+  with a `visualizer@v1_support` object, verified live against Music Assistant; the roles and the
+  support object are one pin. Taking them out again to slim the hello would put the living backdrop
+  back on the theme accent alone — the fallback exists for a server that lacks the roles, not as a
+  mode to prefer.

src/Sendspin.Core/Platform/MacSystemFont.cs

@@ -0,0 +1,35 @@
+namespace Sendspin.Core.Platform;
+
+/// <summary>
+/// The family name the macOS head hands Avalonia as <c>$Default</c>, and the rule for when it
+/// may.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Left to itself, Avalonia's <c>DefaultFontFamily</c> resolves to Helvetica on macOS, not the
+/// system face. <c>.AppleSystemUIFont</c> is the name that resolves to it (measured in the
+/// "System font" section of <c>docs/ARCHITECTURE.md</c>). The same measurement found that an
+/// unresolvable <c>DefaultFamilyName</c> does not degrade: it throws out of the first layout pass
+/// and the process dies before a window appears, with an exception that names only
+/// <c>$Default</c>. So the name is only ever used after the font manager has said it resolves.
+/// </para>
+/// <para>
+/// The resolve check is handed in so the rule is testable without a Mac; the head passes
+/// Skia's font manager.
+/// </para>
+/// </remarks>
+public static class MacSystemFont
+{
+    /// <summary>The name macOS exposes its system UI font under.</summary>
+    public const string FamilyName = ".AppleSystemUIFont";
+
+    /// <summary>
+    /// The family to hand Avalonia: <see cref="FamilyName"/> when <paramref name="resolves"/>
+    /// says the font manager can match it, otherwise null, which leaves the platform default.
+    /// </summary>
+    public static string? Select(Func<string, bool> resolves)
+    {
+        ArgumentNullException.ThrowIfNull(resolves);
+        return resolves(FamilyName) ? FamilyName : null;
+    }
+}

src/Sendspin.Player/Converters/AutoConnectPolicyLabel.cs

@@ -0,0 +1,32 @@
+using System.Globalization;
+using Avalonia.Data.Converters;
+using Sendspin.Core.Configuration;
+
+namespace Sendspin.Player.Converters;
+
+/// <summary>
+/// The auto-connect policies as the settings row names them. The picker binds the enum straight
+/// through to the setting; only what it shows goes through here.
+/// </summary>
+public sealed class AutoConnectPolicyLabel : IValueConverter
+{
+    /// <summary>The one instance, for <c>x:Static</c>.</summary>
+    public static AutoConnectPolicyLabel Instance { get; } = new();
+
+    /// <summary>The row's name for a policy.</summary>
+    public static string For(AutoConnectPolicy policy) => policy switch
+    {
+        AutoConnectPolicy.Never => "Never",
+        AutoConnectPolicy.JustOnce => "Just once",
+        AutoConnectPolicy.Always => "Always",
+        _ => policy.ToString(),
+    };
+
+    /// <inheritdoc/>
+    public object? Convert(object? value, Type targetType, object? parameter, CultureInfo culture) =>
+        value is AutoConnectPolicy policy ? For(policy) : value?.ToString();
+
+    /// <inheritdoc/>
+    public object? ConvertBack(object? value, Type targetType, object? parameter, CultureInfo culture) =>
+        throw new NotSupportedException("The label is display-only; the picker binds the value itself.");
+}

src/Sendspin.Player/Converters/ConnectionModeLabel.cs

@@ -0,0 +1,35 @@
+using System.Globalization;
+using Avalonia.Data.Converters;
+using Sendspin.SDK.Client;
+
+namespace Sendspin.Player.Converters;
+
+/// <summary>
+/// The connection modes as the settings row names them. The picker binds the enum straight
+/// through to the setting; only what it shows goes through here.
+/// </summary>
+public sealed class ConnectionModeLabel : IValueConverter
+{
+    /// <summary>The one instance, for <c>x:Static</c>.</summary>
+    public static ConnectionModeLabel Instance { get; } = new();
+
+    /// <summary>The row's name for a mode.</summary>
+    /// <remarks>
+    /// <c>ConnectionMode.Auto</c> is deliberately not named: it is obsolete, the picker does
+    /// not offer it, and a persisted one is rewritten on load.
+    /// </remarks>
+    public static string For(ConnectionMode mode) => mode switch
+    {
+        ConnectionMode.AdvertiseOnly => "Advertise to servers, and let a server connect",
+        ConnectionMode.DiscoverOnly => "Discover servers, and connect from here",
+        _ => mode.ToString(),
+    };
+
+    /// <inheritdoc/>
+    public object? Convert(object? value, Type targetType, object? parameter, CultureInfo culture) =>
+        value is ConnectionMode mode ? For(mode) : value?.ToString();
+
+    /// <inheritdoc/>
+    public object? ConvertBack(object? value, Type targetType, object? parameter, CultureInfo culture) =>
+        throw new NotSupportedException("The label is display-only; the picker binds the value itself.");
+}

src/Sendspin.Player/PlatformSelection/PlatformSelection.MacOS.cs

@@ -1,6 +1,7 @@
 using Avalonia;
 using Sendspin.Core.Platform;
 using Sendspin.Platform.MacOS.Platform;
+using SkiaSharp;
 
 namespace Sendspin.Player;
 
@@ -40,14 +41,36 @@ internal static class PlatformSelection
     /// answer.
     /// </summary>
     /// <remarks>
-    /// Null for now, and measured: <c>FontManager.DefaultFontFamily</c> resolves to
-    /// <c>Helvetica</c> on macOS 26 (Avalonia 12.1.1), not the system UI font (SF Pro). So
-    /// <c>$Default</c> is the wrong face here and a per-platform name will be needed; which
-    /// family name Skia resolves to SF is still being measured, and guessing one would be worse
-    /// than Helvetica. The SF override is a follow-up once the resolvable name is known
-    /// (<c>dotnet run --project scripts/spike/ShellSpike -- font</c>, with the candidate names).
+    /// <para>
+    /// The platform's own answer is Helvetica (measured on macOS 26, Avalonia 12.1.1), so the
+    /// system face is named: <c>.AppleSystemUIFont</c>, the one name that resolved to it. The
+    /// name is guarded, because an unresolvable <c>DefaultFamilyName</c> kills the process in
+    /// the first layout pass — the rule and the measurement are on <see cref="MacSystemFont"/>.
+    /// Skia's font manager is the resolver: it is what Avalonia asks at start-up, and it is
+    /// already loaded through Avalonia.Skia.
+    /// </para>
+    /// <para>
+    /// This runs before the container exists, so a miss goes to standard error rather than the
+    /// logger; the start-up <c>UI font:</c> log line then shows what <c>$Default</c> became.
+    /// </para>
     /// </remarks>
-    public static string? ReadDesktopFontFamily() => null;
+    public static string? ReadDesktopFontFamily()
+    {
+        var family = MacSystemFont.Select(Resolves);
+
+        if (family is null)
+        {
+            Console.Error.WriteLine($"{MacSystemFont.FamilyName} does not resolve here; leaving the UI font to the platform.");
+        }
+
+        return family;
+
+        static bool Resolves(string name)
+        {
+            using var typeface = SKFontManager.Default.MatchFamily(name);
+            return typeface is not null;
+        }
+    }
 
     /// <summary>
     /// Selects the windowing backend.

src/Sendspin.Player/Program.cs

@@ -62,13 +62,14 @@ public static int Main(string[] args)
     /// and App.axaml overrides that resource to <c>$Default</c>. <c>DefaultFamilyName</c> is what
     /// <c>$Default</c> resolves to: on Linux it is the desktop's interface font read from the
     /// Settings portal (fontconfig's own default is DejaVu Sans inside the Flatpak, which is not
-    /// the desktop's font); on Windows and macOS it is left null, which means "ask the platform".
-    /// On Windows that answer is measured: plain Segoe UI, the face the WPF reference app uses.
-    /// On macOS it is measured too, and wrong: Helvetica rather than SF Pro. The SF override is
-    /// a follow-up once the family name Skia resolves to SF is known — see
-    /// <see cref="PlatformSelection.ReadDesktopFontFamily"/> on each head. The pair was measured
-    /// in the "System font" section of docs/ARCHITECTURE.md; macOS also confirmed that the
-    /// embedded <c>fonts:Inter#Inter</c> is the only way Inter resolves on a box without it
+    /// the desktop's font); on Windows it is left null, which means "ask the platform", and that
+    /// answer is measured: plain Segoe UI, the face the WPF reference app uses. On macOS the
+    /// platform's answer is Helvetica, so the head names the system face,
+    /// <c>.AppleSystemUIFont</c>, guarded by a resolve check because an unresolvable name kills
+    /// the process before a window appears — see
+    /// <see cref="PlatformSelection.ReadDesktopFontFamily"/> on each head. All three were
+    /// measured in the "System font" section of docs/ARCHITECTURE.md; macOS also confirmed that
+    /// the embedded <c>fonts:Inter#Inter</c> is the only way Inter resolves on a box without it
     /// installed, which is why <c>WithInterFont()</c> stays.
     /// </para>
     /// </remarks>