# Phase 11 — Public Site Enhancements
Status: spec / design. Author: product-designer. Date: 2026-06-15 (revised same day after Daniel
resolved the open questions and expanded scope). **Plan only — no code edits made by this doc.**
Cross-references: `PLAN.md §11` (the concise phase entry), `PLAN.md §1.3` (preload/queue — now
**absorbed into this phase**), `product-notes/phase-9-release-medium-types.md` (the medium model —
`ReleaseMedium` enum, the per-medium detail-page strategy, the `ReleaseDetailScaffold` contract),
`COMPLETED.md §9.8` (Wave 8 remediation — the `/archive` release-cardinal browser, the inline nav,
the `TracksView` demotion), memory *One source, multiple views* and *Design for adaptability up
front*.
---
## 0. Why this phase exists, and the state it inherits
Phase 9 made the medium taxonomy real end-to-end and gave each medium a browse + detail surface.
Wave 8 then remediated the public side: `/archive` became a release-cardinal searchable browser,
the nav flattened to ARCHIVE + Cuts/Sessions/Mixes, and the track-cardinal `/tracks` gallery was
demoted from the nav (route kept). That work landed and is stable on dev (2026-06-13/14).
Phase 11 is the **next coherent pass over the public listening surface**. Daniel's hands-on use
surfaced an initial four commitments; on 2026-06-15 he resolved the open questions and expanded the
scope to **seven**. They share one spine: **make the release the cardinal unit of the public site,
make every navigation an addressable, shareable URL, and make the album a first-class playable
object** (ordered, queue-able, shareable). The seven:
1. **Cuts detail page** (`/cuts/{id}`) — structural; the phase's center of gravity.
2. **Player-bar release-title → release detail** via a medium→route resolver — structural.
3. **Retire the whole track-cardinal stack** *and* **normalize release-card rendering into shared
components** — reduction + normalization (the heart of 11.C).
4. **Archive filters in the URL** — addressability polish.
5. **Explicit track-ordinal column** on the track model, editable from the CMS — **new scope**;
data-model + migration; gates correct `/cuts/{id}` ordering.
6. **Release-level Share** — **new scope**; a Cut/Session/Mix header Share shares the release URL.
7. **Play-queue system** — **new scope**; absorbs the deferred `PLAN.md §1.3`. The Cuts "play album"
affordance is its first consumer.
This is not a greenfield phase — most of the scaffolding it needs already exists (the medium browse
pages already share a `ReleaseGallery` card component; the detail pages already share
`ReleaseDetailScaffold`; the Archive already has all filter state). The structural new work is the
**Cuts detail page** and the **queue model** (the one real architecture decision). Everything else
is closing asymmetries and consolidating rendering that drifted into per-surface copies.
> **Headline correction on commitment 5 (read against live source, 2026-06-15).** Daniel asked for
> "an explicit ordinal column, editable from the CMS, with a Daniel-gated migration." **That column
> already exists and shipped in Phase 8.** `TrackEntity.TrackNumber` is an explicit 1-based, non-null
> ordinal (default 1) — *not* insertion-order — with its migration (`20260611005700`) **already
> applied**, its DTO mirror, its API write path (validated `> 0`), and CMS reorder
> (`BatchEdit` assigns ordinal from list position on submit). The read path already sorts on it
> (`ReleaseRepository.OrderBy(t => t.TrackNumber)`). **So commitment 5 carries no new column, no new
> migration, and no Daniel-gated apply step.** What remains is *verify-and-consume*: confirm
> `TrackDto.TrackNumber` is populated on the public read path the Cut page uses, and ensure
> `CutDetailViewModel` orders by it. The reorder-UX question Daniel asked me to surface is also
> already answered in the CMS — `BatchEdit` reorders by list position, not a numeric field. This
> reframing is the most important single change in this revision; §3a carries the detail. If hands-on
> use reveals a gap (e.g. the *public* track read does not project `TrackNumber`), that is a small
> wiring fix, not the schema project the brief anticipated.
### What already exists (verified against live source, 2026-06-15)
| Surface | State | File |
|---|---|---|
| `/sessions/{id}` detail | **Exists, mature.** Hero-dominant overlay; bridged prerender; play wiring. | `Pages/SessionDetail.razor` |
| `/mixes/{id}` detail | **Exists, mature.** Full-page WebGL waveform background + scaffold; bridged prerender. | `Pages/MixDetail.razor` |
| `ReleaseDetailScaffold` | **Exists.** Invariant trio (back link, masthead, play/share) + `Hero`/`MetaContent` slots. Composed by `TrackDetail` and `MixDetail`. | `Controls/ReleaseDetailScaffold.razor` |
| `ReleaseDetailBase` | **Exists.** Shared load + prerender-bridge for single-release detail pages (id-addressed, resolves the playable track via `releaseId`-filtered track page). | `Pages/ReleaseDetailBase.cs` |
| `/cuts` gallery | **Exists** as `AlbumsView` (medium-parameterized card grid). Cards open `/tracks?album={title}`. **Renders its card markup inline (`album-card`), does NOT use `ReleaseGallery`.** | `Pages/AlbumsView.razor` |
| `/sessions`, `/mixes` galleries | **Exist** as `SessionsView`/`MixesView`, both inheriting `MediumBrowseBase` and **both composing the shared `ReleaseGallery` card grid** (with a `DetailRoute` param). | `Pages/{Sessions,Mixes}View.razor` |
| `ReleaseGallery` | **Exists.** The shared release-card grid — cover (+ `--fallback`), title, artist. Cards link ``. **Consumed only by Sessions/Mixes today**; Archive and Cuts re-implement equivalent markup inline. | `Controls/ReleaseGallery.razor` |
| `/archive` browser | **Exists, release-cardinal.** Debounced search + medium chips + genre filter. Cards route per-medium via a private `DetailHref` switch. **Renders card markup inline (`archive-release-card`), does NOT use `ReleaseGallery`. Filters held in component fields, NOT in the URL.** | `Pages/ArchiveView.razor(.cs)` |
| `/track/{EntryKey}` detail | **Exists** as `TrackDetail` — the *track-cardinal* detail the player-bar title links to. | `Pages/TrackDetail.razor` |
| `/albums` | **Exists** as a permanent redirect → `/cuts`. | `Pages/AlbumsRedirect.razor` |
| `SharePopover` | **Exists, track-keyed.** Takes an `EntryKey`; "Copy link" + "Embed player". No release-level share target. | `Controls/SharePopover.razor` |
| Play queue / playlist | **Does not exist.** Player is single-slot (`StreamingAudioPlayerService` holds one `CurrentTrack`). No notion of "next." `PLAN.md §1.3` (preload + queue) is deferred — **now absorbed here**. | — |
| `TrackEntity` ordinal | **ALREADY EXISTS — landed in Phase 8.** `TrackEntity.TrackNumber` (int, 1-based, default 1, non-null), column `track_number`, migration `20260611005700_AddReleaseTypeAndTrackNumber` **already applied**. `TrackDto.TrackNumber` mirrors it; `TrackConverter` round-trips it; `UpdateTrackMetadataRequest.TrackNumber` + `TrackController` validate (`> 0`) and persist it; `BatchEdit` already sets it from reorderable list position on submit; `ReleaseRepository.GetTracks` already `.OrderBy(t => t.TrackNumber)`. **Commitment 5 is not new schema — it is verify-and-consume.** | `TrackEntity.cs:17`, `TrackConfiguration.cs:37`, `BatchEdit.razor:192/225` |
### Three framing corrections (the brief's vocabulary vs. the live routes)
The brief's framing is directionally right but uses route names that do not match the code. Naming
these up front so the implementer is not misled:
1. **There is no `/tracks/{id}` route.** The track-cardinal detail route is **`/track/{EntryKey}`**
(`TrackDetail`), keyed by the FileDatabase entry key (a string), not a numeric id. The player-bar
title links to `/track/{Track.EntryKey}` (`TrackMetaLabel.razor` line 9). When the brief says
"`/tracks/{id}` becomes a pure router," the *intent* is: **the thing a release-title click lands
on should resolve medium → the correct dedicated detail page.** See §2 for what this actually
means against the live routes — the brief's "router" is better realized as a small **medium→route
resolver** than as a literal `/tracks/{id}` page, because the player bar carries a track, not a
release id.
2. **Cuts genuinely have no single-release detail page.** This is the real asymmetry. `/cuts`
(`AlbumsView`) cards and `/archive` Cut cards both open `/tracks?album={title}` — the track
gallery filtered to the album title. Sessions and Mixes route to dedicated `/sessions/{id}` /
`/mixes/{id}` pages. The new `/cuts/{id}` page (§3) closes this gap and is the heart of the phase.
3. **`/archive` filters are already in component state but not the URL.** `ArchiveView` holds
`_selectedMedium`, `_selectedGenre`, `SearchText` as private fields with no
`[SupplyParameterFromQuery]` and no `NavigateTo` on filter change. Requirement 4 is therefore a
**URL-binding pass over an existing browser**, not a new feature. The pattern to borrow already
lives next door: `TracksView` reads `?album=`/`?genre=`/`?q=` via `[SupplyParameterFromQuery]`
(`TracksView.razor.cs` lines 21–23).
---
## 1. The seven commitments (Daniel, faithful capture; decisions of 2026-06-15 folded in)
The original four (1–4) plus three Daniel added when he resolved the open questions (5–7).
1. **Player-bar release-title → release detail, via a medium→route resolver.** **DECIDED
(2026-06-15):** the release-title click resolves the release's `ReleaseMedium` → the correct
dedicated detail page (`/cuts/{id}` | `/sessions/{id}` | `/mixes/{id}`). Realized as a resolver
helper at click sites (the player bar already carries release id + medium), plus a thin
`/tracks/{id}` redirect page for bare-release-id deep links. (Was OQ1; resolved — see §2.)
2. **New `/cuts/{id}` page — album view.**
- Header section, **left-aligned**: release name, artist, genre, release year, plus **Play** and
**Share** buttons.
- Cover art **large-ish, right**, with a **theme border** around the image.
- Below: an **ordered track list** (ordered by the new ordinal column — commitment 5), each row
with a play button.
- Header Play **enqueues the whole album in ordinal order** (commitment 7) and starts track 1.
3. **Retire the whole track-cardinal stack + normalize release-card rendering.** **DECIDED
(2026-06-15):** retire `TracksView` / `TrackDetail` / `TrackCard` / `TracksGallery` and the
`/tracks` + `/track/{EntryKey}` routes entirely (not just the `?album` branch). **And** normalize
release-card presentation into shared component(s) consumed across `/archive`, `/cuts`,
`/sessions`, `/mixes` (and the Cuts detail track-row where applicable). The shared
`ReleaseGallery` already exists but only Sessions/Mixes use it — Archive and Cuts re-implement
equivalent markup inline. This is the normalization heart of 11.C. (Was OQ5; resolved — see §4.)
4. **Archive search params in the URL.** Search term, medium filter, genre filter all encoded in
`/archive?…` so filter actions create navigable history anchors (back/forward, shareable links).
5. **Explicit track-ordinal column, editable from the CMS.** **IN SCOPE (2026-06-15) — but
ALREADY SATISFIED by Phase 8.** Daniel asked for an explicit ordinal (NOT insertion-order),
editable from the CMS. The column (`TrackEntity.TrackNumber`, 1-based, non-null), its migration
(already applied), DTO mirror, API write path, and CMS reorder (`BatchEdit`) **all already exist**.
No new column, no new migration, no Daniel-gated apply step. Remaining work is *verify-and-consume*:
confirm the public read path projects `TrackNumber` and that `CutDetailViewModel` orders by it.
(Was OQ4 "do not assume into Phase 11"; Daniel reversed to in-scope — and the read confirms it is
already built. See §3a.)
6. **Release-level Share.** **NEW SCOPE (2026-06-15):** a Cut/Session/Mix header Share shares the
*release* URL, not a single track's embed. `SharePopover` is track-keyed today; add a
release-level share target. (Was an adjacent gap; promoted to scope. See §3b.)
7. **Play-queue system.** **NEW SCOPE (2026-06-15):** Daniel — "now is the natural time for that."
Absorbs the deferred `PLAN.md §1.3` (preload/queue). A queue model the player consumes; the Cuts
"play album" affordance (header Play → enqueue the release's tracks in ordinal order) is the first
consumer. Carries an unresolved architecture question (queue inside `IPlayerService` vs. a
separate orchestrating service) — framed with a recommendation in §3c; the final call is
staff-engineer's at implementation. (Was an adjacent gap; promoted to scope. See §3c.)
---
## 2. Requirement 1 reframed — the medium→detail resolver
**Recommendation: do not build a literal `/tracks/{id}` page. Build a `medium → detail route`
resolver and apply it at the two click sites that need it.** Here is why, and the three shapes
considered.
### What the player-bar title actually carries
The player bar holds a **`TrackDto`** (`TrackMetaLabel.razor`). A `TrackDto` carries a nested
`Release` (with `Id` and `Medium`). So at the click site we already know the release id *and* the
medium — there is no need for a round-trip "router page" that fetches the release to discover its
medium. The resolver is a pure function:
```
Release { Id, Medium } → "/cuts/{Id}" | "/sessions/{Id}" | "/mixes/{Id}"
```
### Three shapes
- **(i) Literal `/tracks/{id}` router page.** A routable component that fetches the release by id,
reads `Medium`, and `NavigateTo`s the dedicated page (`replace: true` so the router never sits in
history). *Cost:* a network round-trip and a flash of an empty page on every release-title click,
to rediscover a medium the caller already knew. Justified **only** if some entry point has *only*
a release id and not the medium (e.g. an external deep link to `/tracks/{id}`). *Keep this as a
thin fallback, not the primary path.*
- **(ii) Pure resolver helper, applied at click sites (RECOMMENDED).** A single
`ReleaseRoutes.DetailHref(ReleaseDto)` (or `(long id, ReleaseMedium medium)`) helper — **one
table, one location** — that every release-title / release-card click consumes. `ArchiveView`
already has a private `DetailHref` switch (lines 121–126); **promote it to the shared helper** so
the Archive, the player bar, and the new Cuts cards all route through one source. No round-trip,
no flash. This is the *One source, multiple views* discipline applied to routing.
- **(iii) Both.** The resolver helper (ii) is the primary path; a thin `/tracks/{id}` redirect page
(i) exists as the addressable fallback for bare-release-id deep links and for honoring the brief's
literal route. The redirect page consumes the *same* resolver helper.
**Recommend (iii): resolver helper as the spine, plus a thin `/tracks/{id}` redirect page that
reuses it.** This satisfies the brief's literal "`/tracks/{id}` is a pure router" wording *and* gives
the common case (player-bar click, where the medium is already in hand) a zero-round-trip path. The
redirect page is ~15 lines and shares the resolver, so it is not a second source of truth.
> **DECIDED (Daniel, 2026-06-15):** the player-bar title click now points at the **release detail**
> (via the resolver), **not** the track detail. `TrackMetaLabel`'s `` changes from
> `/track/{Track.EntryKey}` to `ReleaseRoutes.DetailHref(Track.Release)`. Implementation note: the
> link today sits on the **track name** (`TrackMetaLabel.razor` line 9). With the repoint it
> resolves to the release page; the artist/genre/year already render from `Track.Release`. This also
> removes `TrackDetail`'s last inbound link — with commitment 3 retiring the whole track-cardinal
> stack, `TrackDetail` and `/track/{EntryKey}` are deleted outright (§4).
### What "resolver" means for Cut
`DetailHref` for a Cut today returns `/tracks?album={title}`. After §3 lands, a Cut resolves to
**`/cuts/{Id}`** (id-addressed, consistent with Session/Mix). This repoint is the hinge between
requirements 1, 2, and 3 — see the dependency note in §6.
---
## 3. Requirement 2 — the `/cuts/{id}` album-detail page
This is the phase's center of gravity: the first **multi-track** release detail page. Sessions and
Mixes are single-track (their detail pages show one play affordance); a Cut is an album/EP/single
with an ordered track list.
### 3.1 Layout (Daniel's spec, literal)
```
┌─────────────────────────────────────────────────────────────┐
│ ← All cuts │
│ │
│ ┌─────────────────────────────┐ ┌──────────────────────┐ │
│ │ RELEASE NAME (h3) │ │ │ │
│ │ Artist (h6, primary) │ │ COVER ART │ │
│ │ Genre · 2025 │ │ (large-ish, │ │
│ │ │ │ theme border) │ │
│ │ [ ▶ Play ] [ ⤴ Share ] │ │ │ │
│ └─────────────────────────────┘ └──────────────────────┘ │
│ ↑ header content LEFT ↑ cover RIGHT │
│ │
│ ───────────────────────────────────────────────────────────│
│ 1. ▶ Track One 3:42 │
│ 2. ▶ Track Two 4:18 │
│ 3. ▶ Track Three 2:55 │
│ … │
└─────────────────────────────────────────────────────────────┘
```
- **Header left:** release name, artist, genre, release year, **Play** + **Share** buttons.
- **Cover right:** large, **theme border** around the image (a `deepdrft-`-prefixed border using a
palette token — mirror the existing cover treatments but with an explicit framed border, which is
the new visual element).
- **Track list below:** ordered rows, each with a play button. Row click / row play streams that
track.
- **Header Play** starts **track 1**.
### 3.2 Compose `ReleaseDetailScaffold`, or not? — the load-bearing design call
Phase 9 §5.3 established `ReleaseDetailScaffold` as the shared detail scaffold and committed to
"refactor `TrackDetail` onto it; per-medium variance rides slots." The scaffold owns the **invariant
trio**: back link, masthead (title + artist), play/share affordance. `MixDetail` composes it;
`SessionDetail` deliberately diverges (overlay layout). The question for Cuts:
- **(i) Compose the scaffold.** The Cut header *is* the invariant trio (title, artist, play, share) —
almost exactly what the scaffold provides. The cover goes in the `Hero` slot; the genre/year go in
`MetaContent`; the **track list** rides a new `BodyContent` slot (the scaffold has no body slot
today — adding one is the cheap, correct extension Phase 9 §5.3 anticipated: *"named slots are fine
where genuinely needed, e.g. `BodyContent` for the Cut/Album multi-track listing"*).
- **(ii) Bespoke page** (like `SessionDetail`). Full control over the left/right header split, but
duplicates the play/share wiring and the back-link/masthead the scaffold already owns.
**Recommend (i): compose the scaffold, add one `BodyContent` slot.** Two caveats that decide whether
this is clean or a fight:
1. **The header layout is left-content / right-cover; the scaffold's masthead is a top row.** The
scaffold today renders masthead-then-Hero vertically (`MixDetail` stacks cover below the
masthead). The Cut layout wants masthead and cover **side by side**. This is a **layout variance**,
and Phase 9 §5.3 is explicit: *"a boolean layout parameter on the scaffold is a design failure —
that variance belongs in a slot."* So the right answer is **not** a `HeroBesideMeta` flag on the
scaffold. Two clean options:
- **(a)** The Cut page supplies its whole left+right header as the page content and uses the
scaffold only for the back link + play/share wiring + body slot — i.e. the scaffold's masthead
is *one* arrangement and the Cut wants a different one, so the Cut composes a richer header into
a slot. Risk: the scaffold's built-in masthead then competes with the Cut's own header.
- **(b)** Generalize the scaffold's header region into a `Header` slot with the current
masthead+play row as the default content, so `MixDetail`/`TrackDetail` are unchanged (default)
and `CutDetail` supplies a left/right `Header`. This is the cleaner *One source* move but
touches the scaffold's shared contract.
- **Recommend (b)**, but flag it: it is a scaffold-contract change that ripples to every composer.
If Wave pressure makes (b) risky, **(ii) bespoke page** is the honest fallback — record it as
deliberate divergence (as `SessionDetail` already is) rather than bending the scaffold with a
boolean.
2. **The play/share affordance differs.** The scaffold renders a `PlayStateIcon` (icon toggle) +
`SharePopover`. Daniel's Cut spec says **Play and Share buttons** (labeled buttons, per the
mockup). If the Cut wants text buttons rather than the icon idiom, that is a **slot for the
affordance row**, not a scaffold edit. Minor — flag for Daniel whether the Cut header keeps the
icon idiom (consistency with Session/Mix) or uses labeled buttons (the literal spec wording).
### 3.3 Data path — the track list
The Cut page needs the release **and its ordered tracks**. Both primitives exist:
- **Release:** `IReleaseDataService.GetById(id)` → `ReleaseDto` (with `Title`, `Artist`, `Genre`,
`ReleaseDate`, `ImagePath`, `Medium`, `ReleaseType`, `TrackCount`).
- **Tracks:** the track-data service already supports a **`releaseId`-filtered** track page —
`ReleaseDetailViewModel.Load` uses `GetPage(pageNumber: 1, pageSize: 1, releaseId: …)` to resolve
the single track for Session/Mix. The Cut page issues the same call with a **larger page size**
(cover the whole album — `pageSize: 100` matches the gallery convention) to get the ordered list.
**Ordering. DECIDED (2026-06-15): order by the new explicit ordinal column** (commitment 5, §3a),
not insertion order. The Cut track list reads tracks for the release sorted ascending by ordinal.
This makes the ordinal column a **hard dependency of correct `/cuts/{id}` ordering** — 11.A's track
list cannot render in the right order until the column exists and the read sorts on it. See §3a for
the column's full cross-stack spec and §6 for the wave dependency (the ordinal work gates 11.A's
ordering, so it sequences first).
**New `CutDetailViewModel` vs. extend `ReleaseDetailViewModel`.** `ReleaseDetailViewModel` resolves
*one* track. The Cut page needs *many*. Two options:
- Extend `ReleaseDetailViewModel` with an optional `Tracks` collection populated when the medium is
Cut. Risk: the VM grows a medium conditional — the smell Phase 9 fought.
- A dedicated `CutDetailViewModel` (loads release + full track list). Cleaner SRP; the Cut detail is
genuinely a different shape (multi-track) from the single-release VM.
**Recommend a dedicated `CutDetailViewModel`** + a `CutDetail` page deriving the same prerender-bridge
discipline `ReleaseDetailBase` encodes (persist release + tracks across the prerender→WASM seam,
guard restore on id). If the bridge logic is substantial, consider generalizing `ReleaseDetailBase`'s
bridge into a shared base both single- and multi-track details use — but only if it doesn't force a
medium conditional into the base. Flag the choice; don't pre-commit the implementer.
### 3.4 Play wiring
- **Row play:** stream the row's track (the `TracksView.PlayTrack` idiom — toggle if already current,
else `SelectTrackStreaming`). Row play **also sets the queue context** to the album from that row
forward (so the queue continues into the rest of the album after a mid-album row start) — see §3c
for the enqueue semantics. If the queue work lands after 11.A's first cut, row play degrades
cleanly to single-track streaming (the `Design for adaptability up front` seam).
- **Header Play: enqueue the whole album in ordinal order, start track 1.** **DECIDED (2026-06-15):**
this is the first consumer of the queue system (commitment 7, §3c). Header Play calls the queue's
`PlayRelease(tracks-in-ordinal-order)` rather than a bare `SelectTrackStreaming(track1)`. Because
11.A and the queue (11.F) may land in either order, **design header Play as a single handler call
that swaps from `SelectTrackStreaming(Tracks.First())` to `Queue.PlayRelease(Tracks)` with no
other change to the page** — the seam Phase 11's earlier draft already anticipated, now made real
by bringing the queue into scope.
---
## 3a. Commitment 5 — the track-ordinal column (already built; verify-and-consume)
**Recommendation: do not spec a schema project. Verify the existing `TrackNumber` reaches the public
Cut read, and consume it.** The brief asked to "spec the implications across the stack" for a new
ordinal column. The honest answer from the read is that the stack is already wired end to end; the
only open risk is the *public* read projection.
### 3a.1 What already exists (each verified, 2026-06-15)
| Layer | State | Evidence |
|---|---|---|
| Entity | `TrackEntity.TrackNumber` — `int`, 1-based, non-null, default 1. Explicit ordinal, **not** insertion-order. | `TrackEntity.cs:17` |
| EF mapping | `track_number` column, configured. | `TrackConfiguration.cs:37` |
| Migration | `20260611005700_AddReleaseTypeAndTrackNumber` — **already applied** (it is in the snapshot and predates current `dev`). | `Migrations/` |
| DTO | `TrackDto.TrackNumber` mirrors it; `TrackConverter` maps both directions. | `TrackDto.cs:18`, `TrackConverter.cs:75/91` |
| API write | `UpdateTrackMetadataRequest.TrackNumber` (`int?`); `TrackController` validates `> 0` (400 otherwise), persists to the track row. Upload path resolves to 1 when unset. | `TrackController.cs:263/395-403` |
| CMS edit/reorder | `BatchEdit` loads tracks `sortColumn: "TrackNumber"`, holds them as a reorderable row list (`BatchRowModel.TrackNumber`), and **assigns each row its ordinal from list position on submit**. | `BatchEdit.razor:192/225` |
| Read sort (release tracks) | `ReleaseRepository.GetTracks` already `.OrderBy(t => t.TrackNumber)`. `TrackManager` sort switch includes `"TrackNumber"`. | `ReleaseRepository.cs:117`, `TrackManager.cs:122` |
### 3a.2 The reorder-UX question Daniel asked me to surface — already answered
Daniel asked: drag-reorder vs. numeric field, recommend the simplest shippable. **It is already
shipped, and it is neither a bare numeric field nor drag-and-drop — it is list-position ordinal
assignment:** `BatchEdit` presents the release's tracks as an ordered row list and writes
`TrackNumber = position` on submit. Editing order = reordering rows. That is the simplest correct
model (the ordinal is derived, never hand-typed, so it cannot collide or skip). **No change wanted
here** unless Daniel specifically wants drag affordance polish in the CMS — which is out of Phase 11
(CMS, not the public site) and should be raised separately if desired.
### 3a.3 The one real verify step — the *public* read projection
The CMS read (`CmsTrackService.GetPagedAsync`) sorts and carries `TrackNumber`. The Cut page uses the
**public** track-data service's `releaseId`-filtered page. The single concrete task for 11.A is to
**confirm that public read both sorts by `TrackNumber` and projects it onto `TrackDto`**, so
`CutDetailViewModel` renders rows in saved order and can label the track number. If the public read
already orders by `TrackNumber` (likely — it shares `TrackManager`'s sort switch), 11.A's ordering is
free. If it does not, the fix is a one-line sort argument, not a migration. **This is why the "ordinal
gates `/cuts/{id}` ordering" dependency in §6 collapses to a verification, not a wave.**
> **Net effect on the waves:** commitment 5 does **not** become its own wave. It folds into 11.A as a
> verification checklist item ("public read projects + sorts `TrackNumber`"). The brief's worry about
> a Daniel-gated migration does not apply — the migration already ran.
---
## 3b. Commitment 6 — release-level Share
**Recommendation: add a release-keyed mode to `SharePopover`, sharing the resolved release URL; keep
the track-keyed mode for any surface that still shares a single track.** This is an additive
extension of an existing control, not a new control.
### 3b.1 What `SharePopover` does today
`SharePopover` takes an `EntryKey` (a track) and offers "Copy link" + "Embed player." Both targets
are track-scoped. A Cut/Session/Mix header has no way to share *the release page* — only a track's
embed. After §2 every release has a canonical detail URL (`ReleaseRoutes.DetailHref`), so a
release-level share target now has a well-defined thing to copy.
### 3b.2 Three shapes
- **(i) New `ReleaseSharePopover` control.** Clean separation, but duplicates the popover chrome,
copy-to-clipboard plumbing, and styling. Two controls to keep in visual sync.
- **(ii) `SharePopover` gains a release mode (RECOMMENDED).** Add an optional release target
(`ReleaseDto` or `(long id, ReleaseMedium medium)`) alongside the existing `EntryKey`. When the
release target is set, "Copy link" copies `ReleaseRoutes.DetailHref(release)` (absolute URL); the
"Embed player" affordance is hidden or repurposed (a release page is not a single-track embed —
see the open sub-question below). One control, two modes, one source of clipboard/chrome logic —
the *One source, multiple views* discipline applied to share.
- **(iii) Make `SharePopover` polymorphic over a share-target abstraction** (`IShareTarget` with
`Title`, `Url`, `EmbedMarkup?`). Most general; over-built for two cases today. Note as the shape to
reach for **only if** a third share target appears (e.g. a playlist/queue share once §3c lands).
**Recommend (ii)** now, with (iii) noted as the refactor target if a third target appears. The Cut
header's Share button (the labeled-button-vs-icon question in §3.2.2 applies here too) opens the
popover in release mode.
### 3b.3 Open sub-question (surface, recommend)
- **Does release-share keep an "Embed player" option?** A release page is multi-track (Cut) or a
single hero track (Session/Mix). For Cuts there is no single embeddable track, so "Embed player"
should be hidden in release mode (copy-link only). For Session/Mix the release *is* effectively one
track, so embed could still make sense — but to keep the contract simple, **recommend release mode
is copy-link-only across all media** and the per-track embed stays available only where a track is
the share subject. Flag for Daniel; trivial either way.
---
## 3c. Commitment 7 — the play-queue system (absorbs `PLAN.md §1.3`)
This is the phase's **one real architecture decision** and Daniel has explicitly asked for a strong
steer while leaving the final call to staff-engineer. The brief's framing — "queue inside
`IPlayerService` vs. a separate orchestrating service" — is the right axis. Recommendation first,
then the two shapes, then the seams to the existing player and the §1.3 preload relationship.
**Recommendation: a separate `IQueueService` that orchestrates *above* the single-slot
`StreamingAudioPlayerService`. The player stays a single-slot device; the queue owns "what plays
next" and drives the player via its existing select-and-stream API.** This is the cleaner separation
and it matches the deferred §1.3's own framing ("the player is a single-slot device that a future
`PlaylistService` orchestrates above").
### 3c.1 The two shapes
- **(i) Queue inside `IPlayerService` (single-slot player gains a queue).** The player holds
`CurrentTrack` *and* a `Queue` and a position pointer; `Next`/`Previous`/`enqueue` are
player methods. *Pro:* one service, no coordination; the player already owns the end-of-stream
event that would advance the queue. *Con:* the player's responsibility balloons from "stream one
track" to "manage a playlist," which is the SRP smell — and it forecloses the case where the queue
outlives a player instance or where a non-audio surface (a visible up-next list) wants the queue
state without coupling to the streaming device.
- **(ii) Separate `IQueueService` orchestrating above the player (RECOMMENDED).** `QueueService`
owns the ordered list, the current index, and `PlayRelease` / `Enqueue` / `Next` / `Previous` /
`Clear`. It drives playback by calling the player's existing `SelectTrackStreaming(track)`. It
subscribes to the player's end-of-stream / track-ended signal to auto-advance. *Pro:* the player
stays single-purpose (the load-bearing streaming seam in `CLAUDE.md` is untouched); the queue is
independently testable and independently observable (the player bar and a future up-next panel both
read `QueueService` state); it is the natural home for the §1.3 preload trigger (the queue knows the
next track, so it owns the "prefetch next at threshold" decision). *Con:* a coordination seam — the
queue must observe the player's track-ended event reliably (the player must expose one; verify the
current `OnTrackEnded`/equivalent hook exists or spec adding it).
### 3c.2 The player seam (what the queue needs from the player)
The queue orchestrator needs three things from `StreamingAudioPlayerService`, all of which are either
present or a small addition:
1. **A way to start a track** — `SelectTrackStreaming(track)` exists (the Cut row-play and
`TracksView` already call it). The queue calls the same path; **no new player surface.**
2. **A track-ended signal** — the queue auto-advances on natural end-of-stream. Verify the player
raises a track-ended/playback-complete event today; if it only exposes position/state, **the one
genuine player addition is a `TrackEnded` event** (or the queue polls "state == ended"). Spec this
as the single new player-side hook.
3. **State for the player bar** — "is there a next?", "is there a previous?" so the bar can enable
skip-forward / skip-back. The bar reads `QueueService.HasNext` / `HasPrevious`.
### 3c.3 Queue data model (minimal, shippable)
```
QueueService
IReadOnlyList Items // ordered; the release's tracks for "play album"
int CurrentIndex // -1 when empty
TrackDto? Current => Items[CurrentIndex]
bool HasNext / HasPrevious
PlayRelease(IEnumerable tracks, int startIndex = 0) // Cuts header Play / row Play
Enqueue(TrackDto) / EnqueueRange(IEnumerable)
Next() / Previous() // advance index, drive player.SelectTrackStreaming
Clear()
event Action QueueChanged // player bar re-renders skip affordances
```
`PlayRelease(tracks)` is the Cuts "play album" entry point (commitment 2's header Play): pass the
release's tracks **in ordinal order** (already sorted, §3a), `startIndex: 0`. Row play is
`PlayRelease(tracks, startIndex: clickedRow)` — start mid-album, queue continues to the end (§3.4).
### 3c.4 Player-bar UI
The player bar today shows the current track + transport. The queue adds **skip-forward** and
**skip-back** controls (enabled per `HasNext`/`HasPrevious`), wired to `QueueService.Next/Previous`.
Optional, deferred-within-phase: a visible **up-next list** (the queue's `Items` past `CurrentIndex`).
Recommend skip controls in scope; the up-next panel as a `[speculative]` follow-on so the queue
work ships without waiting on a new UI surface.
### 3c.5 Relationship to §1.3 preload — IN or OUT?
`PLAN.md §1.3` is two things bundled: (a) a **queue model** ("a notion of next track") and (b)
**preload/prefetch** (begin the next track's bytes during the current track's tail). Commitment 7
brings **(a) the queue model fully into Phase 11**. **Recommend (b) preload stays OUT of Phase 11** —
ship the queue (correct next-track semantics, skip controls, play-album) first; preload is a
*perceived-latency optimization on top of* a working queue, and it is the prerequisite for crossfade
(§1.4) and gapless (§1.5), which are their own later work. Bringing preload in now couples the queue
ship to a staged-decoder change in the streaming path (the most load-bearing seam in the system).
**Design the seam, defer the feature** (memory *Design for adaptability up front*): `QueueService`
knows the next track, so it is the natural owner of a future "prefetch next at threshold" trigger.
Spec the queue so that adding preload later is *adding a subscriber to the queue's "next is known"
state*, not restructuring the queue. Note in `PLAN.md §1.3` that the **queue half is absorbed into
Phase 11; the preload half remains deferred** there (and gates 1.4/1.5 as before).
---
## 4. Requirement 3 — full stack retirement + shared release-card normalization
**DECIDED (2026-06-15):** retire the **whole** track-cardinal stack (not just the `?album` branch),
*and* normalize release-card rendering into shared component(s) consumed across `/archive`, `/cuts`,
`/sessions`, `/mixes`. This is two moves — a **reduction** (delete dead surface) and a
**normalization** (collapse duplicated card markup into one component). The normalization is the
heart of 11.C; the reduction is its precondition cleanup.
### 4.1 The reduction — retire the track-cardinal stack (DECIDED, no longer a Daniel question)
Daniel confirmed the full retirement. The surface that goes:
| Surface | Route | Why it is now dead |
|---|---|---|
| `TracksView` | `/tracks` (+ `?album`/`?genre`/`?q`) | Archive subsumes browse/search; `/cuts/{id}` subsumes album view; nav-demoted since Phase 9 §8.I. |
| `TrackDetail` | `/track/{EntryKey}` | Loses its last inbound link once §2 repoints the player-bar title to the release. |
| `TrackCard` | — | Only consumer is `TracksGallery`, which only `TracksView` uses. |
| `TracksGallery` | — | Only consumer is `TracksView`. |
| `GalleryViewMode` | — | Only the `TracksView` filter-mode enum. |
**Ordering of the retirement (the dependency chain):**
1. §3 — `/cuts/{id}` exists.
2. §2 — `ReleaseRoutes` resolves Cut → `/cuts/{id}`; the resolver repoints the player-bar title to
the release (removing `TrackDetail`'s inbound link) and repoints `AlbumsView` + Archive Cut cards
off `/tracks?album`.
3. §4.1 — with no inbound links remaining, delete the whole stack above.
So the retirement is **gated on §2 and §3 landing first** — you cannot delete `TrackDetail` while the
player bar still links to it, and you cannot delete the `?album` branch while `AlbumsView`/Archive
still point at it. This sequencing is honored in §6.
> **One inbound-link audit before deletion (verify, don't assume):** grep for every `href`/`NavigateTo`
> targeting `/tracks` and `/track/`. The known ones are the player-bar title (`TrackMetaLabel`),
> `AlbumsView.OpenAlbum`, and `ArchiveView.DetailHref` — all repointed by §2. The `/albums → /cuts`
> redirect (`AlbumsRedirect`) stays. The CMS `/tracks/{id}/edit` family is a **different route tree**
> (`DeepDrftManager`) and is untouched — do not confuse the public `/tracks` gallery with the CMS
> track-edit routes.
### 4.2 The normalization — one shared release-card component (the heart of 11.C)
**Recommendation: make `ReleaseGallery` the single release-card grid, and give its card a per-card
href resolver so it can serve Archive's per-medium routing. Repoint `/archive` and `/cuts` onto it;
delete the inline `archive-release-card` and `album-card` markup.** This is the *One source, multiple
views* discipline (memory) applied to card rendering.
#### 4.2.1 What's redundant today (audited against live source, 2026-06-15)
| Surface | Card rendering | Verdict |
|---|---|---|
| `/sessions`, `/mixes` (`SessionsView`/`MixesView`) | Compose **`ReleaseGallery`** with a fixed `DetailRoute`. | **Canonical.** Already shared. |
| `/archive` (`ArchiveView`) | Inline `archive-release-card` markup — cover (+`--fallback`), title, artist. **Byte-for-byte the same structure as `ReleaseGallery`'s `release-card`**, only the CSS class prefix and the per-card `DetailHref` differ. | **Redundant copy.** Fold into `ReleaseGallery`. |
| `/cuts` (`AlbumsView`) | Inline `album-card` markup, card click → `OpenAlbum` → `/tracks?album`. | **Redundant copy + wrong target.** Fold into `ReleaseGallery`, repoint to `/cuts/{id}`. |
Three near-identical card implementations across four browse surfaces. The structure is identical
(cover with `--fallback`, body with truncated title + artist); the only real divergence is **how a
card computes its href**: Sessions/Mixes use a fixed route segment; Archive resolves per-medium.
#### 4.2.2 The shared component contract
`ReleaseGallery` already owns the grid, skeleton-loading, empty-state, and card markup. Generalize its
**href computation** so one component serves both the fixed-route case and the per-medium case:
- **Today:** `[Parameter] string DetailRoute` → card links `/{DetailRoute}/{id}`.
- **Add:** an optional per-card href resolver, `[Parameter] Func? HrefResolver`.
When supplied, the card links `HrefResolver(release)`; otherwise it falls back to the
`DetailRoute`-based href (Sessions/Mixes unchanged). Archive passes
`HrefResolver="@ReleaseRoutes.DetailHref"` (the §2 resolver) — so each Archive card routes by its
own medium through the **same one table**.
- **Optionally fold the medium-route default into the resolver itself:** since `ReleaseRoutes` already
knows medium→route, Sessions/Mixes could *also* drop `DetailRoute` and just pass the resolver. But
keeping `DetailRoute` as the simple default avoids churning two working pages — **recommend adding
`HrefResolver` as the new path, leaving `DetailRoute` as the back-compat default**, and migrating
Sessions/Mixes only if it's free.
After this: `ReleaseGallery` is the one card grid. `archive-release-card` and `album-card` markup
(and their CSS) are deleted; `ArchiveView` keeps **only** its search/filter chrome above the grid
(the chrome is genuinely Archive-specific — it does not belong in the shared card component).
> **CSS consolidation:** the inline copies carry parallel CSS (`archive-release-*`, `album-card-*`).
> When the markup folds into `ReleaseGallery`, those rules collapse into the `release-card-*` rules.
> Verify the visual treatments match before deleting (cover sizing, fallback styling, truncation) —
> if Archive/Cuts cards were tuned differently, fold the differences into `ReleaseGallery` via a
> modifier class, not by keeping the duplicate.
#### 4.2.3 The Cuts-detail track row — same component, or different?
The brief asks whether the shared card extends to "the Cuts detail track list where applicable." The
Cut detail's track *rows* (§3.1 — `1. ▶ Track One … 3:42`) are a **different shape** from a release
*card* (a horizontal row with ordinal + play + duration, not a cover-forward card). **Recommend a
separate small `TrackRow` component** for the Cut track list rather than forcing it into
`ReleaseGallery` — they share nothing structurally. If a `TrackRow` is extracted, it is the natural
shared row for any future track-list surface, but it is *not* the release-card component. Flag this so
the normalization doesn't over-reach into forcing two unlike things into one component.
### 4.3 Residual redundancy (opportunistic, surface don't sprawl)
1. **`ArchiveView.MediumLabel`** — a medium→label lookup. Check whether it duplicates a CMS
`MediumTypeLabels` or the Archive's own medium-chip labels; if the public side has two
medium-label lookups, **consolidate to one**. **Medium confidence; opportunistic.**
2. **`GenresView` (`/genres`)** — already nav-demoted (§8.I); Archive has genre filtering. Likely
retire-able, but **out of this phase's stated scope** — flag as adjacent, low urgency. **Not in
Phase 11** unless Daniel pulls it in.
> Land the full stack retirement (§4.1) and the card normalization (§4.2) — both decided. Treat 4.3
> as tidy-ups: do them if they fall out of the normalization for free, surface `/genres` as adjacent.
---
## 5. Requirement 4 — Archive filters in the URL
**This is a URL-binding pass over the existing `ArchiveView`, borrowing the `TracksView` pattern
verbatim.** No new browser, no new data path — the filter state already drives `LoadReleases`; the
change is making that state **enter and leave via the query string**.
### 5.1 Target URL scheme
```
/archive?q={search}&medium={cut|session|mix}&genre={genre}
```
- All three params optional; omitting one means "no filter on that axis" (matches the current
null-means-all semantics).
- `medium` uses the same lowercase enum token the data service already speaks
(`Medium.ToString().ToLowerInvariant()`), parsed back with `Enum.TryParse(ignoreCase:true)` +
`Enum.IsDefined` — the exact posture `BatchUpload` (§8.E) and the API already use.
- Plain `/archive` (no params) = the unfiltered first page, which is the bridged/prerendered state.
### 5.2 The binding mechanics (borrow `TracksView`)
`TracksView.razor.cs` is the template:
- **In (URL → state):** add `[SupplyParameterFromQuery]` for `q`, `medium`, `genre`. Seed
`SearchText` / `_selectedMedium` / `_selectedGenre` from them in `OnInitializedAsync` **before**
the restore/fetch decision (so a direct nav to a filtered URL fetches filtered, and the bridge
restore is skipped when a filter is active — `ArchiveView` already has `HasActiveFilter` gating
exactly this).
- **Out (state → URL):** each of `OnSearchInput` / `OnMediumSelected` / `OnGenreSelected` calls
`Navigation.NavigateTo($"/archive?{composed query}")` **instead of** (or before) calling
`LoadReleases` directly. The query-param change drives the re-fetch.
### 5.3 The one real subtlety — same-route query change does not re-run `OnInitialized`
Blazor reuses the component on a same-route query-string change and fires `OnParametersSet`, **not**
`OnInitializedAsync` (the `TracksView.ClearFilter` comment, lines 117–120, documents exactly this
trap). So the filter→fetch reaction must live where it sees the change:
- **Option A (history-driven):** filter handlers only `NavigateTo` the new URL; move the
state-seeding + `LoadReleases` into `OnParametersSet`/`OnParametersSetAsync` keyed off the query
params. Cleanest — the URL is the single source of truth; back/forward "just works" because each
nav re-runs the same seed-and-fetch. **Recommended.**
- **Option B (dual-write):** handlers both `NavigateTo` *and* `LoadReleases` directly. Simpler diff
but the URL and the fetch are two writes that can drift, and back/forward needs separate handling.
**Recommend Option A.** It makes the URL the source of truth (which is the whole point of the
requirement) and gets shareable links + back/forward correctness as a structural consequence rather
than as bolted-on handling. Guard against the debounce/nav interplay: the search field debounces
(400ms) before firing; ensure a debounced search nav doesn't fight a rapid medium-chip nav (the
`OnParametersSet` reaction should be idempotent on identical param sets — mirror the
`_loadedEntryKey` guard idiom).
### 5.4 Persistence interaction
The bridged unfiltered first page (`PersistKey = "archive-releases"`) must keep restoring **only**
when no filter is active — `ArchiveView` already gates persist + restore on `HasActiveFilter`. The
URL-binding pass must preserve that gate: a `/archive?medium=mix` direct load must **fetch**, not
restore the unfiltered bridge. The existing `HasActiveFilter` check already expresses this; the
seed-from-URL step just has to run before the restore decision (as §5.2 specifies).
---
## 6. Wave decomposition
Sequenced so the structural chain (Cuts page → resolver → repoint → retire/normalize) is honored,
and the genuinely independent tracks (Archive URL; the queue model) can run in parallel. Seven
commitments, six waves. The queue (11.F) is the one work item that can start cold on day one and is
the gate for the Cuts "play album" affordance.
```
┌──────────────────────────┐ ┌──────────────────────────┐ ┌──────────────────────────┐
│ 11.A /cuts/{id} page │ │ 11.D Archive filters→URL │ │ 11.F Queue model │
│ + CutDetailViewModel │ │ (TracksView-pattern) │ │ (IQueueService above the │
│ + cover theme border │ │ INDEPENDENT │ │ single-slot player) │
│ + ordered track list │ └──────────────────────────┘ │ + player TrackEnded hook │
│ (verify public read │ │ + player-bar skip controls│
│ projects+sorts │ │ INDEPENDENT (cold start) │
│ TrackNumber — §3a) │ └────────────┬─────────────┘
└──────────┬───────────────┘ │
│ (11.A header Play & row Play
▼ consume 11.F's PlayRelease;
┌──────────────────────────┐ degrade to single-track if 11.F
│ 11.B ReleaseRoutes │◄── needs 11.A (Cut→/cuts/id) later — §3.4 seam)
│ resolver + repoint │
│ (player-bar title→release,│
│ Archive + AlbumsView │ ┌──────────────────────────┐
│ cards) + thin /tracks/id │ │ 11.E Release-level Share │
│ redirect │ │ (SharePopover release │
└──────────┬───────────────┘ │ mode, copy ReleaseRoutes │
│ │ URL) — needs 11.B resolver│
│◄────────────────────┤ + a release detail to │
▼ │ share (11.A/Session/Mix) │
┌──────────────────────────┐ └──────────────────────────┘
│ 11.C Retire + normalize │
│ • delete track-cardinal │
│ stack (Tracks*/Track*) │
│ • fold Archive+Cuts cards │
│ into shared ReleaseGallery│
│ • consolidate medium-label│
└──────────────────────────┘
```
- **11.A — `/cuts/{id}` album-detail page.** The page, `CutDetailViewModel`, cover theme border,
ordered track list (ordered by `TrackNumber` — §3a), per-row play, header Play, Share button.
**Ordinal is a verification, not a dependency:** §3a confirmed `TrackNumber` already exists and the
read likely already sorts on it; 11.A's one checklist item is *confirm the public read projects +
sorts `TrackNumber`* (one-line fix if not). **Depends only on existing `GetById` + `releaseId`-
filtered track page (both exist).** Header/row Play call into 11.F when present, else degrade to
single-track streaming (§3.4 seam). **Load-bearing prerequisite for 11.B's Cut resolution.**
- **11.B — `ReleaseRoutes` resolver + repoint.** Promote `ArchiveView.DetailHref` to a shared
`ReleaseRoutes.DetailHref`; Cut now resolves to `/cuts/{id}` (needs 11.A); repoint player-bar
title (→ release), Archive cards, `AlbumsView` cards; add the thin `/tracks/{id}` redirect page.
**Depends on 11.A.** Verify `TrackDto.Release` is always populated on the player bar (so the
resolver has a medium — §7 gap).
- **11.C — retire + normalize (the heart).** With §2 having removed every inbound link: **delete the
whole track-cardinal stack** (`TracksView`/`TrackDetail`/`TrackCard`/`TracksGallery`/
`GalleryViewMode` + `/tracks`, `/track/{EntryKey}` routes — §4.1) **and** fold the Archive + Cuts
inline card markup into the shared `ReleaseGallery` via the new `HrefResolver` (§4.2); consolidate
the medium-label lookup (§4.3). **Depends on 11.B.** (The Cut track-row is a separate small
`TrackRow`, not `ReleaseGallery` — §4.2.3.)
- **11.D — Archive filters in the URL.** `/archive?q=&medium=&genre=`, history-driven (§5). Fully
independent — touches only `ArchiveView`. **No dependency; free-floating.** *Note:* 11.D and 11.C
both touch `ArchiveView` — sequence them so they don't collide (do 11.D's URL-binding and 11.C's
card-fold in one `ArchiveView` pass, or land 11.D first and rebase 11.C onto it).
- **11.E — release-level Share.** `SharePopover` gains a release mode that copies
`ReleaseRoutes.DetailHref(release)` (§3b). **Depends on 11.B** (needs the resolver for the URL) and
on a release detail existing to share (11.A for Cuts; Session/Mix already exist). Wire the Cut
header Share (and optionally Session/Mix headers) to open the popover in release mode.
- **11.F — queue model.** `IQueueService` orchestrating above the single-slot player; the one new
player-side hook (`TrackEnded`); player-bar skip controls (§3c). **Independent — can start cold on
day one**, in parallel with 11.A/11.D. It is the **gate for the Cuts "play album" affordance**:
11.A's header Play calls `QueueService.PlayRelease(tracks)` once 11.F lands (degrading to
single-track before then). **Preload (§1.3b) is OUT of this wave** — design the seam, defer the
feature (§3c.5).
**Dependency shape:**
```
11.A ──► 11.B ──► 11.C
└────► 11.E (also needs a release detail to share)
11.D (free-floating; coordinate with 11.C on ArchiveView)
11.F (free-floating cold start; 11.A's "play album" consumes it)
```
**Critical path:** `11.A → 11.B → 11.C`. **11.D, 11.E, 11.F hang off it** (11.E after 11.B; 11.D and
11.F fully parallel). The two "can start immediately" items are **11.A** and **11.F** — kicking both
off first shortens the wall-clock to a usable Cut page (page + queue arrive together, so "play album"
works on first ship of 11.A rather than as a later retrofit).
> **Honest dependency notes (the brief asked to keep these straight):**
> - **Ordinal does *not* gate a wave.** §3a showed `TrackNumber` already exists end-to-end; the
> "ordering" dependency is a one-line verification inside 11.A, not sequencing.
> - **Queue gates the "play album" affordance, not the Cut page.** 11.A ships with a degradable Play
> (single-track) if 11.F is not yet in; the affordance becomes "enqueue album" the moment 11.F
> lands, via the §3.4 handler swap. So 11.A and 11.F are parallel, with a clean late-binding seam.
> - **Shared cards parallel the stack retirement.** Folding Archive/Cuts cards into `ReleaseGallery`
> (§4.2) and deleting the track-cardinal stack (§4.1) are both in 11.C and both depend on 11.B's
> repoint — they are siblings, not sequential.
---
## 7. Resolved decisions and remaining open questions
### 7.1 Resolved by Daniel (2026-06-15) — kept visible as *decided*, not deleted
1. **Player-bar title target (§2).** **DECIDED:** the title click resolves **release** detail via the
resolver, replacing the `/track/{EntryKey}` link. (Was OQ1.)
2. **Track ordinal (§3a).** **DECIDED:** explicit ordinal column, editable from the CMS — *and the
read confirms it already exists* (`TrackEntity.TrackNumber`, migration applied, CMS reorder live).
No new schema; verify the public read projects/sorts it. (Was OQ4 "do not assume into Phase 11";
Daniel reversed to in-scope, and it turned out already-built.)
3. **`/tracks` retirement scope (§4.1).** **DECIDED:** retire the **whole** track-cardinal stack
(`TracksView`/`TrackDetail`/`TrackCard`/`TracksGallery`/`GalleryViewMode` + routes), not just the
`?album` branch. (Was OQ5; the full-cut option chosen.)
4. **Release-level Share (§3b).** **DECIDED:** in scope. `SharePopover` gains a release-keyed mode.
(Was an adjacent gap; promoted.)
5. **Play-queue system (§3c).** **DECIDED:** in scope; absorbs the queue half of `PLAN.md §1.3`. The
Cuts "play album" affordance is its first consumer. (Was an adjacent gap; promoted.) Preload half
stays deferred.
### 7.2 Still open (need Daniel — recommendations given)
1. **`/cuts/{id}` scaffold strategy (§3.2).** Compose `ReleaseDetailScaffold` with a generalized
`Header` slot (recommended) vs. bespoke page like `SessionDetail`. Sets whether the scaffold
contract changes. *Recommend the `Header`-slot generalization; bespoke as fallback.*
2. **Cut header affordance idiom (§3.2.2).** Keep the icon `PlayStateIcon`+`SharePopover` (consistent
with Session/Mix) vs. labeled **Play/Share buttons** (the literal spec wording). *Minor — flag.*
3. **Queue architecture (§3c).** Queue inside `IPlayerService` vs. a separate `IQueueService`
orchestrating above the single-slot player. *Strong steer: the separate `IQueueService` (§3c.1).*
**Final call is staff-engineer's at implementation** — the spec gives the steer, not the verdict.
4. **Release-share keeps "Embed player"? (§3b.3).** *Recommend copy-link-only in release mode across
all media; per-track embed stays where a track is the subject.* Trivial either way.
5. **`/genres` fate (§4.3).** Already nav-demoted; Archive has genre filtering. Retire `/genres` too?
*Out of stated scope — flag as adjacent, low urgency.* **Not in Phase 11** unless Daniel pulls it.
### 7.3 Small things to get right (not decisions — implementer notes)
- **`TrackDto.Release` nullability on the player bar (11.B).** `TrackMetaLabel` guards `Track.Release?`
— if a track loads without its release populated, the resolver has no medium to route on. Verify the
streaming select path always carries `Release`. *Low risk; a verification line in 11.B.*
- **Public read projects/sorts `TrackNumber` (11.A).** The §3a verify step — confirm the public
`releaseId`-filtered track page sorts ascending by `TrackNumber` and carries it onto `TrackDto`.
- **Player `TrackEnded` hook (11.F).** The queue auto-advances on natural end-of-stream; verify the
player raises a track-ended event or add one (the single new player-side surface — §3c.2).
- **Year-only display (§3.1).** The Cut header shows just the year; `MixDetail`/`SessionDetail` show
"MMMM yyyy". Don't copy the month-year format into the Cut header.
---
## 8. Why this is consistent with the system's grain
- **Release-cardinal everywhere.** Phase 9 + Wave 8 moved the public site to release-cardinal browse
(`/archive`) and per-medium detail. Phase 11 closes the one hole (Cuts had no detail page) and
makes the player-bar→detail path release-cardinal too. After this, the track-cardinal stack is
vestigial — which is *why* the reduction (§4) is available.
- **One source, multiple views.** The medium→route resolver (§2) is one table consumed by the player
bar, Archive, and Cuts cards — not three `DetailHref` switches. The shared `ReleaseGallery` (§4.2)
becomes the one release-card grid across all four browse surfaces, not three inline copies. The
queue (§3c) is one orchestrator the player bar and a future up-next panel both observe. The Cut
detail reuses the scaffold's invariant trio and the existing `GetById` + `releaseId`-filtered track
page — no new data path. (Memory: *One source, multiple views*.)
- **Design the seam, defer the feature.** Header Play binds to a single handler that swaps from
single-track to `QueueService.PlayRelease` with no page change (§3.4); preload subscribes to the
queue's "next is known" state rather than restructuring it (§3c.5). (Memory: *Design for
adaptability up front*.)
- **URL as source of truth (§5).** Borrowing the `TracksView` `[SupplyParameterFromQuery]` pattern
makes the Archive's filters addressable, which is the same shareable-link discipline the embed
player and `/tracks?album` deep links already established.
- **Extension, not modification.** The resolver and the `ReleaseDetailScaffold` `Header`/`BodyContent`
slots are additive; a future medium's detail page composes the same scaffold and the resolver gains
one entry — the Phase 9 Open/Closed discipline, unchanged.
---
## 9. Verified facts (read against live source 2026-06-15)
- **No `/tracks/{id}` route exists.** Track-cardinal detail is `/track/{EntryKey}` (`TrackDetail.razor`
line 1). Player-bar title links to `/track/{Track.EntryKey}` (`TrackMetaLabel.razor` line 9).
- **`/sessions/{id}` and `/mixes/{id}` exist and are mature** (`SessionDetail.razor`, `MixDetail.razor`,
both id-addressed, both inherit `ReleaseDetailBase`'s prerender bridge; `MixDetail` composes
`ReleaseDetailScaffold`, `SessionDetail` deliberately diverges).
- **Cuts have no single-release detail page.** `/cuts` is `AlbumsView` (medium-parameterized card
grid); cards open `/tracks?album={title}` (`AlbumsView.razor.cs` line 62). `/albums` → `/cuts`
redirect exists (`AlbumsRedirect.razor`).
- **`/archive` is release-cardinal, filters held in component fields not the URL.** `ArchiveView`
has `_selectedMedium`, `_selectedGenre`, `SearchText` as private state; no `[SupplyParameterFromQuery]`,
no `NavigateTo` on filter change (`ArchiveView.razor.cs`). It has a private `DetailHref` switch
(lines 121–126) routing Session→`/sessions/{id}`, Mix→`/mixes/{id}`, Cut→`/tracks?album={title}`.
- **`TracksView` already reads `?album=`/`?genre=`/`?q=` from the URL** via `[SupplyParameterFromQuery]`
(`TracksView.razor.cs` lines 21–23) — the pattern requirement 4 borrows. It documents the
same-route-query-change trap (`OnParametersSet` not `OnInitialized`, lines 117–120).
- **`ReleaseDetailScaffold`** owns the invariant trio (back link, masthead, play/share) + `Hero` and
`MetaContent` slots; **no body/track-list slot today** (`ReleaseDetailScaffold.razor`).
- **Data primitives for the Cut page both exist:** `IReleaseDataService.GetById(id)` returns a full
`ReleaseDto`; the track-data service supports `releaseId`-filtered paging (`ReleaseDetailViewModel.Load`
uses `GetPage(…, releaseId: …)`). `ReleaseDto` carries `TrackCount` but the **track list needs the
filtered track page** (the DTO has no nested track collection).
- **`TrackEntity` ALREADY HAS an explicit track-number ordinal.** `TrackEntity.TrackNumber` (`int`,
1-based, non-null, default 1 — `TrackEntity.cs:17`); column `track_number` (`TrackConfiguration.cs:37`);
migration `20260611005700_AddReleaseTypeAndTrackNumber` **already applied**; `TrackDto.TrackNumber`
mirrors it (`TrackDto.cs:18`); `TrackConverter` round-trips it; `UpdateTrackMetadataRequest.TrackNumber`
+ `TrackController` validate (`> 0`) and persist; `BatchEdit` assigns ordinal from reorderable list
position on submit (`BatchEdit.razor:225`); `ReleaseRepository.GetTracks` already
`.OrderBy(t => t.TrackNumber)` (`ReleaseRepository.cs:117`). **Commitment 5 is verify-and-consume,
not new schema.** (This corrects the prior draft's "data-model gap" claim — the gap does not exist.)
- **Release-card markup is triplicated.** `ReleaseGallery` (`release-card`) is the canonical card
grid, used only by Sessions/Mixes. `ArchiveView` (`archive-release-card`) and `AlbumsView`
(`album-card`) re-implement the **same cover/title/artist structure inline** — the only real
divergence is per-card href computation (Archive resolves per-medium, the others use a fixed route).
- **`Pages.cs` `MenuPages`** = ARCHIVE (→ `/archive`) with Cuts/Sessions/Mixes children; `/tracks`
and `/genres` are absent from nav, routes reachable (§8.I).
- **`SharePopover` is track-keyed** (takes `EntryKey`) — sharing a release is a new target.