deepdrft/product-notes/phase-17-player-queue-view.md at 90555dc4e0fcadefb84cefd6cfa7b965acef6d72

Files

T

daniel-c-harvey 90555dc4e0 docs: spec Phase 17 player-bar queue view (queue button, overlay/embed modes, add-to-queue)

2026-06-19 13:29:57 -04:00

25 KiB

Raw Blame History

Status: design spec — open questions pending Daniel. Author: product-designer. Date: 2026-06-19. Plan only — no code has been written by this doc.

This phase makes the play-queue visible and manipulable. Phase 11 (wave 11.F) built the queue engine (IQueueService / QueueService) and wired auto-advance, skip-prev/next, and release embeds — but the queue itself has no UI. A listener can start an album and skip through it, but cannot see what is next, reorder it, drop a track, or hand-build a queue. This phase surfaces it.

Cross-references (read before implementing):

PLAN.md §17 — the concise phase entry.
DeepDrftPublic.Client/Services/IQueueService.cs / QueueService.cs — the engine this phase drives. Its docstrings already anticipate reorder + removal as additive members (see §1).
DeepDrftPublic.Client/Controls/AudioPlayerBar/AudioPlayerBar.razor[.cs] — the bar that gains the Queue button + (Fixed) the embedded panel.
DeepDrftPublic.Client/Controls/AudioPlayerBar/PlayerControls.razor / PlayerTransportZone.razor — where transport buttons live; the Queue button sits relative to these.
DeepDrftPublic.Client/Controls/AudioPlayerProvider.razor[.cs] — cascades the queue (IsFixed). Player + queue state stays here, at layout level (project memory; do not move into pages).
DeepDrftPublic.Client/Pages/FramePlayer.razor + Layout/EmbedLayout.razor — the Fixed/embed surface; the iframe-host sizing constraint lives here (§4).
DeepDrftPublic.Client/Controls/SharePopover.razor / WaveformVisualizerControlPopover.razor — the established overlay/dismissal idioms to borrow for the non-Fixed overlay (§3).
DeepDrftPublic.Client/Pages/CutDetail.razor, Controls/ReleaseHeroOverlay.razor, Controls/ReleaseGallery.razor, Controls/StreamNowButton.razor — the play-affordance sites the "Add to Queue" button (§5) attaches beside.

0. State it inherits (verified 2026-06-19)

The queue engine is mature and complete for orchestration:

IQueueService exposes Items (IReadOnlyList<TrackDto>), CurrentIndex, Current, HasNext, HasPrevious, IsArmed, the QueueChanged event, and commands PlayRelease, Arm, Start, Enqueue, EnqueueRange, Next, Previous, Clear. There is no reorder or remove member yet — but the interface docstring explicitly reserves them as additive ("reordering mutates Items and re-emits QueueChanged"). This phase adds them.
The queue is cascaded from AudioPlayerProvider as an IsFixed cascade alongside the player.
AudioPlayerBar already subscribes to QueueChanged to re-render skip affordances, and reads HasNext/HasPrevious. Adding a Queue button + panel is the same subscription, more rendering.
Fixed (AudioPlayerBar.Fixed) is the embed flag, set true by FramePlayer via EmbedLayout. In Fixed mode the bar is in normal flow (no minimize/spacer/clip); the host iframe is sized by the embed snippet (EmbedSnippetBuilder). Today a release embed arms a shared queue; a single-track embed leaves the queue empty.
"Shared queue" today = a multi-track release loaded via PlayRelease (docked) or Arm/Start (embed). The queue is populated from one release's ordered tracks. There is no hand-assembled multi-source queue yet — Enqueue/EnqueueRange exist on the interface but no UI calls them.

The gap this phase closes: the queue is a black box. You can drive it (skip) but not inspect or edit it. Item 4 ("Add to Queue") also activates the dormant Enqueue path — the first time the queue becomes a thing a listener builds, not just a release they play.

1. Goal

Make the queue a first-class, visible, editable object in the player bar — without moving any player or queue state out of the layout-level provider, and without changing the streaming/playback seam.

Three user-visible capabilities, gated by a single new Queue toggle button in the bar:

See the queue — an ordered list of what is queued, with the current track marked.
Edit the queue (where editing is allowed) — drag-reorder and per-track removal.
Grow the queue — an "Add to Queue" affordance everywhere there is a play button.

The two view modes (overlay vs. embedded panel) differ only in presentation and edit-permission, not in the data they read — both bind the same cascaded IQueueService.Items (project memory: one source, multiple views).

2. Constraints (hard)

