downloader-desktop

name	downloader-desktop
description	Build, run, test and develop the Downloader.Desktop app (Avalonia/.NET download manager). Use for any task in this repo — launching the GUI, running the test suite, regenerating screenshots, or implementing features against the architecture below.

Downloader.Desktop

Cross-platform (Windows/Linux/macOS) Avalonia + .NET 10 GUI for the Downloader multipart-download engine. MVVM with ReactiveUI. Original modern-minimal design (ocean-blue/teal, light+dark). End-user focused: simple, stable, sensible defaults.

All commands run from the src/ folder (where Downloader.Desktop.sln lives).

Maintaining this skill (read first, every session)

Treat this file as a living cache. Whenever you discover something non-obvious that a future session would otherwise have to re-derive (an engine API shape, a gotcha, a settled design choice), append a concise boilerplate note here. The goal is steadily fewer tokens per session: each future run should read the answer here instead of re-grepping the codebase or the sibling ../Downloader engine. Keep additions short and factual — a few lines, not essays. Prune notes that become wrong. This is an explicit standing instruction from the author.

Commit policy: follow root CLAUDE.md → "Workflow & progress tracking" — commit frequently directly to develop and push, including skill-file notes, as part of routine work. (Superseded the older "never commit automatically" rule once the cross-machine PLAN.md/TASKS.md workflow was set up.)

