Merge pull request #754 from Euterpe-org/dev

Release 2.0.0

Author: KARPED1EM

.claude/CLAUDE.md

@@ -0,0 +1,31 @@
+# Euterpe
+
+Avalonia desktop app. Projects under `src/`:
+
+- `Euterpe` — the app: one `Features/<Name>/` folder per feature, holding only views, viewmodels and view-specific code (converters etc.); `Shell/` for app-level windows.
+- `Euterpe.Abstractions` — service interfaces.
+- `Euterpe.Contracts` — wire contracts: any request/response DTO serialized to or from an external API belongs here.
+- `Euterpe.Controls` — reusable Avalonia controls and the app theme. `Themes/EuterpeTheme.axaml` is generated at build time — edit the per-control/per-style files, never the generated file.
+- `Euterpe.Core` — service implementations under `Services/`.
+- `Euterpe.Generators` — Roslyn incremental source generators, driven by the marker attributes in `Euterpe.Shared`.
+- `Euterpe.Localization` — localized `.resx` string tables: `XAML` for view text, `Interaction` for code-side messages.
+- `Euterpe.Models` — app-internal models, DTOs, enums and records (types that cross the network go in `Euterpe.Contracts` instead).
+- `Euterpe.Shared` — dependency-free utilities referenced across projects: attributes, collections, extensions, threading helpers, constants.
+- `Euterpe.Tasks` — custom MSBuild build tasks (e.g. generating `EuterpeTheme.axaml`).
+- `Euterpe.Updater` — standalone console app that applies a downloaded update after the main app exits.
+
+Tests under `tests/` (TUnit):
+
+- `Euterpe.Generators.Tests` — source generator tests, snapshot-verified with Verify (`snapshots/`).
+- `Euterpe.Headless.Tests` — anything that needs running Avalonia UI (controls, views, bindings, input, theming) on Avalonia.Headless.
+- `Euterpe.Tests` — plain unit tests; folders mirror the source projects (`App/` = `src/Euterpe`, plus `Core/`, `Models/`, `Shared/`, `Contracts/`).
+
+## Workflow
+
+- Never push to a remote (`jj git push` / `git push`) — commit locally at most; the user reviews and pushes themselves.
+
+## Rules
+
+- C#: @.claude/rules/csharp.md
+- Tests: @.claude/rules/tests.md
+- XAML: @.claude/rules/xaml.md

.claude/rules/csharp.md

