UX waves 1–35: layouts, native window surfaces, Client models, terminal and window audits

.github/workflows/ci.yml

@@ -44,6 +44,11 @@ jobs:
         shell: bash
         run: dotnet run -c Release --no-build --project tests/SharpMUTerm.Core.Tests/SharpMUTerm.Core.Tests.csproj
 
+      - name: Test — Client
+        if: ${{ !cancelled() }}
+        shell: bash
+        run: dotnet run -c Release --no-build --project tests/SharpMUTerm.Client.Tests/SharpMUTerm.Client.Tests.csproj
+
       - name: Test — Graphics
         if: ${{ !cancelled() }}
         shell: bash

Directory.Packages.props

@@ -69,6 +69,7 @@
     <PackageVersion Include="Avalonia" Version="12.1.4" />
     <PackageVersion Include="Avalonia.Desktop" Version="12.1.4" />
     <PackageVersion Include="Avalonia.Themes.Simple" Version="12.1.4" />
+    <PackageVersion Include="Avalonia.Themes.Fluent" Version="12.1.4" />
     <PackageVersion Include="Avalonia.Headless" Version="12.1.4" />
 
     <!-- PNG encoder for tests that need real image bytes; the sibling of the decoder SharpConsoleUI uses. -->
@@ -87,6 +88,8 @@
     <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-j3p4-wp97-rph4" />
     <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-j9gm-c75j-xc9q" />
     <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-jjfr-hcj7-qf5w" />
+    <!-- TIFF fax (T4/T6/MH) tile decoding: unreachable, ImageDecoder configures the WebP module only. -->
+    <NuGetAuditSuppress Include="https://github.com/advisories/GHSA-v76p-62qx-wwq2" />
   </ItemGroup>
 
 </Project>

SharpMUTerm.slnx

@@ -2,6 +2,7 @@
   <Folder Name="/src/">
     <Project Path="src/SharpMUTerm.Audio/SharpMUTerm.Audio.csproj" />
     <Project Path="src/SharpMUTerm.Avalonia/SharpMUTerm.Avalonia.csproj" />
+    <Project Path="src/SharpMUTerm.Client/SharpMUTerm.Client.csproj" />
     <Project Path="src/SharpMUTerm.Core/SharpMUTerm.Core.csproj" />
     <Project Path="src/SharpMUTerm.Graphics/SharpMUTerm.Graphics.csproj" />
     <Project Path="src/SharpMUTerm.Scripting/SharpMUTerm.Scripting.csproj" />
@@ -10,6 +11,7 @@
   </Folder>
   <Folder Name="/tests/">
     <Project Path="tests/SharpMUTerm.Avalonia.Tests/SharpMUTerm.Avalonia.Tests.csproj" />
+    <Project Path="tests/SharpMUTerm.Client.Tests/SharpMUTerm.Client.Tests.csproj" />
     <Project Path="tests/SharpMUTerm.Core.Tests/SharpMUTerm.Core.Tests.csproj" />
     <Project Path="tests/SharpMUTerm.Graphics.Tests/SharpMUTerm.Graphics.Tests.csproj" />
     <Project Path="tests/SharpMUTerm.Scripting.Tests/SharpMUTerm.Scripting.Tests.csproj" />

docs/PACKAGING.md

@@ -56,6 +56,47 @@ dotnet publish src/SharpMUTerm.Avalonia -p:PublishProfile=linux-x64 -o out/linux
 
 Both use `packaging/icons/sharpmuterm.png` / `.ico`; the `.ico` is also each executable's Windows icon.
 
