docs: spec Track Detail page (/track/{entryKey}) in PLAN.md

PLAN.md

@@ -204,6 +204,116 @@ A small set of items that are real but don't fit a phase yet. Surface them when
 
 ---
 
+## Track Detail Page (/track/{entryKey})
+
+A focused, editorial single-track view in `DeepDrftPublic.Client`. The track gallery answers "what is in the library"; this page answers "tell me about *this* track" — full metadata, cover art, and a single prominent play affordance, styled to feel like a record-sleeve back-cover rather than a form. Link-only for now (reached from a gallery card / Now Playing), not a top-level nav entry.
+
+**Status:** `[spec — not yet built]`. Spec is implementation-ready *except* for the cover-art dependency called out in §4 below, which forks on **2.1**.
+
+### Two facts that correct the originating brief
+
+The dispatch brief carried two assumptions that the current tree does not bear out. Both are load-bearing for whoever implements this:
+
+1. **There is no cover-art URL pattern yet.** The brief said to "confirm and spec the correct URL" for `api/track/{entryKey}/image` as if it existed. It does not. Per **2.1**, the image vault is unwired: `TrackEntity.ImagePath` is still a free-form URL string and no image read endpoint exists on `DeepDrftContent`. The page must therefore treat cover art as a *dependency on 2.1*, not a given. See §4 for the resolution and the graceful-degradation default that lets the page ship before 2.1 lands.
+
+2. **The page consumes `ITrackDataService`, not `TrackClient` directly.** `ITrackDataService.GetTrack(string trackId)` already exists and already delegates to `TrackClient.GetTrack(entryKey)` (`TrackClientDataService.cs:29`). It is the render-mode-agnostic seam — WASM hits it over HTTP, the SSR prerender pass can swap a direct implementation. The ViewModel must depend on `ITrackDataService`, mirroring `TracksViewModel`, so the prerender bridge in §6 actually fetches in-process during prerender rather than round-tripping. Calling `TrackClient` directly would couple the page to the WASM transport and defeat the persisted-state bridge.
+
+### 1. Route and render mode
+
+- **Route:** `@page "/track/{EntryKey}"`. `EntryKey` is a `[Parameter]` string; Blazor route matching is case-insensitive by convention. The segment is the FileDatabase entry key, matching `TrackClient.GetTrack`'s `api/track/meta/by-key/{entryKey}` lookup. The component must `Uri.UnescapeDataString` is **not** needed — Blazor decodes route segments before binding.
+- **Render mode:** `@rendermode InteractiveWebAssembly`, consistent with `TracksView` and the other public pages: server prerenders, WASM hydrates. This is what makes the §6 `PersistentComponentState` bridge necessary.
+
+### 2. ViewModel shape — `TrackDetailViewModel`
+
+Scoped, registered in `Startup.ConfigureDomainServices` alongside `TracksViewModel`. Depends on `ITrackDataService` (the existing seam), not `TrackClient`.
+
+Properties:
+- `TrackDto? Track` — the loaded track, `null` until the fetch resolves. Single source of truth for the view.
+- `bool IsLoading` — `true` from construction until the first load completes (pass or fail). Drives the skeleton.
+- `bool NotFound` — `true` when the load resolved but the result was a failure (404 or deserialize miss). Drives the error state. Kept distinct from `IsLoading` so the view has three clean states: loading / loaded / not-found.
+
+One async command:
+- `Task Load(string entryKey)` — calls `TrackData.GetTrack(entryKey)`. On `Success`, sets `Track` and clears `NotFound`; on failure, sets `NotFound = true` and leaves `Track` null. Sets `IsLoading = false` in a `finally`. Idempotent enough to be safe if called once per `OnInitializedAsync` (it is — see §6).
+
+Note the VM is keyed transiently: unlike `TracksViewModel` (which holds paging state across the session), this VM is per-track. Because it is scoped, navigating between two `/track/...` routes reuses the same instance — `Load` must fully overwrite all three properties each call so a stale `Track` never bleeds across a navigation. Reset `IsLoading = true` and `NotFound = false` at the *top* of `Load`.
+
+### 3. Component layout
+
+Editorial, not a property grid. Target feel: the back of a record sleeve. Single centered column on a generous max-width container (~720–820px), plenty of vertical rhythm, type doing most of the work.
+
+Top to bottom:
+
+1. **Back link.** A subtle, small `← All tracks` at the top-left of the content column, routing to `/tracks`. `MudLink` with low-emphasis styling (`Typo.body2`, muted color from the active palette). Not a button — a quiet text affordance.
+
+2. **Cover art block.** A large square (responsive, ~320–400px, centered). When art resolves (§4), an `<img>` inside a `deepdrft-track-detail-cover` frame. When it does not (null `ImagePath`, or 2.1 not yet wired), a themed placeholder — a `MudPaper` with a centered low-emphasis `Icons.Material.Filled.Album` glyph, *not* a broken image and *not* the word "no image". The placeholder is the default state today, so it must look intentional.
+
+3. **Title / artist masthead.** `TrackName` as the hero — `MudText Typo="Typo.h3"` (or `h2`), in the display serif the theme already loads (Bodoni Moda / Cormorant via the `deepdrft-` type classes). `Artist` directly beneath, `Typo.h6`, lighter weight, `Color="Color.Primary"` or a muted secondary. These two are never null, so they always render.
+
+4. **Play affordance.** Immediately under the masthead — see §5. Prominent; this is the page's primary action.
+
+5. **`MudDivider`** — a hairline rule separating the masthead from the metadata block, reinforcing the back-cover feel.
+
+6. **Metadata block.** The optional fields (`Album`, `Genre`, `ReleaseDate`), each rendered **only if non-null**. No "Unknown Album" placeholders — a null field omits its entire row. Two viable treatments; implementer picks one and stays consistent:
+   - **Definition rows:** small-caps muted label (`Album` / `Genre` / `Released`) left, value right, one `MudText` row each. Editorial, calm.
+   - **Chips:** `Genre` as a `MudChip` (it reads as a tag); `Album` and `ReleaseDate` as definition rows. Mixed, slightly livelier.
+   Recommended: definition rows for all three for coherence, with `Genre` optionally promoted to a chip if the page feels too text-flat in review. `ReleaseDate` (a `DateOnly?`) formats as year-or-full-date — `ToString("MMMM yyyy")` reads editorially; avoid raw ISO.
+
+If *all three* optional fields are null, the metadata block and its preceding divider both collapse — the page is then just back-link / cover / masthead / play, which is still a complete, composed view. Guard the divider on "at least one optional field present."
+
+### 4. Cover-art URL resolution
+
+This is the spec's one real fork, because the endpoint does not exist yet (see correction #1).
+
+- **Default (ship-now) behavior:** treat `ImagePath` as not-displayable and render the §3.2 themed placeholder unconditionally. This lets the page ship before **2.1**. The placeholder is designed to be the resting state, not a degraded one.
+- **When 2.1 lands** (image vault wired, `GET api/image/{entryKey}` on `DeepDrftContent`, `ImagePath` semantics changed to "image vault entry key"): resolve cover art by composing the content-API base with the new endpoint — `api/image/{track.EntryKey}` against the `"DeepDrft.Content"` client's base address — and bind it to the `<img src>`. This mirrors how audio is keyed: structured metadata over `"DeepDrft.API"`, binary over `"DeepDrft.Content"`. The `<img>` should still carry an `onerror` fallback to the placeholder so a missing vault entry degrades cleanly.
+- **Do not** invent an `api/track/{entryKey}/image` endpoint for this page alone. Cover art is a library-wide capability owned by 2.1; the detail page is a *consumer*, not the place to define the seam. If cover art is wanted before 2.1's full scope, that is a scope conversation for 2.1, not a side-door endpoint here.
+
+Captured as a dependency edge: **Track Detail cover art → 2.1 (cover-art / image vault wired through).** The page is shippable without it; the cover block simply stays in placeholder state until 2.1 closes.
+
+### 5. Play affordance
+
+The page resolves a `TrackDto` (carrying both `Id` and `EntryKey`); playback is keyed by the SQL `Id` via the existing stream path, so no ID-space ambiguity arises here (unlike the FramePlayer note above — this page always has the full DTO).
+
+- A single prominent **Play** button under the masthead. `MudButton Variant="Variant.Filled"` with a leading play icon, or a large `MudIconButton` if the visual language wants a circular transport control. Label "Play" (or "Play track").
+- Wires to the cascaded player: `[CascadingParameter] IStreamingPlayerService PlayerService` (cascaded from `AudioPlayerProvider` in `MainLayout`, available to all pages).
+- Click handler mirrors `TracksView.PlayTrack`: if `PlayerService.CurrentTrack?.Id == Track.Id && PlayerService.IsPaused`, call `TogglePlayPause()` (resume); otherwise `SelectTrackStreaming(Track)`. (The brief named `SelectTrackStreaming` — that is correct and current; `TracksView` happens to call the base `SelectTrack`, but the streaming entry point is the right one for an explicit Play action.)
+- **State-reactive label:** the button should reflect live transport state for *this* track — show "Pause" when this track is the current track and playing, "Play"/"Resume" otherwise. That requires the same multicast subscription `TracksView` uses: subscribe to `PlayerService.StateChanged` in `OnParametersSet` (reference-guarded, idempotent), `InvokeAsync(StateHasChanged)` on fire, unsubscribe on `Dispose`. The cascade is `IsFixed`, so without this subscription the button label goes stale when the dock bar drives state. This is mandatory, not polish — copy the `_subscribedService` guard pattern verbatim from `TracksView.razor.cs`.
+- Optional, defer: a secondary "Now playing" indicator or the `WaveformProfile` mini-render. Out of scope for v1 — note it as a later enhancement, don't build it.
+
+### 6. Loading and error states
+
+Three states, driven by the §2 VM flags.
+
+- **Loading (`IsLoading`):** a skeleton matching the loaded layout's silhouette so the transition doesn't reflow — a square `MudSkeleton` (Rectangle) for the cover, a wide `MudSkeleton` (Text) for the title, a narrower one for the artist, and two or three short ones for the metadata rows. Reuse the `MudSkeleton` idiom already in `TracksView.razor` for visual consistency.
+- **Loaded (`Track != null`):** the §3 layout.
+- **Not found (`NotFound`):** 404-style messaging — a centered `MudText` ("Track not found") with a quieter line ("This track may have been moved or removed.") and a `MudButton`/`MudLink` back to `/tracks`. Theme-coherent, calm, not an error-red alert. This is the failure surface for both a genuine 404 and a deserialize miss; the VM collapses both into `NotFound`, so the page need not distinguish them.
+
+### 7. CSS — new `deepdrft-` classes
+
+All in `DeepDrftPublic/wwwroot/styles/deepdrft-styles.css` (shared server/client). Described semantically; implementer writes the rules.
+
+- `deepdrft-track-detail-container` — the centered single column: max-width, horizontal auto-margins, top/bottom padding for vertical rhythm.
+- `deepdrft-track-detail-cover` — the square cover frame: aspect-ratio 1/1, rounded corners consistent with the gallery cards, subtle shadow/border keyed to the active palette, `overflow: hidden` so the `<img>` crops cleanly. Applies to both the `<img>` and the placeholder `MudPaper` so they occupy identical space (no layout jump between placeholder and real art once 2.1 lands).
+- `deepdrft-track-detail-masthead` — title/artist spacing and the display-serif type treatment (lean on existing `deepdrft-` font classes rather than redefining font stacks).
+- `deepdrft-track-detail-meta` — the metadata block: the small-caps muted label treatment and row rhythm for the definition rows.
+- `deepdrft-track-detail-back` — the quiet back-link affordance (muted color, hover treatment).
+
+Theme coherence comes for free via MudBlazor palette tokens (`Color.Primary`, `Color.Secondary`, surface/text from the active `PaletteLight`/`PaletteDark`); the `deepdrft-` classes handle layout, rhythm, and the serif/small-caps editorial touches that MudBlazor doesn't express. Verify both palettes ("Charleston in the Day" / "Lowcountry Summer Nights") in review — the cover shadow and back-link muted color are the two spots most likely to read wrong in one mode.
+
+### 8. `Pages.cs` registration
+
+**Link-only — do not add to `MenuPages`.** A per-track detail route is not a destination you navigate to from the header; it's reached contextually (a gallery card, the Now Playing surface). Adding it to nav makes no sense without a specific `{entryKey}`.
+
+Open question for a follow-up, not this page: should gallery cards / Now Playing link *into* `/track/{entryKey}`? That is the inbound-link wiring that makes this page reachable, and it lives in those components, not here. This spec delivers the destination; the links that point at it are a small separate change (likely: make the `TrackCard` cover/title a `MudLink` to `/track/@track.EntryKey`). Flag it so the page isn't shipped orphaned and unreachable.
+
+### Dependencies and sequencing
+
+- **Shippable now** in placeholder-cover form — no blocking dependency.
+- **Cover art** depends on **2.1**; until then the cover block is the themed placeholder. (§4)
+- **Reachability** depends on a small inbound-link change in `TrackCard` / Now Playing (§8) — trivial, but required or the page is orphaned. Recommend bundling that link change with this page so v1 is actually reachable.
+
+---
+
 ## Working with this file
 
 - **Add items by extending an existing phase first**; only create a new phase when the addition genuinely doesn't fit any of 1–5. Phase numbers are organisational, not sequencing.