@@ -0,0 +1,58 @@
+# C# Rules
+
+## Design
+
+- Design the change, don't just complete the feature: a working implementation that leaves tech debt is not acceptable. If every viable approach leaves debt, the module itself is due for a redesign — surface that instead of bolting on.
+- Build along the known extension axes; this app already paid for assuming a single game (the `[PerGame]`/game-scope rework when multi-game support arrived). Ask "what varies when the next game/variant arrives" before hardcoding, and keep game-specific state and services game-scoped.
+
+## Language & APIs
+
+- Use the newest C# syntax and BCL APIs the repo's `LangVersion`/TFM allows (`field` keyword, `extension` members, collection expressions, span/`IFormatProvider` overloads) — never an older equivalent out of habit; the newer API is usually the better-optimized one.
+- When several APIs solve the same problem, pick the best-performing one for the concrete situation (allocations, lookup cost, parse overloads) — deliberately, not first-that-works.
+
+## Naming & comments
+
+- Method and variable names must be self-explanatory; if a name needs a comment to be understood, rename it (e.g. `PlayingFolderName`, not `CurrentlyPlaying` + a comment).
+- When a name is hard to settle, mirror an existing name in this project first; with no precedent, follow the general .NET/community convention for that concept (how the BCL or well-known libraries name it).
+- No narration comments: never comment what the code does, where it came from, or why a change is correct.
+- The only acceptable comment is a single short line stating a constraint the code cannot show (threading requirements, external library quirks). No multi-line essays.
+- No XML doc comments on members whose name already says everything.
+
+## Async
+
+- Never wrap an async call chain in `Task.Run`. If the chain has real awaits (file I/O, network), it does not block the caller. `Task.Run` is only justified to push genuinely synchronous blocking work (e.g. synchronous audio decode) off the UI thread.
+- `ConfigureAwait(false)` on every await outside UI-bound continuations; use `Dispatcher.UIThread` explicitly when touching UI-bound state afterwards.
+
+## Code organization
+
+- Where a type belongs is defined by the project map in CLAUDE.md.
+- Values derivable from a model are computed properties on the model itself (see `ChartDto.SizeDisplay`, `BpmDisplay`, `DifficultyBadges`), not static helper classes or converter wrappers.
+- Large types split into `Name.Topic.cs` partial files.
+- Service layout: the suffix-less `<Service>.cs` holds only the public interface implementation. Everything else lives in partials — `<Service>.Private.cs` when the helpers are few, `<Service>.<Topic>.cs` (`.Core`, `.Import`, ...) when there is enough to split by topic.
+- Private helper types are nested inside the owning partial class file, not separate top-level types.
+
+## Services & notifications
+
+- Toast notifications live in core services, not viewmodels. Worker methods return results; the public method notifies per granularity: single operation = per-item toast, bulk operation = one summary toast. Never add a notification-suppress flag.
+- Bulk methods return a count so an explicit UI action can toast "nothing to do" (silent no-op stays correct for automatic startup paths).
+- No redundant wrapper services or pass-through methods: put the method on the existing domain service and make the real method public.
+- File/IO primitives go through `IFileSystemService` (`Try*` pattern); never raw `Directory`/`File` calls with ad-hoc try/catch in services.
+
+## Localization
+
+- During development add the neutral `.resx` plus `zh-Hans`/`zh-Hant` only — those are the locales the user can read and test with, and keys may still churn while the feature settles. The remaining locales get batch-translated once the feature is final.
+- Pick the table by where the text is shown, not by who assigns it: `XAML` = presentation-surface text (labels, titles, descriptions, button captions, and inline status/progress shown inside a page/panel — even when set from a viewmodel or core service, e.g. `MelonLoader_State_Downloading`, `Setup_Step_Failed`, `Setup_Progress_*`); `Interaction` = transient interaction surfaces (message boxes, toast notifications, OS file/folder pickers). So "code-side messages in `Interaction`" below means dialog/notification text, not every code-set string; a core service reads an `XAML` value via `XAML.Key` (Core imports only `static Interaction`, so add `global using Euterpe.Localization;` there).
+- Keys are `Name_Action_State` segments, scoped by where the text belongs:
+  - Page/panel-scoped view text: `<PanelName>_<Element>` (`ChartManage_SortBy`, `Setting_Title_Language`).
+  - Self-identifying concepts, especially enum members: `<TypeName>_<Member>` (`ChartDifficulty_Easy`, `ChartSortField_MapCount`, `ModFilterType_All`) — never borrow another feature's key because the value happens to match today.
+  - Code-side messages in `Interaction`: `<Kind>_Content_<Domain>_<Action>_<State>` (`Notification_Content_Chart_UpdateAll_Success`, `MessageBox_Content_SetPathEnvironment_Windows`).
+- Keep `.resx` data entries alphabetically ordered — merge new keys into place, never append at the end.
+
+## Misc
+
+- Deduplicate shared one-liners into a single home (e.g. `ChartFiles.MapName`), even tiny ones.
+- Before writing anything by hand, check the packages already referenced (`Directory.Packages.props`) for an existing facility — especially the easily-forgotten ones: CommunityToolkit.Mvvm's `[NotifyPropertyChangedFor]` for dependent properties instead of manually raising `OnPropertyChanged`, R3 `Observable`s for event wiring/composition instead of manual event handlers.
+- Prefer an existing library over hand-rolling, but verify its actual behavior (decompile if needed) before adopting or rejecting it.
+- Logging via ZLogger interpolation (`Logger.ZLogInformation($"...")`).
+- DI: `public required T Name { get; init; }` properties inside `#region Injections`.
+- `.cs` files end with exactly one trailing newline (`insert_final_newline` applies to `[*.cs]` only).

.claude/rules/tests.md