C1 — Player/queue state stays at layout level. The Queue view reads the cascaded IQueueService; it does not own or relocate queue state. No page-level player state. (Project memory.)
C2 — No new playback semantics. Reorder/remove mutate Items + CurrentIndex and re-emit QueueChanged; they must not restart, re-stream, or interrupt the currently-playing track (matching the engine's existing "the player stays a single-track device" posture). Reordering the currently-playing item or items around it must keep playback uninterrupted.
C3 — Embed = read-only shared queue. In Fixed (embed) mode, a shared (release) queue is fixed-order and non-editable: no drag, no remove. The panel is a display of the up-next list.
C4 — The engine is extended additively, never reshaped. New members (Move/RemoveAt) are added to IQueueService; existing members and their contracts are untouched. Consumers written against today's surface keep working (the interface's stated open/closed posture).
C5 — Reorder/remove are interop-free state mutations. Like Enqueue/Arm, they touch only the in-memory list + index + QueueChanged. They run safely during prerender. Only PlayRelease/ Start/Next/Previous touch JS.
C6 — Drag-and-drop must be touch-viable. The public site's primary listening surface includes mobile (per PLAN.md §1.7). Whatever DnD mechanism is chosen must work with touch, or the design must offer a non-drag fallback for reordering (up/down affordance). Flag — see OQ4.
C7 — Embedded panel must not break the iframe host. Adding the panel in Fixed mode grows the player's intrinsic height; the embed snippet's iframe dimensions must account for it (§4, OQ6).

3. Item 1+2 — Queue button & non-Fixed (overlay) mode

3.1 The Queue button

A new icon button in the player bar, shown only when a queue is loaded (Items.Count > 0). Mirror the existing skip-affordance gating: with no queue (null) or empty queue, the button is absent, so the bar is byte-for-byte its pre-queue self for single-track play.

Placement (Daniel): to the left of the timestamps and below the other player control buttons. Today PlayerTransportZone is a vertical MudStack of (transport-button row) over (TimestampLabel). The Queue button sits between those two — a second row below the play/skip controls and above the timestamp. That literally satisfies "below the control buttons, to the left of the timestamps."
Glyph: Icons.Material.Filled.QueueMusic (or a bespoke DDIcons queue glyph if Daniel wants the hand-rolled aesthetic — OQ7). Color.Primary to match the transport row.
Active state: when the overlay/panel is open, the button reads active (filled/highlighted), matching the visualizer popover idiom.

3.2 Non-Fixed overlay panel

When the bar is not Fixed (the docked public player), clicking Queue toggles a screen-centered overlay — borrow the exact idiom Phase 15 settled on for the visualizer controls: MudOverlay (DarkBackground, Modal), panel stops click propagation, scrim-click closes, drag-safe (a position:fixed drag capture sits above the scrim so a drag that ends outside the panel does not dismiss). Not a MudPopover anchored to the bar — a centered modal is the proven pattern here and avoids anchor math against a position:fixed dock.

Shape: "mostly square" (Daniel) — a panel roughly min(90vw, 520px) square, scrollable track list inside. Chrome matches NowPlayingCard / the visualizer panel (square corners, lighter-navy, thin border) for family resemblance.
Contents: ordered list of Items. Each row: drag handle, track number/position, track name + artist, a now-playing marker on Current (index == CurrentIndex), a remove (×) button. Clicking a row's body jumps playback to that track (PlayRelease(Items, thatIndex) — reuses the existing "play from index" semantics; OQ2 confirms this is desired vs. a dedicated jump).
Reorder: drag-and-drop reordering of rows → IQueueService.Move(from, to) (new member, §6).
Remove: per-row × → IQueueService.RemoveAt(index) (new member, §6).
Header: title ("Queue" / "Up Next"), optional "Clear" action (calls existing Clear(); OQ5 — does Clear belong in the UI, and does it stop playback?).
Empty state: the button is hidden when empty, so the overlay is never opened empty by the button. But removal can empty a non-empty queue mid-session — define the terminal state (OQ3).

3.3 Borrowed precedent

The overlay shell, dismissal, and drag-safety are a direct lift of WaveformVisualizerControlPopover (Phase 15 §4). The "mostly square panel, family chrome" is the NowPlayingCard look. Reuse, don't reinvent.

4. Item 3 — Fixed (embedded) mode

When the bar is Fixed (the /FramePlayer iframe embed), the queue list is always shown below the existing player-bar controls — not a toggle overlay. It is part of the embed's standing layout.