Code map (read this before grepping — it's where things live)

Skip the discovery grep; jump straight to the file. src/Downloader.Desktop/:

• Download lifecycle / queues / scheduler: Services/DownloadManager.cs (+ IDownloadManager.cs). Owns Items, all state transitions (Start/Pause/Cancel/Resume/Retry/StopAll), PumpQueue (the ONLY capped start path — Start is the uncapped primitive), EvaluateSchedules, ApplyGlobalSpeedLimit. Start builds the DownloadConfiguration from Settings.ToConfiguration() synchronously before its first await, so vm.Status=Running + vm.Configuration are observable right after Add(autoStart:true) — that's how the headless tests assert without real I/O (unreachable IP 10.255.255.1).
• Per-row state/UI: ViewModels/DownloadItemViewModel.cs. Model-backed props write through to _item (pattern: get => _item.X; set { _item.X = value; RaisePropertyChanged(); } — see Status, HasCustomSpeedLimit). Exposes GetItem(), Manager, live Configuration.
• Persisted record: Models/DownloadItem.cs. Global settings (mirrors the engine DownloadConfiguration): Models/DownloadSettings.cs (+ ToConfiguration()). Root persisted state: Models/Config.cs (Settings/Queues/Schedules/Downloads, DefaultQueue).
• Settings screen: ViewModels/SettingViewModel.cs — S = the DownloadSettings; setters that must "bite" live also call the manager (e.g. MaxConcurrentDownloads→PumpQueue, MaxSpeedKbPerSecond→ApplyGlobalSpeedLimit).
• Details dialog: ViewModels/DownloadDetailsViewModel.cs + Views/DownloadDetailsView.axaml (per-connection strip, mirror editor, speed-limit box). Reaches global config via Item.Manager.Config.
• Custom window chrome: Views/TitleBar, Views/ResizeGrips.axaml.cs (+ pure Views/WindowResize.cs). Notch overlay: Views/NotchView.axaml(.cs) (height constants) + ViewModels/NotchViewModel.cs (MaxRows=3, HasOverflow).
• i18n: Assets/i18n/*.json (16 packs) + Services/Localizer + Markup/TrExtension. Notifications: Services/NotificationService. Tray/startup/update: Services/{TrayService,StartupService,UpdateService}.
• Tests (src/Downloader.Desktop.Tests/): foldered by kind — Unit/ (pure), Integration/ (manager+engine, headless via [AvaloniaFact]), UI/, Plugins/. Build manager tests with new DownloadManager(); Initialize(Config.New()); Add(item, autoStart).

Token discipline in this repo (the author flagged over-spend on small fixes)

1. Use the Code map above instead of grepping for where a thing lives. Only grep for a specific symbol you can't place from it.
2. Read the method, not the file — use Read with offset/limit (or grep -n the symbol first) rather than dumping 400-line files. VMs/DownloadManager are large.
3. Batch independent reads/greps into one message (multiple tool calls per turn) — don't serialize discovery.
4. Build once per logical chunk, not after every edit; Edit already fails loudly on a bad match, so don't re-Read a file just to confirm an edit landed.
5. For a small, well-scoped fix, target the one file the Code map names, edit, then one build+filtered-test — that's the whole loop.

Engine (Downloader 5.8.0) quick reference — sibling repo ../Downloader is exactly this version

• DownloadBuilder is single-URL only (WithUrl(string)) and its IDownload cannot take a logger (no AddLogger on IDownload). For mirrors and logging, use DownloadService directly instead of the builder.
• DownloadService(DownloadConfiguration cfg, ILoggerFactory factory = null) — implements IDownloadService: same events (DownloadStarted/DownloadProgressChanged/ChunkDownloadProgressChanged/DownloadFileCompleted), plus Package, Pause(), Resume(), CancelAsync()/CancelTaskAsync(), Clear(), and AddLogger(ILogger).
• Multi-URL / mirrors are first-class: DownloadFileTaskAsync(string[] urls, DirectoryInfo folder, ct) (auto-resolves name), (string[] urls, string fileName, ct), and package overloads. DownloadPackage.Urls is string[]. So the data model should carry List<string> Urls (first = primary, rest = mirrors), not a separate Url + Mirrors.
• Filename still auto-resolves from URL/Content-Disposition; read it from DownloadStartedEventArgs.FileName (full path).

Localization (i18n) — how it works here

• Services/Localizer (singleton) loads Assets/i18n/{lang}.json (en, fa, es, fr, ar, eo) via AssetLoader; English is the fallback. Active language persists in DownloadSettings.Language; load it at startup in MainViewModel and switch it from Settings (SelectedLanguage).
• XAML usage: Text="{i18n:Tr Some_Key}" (xmlns i18n="clr-namespace:Downloader.Desktop.Markup"). VM strings: Localizer.Instance["Key"]. Format strings use {0} + string.Format.
• Live-switch gotcha (important): Avalonia indexer-change notifications ("Item[]"/empty PropertyChanged) do NOT reliably refresh already-rendered [key] bindings. Instead {i18n:Tr} binds to Localizer.Tick (a normal int bumped each Load) through TrConverter, which DOES refresh. Don't revert to a raw indexer binding.
• RTL: Localizer.FlowDirection is RightToLeft for fa/ar; each Window binds FlowDirection="{Binding FlowDirection, Source={x:Static services:Localizer.Instance}}" (UserControls inherit it).
• VM-computed localized strings (row StatusText/DisplayName/Group, details headers) subscribe to Localizer.PropertyChanged and re-raise; DownloadItemViewModel.Detach() unsubscribes on removal (called by the manager) to avoid leaks.
• Adding a key: add to en.json first (it's the fallback), then translate into the other 5. Missing keys fall back to English gracefully.

Engine/behavior gotchas worth caching

• Plan-part completion must NOT gate on DownloadPart.ExpectedSize (DownloadManager.Plans.cs): for extracted streams (progressive/video/audio via yt-dlp) ExpectedSize is filesize_approx — an estimate (e.g. x.com reported 5.36 MB, real file 3.66 MB). An exact len==ExpectedSize gate made a finished part look unfinished → "Part 1/1 did not finish downloading" and an infinite re-download. IsPartComplete/PartDownloadedOk/MarkPartDone now rely on the .done marker + non-empty file (the engine already validates the full download and reports errors via the completion event). ExpectedSize is kept only for progress display. x.com/YouTube page-URL downloads work directly — the HLS plugin (com.bezzad.hls, now in-repo at src/Downloader.Desktop.Plugins/Downloader.Desktop.Plugins.Hls, an optional/catalog-tier plugin — was the separate ../Downloader.Plugins repo, consolidated in; see the "Plugin consolidation" note near the end) runs yt-dlp, no browser-extension .m3u8 hunting needed. yt-dlp runs bare (no cookies) so public content works but login-gated/age-restricted media would need --cookies-from-browser (future work). Two plugin bugs fixed in v1.1.1 (root-relative segments becoming file:// on Unix; codecless progressive MP4s skipped — see Downloader.Plugins issue #2). YouTube (plugin v1.1.2): needs BOTH browser cookies (bot check — plugin retries --cookies-from-browser per installed browser) AND a deno JS runtime (--js-runtimes deno:<path>, auto-provisioned like yt-dlp/ffmpeg) — without deno yt-dlp can't solve the "n challenge" and returns ONLY storyboard images (no formats). Node ≤20 is "unsupported" by yt-dlp's EJS solver — don't bother with it; deno is the supported default (see Downloader.Plugins issue #3).

• HttpClientTimeout is the WHOLE-request timeout (HttpClient.Timeout), incl. reading a chunk's body — keep it large (default 100 s). Setting it small (e.g. 10 s) makes longer chunks fail with "Operation Cancelled" after retries (~1 min). Per-block stalls are handled by BlockTimeout, not this.

• Cancellation vs failure status: the engine raises DownloadFileCompleted with Cancelled=true for BOTH a user pause/stop and an internal abort (e.g. timeout). Disambiguate by the status we set before calling the engine: if it's already Paused/Stopped it was the user; a cancel while still Running = real failure → mark Failed.

• "File already exists" is NOT a failure (FileExistPolicy=IgnoreDownload, the app default): when the target already exists the engine skips the download — it SendDownloadCompletionSignal(Stopped) (so DownloadFileCompleted arrives Cancelled=true, Error=null) and never fires DownloadStarted. That used to be misread as a timeout failure. The manager now calls TryMarkAlreadyExists in the cancelled branch: if DownloadManager.LooksAlreadyDownloaded(policy, path) (policy==IgnoreDownload && the resolved file exists on disk), it backfills name/folder/size from that file and marks the row Completed with DownloadItemViewModel.AlreadyExisted=true (StatusText → State_Exists "Already downloaded"; still IsCompleted, green bar). The final path comes from (e.UserState as DownloadPackage)?.FileName (the event's userState IS the DownloadPackage) or vm.Download.Package.FileName. AlreadyExisted is reset in Start. No new enum state was added (would ripple through filters/converters) — it's a Completed row with a display flag.

• Queued-item file names: the engine only resolves the name once a download starts, so queue-capped items show no name. UrlResolver.ResolveFileNameAsync (Content-Disposition → URL path) fills a VM-only PreviewName in the background; don't write it to DownloadItem.FileName or it gets forced on the engine.

• Integration test pattern: spin up a loopback HttpListener with Range/206 support and download through a real DownloadService — no external network, CI-safe (see IntegrationTests).

• UI progress coalescing (perf — main-thread budget): do NOT marshal each engine DownloadProgressChanged to the UI (with N downloads × M connections that floods the dispatcher and makes the grid lag). Handlers call vm.StageProgress(...) (plain fields, any thread, no UI touch); a single DispatcherTimer in DownloadManager (EnsureUiPump, 250 ms) flushes all rows via vm.FlushProgress() and fires StatsChanged once per tick. The pump self-stops when no row is Running. FlushProgress drops staged values unless Status==Running, so a paused row keeps its last fill. This bounds main-thread work regardless of download count — keep it; don't re-add per-event Dispatcher.UIThread.Post.

• Queue concurrency cap — single choke point: Start(vm) is the uncapped primitive and must only be reached via PumpQueue. Every user-facing start path (Resume, Retry, StartAll, bulk StartSelected → Resume, Add(autoStart), completion's TryStartNextInQueue) must re-queue the item (set Status=Created) and call PumpQueue, which starts/resumes only while running < MaxConcurrent. PumpQueue handles both Paused (resume in place) and Created/None (start fresh), paused first. Regression to watch: making Resume/StartAll call Start directly bypasses the cap (e.g. select 10 with cap 2 → all 10 ran). Start sets Status=Running synchronously before its first await, so PumpQueue's running recount is correct mid-loop.

• Cap value lives on DownloadQueue.MaxConcurrent, but the user sets it via Settings (DownloadSettings.MaxConcurrentDownloads). These are TWO fields — MaxConcurrentDownloads historically only seeded new queues, so changing it never limited anything (the real bug behind "I set max 2 but 10 ran"). They're now kept in lockstep for the primary/default queue (Config.DefaultQueue = Queues[0]): SettingViewModel.MaxConcurrentDownloads setter writes it through to DefaultQueue.MaxConcurrent + PumpQueue; DownloadManager.Initialize re-syncs the default queue from the setting on load (fixes stale saved configs); and the Queues page (QueueRowViewModel.MaxConcurrent) mirrors edits of the default queue back into the setting. Extra (non-default) queues keep their own caps. So enforcement reads queue.MaxConcurrent, but the default queue's value always equals the Settings number.

• State transitions must be guarded in the manager, not just the buttons: per-row buttons gate via IsVisible/Can*, but bulk actions (StopSelected→Cancel, StartSelected→Resume) apply to every selected row regardless of state. So the guards live in DownloadManager (the single choke point that all callers — buttons, bulk, scheduler, pump — go through):

  • Pause no-ops unless Running.
  • Cancel (= "Stop") acts on Running/Paused and queued (Created/None) → all become Stopped; it no-ops only for terminal/idle states (Completed/Failed/already-Stopped). Stopping the queued rows too is essential: otherwise stopping the running rows fires DownloadFileCompleted→TryStartNextInQueue and the pump immediately starts the next queued rows ("select all → Stop: 3 stop, 3 start"). The StopSelected loop runs synchronously before any completion callback is posted, so by the time the pump runs there are no queued rows left to start. (Do not restrict Cancel to Running/Paused only — that reintroduces the bug.)
  • Resume/Start no-op if Running/Completed; Retry only acts on Failed/Stopped. Prevents re-running a completed download from 0% and stray double-Start (a second engine reporting from 0% → "100% then begins again from 0"). Keep state-machine rules in the manager methods, not scattered across VMs/views.

• StartQueue must re-queue Stopped/Failed: PumpQueue only picks up Paused/Created/None, so StartQueue/StartAll must first flip Stopped (and Failed, for StartQueue) rows to Created — otherwise "Start queue → " after a Stop/Stop-all does nothing (rows are Stopped). StartQueue does this in a RunBatch then pumps.

• Completed rows always show 100%: don't compute a completed row's bar from Downloaded/Size — a file that already existed on disk is Completed with Downloaded=0, and that read 0% (esp. after restart). The DownloadItemViewModel ctor forces _progress=100 when Status==Completed, the Status setter sets Progress=100 on transition to Completed, and the already-exists handler persists Downloaded=fileLength.

• Status badge colors live in Converters/StatusToBrushConverter: Running teal, Completed green, Failed red, Paused amber, Stopped neutral-gray, Queued steel-blue (#4F6D9C — deliberately distinct from Stopped's gray so a waiting vs stopped row is tellable apart). Badge shows for every state except Running (which shows live %); DownloadItemViewModel.ShowStatusBadge = Status != Running.

• Queues page = a real queue manager (Views/QueuesView.axaml, ViewModels/QueuesViewModel.cs): per-queue card shows live aggregate stats (RunningCount/WaitingCount/DoneCount/FailedCount, TotalSpeedText, SummaryText) + a combined OverallProgress bar (average of item Progress), a run/pause ToggleSwitch, the concurrency cap, and the queue's downloads with per-item progress + pause/resume/retry/cancel/remove + reorder (ChevronUp/Down → manager.MovePriority(vm, ±1)) + move-between-queues (a MenuFlyout of QueueMoveTargets → manager.MoveToQueue(vm, queueId), hidden when only one queue). Rows are wrapped in QueueItemViewModel (holds the real DownloadItemViewModel as Item + the reorder/move commands); the card's Items is an ObservableCollection<QueueItemViewModel> rebuilt on ListChanged (order = master Items order = pump priority), and aggregates refresh on both ListChanged and StatsChanged (live). QueueRowViewModel.Detach() unsubscribes both events. Pump order follows master-list order, so MovePriority just Items.Moves past the same-queue neighbour. Initialize now backfills QueueId=DefaultQueue.Id for items saved without one (older configs) so they always appear on a queue. DownloadItemViewModel.FormatBytes is now public static for reuse.

System tray / startup / auto-update (Round 11) — patterns worth caching

• Tray (Services/TrayService, static): create TrayIcon in code and register via TrayIcon.SetIcons(Application.Current, new TrayIcons { icon }). NativeMenuItemToggleType does NOT exist in this Avalonia 12 — don't use ToggleType/IsChecked on NativeMenuItem; reflect state by swapping the item's Header ("Disable/Enable notifications"). Wrap creation in try/catch — headless/no-session platforms throw; on failure leave _tray=null so close-to-tray fails soft. Tray menu not showing on Linux (Ubuntu GNOME/AppIndicator) — two real causes: (1) Do NOT subscribe TrayIcon.Clicked — on SNI/AppIndicator the icon has no separate "activate", the primary click opens the context menu, so a Clicked→ShowWindow handler swallows the click and the menu never appears. The menu's "Open" item is the way back from the tray. (2) Use a SMALL tray icon (downscale to 64×64 via Bitmap.CreateScaledBitmap) — the 1080×1080 app PNG is a ~4.6 MB pixmap over DBus and can make the SNI item render while its menu fails to attach. Both fixed for v1.4.x. Linux tray menus are NOT verifiable in the headless test box — needs on-device confirmation.
• Close-to-tray: handle window.Closing, e.Cancel=true; window.Hide() — but gate on TrayService.IsActive, NOT the setting, or a failed tray strands the window with no way back. Real quit sets a _quitting flag then window.Close() (ShutdownMode is OnMainWindowClose → App.ShutdownRequested still saves). Wired in MainViewModel.SetupAppShell() after config loads (needs View as Window).
• Run-at-startup (Services/StartupService): no extra deps — Windows via reg.exe add/query/delete HKCU\...\Run (avoids Microsoft.Win32.Registry package on the non-windows TFM), Linux ~/.config/autostart/downloader.desktop, macOS ~/Library/LaunchAgents/*.plist. Launches with --minimized; MainViewModel hides the window at startup if that arg is present AND tray active. Coupling lives in SettingViewModel: disabling tray disables startup; enabling startup enables tray.
• Auto-update (Services/UpdateService + UpdateFlow): version compare uses Assembly.GetName().Version (CurrentVersion = Major.Minor.Build), NOT InformationalVersion (that has the date-derived revision and would never compare sensibly to a v1.1.0 tag). Versioning fix (#update-false-alarm, 2026-06-19): VersionPrefix is now the FULL 3-part semver (e.g. 1.1.2) and AssemblyVersion=$(VersionPrefix).0 so the app reports its real patch — the old major.minor.0.0 pin made it always report x.y.0, so every patch release (e.g. v1.1.1) looked "newer" forever → false "update available". release.yml stamps -p:VersionPrefix=<tag-without-v> from the tag so a released build reports exactly the tag; About card (SettingViewModel.AppVersion) shows UpdateService.CurrentVersion so About + update status + release tag all agree. Keep VersionPrefix three-part. UpdateService.IsNewer(tag, current) + Normalize(tag) are pure/tested. Flow: GitHub releases/latest → if newer, in-app actionable toast (NotificationService.ShowAction, click = accept) → download the per-RID asset (ExpectedAssetName() matches release.yml names) via a throwaway DownloadService → ApplyDownloadedArchive spawns a detached unix .sh/win .cmd that waits for the PID to exit, extracts over the app dir, relaunches → UpdateFlow.RequestShutdown (= MainViewModel.Quit). The self-swap is untestable here; only the version logic has tests.
• Notification click action: NotificationService.ShowAction(title,msg,onClick) uses the in-app WindowNotificationManager toast (the native paths can't carry a click); always in-app, ignores the on/off switch (it's an actionable prompt).

Avalonia 12 UI patterns (Round 11)

• Rounded window corners (now 10px, all three windows): set Window Background="Transparent" + TransparencyLevelHint="Transparent", move the real background onto the root Border with CornerRadius="10" ClipToBounds="True". The root border's Background MUST be an opaque resource — ThemeBackgroundColor is NOT defined by the Fluent theme here, so it resolved to nothing and the transparent window showed the desktop/window behind through dialogs. Use {DynamicResource SystemRegionColor} (what MainWindow uses). Caveat: on Linux WMs without a compositor the corners/shadow vary — accepted.
• Per-fragment colors in the details strip (#7): give ChunkProgressViewModel a stable IBrush Brush from a curated palette indexed by Index (no reshuffle on update), and bind the segment ProgressBar Foreground="{Binding Brush}" (the plain-track+fill ProgressBar's fill is its Foreground). Palette stays within one blue→teal family (deep blue → sky → cyan → teal), not a rainbow — author preference.
• Theme-aware README images: GitHub honors <picture><source media="(prefers-color-scheme: dark)" srcset="…dark.png"><img src="…light.png"></picture> — dark shot in dark mode, light otherwise. Needs both light+dark captures (added a settings-light.png capture alongside the dark one). GitHub renders .svg images referenced from markdown, so the README banner is a hand-authored docs/banner.svg (no PNG rasterizer needed; use web-safe font-family so text renders through camo).
• Notification success icon: Linux notify-send -i emblem-default (green check) for success, dialog-error (red) for failure — don't use dialog-information (blue "i") for a completed download (#3).
• Icon inside a TextBox: <TextBox.InnerLeftContent><PathIcon .../></TextBox.InnerLeftContent> (search = SearchRegular, link = LinkRegular, both added to Icons.axaml).
• Nav count pill on a selected (accent-filled) item: the selected nav sets descendant text white via TextElement.Foreground, which made the pill number invisible on the light pill. Fix with a more-specific style: Button.nav.selected Border.pill → opaque white bg, Button.nav.selected Border.pill > TextBlock → accent foreground (a style setter on the TextBlock beats the inherited attached value). Pills also get Margin="8 0 0 0".
• Linux taskbar icon: set X11PlatformOptions.WmClass = "Downloader" in Program.cs and make the installed .desktop StartupWMClass=Downloader match — that's what makes the DE use our icon instead of a generic/host (e.g. IDE) one. A raw ELF can't carry a file-manager icon; the .desktop from scripts/install.sh provides it.

Round 15 patterns (shutdown-on-complete, queue buttons, granular notifications, browser, i18n, icon)

• Dynamic MenuFlyout of runtime items: bind MenuFlyout ItemsSource="{Binding Targets}" + an ItemContainerTheme ControlTheme TargetType=MenuItem x:DataType=<wrapper> BasedOn="{StaticResource {x:Type MenuItem}}" with Header/Command setters. The wrapper is a tiny { string Name; ICommand Command } built in the VM. Live examples: QueueActionTarget (Start/Stop queue buttons in DownloadsView) and QueueMoveTarget (move-to-queue in QueuesView). Don't try to bind a generated MenuItem's Command back to the page VM — its DataContext is the item.
• All-downloads-complete + shutdown-on-completion: DownloadManager raises AllDownloadsCompleted once when a completion drains the list (ActiveCount==0 && QueuedCount==0 && CompletedCount>0), guarded by _allCompleteFired (re-armed in Start). CRITICAL: the trigger must only fire when a download actually COMPLETED, never on a stop/cancel/fail — else "Stop All" (which cancels rows → Stopped) would arm a shutdown whenever a finished item sits in the list. The terminal handler routes through FinishTerminal(vm) which calls MaybeAllCompleted() only if (vm.Status == DownloadStatus.Completed). Test seams RaiseCompletedForTest/RaiseStoppedForTest both go through FinishTerminal. MainViewModel.OnAllDownloadsCompleted does the UI/OS parts (all-complete notification + ShutdownService.Schedule) so the manager stays UI/OS-free + testable.
• ShutdownService (the cancel UX matters): shows a Topmost standalone ShutdownView countdown dialog (ShutdownViewModel, 30 s, "Cancel" + "Shut down now" + Esc=cancel) — a top-level window so it's visible even when the app is minimized to the tray (an in-app WindowNotificationManager toast is NOT, since its host is the hidden main window — don't use it here). It ALSO fires a native OS notification (NotificationService.Notify, prefers notify-send/osascript) as a heads-up when NotifyOnShutdown is on. The dialog is always shown (it's the safety/cancel mechanism); notify only gates the extra native alert. Power-off (shutdown /s / osascript … shut down / systemctl poweroff) has a PowerOffOverride test seam.
• Granular notifications: master EnableNotifications gates inside NotificationService.Notify; per-event toggles (NotifyOnComplete/Failed/AllComplete/Shutdown) are checked in the manager / MainViewModel before calling NotificationService (they read _config.Settings live). Settings UI: a "NOTIFICATIONS" card with sub-toggles IsEnabled="{Binding EnableNotifications}".
• StopAll now cancels every Running/Paused/queued item (→ Stopped) via Cancel (was: pause running). Cancel already guards terminal states, so completed/failed rows are untouched.
• Browser integration (Services/BrowserIntegrationService, opt-in, default off): HttpListener on http://127.0.0.1:15151/, permissive CORS, reads ?url=; OnUrlCaptured → MainViewModel.CaptureUrl surfaces the window + opens Add pre-filled. Parse the query manually (don't pull in System.Web). App side only — the extension ships separately.
• Test seams for OS/engine side-effects: give production code an override so tests don't hit the network/OS — ShutdownService.PowerOffOverride (Action), DownloadManager.RaiseCompletedForTest(vm) (post-completion bookkeeping without a real download). In completion tests set config.DefaultQueue.IsRunning=false so PumpQueue doesn't kick off background (network) starts.
• Adding a UI language: add new LanguageOption(code,name) to Localizer.Languages + create Assets/i18n/{code}.json (auto-embedded by AvaloniaResource Include="Assets\**"). Only en.json strictly needs every key (fallback); full packs carry all keys. Bulk-add new keys to existing locales with a small python3 json script (object_pairs_hook=OrderedDict, json.dump(…, ensure_ascii=False, indent=2)). Shipped locales (16): en, fa, es, fr, ar, eo, tr, az, de, it, pt, ru, hi, zh, ja, ko.
• Linux app icon (a raw ELF can't carry one): scripts/install.sh fetches downloader.png from the repo raw URL when the tarball lacks it, installs to hicolor/{512,256,128}x*/apps + ~/.local/share/pixmaps, then gtk-update-icon-cache -f. publish.sh + release.yml also copy Assets/downloader.png into the linux tarball so future installs find it locally. .desktop keeps Icon=downloader + StartupWMClass=Downloader.

Round 16 patterns (About dialog, donate, grid toolbar, time-left, browser extension)

• About dialog: Views/AboutView + ViewModels/AboutViewModel, opened via DialogHelper.ShowAbout() (own Window, transparent+rounded like DownloadDetailsView, Esc closes). Left = logo/title/version/donate/website; right = three clickable Button.about section cards + GitHub/Telegram/Email contact Button.icons. All links open with Process.Start(UseShellExecute=true). Canonical links are consts on AboutViewModel (RepoUrl/EngineRepoUrl/DonateUrl/TelegramUrl/Email…) so they're testable without constructing the VM (its VersionText touches Localizer → needs headless). Original layout — never name or clone another download app (repo design rule).
• Top-bar Donate(♥)/About(i): small Button.icons in MainWindow top bar; MainViewModel.DonateCommand opens AboutViewModel.DonateUrl (repo Donate.md), ShowAboutCommand → DialogHelper.ShowAbout. Tether/Liberapay addresses live in repo-root Donate.md (sourced from the sibling ../Downloader README).
• Square toolbar buttons (Button.tool in App.axaml): icon-on-top/label-below (vertical StackPanel), :disabled → Opacity .4. Per-row bulk actions (Start/Pause/Stop/Remove) pass an IObservable<bool> canExecute (this.WhenAnyValue(x => x.HasSelection)) so they grey out when nothing is checked; Stop-All / Start-Queue / Stop-Queue take no canExecute (always enabled).
• Tri-state select-all in the grid header: bool? SelectAllState on DownloadsViewModel (true=all / false=none / null=some). GOTCHA: this Avalonia 12 DataGrid does NOT render a control placed in a column header — only string Header="..." shows; a <DataGridTemplateColumn.Header><CheckBox/></...> (any control, even a plain TextBlock) renders blank, regardless of compiled-vs-ReflectionBinding. So the select-all CheckBox is overlaid over the first column's header band: it's a sibling of the DataGrid inside the wrapping Panel, HorizontalAlignment=Left VerticalAlignment=Top Margin="14 9 0 0", with the DataGrid pinned to ColumnHeaderHeight="38" and the checkbox column Width=44 CanUserResize=False so the overlay stays aligned. Bound normally (page DataContext) since it's outside the column scope. Keep selection state live by subscribing to each row's PropertyChanged (IsChecked) + manager.Items.CollectionChanged. There is NO toolbar select-all checkbox.
• Toolbar acts on selected rows = checked OR highlighted: the bulk buttons enable when a row is either checked or highlighted in the DataGrid. The view's SelectionChanged pushes grid.SelectedItems into DownloadsViewModel.SetGridSelection(...); SelectedTargets() = Items.Where(IsChecked || _gridSelection.Contains(i)); HasSelection drives the commands' WhenAnyValue canExecute. (Headless screenshot capture can't reproduce real row-selection — a click reads as hover — so verify this via a unit test calling SetGridSelection, not a screenshot.)
• Time-left column: DownloadItemViewModel.TimeLeftText = remaining ÷ Speed (only while Running), formatted by public static FormatDuration(double seconds) ("45s"/"1m 23s"/"2h 5m"; "—" for non-finite/idle). Re-raised from the Speed and Status setters.
• State → only the progress bar recolors: bind ProgressBar.Foreground="{Binding Status, Converter=StatusToBrushConverter}" and show StatusText ("62% · Paused") under it. The row name keeps one consistent style across states (removed the old TextBlock.failed/.pending name classes + the colored badge) — author preference.
• Browser extension lives at src/browser-extension/ (NOT a .NET project, excluded from build/tests): cross-browser MV3, manifest.json (Chrome/Edge, background.service_worker) + manifest.firefox.json (background.scripts + gecko id). background.js guards importScripts (if (typeof importScripts === "function")) so the same file works as a Chrome SW (imports common.js) and a Firefox event page (manifest loads common.js first). It does context menus + webRequest.onHeadersReceived media sniffing (video/audio/HLS .m3u8; YouTube/DRM unsupported) + forwards to the app via GET http://127.0.0.1:15151/add?url=…. The app listener answers /ping (200) for the popup's status dot. Resize icons with Pillow (Image.LANCZOS) — no ImageMagick on this box. Store deploy is the author's (needs dev accounts); Safari intentionally skipped.

Round 17 patterns (CI flake, single-instance, Telegram-update, snap, queue scroll)

• Tests that read Localizer MUST be [AvaloniaFact] (in AppTests), not plain [Fact] (in LogicTests). The i18n maps only load under the Avalonia headless runtime (AssetLoader); a plain Fact gets the raw key back (e.g. "State_Pending" instead of "Pending") and is order-dependent → flaky on CI (it passed only if an AvaloniaFact had loaded assets first). Start such a test with Localizer.Instance.Load("en"). This was the cause of the intermittent macOS CI failures.
• Single instance + IPC (Services/SingleInstanceService, called first thing in Program.Main): a fixed loopback lock-port (SingleInstanceService.LockPort = 15150 — moved from 15152, see next note) doubles as the mutex.
• The single-instance lock port MUST stay OUTSIDE LocalApiService.PortRange (15151–15155). It was 15152 — inside the API range — so the app's own single-instance lock permanently held 15152 and the API's fallback silently skipped it (verified live: with 15151 blocked the API landed on 15153, not 15152). Moved LockPort to 15150. Invariant guarded by test SingleInstance_lock_port_is_outside_the_api_range. If you ever change either the range or the lock port, keep them disjoint. LockPort is a public const (exposed for that test). First instance binds it (primary) + runs an accept loop; a later launch fails to bind → forwards its args (the first http(s) URL) to the primary and returns from Main (exits). MainViewModel.SetupAppShell calls SetMessageHandler(...) → BringToFront() + CaptureUrl(msg). Only SocketError.AddressAlreadyInUse means "secondary"; other bind errors fail open (run normally). This is the cross-platform replacement for the Windows named-mutex + WM_COPYDATA trick.
• Telegram-style auto-update (Services/UpdateFlow, stateful): check → auto-download in background → on ready, show a persistent "Update Downloader" button at the bottom of the nav rail (MainViewModel.IsUpdateReady + ApplyUpdateCommand) AND a native system notification (NotificationService.Notify, not an in-app toast). The swap is applied on app exit via App.DesktopOnShutdownRequested → UpdateFlow.ApplyPendingOnExit(), so clicking the button (which quits) OR just closing the app both install it; close-to-tray is bypassed when UpdateFlow.IsReady. Settings shows live download progress then a "Restart to update" button. All UpdateFlow state changes marshal to the UI thread — the old bug was calling quit from a background ConfigureAwait(false) continuation, which hung the window + close button. Disabled under snap (UpdateFlow.IsManagedExternally ⇐ SNAP env).
• Snap (snap/snapcraft.yaml, core22 + extensions: [gnome], strict confinement): the part is plugin: dump over the pre-published publish/linux-x64 self-contained single-file (built by scripts/build-snap.sh / .github/workflows/snap.yml), organize: { Downloader: bin/Downloader }; stage-packages: libicu70, libssl3 (gnome ext provides the rest). Desktop+icon live in snap/gui/. The Store / snap info icon needs a top-level icon: snap/gui/downloader.png key (or a file literally named snap/gui/icon.png) — the .desktop Icon= line only sets the launcher icon, not the Store icon (fixed in b5d00a1). The Store icon must be ≤512×512 — snap/gui/downloader.png is the 512×512 Assets/downloader512.png (the 1080×1080 Assets/downloader.png was rejected by the Store for size; fixed in fb53047). Version stamped from snap/local/VERSION via an adopt-info nil part. Single-file extraction under strict confinement: the single-file build self-extracts native libs (libSkiaSharp.so …) to ~/.cache/dotnet_bundle_extract by default, but the home interface DENIES hidden dot-dirs like ~/.cache → Failure processing application bundle … Error code: 13 (EACCES) and the app never opens. Fix = apps.downloader.environment.DOTNET_BUNDLE_EXTRACT_BASE_DIR: $SNAP_USER_COMMON/.dotnet_bundle_extract (snapd expands $SNAP_USER_COMMON; always writable). Fixed in b289fd8. Snaps auto-update via the Store, so the in-app updater self-disables under SNAP. Publishing needs the author's snapcraft login (or a SNAPCRAFT_STORE_CREDENTIALS repo secret for CI auto-publish).
• Browser-extension store packaging: scripts/build-extension.sh makes two zips from src/browser-extension — Chrome/Edge (uses manifest.json) and Firefox (swaps in manifest.firefox.json as manifest.json). Listing copy + step-by-step submission in PUBLISHING.md; PRIVACY.md is the required privacy-policy URL. Store submission needs the author's dev accounts.
• Queue page ScrollViewer: set HorizontalScrollBarVisibility="Disabled" so cards stay within the viewport (they overflowed behind the window when narrow), and put the page padding on the inner content's Margin (NOT ScrollViewer.Padding) so the bottom gap is part of the scroll extent and the last row is reachable at scroll end.
• Stop vs Pause a queue: PauseQueue only pauses running items (the Queues-page Run/Pause toggle); StopQueue (toolbar "Stop queue") cancels every running/paused/queued item → Stopped. Two distinct manager methods.

Packaging / publish

• macOS must NOT use single-file/compression (PublishSingleFile/EnableCompressionInSingleFile/IncludeNativeLibrariesForSelfExtract). On Apple Silicon the compressed bundle crashes the first time a managed assembly is loaded — inflate hits a "(Data Abort) byte write Translation fault" → FailFastIfCorruptingStateException → abort()/SIGABRT (seen as a crash on Start download, when the Downloader engine assembly is first bound). Fix: macOS publishes plain --self-contained true (loose assemblies + dylibs); make-macos-app.sh already copies the whole publish dir into Downloader.app/Contents/MacOS, so the apphost rename (Downloader.Desktop→Downloader) still works. Windows/Linux keep single-file+compression (they work). Applied in both release.yml and scripts/publish.sh (gated on osx-*).
• Self-contained, dependency-free single file: dotnet publish -r <rid> --self-contained true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true (the last flag is required so Skia/native libs are bundled). Validated ~49 MB ELF.
• The output binary is Downloader.Desktop[.exe] (= project name). Renaming the file to Downloader is safe — avares://Downloader.Desktop/... uses the embedded assembly name, not the file name, so don't change AssemblyName (that WOULD break every avares URI).
• CI/release live in .github/workflows/ (dotnet-desktop.yml = build+test on push/PR, release.yml = matrix publish on v* tag → creates the GitHub Release for the tag and attaches zip/tar.gz). Local: scripts/publish.sh [rid ...].
• winget: the package identifier MUST be Publisher.Package (winget rejects a bare name), so it stays bezzad.Downloader. To let users run the short winget install downloader, add Moniker: downloader to the locale manifest — don't try to rename the identifier. Submitting to microsoft/winget-pkgs (no wingetcreate on Linux): fork (gh repo fork), sync the fork's master (gh api -X POST repos/<you>/winget-pkgs/merge-upstream -f branch=master), create a branch, PUT the 3 manifests under manifests/b/bezzad/Downloader/<ver>/ via the Contents API, then gh pr create --repo microsoft/winget-pkgs. The PR auto-validates (Azure pipeline) then waits on a community moderator to merge; the CLA is already signed for bezzad. scripts/release.sh does this automatically (submit_winget) each release and is dedup-safe — ALWAYS check gh pr list --repo microsoft/winget-pkgs --author @me for an existing open PR before opening another (we once stacked a 1.1.0 + 1.3.3 dup; close the older one). Installer manifest = InstallerType: zip + NestedInstallerType: portable (the win zip ships Downloader.exe at its root).
• Release matrix RIDs: win-x64, linux-x64, osx-x64, osx-arm64 (only macOS ships both arches; Windows/Linux are x64-only). Versioning — VersionPrefix is the full 3-part semver in the csproj (currently 1.1.2); release.yml overrides it from the tag (-p:VersionPrefix=<tag-without-v>). To release: bump VersionPrefix to the new 3-part version, ensure green + pushed, then git tag vMAJOR.MINOR.PATCH && git push origin <tag> (tag must equal VersionPrefix). NOTE this repo currently releases off develop (the working branch), not main. softprops/action-gh-release creates the Release if absent; re-running needs the tag + Release deleted first.

Avalonia 12 gotchas worth caching

• DataGrid cell focus/current border: there is NO named FocusVisual/CurrencyVisual element in v12. The current/focus outline is on an unnamed template Border; kill it with DataGridCell:current /template/ Border + DataGridCell:focus /template/ Border → BorderThickness=0/BorderBrush=Transparent (and Rectangle Stroke for safety). Focusable=False does NOT remove it. Full-row selection highlight comes from the Fluent theme's :selected default.
• DataGrid grouping kills row virtualization → janky scroll/UI past ~10 rows. Keep the DataGridCollectionView flat (no GroupDescriptions) for performance.
• DataGrid.FontSize does NOT cascade to cell/header content — setting it on the <DataGrid> has no visible effect on rows. To resize cell text: set FontSize on each template-column TextBlock, set FontSize on DataGridTextColumn (it has its own), and/or add scoped styles DataGrid.Styles → Selector="DataGridCell TextBlock" and "DataGridColumnHeader TextBlock".
• Single-line TextBox strips newlines on paste (AcceptsReturn=false), merging pasted multi-line input. For multi-URL paste, set AcceptsReturn="True" + a KeyDown handler that fires the action on Enter (Shift+Enter = newline).
• To intercept Enter on an AcceptsReturn="True" TextBox you MUST use the TUNNEL phase, not a bubble KeyDown=. The TextBox inserts the newline in its own bubble-phase key handler which runs first and marks the event Handled, so a bubble-phase XAML KeyDown="…" handler never fires (bug: "Enter just adds a new line" in the Add dialog's clipboard-suggestion accept). Fix = code-behind box.AddHandler(KeyDownEvent, OnKey, RoutingStrategies.Tunnel) (tunnel runs root→target before the TextBox's bubble handler; set e.Handled=true there). Headless-testable: view.Show() + focus the box + view.KeyPress(Key.Enter, RawInputModifiers.None, PhysicalKey.Enter, "\r") (from using Avalonia.Headless;); find named controls in tests via GetVisualDescendants().OfType<T>().First(t => t.Name == "…") — FindControl<T> is not available cross-assembly in Avalonia 12.
• Reveal-a-file-in-folder cross-platform: Windows explorer /select,"path", macOS open -R path, Linux dbus-send … org.freedesktop.FileManager1.ShowItems array:string:file://path string: (fallback: open the directory). For an in-progress row the final file doesn't exist yet — the engine writes <name>.download — so OpenContainingFolder reveals the final file if present, else <final>.download, else just opens the folder (completed rows already selected correctly).
• Custom window chrome: ExtendClientAreaChromeHints was removed in Avalonia 12 (compile error AVLN2000). Use only ExtendClientAreaToDecorationsHint="True" + ExtendClientAreaTitleBarHeightHint="-1", then draw your own bar (see Views/TitleBar). OS resize/snap still works. Drag = host.BeginMoveDrag(e) on left-button PointerPressed; get the window via TopLevel.GetTopLevel(this) as Window.
• All three windows (MainWindow, AddDownloadItemView, DownloadDetailsView) use TitleBar; dialogs set ShowMinMax="False".
• CanResize="True" is NOT enough to edge-drag-resize these windows — they set WindowDecorations="None" (+ transparent rounded chrome), which removes the OS resize border, so CanResize only drives maximize/restore. To get edge/corner dragging you MUST wrap the root border in a <Panel> and add <v:ResizeGrips /> as the last child (an 8-zone transparent overlay in Views/ResizeGrips; it resizes manually via pointer-capture + Window.Position/Width/Height because Window.BeginResizeDrag is a no-op on macOS for borderless windows). MainWindow + DownloadDetailsView already had it; a resizable dialog WITHOUT ResizeGrips silently only maximizes (the resizable-persisted-dialog-sizes regression: Add-link + PageDialog were missing it). Any new custom-chrome resizable window needs this overlay.
• Esc-to-close dialogs: with WindowDecorations="None" there's no native close-on-Esc. Override OnKeyDown on the dialog window and Close() on Key.Escape (see DownloadDetailsView). A focused TextBox doesn't swallow Esc, so the window-level override is enough.

Build / run / test

dotnet build Downloader.Desktop.sln                                   # 0 warnings / 0 errors expected
dotnet run  --project Downloader.Desktop/Downloader.Desktop.csproj    # launch the GUI (needs a desktop session)
dotnet test Downloader.Desktop.Tests/Downloader.Desktop.Tests.csproj  # all tests (foldered: Unit/ Integration/ UI/ Plugins/ + Plugins/Hls/)

Headless smoke check (no display interaction): timeout 10 dotnet run --project Downloader.Desktop/Downloader.Desktop.csproj — a clean 10s run (SIGTERM/143) with no exceptions means it launched OK. Note: empty-list startup does NOT exercise row/file-kind icons.

Regenerate README screenshots

A gated headless test renders real PNGs to docs/screenshots/ (home-dark, home-light, settings-dark):

DLDESKTOP_CAPTURE=1 dotnet test Downloader.Desktop.Tests/Downloader.Desktop.Tests.csproj --filter FullyQualifiedName~CaptureScreenshots

Then verify the PNGs by viewing them. Capture uses the real App with .UseSkia().UseHeadless(UseHeadlessDrawing=false).

Architecture (where things live)

• Services/DownloadManager (DI singleton IDownloadManager): owns the master ObservableCollection<DownloadItemViewModel>, builds engine DownloadService instances, coalesces engine progress onto the UI via the shared EnsureUiPump DispatcherTimer (see perf note above), enforces queue concurrency through PumpQueue, runs the DispatcherTimer scheduler, raises StatsChanged/ListChanged.
• ViewModels/: MainViewModel (nav rail, filters, status bar, autosave, sidebar collapse), DownloadsViewModel (filterable DataGridCollectionView + multi-select bulk actions), DownloadItemViewModel (live row: progress/speed/status/FileKind/error), QueuesViewModel, SchedulerViewModel, SettingViewModel (full engine options), AddDownloadItemViewModel (multi-URL), DownloadDetailsViewModel (per-connection parts).
• Models/: Config (persisted), DownloadSettings (all engine options + ToConfiguration()), DownloadItem, DownloadQueue, DownloadSchedule.
• Views/ axaml + Converters/FileKindToIconConverter. App-wide styles/theme palettes in App.axaml; icon geometries in Assets/Icons.axaml.
• Persistence: Services/FileService → JSON at %AppData%/Downloader/config.json (Linux ~/.config/Downloader). Saved on shutdown + autosaved every 20s.

Conventions / gotchas

• Filename auto-resolve: pass only URL+folder to the engine when the user gives no name; read the resolved name from DownloadStartedEventArgs.FileName (NOT IDownload.Filename, which stays empty).
• DataGrid bindings: DataGridTextColumn.Binding must use {ReflectionBinding ...} (compiled bindings resolve against the page VM); template columns set x:DataType.
• New icon geometries are parsed at runtime — validate by adding to the converter/icons and relying on the headless geometry tests, or by viewing a screenshot.
• Tests: xUnit v3 (don't add v2); [assembly: AvaloniaTestApplication] is in namespace Avalonia.Headless; the test csproj must be SelfContained=true with RuntimeIdentifier=$(NETCoreSdkPortableRuntimeIdentifier) because the app project is self-contained.
• Shutdown save uses .Wait() on the UI thread — keep ConfigureAwait(false) on the save path to avoid deadlock.
• Keep each commit green (build + tests). Commit messages end with the Co-Authored-By line. Don't reference other download-manager apps anywhere — this is an original design.

See CLAUDE.md at the repo root for product vision, locked decisions, and the full roadmap.

Snap publishing (done — downloader is live on the Snap Store)

• Store name downloader is registered to bezzad (public); latest/stable carries the release. Publisher login: snapcraft whoami (token expires 2027-06). Verify: snapcraft status downloader / snap info downloader.
• Do NOT build the snap locally on this dev box with --destructive-mode: the host is Ubuntu 26.04 (resolute) but the snap targets base: core22 (22.04). Destructive mode fetches stage-packages (libicu70, libssl3) from the host archive, which 26.04 doesn't have → "Stage package not found: libicu70". A real build needs an isolated core22 env (LXD/multipass, both need sudo) or just use CI.
• Easiest publish path = reuse the CI-built .snap: the Snap workflow (.github/workflows/snap.yml) builds correctly via snapcore/action-build (clean core22) and uploads a downloader-snap artifact on every v* tag. To publish: gh run download <id> -n downloader-snap then snapcraft upload --release=stable downloader_<ver>_amd64.snap (uses the local login; ~processing 1-2 min → "released to 'stable'").
• CI auto-publish caveat (fixed): the publish step runs only on refs/tags/. The v1.3.1 run built+uploaded the artifact but died at "Attach snap to the GitHub Release" (Resource not accessible by integration — default GITHUB_TOKEN can't update a Release another workflow created), which skipped "Publish to the Snap Store". Fixed by continue-on-error: true on the attach step + always() && … on the publish step. Re-running an OLD tag run won't pick up the fix (tag runs use the workflow at the tag commit) — the fix applies to the next tag. The SNAPCRAFT_STORE_CREDENTIALS repo secret is already set (from snapcraft export-login).
• Never commit snap-creds.txt (the export-login token) — gitignored, along with *.snap and parts/ stage/ prime/.
• In-app updater self-disables under snap (SNAP env) — the Store handles updates.

Round 18 patterns (themes/accent, selection, tray threading, numeric, flags)

• Accent picker (Light/Dark + accent): Services/ThemeService holds Accents (Teal/Blue/Purple/Green/Amber) and ApplyAccent(key) overrides the Fluent accent color resources at the Application level — SystemAccentColor + SystemAccentColorLight1/2/3 + Dark1/2/3 (shades computed by mixing toward white/black) — which beats the per-theme palette Accent and recolors every {DynamicResource SystemAccentColor} consumer (nav selection, accent buttons, links, pill) in both themes. ThemeService.Apply(config) sets the variant + accent together; call it at startup (MainViewModel) and on Reset. Persisted as DownloadSettings.AccentColor. Status colors stay semantic (NOT accent-driven). Selected accent VM: SettingViewModel.SelectedAccent/Accents with a swatch+name ComboBox (AccentOption.Brush).
• Selected-row contrast (#row-select): the Fluent default fills a selected DataGrid row with the SOLID accent → dark text becomes unreadable. Fix in App.axaml DataGridCell:selected: Background={DynamicResource RowSelectionBrush} (a translucent accent, alpha ~0.28, kept in sync by ThemeService.ApplyAccent) + Foreground={DynamicResource SystemBaseHighColor} (normal text). Verify by programmatically selecting grid.SelectedIndex=1 in CaptureScreenshots (a headless click only reads as hover) → home-selected-{dark,light}.png.
• Tray/relaunch "does nothing" = wrong thread: SingleInstanceService.Dispatch runs on the background TCP accept thread and TrayIcon.Clicked can fire on a DBus thread; calling window.Show()/Activate() off the UI thread silently no-ops (and the off-thread throw can wedge the tray event pipeline, plausibly killing the right-click menu too). Both now marshal via Dispatcher.UIThread.Post (Dispatch wraps _onMessage; TrayService.ShowWindow wraps its body + a topmost flip). Linux tray menu behavior is DE-specific and NOT verifiable headlessly — keep both _tray.Menu (right-click) and _tray.Clicked→ShowWindow (left-click); the menu's "Open" is the reliable restore.
• NumericUpDown empty → null crash: clearing a NumericUpDown sets Value=null, which a binding to a non-nullable int/long setting can't convert → a "value cannot be null" validation error in the view. Behaviors/NumericCoerce.EmptyToMinimum (attached prop, enabled globally by a NumericUpDown style in App.axaml) snaps an empty box back to its Minimum. Covers Settings/Queues/Details numerics at once.
• Interrupted downloads load as Stopped: DownloadManager.Initialize normalizes BOTH saved Running AND Paused → Stopped (a live/paused server connection can't survive a restart). Terminal states (Completed/Failed/Stopped) are kept.
• Language flags: Assets/flags/{code}.png (auto-embedded by AvaloniaResource Include="Assets\**"), generated by a one-off PIL script (no SVG rasterizer on this box). LanguageOption.Flag lazy-loads the bitmap via AssetLoader (null if missing). Picker ComboBox shows <Image Source="{Binding Flag}">+name. Mapping: en→US, pt→Brazil, ar→UAE, eo→Esperanto star, fa→green/white/red Iran tricolor WITH a simplified gold Lion & Sun emblem (this line previously said "no emblem" — that was stale/wrong; the shipped asset has always carried the emblem, see the "Round 19" flag note below — never the official Sun&Lion/takbir version, just a crude sun-disc+lion silhouette). New i18n keys only strictly need en.json (others fall back to English).

Round 19 patterns (queue-stuck bug, update redesign, flags, banner, release notes)

• "Start just queues, never downloads" (1.3.2/1.3.3 regression): DownloadQueue.IsRunning is persisted and PumpQueue early-returns when !IsRunning. Since every per-item start (Resume/Retry, row button, bulk) funnels through PumpQueue, a queue saved with IsRunning=false (after Stop-queue / Pause-queue) silently swallows all starts — items sit as Created ("Queued") until the scheduler's StartQueue flips IsRunning=true. Fix: an explicit user start calls EnsureQueueRunning(queueId) (sets IsRunning=true) before PumpQueue. Don't remove the IsRunning gate from PumpQueue itself — completion's TryStartNextInQueue still needs it so a paused queue doesn't auto-advance. Regression test: Start_runs_item_even_when_its_queue_was_paused.
• Removing a queue deactivates its schedules: RemoveQueue now disables (Enabled=false) + unbinds (TargetQueueId=null) any Schedules pointing at it, so the scheduler can't act on a deleted target. Test: Removing_a_queue_deactivates_its_schedules.
• Auto-update is now user-initiated (was Telegram-style silent auto-download): UpdateFlow gained an Available state + PromptUpdate callback (wired in MainViewModel → DialogHelper.ShowUpdatePrompt). CheckAsync no longer auto-downloads — it raises Available and shows the in-app UpdatePromptView (Download / Later, modeled on ShutdownView: Topmost, Esc=Later). StartDownloadAsync() runs only on Download (so the Settings progress bar is actually seen). Settings button flows Check → Download update (Available) → Restart to update (Ready). The "invisible progress" was because the old flow downloaded silently at startup.
• Update restart relaunch: the Unix swap script (UpdateService.WriteUnixScript) now trap '' HUP + relaunches via setsid (fallback nohup) so the NEW app runs in its own session and isn't torn down with the old process group — that detachment is what makes "restart to update" actually relaunch. (Self-swap still can't be tested headlessly.)
• Flag rendering (PIL, ~30×20): real 5-point star() polygons (not dots) for the US canton; Korea taeguk = full red circle → blue bottom-semicircle → left small circle red + right small circle blue (the S-curve) + 4 corner trigram bars — without the two small circles it looks like Japan's disc. Iran (per author's reversal) = green/white/red + a simplified gold Lion & Sun emblem on the white stripe (sun disc+rays + crude lion silhouette); a detailed emblem isn't legible at this size.
• Flags are SVG now (Assets/flags/{code}.svg), NOT PNG (author request 2026-07-04, superseding the PIL/PNG notes above): hand-authored vector SVGs (viewBox 90×60), rasterized at load time by Localizer.RenderSvg via the Svg.Skia 5.1.1 package — the Avalonia-independent core (Avalonia.Svg.Skia has NO Avalonia-12 build, but plain Svg.Skia only needs SkiaSharp ≥3.119.2 and Avalonia.Skia 12.0.4 ships 3.119.4). LanguageOption.Flag stays a Bitmap so the XAML is unchanged: SKSvg.Load → scale to 45px height (3x the 22×15 display) → SKSurface → PNG-encode → Avalonia Bitmap. fa.svg embeds the author's provided Lion & Sun (Naval flag of Iran) JPEG as a base64 <image> data URI (resized 360×240) — do NOT redraw it procedurally; SKSvg renders embedded raster images fine. eo now has the correct GREEN Esperanto star (the old PNG had red); az the real 8-point star. Preview SVGs on macOS with qlmanage -t -s 300 -o <dir> <files>. Test Every_language_has_a_loadable_flag asserts non-null + 45px height for all 16.
• README docs/banner.svg: embed the real app icon as a base64 data:image/png <image> (SVG2 plain href, NOT xlink:href) so GitHub renders it — don't hand-draw a stand-in logo. Source PNG = Assets/downloader512.png.
• Release notes MUST be pretty Markdown (CLAUDE.md release routine): one-line summary + emoji section headers (### ✨ New / ### 🐛 Fixes / ### 🔧 Under the hood), short end-user bullets, no commit hashes. Backfill empty/plain releases with gh release edit <tag> --notes-file. Good examples on GitHub: v1.0.0 / v1.1.0 / v1.2.0. CI gotcha: never put generate_release_notes: true on release.yml's matrix action-gh-release steps — 4 concurrent creates race → tag_name already_exists and one asset (osx-x64) fails to upload (bit v1.4.0). A single post-build notes job fills auto-notes only if the body is empty instead.

Plugin system (Phase 1 — foundation) — patterns

• SDK assembly: src/Downloader.Desktop.Plugins.Abstractions (net10.0, nullable on) holds ONLY interfaces + POCO types — the stable surface external plugins reference. App + tests reference it via ProjectReference. Design: docs/plugins-architecture.md. Pipeline = Resolve (ILinkResolver) → Transfer (ITransferProvider/ITransfer) → Post-process (IPostProcessor); a plugin implements only the phases it needs (IDownloaderPlugin.Initialize(IPluginContext) registers contributions).
• Loader: Services/PluginManager (DI singleton, UI-free → unit-testable). Loads each plugin DLL in a collectible AssemblyLoadContext + AssemblyDependencyResolver. Critical: the load context MUST return null for the Downloader.Desktop.Plugins.Abstractions assembly name so it resolves from the host → shared type identity (else IsAssignableFrom/is IDownloaderPlugin fails). AssemblyDependencyResolver method is ResolveAssemblyToPath (not ResolveAssemblyPath). Only ENABLED plugins' contributions are returned by FindResolver/FindPostProcessor/FindTransferProvider/ResolveAsync. Disabled ids persist in Config.DisabledPlugins. Plugins live in PluginManager.PluginsRoot (~/.config/Downloader/plugins).
• Plugin projects set <EnableDynamicLoading>true</EnableDynamicLoading> (emits the deps.json the ADR needs) and reference Abstractions with <Private>false</Private><ExcludeAssets>runtime</ExcludeAssets> (don't ship a 2nd SDK copy). Example: samples/Downloader.Desktop.SamplePlugin.
• TDD: PluginTests.cs (plain [Fact], in-process fakes) covers register/route/enable-disable/idempotency/safe-missing-dir, PLUS a real external-DLL load — the test csproj builds the sample plugin and stages its DLL into <testout>/plugins-sample (MSBuild StageSamplePlugin target + ReferenceOutputAssembly=false ProjectReference), and the test asserts LoadFromDirectory loads it. This validates the ALC + shared-SDK identity end-to-end.
• UI: Views/PluginsView + ViewModels/PluginsViewModel — nav (MANAGE) → Plugins; lists installed plugins (name/version/author/description + enable toggle), Install (file picker → copy DLL to PluginsRoot → reload) + Open-folder. DialogHelper.OpenFilePicker(title,filterName,ext) added.
• NOT YET (Phase 2): the download-pipeline integration (JobCoordinator + multi-part download + the ITransfer refactor so the queue/UI drive torrent/HLS uniformly) and the official HLS (yt-dlp+ffmpeg)/torrent plugins. PluginManager.ResolveAsync is the ready hook.

Round 20 patterns (no-left-nav UI, dialogs, update fixes, expired-link, plugin docs)

• NO left nav rail anymore. The main view is ALWAYS DownloadsView. Queues/Scheduler/Settings open as dialogs via Views/PageDialogView (generic Window host with its own DataTemplates + StyledProperties Page/PageTitle, Esc-closes) → DialogHelper.ShowPage(vm, title). Nav buttons live in the DownloadsView toolbar (group 3) and bind to MainViewModel through the window: Command="{Binding $parent[Window].((vm:MainViewModel)DataContext).ShowQueuesCommand}". The status filters (All/Active/Completed/Failed) were dropped (search-box only); MainViewModel still has the now-unused filter commands/flags — harmless. The "Update Downloader" ready button moved to the top bar. Plugins are NOT a top-level page — they're a collapsible Expander ("Sec_Plugins") in SettingView, hosting PluginsView (which had its outer ScrollViewer removed to be embeddable) bound to SettingViewModel.Plugins.
• Capture gotcha: management pages are dialogs now — render them in CaptureScreenshots via new PageDialogView(vm.Queues, "Queues").Show() (Show, NOT ShowDialog, or the headless capture blocks), then Close().
• Auto-update macOS restart loop: the old swap extracted Downloader.app INTO Contents/MacOS (nesting) and relaunched the OLD binary → re-detect → loop. UpdateService.WriteMacScript now replaces the whole .app bundle (appDir=<bundle>.app/Contents/MacOS → bundle = appDir/../..) and relaunches via open. NOTE: an update FROM a buggy build still uses that build's broken swap — the fix only helps updates initiated from a fixed build (tell users to manually install once to break the loop). Unverifiable headless.
• Update cancel + version: UpdateFlow.CancelDownload() (CancellationTokenSource in DownloadAsync; cancel → back to Available). Settings shows a × (DismissRegular) on the progress bar + AvailableVersionText ("vX.Y.Z available", from UpdateFlow.AvailableTag).
• Expired-link detection: DownloadManager.Start captures vm.PreAttemptSize = item.Downloaded>0 ? item.Size : null (the known size BEFORE progress events overwrite vm.Size, which writes through to _item.Size). On a successful completion, ExpiredLinkHeuristic(known, finalBytes) (pure, tested) flags a RESUME that finished at <half the known size as Failed ("re-add with a fresh link") instead of Completed. finalBytes from (e.UserState as DownloadPackage)?.ReceivedBytesSize ?? vm.Download?.Package?.ReceivedBytesSize.
• Stop All vs Stop icon: were identical (StopRegular square). Stop All now uses StopAllRegular (a solid octagon stop-sign). Added DismissRegular (×) too.
• Plugin developer docs: docs/writing-plugins.md (how to write/build/install a plugin). The sample samples/Downloader.Desktop.SamplePlugin is now GitHub Releases (com.bezzad.github-releases) implementing ALL interfaces (resolver = repo→latest asset; IPostProcessor = .sha256 sidecar; ITransferProvider = file:// copier). The integration test loads it and checks the GitHub resolver + file:// transfer.

Plugin SDK refinements (naming + logging)

• IMediaResolver → ILinkResolver, MediaPart → DownloadPart (author: the app downloads any file, not just media). PartKind (Combined/Video/Audio/Segment/Subtitle) stays — it's a post-processing hint, default Combined.
• Logging is Microsoft.Extensions.Logging.ILogger, NOT a custom Log(string). IPluginContext.Logger is an ILogger (the SDK references Microsoft.Extensions.Logging.Abstractions). PluginManager's context builds it via AppLog.Factory.CreateLogger($"plugin:{id}"). CLAUDE.md Conventions now mandates ILogger everywhere (engine/app/plugins → one log via AppLog.Factory).

UX batch 4 patterns (footer filters, plugin install feedback, settings sizing, corrupted-resume)

• Footer status pills double as the list filter. The orphaned StatusFilter enum + Show{All,Active,Queued,Completed,Failed}Command + Is*Selected flags + *FilterCount (left over from the removed nav rail) are now reused by clickable footer buttons in MainWindow.axaml (Button.filterpill style + Classes.active="{Binding Is*Selected}"; accent fill when active). Filters are disjoint: Active=Running/Paused, Queued=Created/None, Completed, Failed=Failed/Stopped, All. Counts (ActiveFilterCount etc.) match each bucket exactly and are re-raised in OnStatsChanged/RaiseNavFlags. To add a filter: enum value + DownloadsViewModel.Matches case + command/flag/count + footer button.
• File pickers must parent to DialogHelper.ActiveWindow, not MainWindow. Management pages (Settings/Queues) are modal dialogs; opening a picker from the background MainWindow opens behind the modal / fails on some Linux WMs. ActiveWindow = AppLifetime.Windows.LastOrDefault(w => w.IsActive) ?? MainWindow. OpenFilePicker now uses it.
• Plugin Install must give feedback (it silently swallowed failures → "nothing happened"). PluginsViewModel.InstallAsync now diffs _manager.Plugins before/after and shows an always-on in-app toast: installed plugin name / "no plugin in that file" / the exception. Use NotificationService.Inform(title,msg,isError) (added) — it always shows the in-app toast regardless of the notifications on/off switch (direct action feedback). Also copies the .deps.json sidecar next to the DLL so plugins with their own deps resolve (the sample has none, so a bare DLL still loads — proven by Loads_a_real_external_plugin_DLL_from_disk).
• Settings double-border: wrap nothing extra around an Expander — the Plugins section was Border.card > Expander (two borders); a bare <Expander> matches the Advanced section. Right-hand inputs: ComboBox.ctrl/TextBox.ctrl set Width=148 Height=34 MinHeight=34 to line up with the global NumericUpDown (MinHeight=34, .ctrl Width 148). Proxy is a single-line Grid ColumnDefinitions="Auto,*" (label left, box fills) not a label-over-box StackPanel.
• ExpiredLinkHeuristic → LooksCorruptedAfterResume (author spec): a first-time download finishing small is FINE (never flagged — PreAttemptSize is null when item.Downloaded==0); only a RESUME (PreAttemptSize>0) that finishes smaller than the known size is flagged → Failed with a "file looks corrupted / incomplete" message (threshold is < knownSize, not < knownSize/2). Same PreAttemptSize capture + ReceivedBytesSize read as before.

Drag-to-reorder rows (main grid)

• 6-dot grip = first column of DownloadsView (left of the select-all checkbox). Dragging a row reorders the master Items list = queue pump priority (same ordering the Queues-page chevrons drive). Dropping onto a row in another queue moves the dragged item into that queue (adopts the target's QueueId).
• Manager: DownloadManager.ReorderTo(vm, target, placeAfter) (on IDownloadManager) — Items.Move to the drop index (decrement when source was above target), adopt target's QueueId if different (+ vm.RaiseQueueNameChanged()), NotifyList(), then PumpQueue the old and new queues. Keep MovePriority (±1) for the Queues page. DownloadsViewModel.Reorder(...) just forwards to the manager (code-behind calls it).
• Row VM: DownloadItemViewModel.QueueName is computed live from _manager.Queues by _item.QueueId (no manual sync); RaiseQueueNameChanged() re-raises it after a cross-queue move.
• Queue column: shown only when DownloadsViewModel.ShowQueue (Queues.Count > 1, re-raised in Refresh()). An x:Name on a DataGridColumn does NOT generate a code-behind field (CS0103) — find it instead via Root.Columns.FirstOrDefault(c => c.SortMemberPath == "QueueName") and set IsVisible from code-behind (subscribe to the VM's PropertyChanged for ShowQueue).
• Avalonia 12 drag-drop API changed: DataObject/DragDrop.DoDragDrop/DragEventArgs.Data are obsolete. DataTransfer/DoDragDropAsync exist but the OS drag session renders NO moving visual on Linux/X11 — the row never appears to follow the cursor. We no longer use OS DragDrop here (see "Sticky drag ghost" below); only ReorderTo/Reorder/placeAfter = e.GetPosition(row).Y > row.Bounds.Height/2 are kept.
• Adding the grip column shifted the overlaid select-all checkbox: its Margin went 14 9 0 0 → 42 9 0 0 (28px grip + 14px).

Sticky drag ghost (manual pointer drag — replaces OS DragDrop)

• Why: Avalonia's OS DragDrop.DoDragDropAsync shows no moving adorner on X11, so the picked-up row didn't visibly follow the pointer. The fix is a hand-rolled pointer-capture drag with a floating ghost — this is the only way to get "row sticks under the cursor" here.
• Overlay: a <Canvas x:Name="DragOverlay" IsHitTestVisible="False" ClipToBounds="False" /> is the last child of the Panel wrapping the DataGrid (so the ghost paints above rows).
• Ghost = a Border (opaque SystemRegionColor bg, accent border, BoxShadows.Parse("0 6 18 0 #50000000"), Opacity ~0.92, IsHitTestVisible=False) whose Child is a Border{ Background = new VisualBrush(sourceRow){ Stretch=None, AlignmentX=Left, AlignmentY=Top } } — i.e. a live snapshot of the dragged DataGridRow. Size it to sourceRow.Bounds.
• Flow (all in DownloadsView.axaml.cs, grip Border wires PointerPressed/Moved/Released/CaptureLost):
  • Press: find source DataGridRow, add dragging class, build the ghost, Canvas.SetLeft/Top it to the row's position translated into DragOverlay space (row.TranslatePoint(new Point(0,0), DragOverlay)), record _ghostGrabY = e.GetPosition(row).Y, e.Pointer.Capture(grip).
  • Move: Canvas.SetTop(ghost, e.GetPosition(DragOverlay).Y - _ghostGrabY) (keep X fixed); highlight the row under the pointer via Root.InputHitTest(e.GetPosition(Root)) → FindAncestorOfType<DataGridRow>(includeSelf:true) → droptarget class (skip the dragged row itself).
  • Release: RowAt(pointer) → if a different row, pageVm.Reorder(_dragRow, target, placeAfter); then ClearDrag() (remove ghost from overlay, drop both classes, null fields), e.Pointer.Capture(null).
  • CaptureLost: also ClearDrag() (covers Esc / focus steal).
• Gotcha: VisualBrush(sourceRow) re-renders the row's live appearance — if you also dim the source with Opacity, the ghost dims too. We keep the source's dragging class subtle for that reason; don't crank source opacity down.
• DataGridRow.droptarget/.dragging styles still live in DownloadsView.axaml DataGrid.Styles.

Drag-reorder follow-up (cursor, highlight, queue label visibility)

• AddQueue MUST NotifyList() — without it the main grid's DownloadsViewModel.ShowQueue is never re-raised, so the per-row Queue column stays hidden even after adding a 2nd queue (RemoveQueue already notified; AddQueue didn't — that was the "I can't see the queue name" bug).
• Drag cursor = Cursor="SizeNorthSouth" (vertical ↕) on the grip Border (not SizeAll).
• Queue shown in the details dialog: DownloadDetailsViewModel.HasQueue (= Item.QueueName non-empty) gates the queue display. It's inline on the Status line (one row): Status 62% · Stopped | Queue main — a multi-column Grid with a thin Border separator + Det_Queue label + Item.QueueName, all three gated by HasQueue, with Size/Speed still right-aligned. (Was a separate line below; author wanted it on the status line.)

UX batch 5 patterns (focus-aware notifications, copyable toasts, add-dialog resolve, expired link, sample plugin)

• Avalonia here is 12.0.4, NOT 11.x (csproj wins over Directory.Build.props's AvaloniaVersion=11.0.2). Two 12-specific gotchas hit this batch: (a) IClipboard.SetTextAsync moved to an extension Avalonia.Input.Platform.ClipboardExtensions.SetTextAsync(this IClipboard, string) — using Avalonia.Input.Platform; or it won't compile. (b) The rich toast overload WindowNotificationManager.Show(object content, NotificationType, TimeSpan?, Action onClick, Action onClose, string[] classes) does exist in 12 — pass a custom Control as content to get a fully custom toast (the card hosts your visual; type still colors it, onClick makes the card clickable).
• Clipboard READ in Avalonia 12: there is NO IClipboard.GetTextAsync() — the read method is the extension Avalonia.Input.Platform.ClipboardExtensions.TryGetTextAsync(this IClipboard) (returns Task<string>, null if nothing/denied). IClipboard itself only exposes SetDataAsync/TryGetDataAsync/TryGetInProcessDataAsync/ClearAsync/FlushAsync; text/bitmap/file helpers are all ClipboardExtensions (SetTextAsync, TryGetTextAsync, TryGetBitmapAsync, …). Same extension class as the write path.
• Focus-aware notification routing (NotificationService): one channel per message by focus. AppFocused (default true = gentler in-app when unknown) is set from window.Activated/Deactivated wired in MainViewModel.SetupAppShell() (SetFocused(window.IsActive) + the two events). Notify → focused: in-app; unfocused/tray: native OS (fallback to in-app only if no native channel, e.g. Windows). All passive callers already funnel through Notify/NotifyCompleted/Failed/AllCompleted, so routing is centralized — don't add per-call channel logic. Hiding to tray fires Deactivated (IsActive=false) so tray messages correctly go to the OS.
• Actionable prompts when unfocused (ShowAction, e.g. update available): send a plain OS notification now AND enqueue (title,message,onClick); SetFocused(true) flushes the queue by re-showing the clickable in-app toast — so the action is never lost. Focused ⇒ in-app actionable immediately.
• Copyable/custom in-app toast = BuildToast(...) returns a Border (severity stripe) → StackPanel with SelectableTextBlock title+message (selectable satisfies "let me copy the text") + a Copy button (_topLevel.Clipboard.SetTextAsync($"{title}: {message}")) + an optional action button. The action button (not card-onClick) handles ShowAction so it doesn't conflict with the in-content Copy button.
• Add-dialog single-link name/size pre-resolve (AddDownloadItemViewModel): on Urls change, TriggerResolve() — debounce Task.Delay(600, cts.Token) then UrlResolver.ResolveFileInfoAsync(url, Settings.ToConfiguration()) → RemoteFileInfo (.FileName string + .FileSize long, FileSize≤0 = unknown). Per-keystroke CancellationTokenSource; only apply if the input is still that exact single link and _userTypedName is false (the Filename setter tracks user typing so resolve never clobbers it; resolve writes _fileName via RaiseAndSetIfChanged(ref _fileName, …, nameof(Filename)) to bypass the setter). IsFilenameEnabled = !IsMultiple disables (not hides) the name box for multi-link adds; size hint row is IsVisible=IsSingleLink + Resolving/HasSizeText. Unknown size → engine downloads single-part natively (no app code needed — RangeDownload needs a known size + range support).
• Expired/anti-bot link detection (DownloadManager): pure LooksExpiredOrInvalid(string head, long bytes) — flags a "completed" download that's small (≤512KB) AND looks like markup (head trimmed/lowercased starts-with <!doctype html/<html/<?xml or contains <head/<body/<title). Wrapper IsExpiredOrInvalidLink sniffs the first 1KB of the saved file (path from (e.UserState as DownloadPackage)?.FileName); checked in the success else branch of DownloadFileCompleted, before marking Completed → sets Failed + Localizer.Instance["Error_LinkExpired"]. Sits alongside LooksCorruptedAfterResume/LooksAlreadyDownloaded (same pure-helper + completion-branch pattern). Genuine small non-markup files are not flagged.
• Sample plugin "not a Downloader plugin" root cause was the sample wasn't in Downloader.Desktop.sln → dotnet build never produced a fresh DLL, so users installed a stale/absent one. Fix = dotnet sln add ../samples/Downloader.Desktop.SamplePlugin/...csproj. The loader + source were already current (the green Loads_a_real_external_plugin_DLL_from_disk test, which builds+stages the sample via the test csproj StageSamplePlugin target, proves it). If "install does nothing/errors" recurs, suspect a stale DLL on disk, not the SDK.

UX batch 6 patterns (queue menu refresh, combo padding, name tooltip)