+### `telnet://` links
+
+Both packages can make `telnet://` and `telnets://` links open the window. The program never registers itself;
+the package does, and only where the player agreed to it:
+
+- **Linux** — `sharpmuterm.desktop` declares `MimeType=x-scheme-handler/telnet;x-scheme-handler/telnets;` and runs
+  `sharpmuterm-window --open-link %U`. It takes effect once the desktop integrates the AppImage (AppImageLauncher,
+  appimaged), or by hand: copy the desktop file to `~/.local/share/applications/`, point its `Exec=` at the AppImage,
+  and run `xdg-mime default sharpmuterm.desktop x-scheme-handler/telnet x-scheme-handler/telnets`.
+- **Windows** — the installer's *Open telnet:// and telnets:// links in SharpMUTerm* task (unchecked by default)
+  writes `Software\Classes\telnet` and `…\telnets` under `HKA` (the current user in the default per-user install)
+  with `"…\sharpmuterm-window.exe" --open-link "%1"`. Uninstalling removes both keys.
+
+`--open-link` is why the handler can be trusted with a link: with it on the command line, the client reads the one
+argument after it and drops every other (`ClientOptions.NarrowToLink`), so a link holding a quote cannot add
+arguments of its own. The link itself is read as server text (`TelnetLink`): host, port and TLS only — no user
+name or password, no path, no command. A running client is handed the link over a socket in
+`$XDG_RUNTIME_DIR/sharpmuterm/` (or beside `config.json`), and the new launch exits.
+
+### Alerts and the AppUserModelID
+
+The window takes the AppUserModelID `SharpMUTerm.Window` at start (`SetCurrentProcessExplicitAppUserModelID`), and
+the installer gives its Start menu and desktop shortcuts the same id and writes
+`Software\Classes\AppUserModelId\SharpMUTerm.Window` (`DisplayName`, and `IconUri` pointing at the installed
+`sharpmuterm.png`) under `HKA`, removed on uninstall. That key is what Windows needs before it shows a toast under the
+id, and its presence is how the window knows it may: an alert then shows a toast (through Windows PowerShell 5.1's
+WinRT `ToastNotificationManager`, the text base64-encoded inside the script) as well as flashing the taskbar. A copy
+run from the `.zip` has no key and only flashes. The program never writes the key itself. **Built, never run on
+Windows**: neither the toast nor the shortcut's id has been seen on a desktop.
+
+Linux needs nothing from the package: `notify-send` and, on X11, the window's urgency hint. macOS uses
+`/usr/bin/osascript`, which files the notification under Script Editor and asks once whether to allow it.
+
+### Passwords
+
+Character passwords go to the system's credential store when there is one that answers: Windows Credential Manager
+(built in), the Secret Service through libsecret's `secret-tool` on Linux (`libsecret-tools` on Debian and Ubuntu,
+`libsecret` on Fedora and Arch — recommend it, do not require it), and the login Keychain through `security` on
+macOS. Without one, or for a password it refuses, they stay in `secrets.json` beside `config.json`, as before.
+Existing `secrets.json` entries move into the store the first time the client starts with one.
+
 ## CI / releases
 
 `.github/workflows/release.yml` runs on `v*` tags (and manual dispatch). For `linux-x64` and `win-x64` it

packaging/linux/sharpmuterm.desktop

@@ -3,9 +3,13 @@ Type=Application
 Name=SharpMUTerm
 GenericName=MU* Client
 Comment=A MUSH, MUCK and MUD client
-Exec=sharpmuterm-window %U
+Exec=sharpmuterm-window --open-link %U
 Icon=sharpmuterm
 Terminal=false
 Categories=Game;RolePlaying;
 Keywords=MUD;MUSH;MUCK;MU*;telnet;
 StartupWMClass=sharpmuterm-window
+# telnet:// and telnets:// links open the client. Registered only when the desktop integrates the AppImage
+# (AppImageLauncher, appimaged, or `xdg-mime default sharpmuterm.desktop x-scheme-handler/telnet`); the program never
+# registers itself.
+MimeType=x-scheme-handler/telnet;x-scheme-handler/telnets;

packaging/windows/sharpmuterm.iss

@@ -45,15 +45,37 @@ WizardStyle=modern
 [Tasks]
 Name: "desktopicon"; Description: "{cm:CreateDesktopIcon}"; GroupDescription: "{cm:AdditionalIcons}"; Flags: unchecked
 Name: "addtopath"; Description: "Add the install folder to PATH, so sharpmuterm runs from any terminal"; GroupDescription: "Terminal:"
+Name: "telnetlinks"; Description: "Open telnet:// and telnets:// links in SharpMUTerm"; GroupDescription: "Links:"; Flags: unchecked
 
 [Files]
 Source: "{#PublishDir}\sharpmuterm-window.exe"; DestDir: "{app}"; Flags: ignoreversion
 Source: "{#PublishDir}\sharpmuterm.exe"; DestDir: "{app}"; Flags: ignoreversion
 Source: "..\..\LICENSE"; DestDir: "{app}"; DestName: "LICENSE.txt"; Flags: ignoreversion
+Source: "..\icons\sharpmuterm.png"; DestDir: "{app}"; Flags: ignoreversion
 