Permissions (C3): the embedded shared (release) queue is fixed-order, non-editable — no drag handles, no remove buttons. It is a read-only up-next display: ordered track list, current track marked, future tracks listed. Tapping a future row may jump to it (OQ2 — even read-only queues could allow jump-to-track; reorder/remove are the forbidden ops, jump is arguably fine).
Container resize (C7): the Fixed bar gains vertical height for the panel. Two coupled changes:
1. The EmbedLayout / FramePlayer Fixed bar renders the panel inline below the controls.
2. EmbedSnippetBuilder.ForRelease(...) must mint an iframe tall enough to show the panel. ForTrack(...) stays at today's compact height (single-track embeds have no queue, so no panel). This makes the two embed snippets diverge in height — track-embed compact, release-embed taller. That is correct: only release embeds have a queue to show. (OQ6 — fixed taller height for all release embeds, vs. a height that scales with track count up to a cap. Recommend: a fixed sensible height with the panel internally scrollable past N rows.)

4.1 The Queue button in embed mode (Daniel asked to clarify)

Recommendation: in Fixed mode the panel is always shown, so the Queue button is not needed for toggling — but rather than hide it, repurpose it as a collapse/expand control for the panel so a listener can reclaim the iframe space. Two viable readings, pick one:

Option A (recommend) — collapse toggle. Queue button is present in Fixed mode and collapses/expands the always-default-open panel. Default = expanded. Gives the embedder's viewer control without changing the snippet height (collapsed just shows less; the iframe stays sized for expanded). Consistent button meaning across modes ("toggle the queue view").
Option B — omit the button in Fixed mode entirely. Panel is always open, no toggle. Simpler, but the button's meaning then differs by mode (present+toggles-overlay when docked, absent when embedded), and a viewer can't reclaim space.

This is OQ1 — Daniel's call. The brief explicitly flagged it.

5. Item 4 — "Add to Queue" affordance

An "Add to Queue" icon button with a tooltip beside every play button for a release or track.

Glyph + tooltip: Icons.Material.Filled.QueueMusic / PlaylistAdd with MudTooltip "Add to queue" (track) / "Add release to queue" (release). (OQ7 — Material vs. bespoke glyph.)
Behavior:
- Track context: IQueueService.Enqueue(track) — appends without disturbing current playback (existing member, no UI calls it today; this lights it up).
- Release context: IQueueService.EnqueueRange(orderedTracks) — appends the whole release's ordered track list (existing member).
First-add semantics (define): if the queue is empty/dormant (CurrentIndex == -1), what does "Add to Queue" do? Enqueue appends but does not set a current index or start playback, so adding to an empty queue leaves it with items but Current == null and nothing playing. Options: (a) pure append, listener must press play; (b) if dormant, first add also stages/sets current without auto-playing; (c) if dormant, first add behaves like PlayRelease/play. Recommend (a) — Add-to-Queue is explicitly not play; keep the verbs distinct. But this needs a tiny engine affordance so an appended-into-empty queue has a sensible CurrentIndex for the next skip/play. OQ8.

5.1 Where the button attaches (inventory)

Every site that currently has a play affordance:

Site	Current play affordance	Add-to-Queue target
`CutDetail` header	"Play" `MudButton` (whole album)	release → `EnqueueRange`
`CutDetail` track rows	per-row `PlayStateIcon`	track → `Enqueue`
`SessionDetail` / `MixDetail`	`PlayContent` slot in `ReleaseHeroOverlay` (single track)	track → `Enqueue`
`StreamNowButton`	random-track stream trigger	edge case — OQ9 (random has no fixed track until resolved)
`ReleaseGallery` cards	none today (cards are pure links)	scope question — OQ10

ReleaseGallery cards have no play button today — they navigate to detail. Adding an Add-to-Queue button there is new affordance, arguably out of the literal brief ("anywhere there is a play button"). OQ10 — do cards get one? If yes, they probably want a play button too, which is a bigger card-redesign question. Recommend: defer card-level affordances; scope item 4 to the detail-page play sites (rows 1–3 above) where a play button genuinely exists today.
StreamNowButton is a "surprise me" trigger, not a fixed track — Add-to-Queue has no concrete item until a track resolves. Recommend: exclude it from item 4. OQ9.

So the grounded scope of item 4: the CutDetail header + track rows, and the Session/Mix hero play slot. That is "every play button that targets a known release or track."

6. Engine additions (the only `IQueueService` changes)

Two new members, both interop-free state mutations that re-emit QueueChanged:

void Move(int fromIndex, int toIndex) — reorders Items; adjusts CurrentIndex so the same track stays current across the move (find current track's new position). No re-stream (C2). No-op on out-of-range or equal indices.
void RemoveAt(int index) — removes Items[index].
- Removing a track after current: just remove; CurrentIndex unchanged.
- Removing a track before current: remove + decrement CurrentIndex (current track stays the same item, new lower index). Playback uninterrupted.
- Removing the current track: define — recommend stop is not triggered (C2 says mutations don't touch playback), so the playing track keeps playing to its natural end even though it's no longer in the list, and CurrentIndex points at what is now at that slot (the next track) so the next auto-advance / skip is coherent. Edge: removing current when it's the last item → queue becomes shorter; auto-advance simply has nothing to advance to (existing behavior). OQ3/OQ11.
- Removing the last remaining track → empty queue (CurrentIndex = -1, dormant). The Queue button disappears; if the overlay is open it closes (or shows empty state then closes). OQ3.

Both are additive (C4). Unit-testable against the existing QueueServiceTests fake-player harness with no container (the engine's stated design intent).

7. Use cases

UC1 — Inspect up-next (docked). Listener playing an album opens the Queue overlay, sees the ordered remaining tracks with the current one marked, closes it. No edit.
UC2 — Reorder (docked). Listener drags track 5 above track 2; playback continues uninterrupted; the new order drives the next auto-advance.
UC3 — Remove (docked). Listener removes a track they don't want; if it was upcoming, it's gone from the up-next; if it was current, current keeps playing to natural end (per §6).
UC4 — Build a queue (docked). Listener on a Cut detail page clicks "Add to Queue" on three individual tracks across two albums, then opens the queue and plays from the top.
UC5 — Embed up-next (Fixed). A blog embeds a release; the iframe shows the player and the fixed-order track list below it; viewer sees what's coming, cannot reorder/remove; (Option A) collapses the panel to reclaim space.
UC6 — Single-track embed unchanged. A single-track embed shows no Queue button and no panel — the compact iframe is byte-for-byte today's.
UC7 — Jump to track. Listener clicks a queued row → playback jumps to that track and continues from there (if OQ2 = yes).

8. Acceptance criteria

AC1 — When Items.Count == 0, the Queue button is absent and the docked bar renders exactly as it does today (no layout shift, no empty panel).
AC2 — When Items.Count > 0 and not Fixed, the Queue button appears below the transport controls and to the left of the timestamp; clicking it opens a centered, mostly-square overlay listing the queue with the current track marked.
AC3 (docked) — Drag-reordering a row changes the queue order and is reflected in subsequent skip/auto-advance; the currently-playing track is not re-streamed or interrupted by any reorder.
AC4 (docked) — Removing an upcoming track removes it from the list and from auto-advance; removing a track before the current one keeps the same track playing; removing the current track does not stop playback (per §6 decision).
AC5 (Fixed) — In a release embed, the queue panel renders below the controls by default, shows the ordered tracks with the current marked, and exposes no drag handles or remove buttons.
AC6 (Fixed) — The release embed iframe (via EmbedSnippetBuilder.ForRelease) is tall enough to show the panel without clipping; the single-track embed (ForTrack) height is unchanged.
AC7 — An "Add to Queue" button with tooltip appears beside the Cut header Play, each Cut track row's play, and the Session/Mix hero play; clicking it appends the track/release to the queue without disturbing the currently-playing track.
AC8 — Add-to-Queue on a dormant (empty) queue leaves the queue populated with a coherent CurrentIndex such that the next play/skip behaves correctly (per OQ8 resolution).
AC9 — Move and RemoveAt are additive to IQueueService; all existing QueueServiceTests pass unchanged; no existing member's behavior changes.
AC10 — All queue-view rendering and the new engine mutations run during prerender without JS interop (no prerender exceptions); only playback transitions touch JS.

9. Test cases

Engine (QueueServiceTests, fake-player harness — no container):

T1 Move(2, 0) on a 4-item queue reorders correctly; Items reflects new order; QueueChanged fired once.
T2 Move keeps the current track current: with CurrentIndex at track X, moving other items around it leaves Current == X; moving X itself updates CurrentIndex to X's new slot.
T3 Move does not call the player's stream method (assert fake player saw no SelectTrackStreaming).
T4 RemoveAt after current: CurrentIndex unchanged, item gone.
T5 RemoveAt before current: CurrentIndex decremented, same track current.
T6 RemoveAt of current: player not stopped (per §6); CurrentIndex resolves to the new occupant or -1 if it was last.
T7 RemoveAt of last remaining item → empty + dormant (CurrentIndex == -1, Items empty, QueueChanged fired).
T8 Move/RemoveAt out-of-range / no-op cases do not throw and do not fire QueueChanged.
T9 Enqueue into a dormant queue then play behaves per OQ8 resolution.
T10 Reordering the currently-playing item to a new slot leaves auto-advance pointing at the correct next track when the current ends.

Component (if/when component test coverage is in scope — today none exists for the client, per DeepDrftPublic.Client/CLAUDE.md):

T11 Queue button absent when queue empty (render assertion).
T12 Overlay opens/closes via button + scrim; a simulated drag that ends on the scrim does not dismiss.
T13 Fixed-mode panel renders inline with no drag/remove controls.
T14 EmbedSnippetBuilder.ForRelease height differs from ForTrack (unit test on the builder).

10. Open questions for Daniel

OQ1 — Queue button in embed (Fixed) mode. Panel is always shown there. Option A: keep the button as a collapse/expand toggle (recommend). Option B: omit the button entirely. Daniel's call — explicitly flagged in the brief.
OQ2 — Click-to-jump. Does clicking a queued row jump playback to that track? Recommend yes in both modes (reuses PlayRelease(Items, index)); jump is not a forbidden edit, only reorder/ remove are. Confirm for the read-only embed too.
OQ3 — Terminal/empty states. When removal empties the queue mid-session: close the overlay? Show an empty state then auto-close? And when the current track is removed, what should the panel and the player show?
OQ4 — Drag-and-drop mechanism & touch. MudBlazor has MudDropContainer (HTML5 DnD, weak on touch) vs. a JS-interop pointer-drag (like RadialKnob's capturePointer) vs. a non-drag up/down-arrow reorder fallback. Mobile is a primary surface (C6). Which mechanism? Recommend: pointer-based interop reorder (touch-viable, matches the codebase's existing pointer-capture pattern) or ship up/down arrows for v1 and add drag later. Daniel's taste call.
OQ5 — "Clear queue" in the UI. Include a Clear action in the overlay header? Does Clear stop playback or just empty the up-next (engine's Clear does not stop the player today)?
OQ6 — Embed panel height. Fixed sensible height with internal scroll past N rows (recommend), vs. height that grows with track count up to a cap. Affects EmbedSnippetBuilder.ForRelease.
OQ7 — Glyph. Material QueueMusic/PlaylistAdd, or a bespoke hand-rolled DDIcons queue glyph to match the gas-lamp/lava-lamp family aesthetic?
OQ8 — Add-to-Queue into a dormant (empty) queue. Pure append (recommend — keep "add" ≠ "play"), vs. first-add also stages current, vs. first-add plays. Affects the engine's index handling.
OQ9 — StreamNowButton. Exclude from Add-to-Queue (recommend — no fixed track until resolved)?
OQ10 — ReleaseGallery cards. Do browse-grid cards get an Add-to-Queue (and implicitly a play) button? Recommend defer — cards have no play button today; adding one is a card redesign beyond this brief. Scope item 4 to the detail-page play sites.
OQ11 — Removing the current track. Confirm the recommended "keep playing to natural end, don't stop" behavior (C2-consistent) vs. "removing current skips to next immediately."

11. Wave decomposition (implementation sequencing)

Three waves; 17.1 is the load-bearing prerequisite (engine + the shared queue-list view that both modes render). 17.2 and 17.3 then hang off it and are largely parallel.

17.1 — Engine additions + shared queue-list view. Add Move/RemoveAt to IQueueService/ QueueService (+ QueueServiceTests). Build a single presentational QueueList component that renders Items with the current marked and takes an Editable flag (drag/remove on when true). This is the one source both modes consume. Cold-start. Gates 17.2 + 17.3. No bar changes yet.
17.2 — Non-Fixed overlay. Queue button in the bar (gated on Items.Count > 0, placed per §3.1), the centered overlay borrowing the visualizer-popover idiom, hosting QueueList Editable. Reorder/remove/jump wired. Depends on 17.1.
17.3 — Fixed embed panel + snippet resize + Add-to-Queue. Inline QueueList (non-editable) below the Fixed bar; the (OQ1) button behavior; EmbedSnippetBuilder.ForRelease height bump; the Add-to-Queue buttons at the detail-page play sites (§5.1 grounded scope). Depends on 17.1. (Add-to-Queue could split into its own wave 17.4 if Daniel wants it shipped independently — it only needs the existing Enqueue/EnqueueRange, not 17.1's new members.)

Dependency shape: 17.1 → {17.2, 17.3}. The cold-start item is 17.1. Most open questions (OQ1–OQ11) must be resolved before 17.2/17.3 land, but 17.1 can begin immediately — the engine contract for Move/RemoveAt is settled (§6) and independent of the UI decisions.

25 KiB Raw Blame History Unescape Escape

Phase 17 — Player-Bar Queue View