Upgrade WLED.NET JSON API coverage and ergonomics (#15)

* Add roadmap plans for full WLED JSON API coverage

* Plan 0: multi-target net8/9/10 and modernise toolchain

* Plan 1: core value types and enums

* Plan 2: command-value types and fluent state/segment builders

* Plan 3: complete the state object with typed fields and write-only commands

* Plan 4: complete the segment object with colors, effect params and 2D fields

* Plan 5: complete info object and add si/net/live read endpoints

* Plan 6: presets API with list, apply, save and delete

* Plan 7: playlists API with typed entries and parallel-array transform

* Plan 8: per-segment individual LED control with auto-chunking

* Plan 9: effect metadata parsing from /json/fxdata

* Plan 10: config API with safe partial writes and node discovery

* Plan 11: client ergonomics, typed exceptions, cancellation and DI

- Add intent methods (TurnOn/TurnOff/Toggle/SetBrightness/SetColor/SetEffect/SetPalette/Reboot)
- Add CancellationToken to every client method
- Add typed exception hierarchy (WledException + connection/response/version)
- Add HttpClient constructor and Kevsoft.WLED.DependencyInjection AddWledClient
- Add intent, exception and DI tests

* Plan 11: refresh README with feature matrix, add CHANGELOG and modern sample

- Rewrite README around intent methods, fluent builders, DI and error handling
- Add a supported-features capability matrix and document target frameworks
- Add CHANGELOG.md (Keep a Changelog format)
- Rewrite BasicConsole sample to showcase the ergonomic API

* Add WLED JSON API coverage review

* Add plan 12: usability and correctness improvements from review

* Widen transition (transition/tt) from byte to ushort to support 0-65535 range

* Add ranged-random effect/palette selector (Selector.RandomInRange, 'from~tor')

* Widen ColorTemperature Kelvin range to 1000-20000 and add KelvinUnchecked escape hatch

* Fix no-id intent methods to target selected segments via seg object form

Model the state 'seg' field as a union (SegmentPayload) that serializes as either
an object (selected segments) or an array (id-targeted), matching the WLED API.
No-id SetColor/SetEffect/SetPalette now emit the object form instead of an array
that WLED would infer as id:0.

* Add typed config fields for identity mDNS, MQTT and boot defaults

Model id.mdns, if.mqtt (en/broker/port/user/cid) and def (on/bri/ps) as typed
properties while keeping JsonExtensionData as an escape hatch for everything else.

* Update README, CHANGELOG and sample for post-review API changes

* Add plan 13 for device ergonomics and agent guidance

* Add AGENTS.md and typed effect/palette catalogs

Add root AGENTS.md with project conventions, commands and gotchas.
Add EffectCatalog/PaletteCatalog with id/name lookup, reserved-entry
filtering (RSVD/-), and SetEffect/SetPalette catalog-entry overloads.

* Add SelectedSegments fluent update for selected-segment object form

StateUpdate.SelectedSegments(...) targets the selected segments via the
seg object form and accumulates across calls. Mixing it with Segment(id, ...)
in one update throws, since WLED's seg field is one form or the other.

* Add cohesive WLedDevice snapshot via GetDevice()

GetDevice() issues a single GET /json and exposes state, info and typed
effect/palette catalogs as one snapshot, with per-segment effect/palette
resolution and derived helpers (SelectedSegments, ActiveSegments,
SupportsWhiteChannel, etc). Effect metadata is opt-in to avoid extra requests.

* Make effect metadata actionable

Add lookup helpers (FindById/FindByName/Try*) over effect metadata
collections, plus SegmentUpdate.Effect(EffectMetadata) and
ApplyEffectDefaults(EffectMetadata) to set speed/intensity/custom sliders
from metadata defaults (c3 clamped to 0-31).

* Add strong id and range value types

Introduce SegmentId, EffectId, PaletteId, PresetId, PlaylistId,
LedMapId, SegmentBounds and MatrixBounds readonly structs with range
validation, equality and netstandard2.0-safe hashing. Wire SegmentBounds
and MatrixBounds into SegmentUpdate.Range/Range2D and LedMapId into
StateUpdate.LoadLedMap as non-ambiguous overloads.

* Add fluent config update builder

Introduce ConfigUpdate and an UpdateConfig(Action<ConfigUpdate>) client
overload exposing Identity, Mqtt and BootDefaults helpers. Only touched
sections and fields are serialised, reusing the existing network opt-in
guard.

* Document Plan 13 ergonomics features

Add README sections and feature-matrix rows for the device snapshot,
catalogs, selected-segment updates, strong value types and the fluent
config builder; expand the CHANGELOG and BasicConsole sample to match.

* Remove outdated gotchas from AGENTS.md for clarity and conciseness

* Fix Docker build for DependencyInjection project

Copy the Kevsoft.WLED.DependencyInjection csproj and sources so dotnet
restore (which reads the solution) and the build/pack stages succeed.
Build the DI project (transitively building the main library) instead of
globbing multiple csproj into a single dotnet build, and pack each
packable library explicitly. Also align FROM..AS keyword casing.

Author: kevbite

AGENTS.md

@@ -0,0 +1,84 @@
+# AGENTS.md — WLED.NET
+
+Guidance for coding agents (and humans) working in this repository. Read this before
+making changes; it captures the project's purpose, conventions, commands and gotchas so a
+change can be made safely without prior conversation history.
+
+## Project purpose
+
+**WLED.NET** is a strongly typed, hard-to-misuse .NET client for the
+[WLED JSON API](https://kno.wled.ge/interfaces/json-api/). It turns the device's loosely
+typed JSON (`/json`, `/json/state`, `/json/info`, `/json/eff`, `/json/pal`, `/json/cfg`,
+`/json/fxdata`, `/json/nodes`, `presets.json`, …) into expressive C# types.
+
+## Core design principle
+
+> Model things well so they're easy to use. Make it impossible to send the wrong
+> information by how we model the library.
+
+Concretely:
+
+- **Types over primitives.** Prefer value types, enums and command types over raw
+  `int`/`byte`/magic strings (`RgbColor`, `SegmentColors`, `Selector`, `ByteAdjust`,
+  `Toggleable`, `LightCapability` `[Flags]`, the `*Id`/`*Bounds` value types, …).
+- **Validation at construction.** Where WLED documents a range (e.g. `c3` is 0–31, `bri`
+  is 0–255, ledmap is 0–9), the constructing type guards it so an out-of-range value
+  throws *before* it hits the wire.
+- **Read model ≠ write model.** Responses are immutable/total; requests/builders expose
+  only what is settable.
+- **Builders, not nullable bags.** High-level fluent builders (`StateUpdate`,
+  `SegmentUpdate`, `PlaylistBuilder`, `ConfigUpdate`) sit on top of the raw DTOs.
+
+## Repository conventions
+
+- **Dual DTO layer.** Each JSON object is a pair: an immutable `XResponse` (all fields,
+  non-null) and a sparse mutable `XRequest` (nullable fields with
+  `[JsonIgnore(WhenWritingNull)]`), usually with a static `Request.From(Response)` factory
+  and an implicit operator. The wire format never leaks into the public happy path.
+- **`[JsonPropertyName]` always carries the raw WLED key**; the C# member uses a
+  descriptive .NET name (e.g. `EffectId` → `"fx"`).
+- **Every new endpoint** adds a method to `IWLedClient` + `WLedClient`, with GET/POST
+  tests in `test/Kevsoft.WLED.Tests` (extend `JsonBuilder` and `MockHttpMessageHandler`).
+- **Custom `JsonConverter`s** carry the "impossible to misuse" types across the wire and
+  are unit-tested in both directions against realistic WLED payloads.
+- **Unknown keys round-trip.** Config sections use `[JsonExtensionData]` (`Unknown`) so a
+  read-modify-write cycle never drops firmware-specific fields.
+
+## Target frameworks & netstandard2.0 constraints
+
+- The library multi-targets `netstandard2.0;net8.0;net9.0;net10.0`
+  (see `Directory.Build.props`). Tests run on `net8.0;net9.0;net10.0`.
+- Because of `netstandard2.0`, **do not** use:
+  - `Math.Clamp` — clamp manually.
+  - `System.HashCode` — implement `GetHashCode()` with `unchecked` arithmetic.
+  - newer async/Span API shapes that aren't available there.
+- Prefer `readonly struct` + `IEquatable<T>` for small value types.
+
+## Commands
+
+```pwsh
+dotnet build WLED.NET.sln -c Release
+dotnet test  WLED.NET.sln -c Release
+```
+
+## Breaking-change stance
+
+- No `[Obsolete]` compatibility shims unless explicitly requested.
+- Record user-facing and breaking changes in `CHANGELOG.md`.
+- Keep raw `XResponse`/`XRequest` DTOs available as escape hatches even when adding
+  ergonomic builders/value types on top.
+
+## Docs & sample expectations (acceptance criteria)
+
+A feature isn't done when it compiles and tests pass. Also:
+
+1. Update the root `README.md` feature matrix and add/refresh a short usage snippet.
+2. Keep `samples/BasicConsole` exemplary — demonstrate the *ergonomic* path (builders,
+   intent methods, catalogs, snapshots), not raw DTOs.
+3. Update `CHANGELOG.md`.
+
+## Reference material
+
+- WLED JSON API docs: <https://kno.wled.ge/interfaces/json-api/>
+- This repo's `plans/` folder contains the staged roadmap (Plans 0–13) and the conventions
+  every plan must uphold.

CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+This release is a substantial, breaking overhaul that reworks the library to cover the full
+WLED JSON API with a strongly-typed, hard-to-misuse design. Legacy members were removed
+rather than deprecated, so consuming code must be updated.
+
+### Added
+
+- **Multi-targeting** for `net8.0`, `net9.0`, `net10.0` and `netstandard2.0`.
+- **Strong value types and enums** for colours (`RgbColor`, `RgbwColor`, `Color`),
+  brightness/relative adjustments (`ByteAdjust`), toggles (`Toggleable`), selectors and more.
+- **Fluent builders** for state updates (`UpdateState`), segments, playlists and individual LEDs.
+- **Intent methods**: `TurnOn`, `TurnOff`, `Toggle`, `SetBrightness`, `SetColor` (RGB/RGBW),
+  `SetEffect`, `SetPalette` and `Reboot`.
+- **Presets**: read, apply, save and delete (`GetPresets`, `ApplyPreset`, `SavePreset`, `DeletePreset`).
+- **Playlists**: read, start and save (`GetPlaylists`, `StartPlaylist`, `SavePlaylist`).
+- **Individual LED control** with automatic, sequential request chunking (`SetIndividualLeds`).
+- **Effect metadata** parsing from `/json/fxdata` (`GetEffectMetadata`).
+- **Node discovery** via `/json/nodes` (`GetNodes`).
+- **Device configuration** read and safe partial writes via `/json/cfg`
+  (`GetConfig`, `UpdateConfig`); network/access-point changes require explicit opt-in.
+- **Typed exception hierarchy**: `WledException`, `WledConnectionException`,
+  `WledResponseException` (with `StatusCode`/`Body`) and `WledUnsupportedVersionException`.
+- **`CancellationToken`** support on every asynchronous method.
+- **Dependency-injection integration** in a new `WLED.DependencyInjection` package via
+  `services.AddWledClient(...)`, backed by `IHttpClientFactory`.
+- A new `WLedClient(HttpClient)` constructor for DI / `IHttpClientFactory` scenarios.
+
+### Changed
+
+- Requests and responses are now modelled as separate immutable response types and mutable
+  request types, preventing accidental round-tripping of read-only fields.
+- Posting state is now done through intent methods or `UpdateState(...)` rather than mutating
+  and re-posting a response object.
+- **`SetColor`/`SetEffect`/`SetPalette` with no `segmentId` now target the *selected* segments**
+  (the WLED `"seg":{…}` object form) instead of segment 0. The state `seg` field is modelled as
+  a `SegmentPayload` union that serialises as either an object (selected segments) or an array
+  (id-targeted).
+- **Transition values (`transition`/`tt`) widened from `byte` to `ushort`** to support the
+  documented `0–65535` range (~109 minutes) instead of clamping at 25.5 s.
+- **`ColorTemperature.Kelvin` range widened to `1000–20000 K`** to match the docs' forward-
+  compatible guidance, with a new `ColorTemperature.KelvinUnchecked(int)` escape hatch for
+  values outside that range.
+
+### Added
+
+- **Ranged-random effect/palette selection** via `Selector.RandomInRange(from, to)`
+  (the WLED `"from~tor"` token).
+- **Typed device-configuration fields** for `id.mdns`, `if.mqtt` (`en`/`broker`/`port`/`user`/`cid`)
+  and `def` (`on`/`bri`/`ps`), while preserving all other keys through `JsonExtensionData`.
+- **Device snapshot read model** (`GetDevice`) returning a queryable `WLedDevice`/`WLedDeviceSegment`
+  graph from a single `GET /json`, resolving each segment's effect and palette and optionally
+  fetching effect metadata via `DeviceSnapshotOptions.IncludeEffectMetadata`.
+- **Effect & palette catalogs** (`GetEffectCatalog`, `GetPaletteCatalog`) with `FindById`/`FindByName`
+  (and `Try*`) lookups, an `AvailableOnly` view that hides reserved `RSVD`/`-` slots, and
+  `SetEffect`/`SetPalette` overloads that accept catalog entries.
+- **Selected-segment fluent updates** via `StateUpdate.SelectedSegments(...)` (the WLED `"seg":{…}`
+  object form); mixing selected and id-targeted segments in one update throws.
+- **Actionable effect metadata**: collection lookups over `IReadOnlyList<EffectMetadata>`, plus
+  `SegmentUpdate.Effect(EffectMetadata)` and `ApplyEffectDefaults(EffectMetadata)` to seed
+  speed/intensity/custom sliders from metadata defaults.
+- **Strong id and range value types**: `SegmentId`, `EffectId`, `PaletteId`, `PresetId`,
+  `PlaylistId`, `LedMapId`, `SegmentBounds` and `MatrixBounds`, with range validation and
+  overloads on `SegmentUpdate.Range`/`Range2D` and `StateUpdate.LoadLedMap`.
+- **Fluent configuration updates** via `UpdateConfig(Action<ConfigUpdate>)` with `Identity`,
+  `Mqtt` and `BootDefaults` helpers that emit only the sections and fields you touch.
+
+### Removed
+
+- Legacy members were removed outright (no `[Obsolete]` shims). Update to the new API surface.

Directory.Build.props

@@ -4,6 +4,9 @@
         <Copyright>Copyright 2020 Kevsoft</Copyright>
         <Authors>Kevin Smith</Authors>
         <LangVersion>latest</LangVersion>
+        <LibraryTargetFrameworks>netstandard2.0;net8.0;net9.0;net10.0</LibraryTargetFrameworks>
+        <TestTargetFrameworks>net8.0;net9.0;net10.0</TestTargetFrameworks>
+        <SampleTargetFramework>net10.0</SampleTargetFramework>
         <nullable>enable</nullable>
         <ImplicitUsings>enable</ImplicitUsings>
         <GenerateDocumentationFile>true</GenerateDocumentationFile>

Dockerfile

@@ -1,35 +1,38 @@
 ARG VERSION=0.0.0
-FROM mcr.microsoft.com/dotnet/sdk:6.0 AS restore
+FROM mcr.microsoft.com/dotnet/sdk:10.0 AS restore
 WORKDIR /
 
 COPY ./nuget.config .
 COPY ./*.sln .
 COPY ./Directory.Build.props .
 COPY ./src/Kevsoft.WLED/*.csproj ./src/Kevsoft.WLED/
+COPY ./src/Kevsoft.WLED.DependencyInjection/*.csproj ./src/Kevsoft.WLED.DependencyInjection/
 COPY ./test/Kevsoft.WLED.Tests/*.csproj ./test/Kevsoft.WLED.Tests/
 COPY ./samples/BasicConsole/*.csproj ./samples/BasicConsole/ 
 RUN dotnet restore
 
-FROM restore as build
+FROM restore AS build
 ARG VERSION
 COPY ./icon.png .
 COPY ./src/Kevsoft.WLED/ ./src/Kevsoft.WLED/
-RUN dotnet build ./src/**/*.csproj --configuration Release -p:Version=${VERSION} --no-restore
+COPY ./src/Kevsoft.WLED.DependencyInjection/ ./src/Kevsoft.WLED.DependencyInjection/
+RUN dotnet build ./src/Kevsoft.WLED.DependencyInjection/Kevsoft.WLED.DependencyInjection.csproj --configuration Release -p:Version=${VERSION} --no-restore
 
-FROM build as build-tests
+FROM build AS build-tests
 ARG VERSION
 COPY ./test/Kevsoft.WLED.Tests/ ./test/Kevsoft.WLED.Tests/
 RUN dotnet build ./test/**/*.csproj --configuration Release -p:Version=${VERSION} --no-restore
 
-FROM build-tests as test
+FROM build-tests AS test
 ENTRYPOINT ["dotnet", "test", "./test/Kevsoft.WLED.Tests/Kevsoft.WLED.Tests.csproj", "--configuration", "Release", "--no-restore", "--no-build"]
 CMD ["--logger" , "trx", "--results-directory", "./TestResults"]
 
-FROM build as pack
+FROM build AS pack
 ARG VERSION
-RUN dotnet pack --configuration Release -p:Version=${VERSION} --no-build
+RUN dotnet pack ./src/Kevsoft.WLED/Kevsoft.WLED.csproj --configuration Release -p:Version=${VERSION} --no-build
+RUN dotnet pack ./src/Kevsoft.WLED.DependencyInjection/Kevsoft.WLED.DependencyInjection.csproj --configuration Release -p:Version=${VERSION} --no-build
 
-FROM pack as push
+FROM pack AS push
 RUN env
 
 ENTRYPOINT ["dotnet", "nuget", "push", "./src/Kevsoft.WLED/bin/Release/*.nupkg", "--source", "NuGet.org"]