+; AppUserModelID: the window takes the same id at start (WindowsAppId in src/SharpMUTerm.Avalonia/DesktopAlert.cs), so
+; the taskbar groups it with this shortcut and an alert's toast is shown under it.
 [Icons]
-Name: "{autoprograms}\SharpMUTerm"; Filename: "{app}\sharpmuterm-window.exe"
-Name: "{autodesktop}\SharpMUTerm"; Filename: "{app}\sharpmuterm-window.exe"; Tasks: desktopicon
+Name: "{autoprograms}\SharpMUTerm"; Filename: "{app}\sharpmuterm-window.exe"; AppUserModelID: "SharpMUTerm.Window"
+Name: "{autodesktop}\SharpMUTerm"; Filename: "{app}\sharpmuterm-window.exe"; AppUserModelID: "SharpMUTerm.Window"; Tasks: desktopicon
+
+; telnet:// and telnets:// links, for this user (HKA is HKCU in the default per-user install). Only with the task above;
+; the program never registers itself. --open-link makes the client read the link and nothing else, so a link holding a
+; quote cannot add arguments of its own to the command line Windows builds from this template.
+[Registry]
+Root: HKA; Subkey: "Software\Classes\telnet"; ValueType: string; ValueName: ""; ValueData: "URL:Telnet Protocol"; Flags: uninsdeletekey; Tasks: telnetlinks
+Root: HKA; Subkey: "Software\Classes\telnet"; ValueType: string; ValueName: "URL Protocol"; ValueData: ""; Tasks: telnetlinks
+Root: HKA; Subkey: "Software\Classes\telnet\DefaultIcon"; ValueType: string; ValueName: ""; ValueData: """{app}\sharpmuterm-window.exe"",0"; Tasks: telnetlinks
+Root: HKA; Subkey: "Software\Classes\telnet\shell\open\command"; ValueType: string; ValueName: ""; ValueData: """{app}\sharpmuterm-window.exe"" --open-link ""%1"""; Tasks: telnetlinks
+Root: HKA; Subkey: "Software\Classes\telnets"; ValueType: string; ValueName: ""; ValueData: "URL:Telnet over TLS Protocol"; Flags: uninsdeletekey; Tasks: telnetlinks
+Root: HKA; Subkey: "Software\Classes\telnets"; ValueType: string; ValueName: "URL Protocol"; ValueData: ""; Tasks: telnetlinks
+Root: HKA; Subkey: "Software\Classes\telnets\DefaultIcon"; ValueType: string; ValueName: ""; ValueData: """{app}\sharpmuterm-window.exe"",0"; Tasks: telnetlinks
+Root: HKA; Subkey: "Software\Classes\telnets\shell\open\command"; ValueType: string; ValueName: ""; ValueData: """{app}\sharpmuterm-window.exe"" --open-link ""%1"""; Tasks: telnetlinks
+
+; The AppUserModelID's name and icon for toasts. Always written: its presence is what tells the window a toast can be
+; shown (a portable copy has none and only flashes the taskbar).
+Root: HKA; Subkey: "Software\Classes\AppUserModelId\SharpMUTerm.Window"; ValueType: string; ValueName: "DisplayName"; ValueData: "SharpMUTerm"; Flags: uninsdeletekey
+Root: HKA; Subkey: "Software\Classes\AppUserModelId\SharpMUTerm.Window"; ValueType: string; ValueName: "IconUri"; ValueData: "{app}\sharpmuterm.png"
 
 [Run]
 Filename: "{app}\sharpmuterm-window.exe"; Description: "{cm:LaunchProgram,SharpMUTerm}"; Flags: nowait postinstall skipifsilent

src/SharpMUTerm.Avalonia/App.cs

@@ -1,6 +1,7 @@
 using Avalonia;
 using Avalonia.Controls;
 using Avalonia.Controls.ApplicationLifetimes;
+using Avalonia.Controls.Primitives;
 using Avalonia.Themes.Simple;
 
 namespace SharpMUTerm.Avalonia;
@@ -19,6 +20,9 @@ public override void OnFrameworkInitializationCompleted()
             // The client decides when the program ends: closing the window asks it to quit, and it is the
             // client's loop ending that shuts the application down.
             desktop.ShutdownMode = ShutdownMode.OnExplicitShutdown;
