Files

T

daniel-c-harvey e9f4411fdf docs(plan): revise Phase 11 — ordinal, full stack retirement, shared cards, release-share, queue

Fold Daniel's 2026-06-15 decisions into PLAN.md §11 and the product note:
4→7 commitments, six waves. Headline: the track ordinal already shipped
in Phase 8, so commitment 5 is verify-and-consume, not a new migration.
Queue half of §1.3 absorbed; preload stays deferred.

2026-06-15 23:30:28 -04:00

64 KiB

Raw Blame History

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:

Cuts detail page (/cuts/{id}) — structural; the phase's center of gravity.
Player-bar release-title → release detail via a medium→route resolver — structural.
Retire the whole track-cardinal stack and normalize release-card rendering into shared components — reduction + normalization (the heart of 11.C).
Archive filters in the URL — addressability polish.
Explicit track-ordinal column on the track model, editable from the CMS — new scope; data-model + migration; gates correct /cuts/{id} ordering.
Release-level Share — new scope; a Cut/Session/Mix header Share shares the release URL.
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 `<a href="/{DetailRoute}/{id}">`. 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:

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.
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.
/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).

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.)
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.
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.)
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).
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.)
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.)
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.

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 NavigateTos 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 <a href> 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:

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.
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.

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.

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<TrackDto> 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:

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.
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.
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<TrackDto> Items          // ordered; the release's tracks for "play album"
  int CurrentIndex                        // -1 when empty
  TrackDto? Current => Items[CurrentIndex]
  bool HasNext / HasPrevious
  PlayRelease(IEnumerable<TrackDto> tracks, int startIndex = 0)   // Cuts header Play / row Play
  Enqueue(TrackDto) / EnqueueRange(IEnumerable<TrackDto>)
  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).

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):

§3 — /cuts/{id} exists.
§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.
§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<ReleaseDto, string>? 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)

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.
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

Player-bar title target (§2). DECIDED: the title click resolves release detail via the resolver, replacing the /track/{EntryKey} link. (Was OQ1.)
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.)
/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.)
Release-level Share (§3b). DECIDED: in scope. SharePopover gains a release-keyed mode. (Was an adjacent gap; promoted.)
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)

/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.
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.
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.
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.
/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.

64 KiB Raw Blame History Unescape Escape