@@ -0,0 +1,22 @@
+# Test Rules
+
+All C# rules apply to test code too; the rules below are test-specific.
+
+## Placement
+
+- Plain unit test → `tests/Euterpe.Tests`, at the mirrored path of the type under test (`App/` = `src/Euterpe`, plus `Core/`, `Models/`, `Shared/`, `Contracts/`).
+- Anything needing live Avalonia UI (control, view, binding, input, theme) → `tests/Euterpe.Headless.Tests`; inherit `HeadlessTest` and touch UI only inside `RunOnUI`.
+- Source generator test → `tests/Euterpe.Generators.Tests`, snapshot-verified with Verify (`snapshots/`).
+
+## Conventions
+
+- TUnit: `[Test]` methods named `Method_Scenario_Expectation`, assertions via `await Assert.That(...)`; Verify.TUnit for snapshot assertions.
+- TUnit releases fast and its API surface is large (`[Arguments]`, `[MethodDataSource]`, `[ClassDataSource]`, hooks, ...) — don't write TUnit patterns from memory: fetch the docs (https://tunit.dev) to confirm the current idiom for the situation and check it against the version pinned in `Directory.Packages.props`.
+- One `sealed class <Type>Test` per type under test, annotated `[TestSubject(typeof(T))]` and a `[Category]`.
+- A large test class becomes `partial`, split per tested method into `<Type>Test.<Method>.cs` in a folder named after the type (mirrors the `Name.Topic.cs` source convention).
+- Mocks via TUnit.Mocks: `IFoo.Mock()` for interfaces, `Mock.Logger<T>()` for loggers, TUnit.Mocks.Http for HTTP. Build the subject with a `Create<Service>()` helper whose optional parameters default to mocks.
+- Layer invariants (visibility, sealed, namespaces) are enforced by `Architecture/ArchitectureTests.cs` (NetArchTest) — extend it when adding a project or layer rule.
+
+## Running
+
+- Test projects are Microsoft.Testing.Platform executables: `dotnet run --project tests/Euterpe.Tests`; filter with `--treenode-filter "/*/*/<ClassName>/*"`, not `--filter`.

.claude/rules/xaml.md

@@ -0,0 +1,30 @@
+# XAML Rules
+
+## Formatting
+
+- XamlStyler formatting: one attribute per line, attributes alphabetically ordered, two-space comment padding (`<!--  text  -->`).
+- Files are UTF-8 without BOM, LF line endings, no trailing newline (`insert_final_newline = false` for non-`.cs` files).
+
+## Bindings
+
+- Always use compiled bindings: `x:DataType` on the root element and on every `DataTemplate`. The app is `PublishAot`, so reflection bindings break AOT/trimming — never reach for `{ReflectionBinding}` or `x:CompileBindings="False"` to escape a binding that won't compile.
+- When a reusable control's theme `ItemTemplate` is fed item types it can't reference (the control sits below the app), it still needs an `x:DataType` to compile: extract the minimal display contract as an interface in `Euterpe.Controls.Models` (e.g. `IEnumOption { LocalizedString Display { get; } }`), have the app type implement it, and `x:DataType` the interface — do not move the whole app/VM type down into `Euterpe.Controls`, and do not fall back to reflection.
+- Bind directly to model computed properties (`{Binding SizeDisplay}`); do not add a converter for anything derivable from the model — add a property to the model instead.
+- Converters that encode genuine view logic (icons, brushes, multi-input visual state) live in `FuncValueConverters` as static `FuncValueConverter`/`FuncMultiValueConverter` properties.
+
+## Localization
+
+- All user-facing text via `{Localize {x:Static loc:XAMLLiteral.Key}}` — never hardcoded strings.
+
+## Styling
+
+- Prefer Semi theme tokens (`{DynamicResource SemiBlue6}`, `SemiColorText0`, `SecondaryCardColor`, ...) over hardcoded hex. Alpha overlay masks (`#40000000`-style) are acceptable when no token fits.
+- A local property value outranks a style setter: when a pseudo-class (`:pointerover`) must change a property, define both the idle and the pseudo-class value as style setters.
+- Styles reused across views live in `Euterpe.Controls/Themes/ControlStyles/` (one file per control type, e.g. `ButtonStyles.axaml`); any `.axaml` there is picked up by the theme generation automatically — no manual include.
+- A page/panel's own styles stay inline only while small; once they dominate the view file and bury the actual content, extract them to `ControlStyles/Pages/` or `ControlStyles/Panels/` as `<Name>Styles.axaml`.
+- Comments: short section labels or one-line constraint notes only.
+
+## Controls
+
+- Need a new control? Source it in this order: Ursa first, then a mature community package, and only write our own (in `Euterpe.Controls`) when neither fits.
+- Before adopting a community package, vet it: maintenance activity, Avalonia version compatibility, AOT/trimming friendliness — and verify its actual behavior per the C# library rule.