+
+            // A menu's or a tooltip's popup is a top level of its own, so it does not inherit the windows' light hinting.
+            Control.LoadedEvent.AddClassHandler<PopupRoot>((root, _) => NativeTokens.ApplyTextRendering(root));
             desktop.MainWindow = new MainWindow(Options, desktop);
         }
 

src/SharpMUTerm.Avalonia/AvaloniaConsoleDriver.cs

@@ -70,6 +70,33 @@ public AvaloniaConsoleDriver(int columns, int rows)
     /// <summary>The window's screen-reader regions; the window adds them beside the view.</summary>
     public WindowAnnouncer Announcer { get; } = new();
 
+    /// <summary>The window's native settings window, which the main window owns (<see cref="SettingsPresenter"/>).</summary>
+    public SettingsPresenter Settings { get; } = new();
+
+    /// <summary>The window's native ⌃P, drawn over everything in the main window (<see cref="PalettePresenter"/>).</summary>
+    public PalettePresenter Palette { get; } = new();
+
+    /// <summary>The window's native F1, drawn over the cells in the main window (<see cref="ComposerPresenter"/>).</summary>
+    public ComposerPresenter Composer { get; } = new();
+
+    /// <summary>
+    /// The window's native quit prompt, ⌃F, ⌃R, ⌥M and welcome, drawn over everything in the main window, the quit prompt
+    /// always in front (<see cref="ModalPresenter"/>).
+    /// </summary>
+    public ModalPresenter Modals { get; } = new();
+
+    /// <summary>The panels popped out into windows of their own (<see cref="ClientHost.FloatingPanels"/>).</summary>
+    public FloatingPanelPresenter Floating { get; } = new();
+
+    /// <summary>The window's title for what is in front, which the main window shows (<see cref="WindowTitleBar"/>).</summary>
+    public WindowTitleBar TitleBar { get; } = new();
+
+    /// <summary>The window's alerts while it is behind another (<see cref="WindowAttention"/>).</summary>
+    public WindowAttention Attention { get; } = new();
+
+    /// <summary>The desktop's file picker, for an import from another client (<see cref="WindowFilePicker"/>).</summary>
+    public WindowFilePicker FilePicker { get; } = new();
+
     public bool IsRunning { get; private set; }
 
     // ── IConsoleDriver: output ────────────────────────────────────────────────────────────────
@@ -90,7 +117,19 @@ public void Stop()
 
     public void Flush()
     {
-        Volatile.Write(ref _frame, _grid.Snapshot(_caret));
+        // The band the client said while this frame was painted (PostBufferPaint runs before the flush, on this thread).
+        var frame = _grid.Snapshot(_caret);
+        if (Pointer.Band is { } band && band.Top + band.Rows <= frame.Height)
+        {
+            frame = frame.WithBand(band);
+        }
+
+        if (Pointer.Dividers is { Count: > 0 } dividers)
+        {
+            frame = frame.WithDividers(dividers);
+        }
+
+        Volatile.Write(ref _frame, frame);
         Interlocked.Increment(ref _frames);
         FrameReady?.Invoke();
     }
@@ -156,3 +195,27 @@ public void Resize(int columns, int rows)
 
     public void Dispose() => Pictures.Dispose();
 }
+
+/// <summary>
+/// The window's half of <see cref="IWindowTitle"/>: the client hands it <c>Character@World — SharpMUTerm</c> on its own
+/// thread, and the main window, which subscribes, puts it on the title bar and the taskbar entry on Avalonia's.
+/// </summary>
+internal sealed class WindowTitleBar : IWindowTitle
+{
+    /// <summary>The last title, or null before the client has said one.</summary>
+    public string? Current { get; private set; }
+
+    /// <summary>Raised on the client's thread with each new title.</summary>
+    public event Action<string>? Changed;
+
+    public void Show(string title)
+    {
+        Current = title;
+        Changed?.Invoke(title);
+    }
+
+    /// <summary>A window's title goes with the window; there is nothing to give back.</summary>
+    public void Restore()
+    {
+    }
+}

src/SharpMUTerm.Avalonia/BundledFonts.cs

@@ -0,0 +1,109 @@
+using Avalonia;
+using Avalonia.Media;
+using Avalonia.Media.Fonts;
+
+namespace SharpMUTerm.Avalonia;
+
+/// <summary>
+/// The faces this program carries (<c>Fonts/</c>, embedded): Inter for every native view and JetBrains Mono for game
+/// text, registered with Avalonia's font manager so a view naming either finds the bundled face on every OS — before
+/// this, "JetBrains Mono" resolved only where it happened to be installed, and the UI face was whatever the platform's
+/// default was (Segoe UI, Cantarell, San Francisco), so the window looked different on each.
+/// <para>
+/// Read from the assembly's manifest resources, the same streams <see cref="CellFonts"/> reads for the cells, so each
+/// file is carried once. The bare family names are mapped onto the bundle (<see cref="Options"/>), so a view that says
+/// <c>"JetBrains Mono"</c> or <c>"Inter"</c> gets the bundled face and an installed copy cannot replace it.
+/// </para>
+/// </summary>
+/// <para>
+/// <b>The faces are made once per process and shared by every collection.</b> A font manager disposes its collections,
+/// and the base collection disposes every face it holds; the headless tests set up a fresh application, and so a fresh
+/// font manager and collection, for every test, so the faces were read, made and disposed once per test, hundreds of
+/// times a run, and now and then one test failed to find Inter. Shared and never disposed, the eight faces are made
+/// once; the window has one font manager, so nothing changes there.
+/// </para>
+internal sealed class BundledFonts : FontCollectionBase, IDisposable
+{
+    private static readonly object Gate = new();
+    private static GlyphTypeface[]? s_faces;
+
+    /// <summary>The collection's key: families in it are named <c>fonts:SharpMUTerm#Inter</c>.</summary>
+    public static readonly Uri CollectionKey = new("fonts:SharpMUTerm");
+
+    /// <summary>The bundled UI face.</summary>
+    public const string Ui = "fonts:SharpMUTerm#Inter";
+
+    /// <summary>The bundled text face, the cells' own.</summary>
+    public const string Mono = "fonts:SharpMUTerm#JetBrains Mono";
+
+    /// <summary>Every face that is registered: the four Inter weights the views use, and JetBrains Mono's four.</summary>
+    internal static readonly string[] Files =
+    [
+        "Inter-Regular.ttf", "Inter-Medium.ttf", "Inter-SemiBold.ttf", "Inter-Bold.ttf",
+        "JetBrainsMono-Regular.ttf", "JetBrainsMono-Bold.ttf", "JetBrainsMono-Italic.ttf", "JetBrainsMono-BoldItalic.ttf",
+    ];
+
+    public override Uri Key => CollectionKey;
+
+    /// <summary>How many faces were loaded. Internal for tests: a packaging slip that drops a file shows here.</summary>
+    internal int Loaded { get; }
+
+    public BundledFonts()
+    {
+        GlyphTypeface[] shared;
+        lock (Gate)
+        {
+            if (s_faces is null)
+            {
+                var faces = new List<GlyphTypeface>();
+                foreach (var file in Files)
+                {
+                    using var stream = typeof(BundledFonts).Assembly.GetManifestResourceStream($"Fonts.{file}");
+                    if (stream is not null && TryAddGlyphTypeface(stream, out var face))
+                    {
+                        faces.Add(face);
+                    }
+                }
+
+                s_faces = [.. faces];
+                Loaded = s_faces.Length;
+                return;
+            }
+
+            shared = s_faces;
+        }
+
+        foreach (var face in shared)
+        {
+            if (TryAddGlyphTypeface(face))
+            {
+                Loaded++;
+            }
+        }
+    }
+
+    /// <summary>The shared faces outlive any one font manager, so a manager disposing this collection disposes none of them.</summary>
+    void IDisposable.Dispose()
+    {
+    }
+
+    /// <summary>
+    /// Inter as the default family (what <see cref="FontFamily.Default"/> resolves to, so every view that names none
+    /// is Inter), and the bare names mapped onto the bundle.
+    /// </summary>
+    public static FontManagerOptions Options => new()
+    {
+        DefaultFamilyName = Ui,
+        FontFamilyMappings = new Dictionary<string, FontFamily>(StringComparer.OrdinalIgnoreCase)
+        {
+            ["Inter"] = new FontFamily(Ui),
+            ["JetBrains Mono"] = new FontFamily(Mono),
+        },
+    };
+
+    /// <summary>Registers the bundle and the options on an app being built: the window's and the headless tests' alike.</summary>
+    public static AppBuilder Use(AppBuilder builder) =>
+        builder
+            .ConfigureFonts(manager => manager.AddFontCollection(new BundledFonts()))
+            .With(Options);
+}