docs(quick-9): complete fix queue panel scroll bar plan
- Add 9-SUMMARY.md with execution results - Update STATE.md with quick task 9 entry
This commit is contained in:
+5
-4
@@ -56,17 +56,18 @@ Decisions from v1.0 are archived in PROJECT.md Key Decisions table. Key patterns
|
||||
| 006 | Remove list icon, add favorites icon | 2026-03-01 | 3c19766 |
|
||||
| 007 | Pin default playlist to top | 2026-03-01 | e6378e1 |
|
||||
| 008 | Duplicate tracks dialog | 2026-03-01 | 917a79a |
|
||||
| 009 | Fix queue panel scroll bar not following mouse | 2026-03-05 | ebde5e5 |
|
||||
|
||||
## Session Continuity
|
||||
|
||||
### Last Session
|
||||
|
||||
**Date:** 2026-03-05
|
||||
**What happened:** Completed v1.0 milestone — archived roadmap, requirements, and phase directories to milestones/. Updated PROJECT.md, ROADMAP.md, RETROSPECTIVE.md. Tagged v1.0.
|
||||
**Where we stopped:** Milestone v1.0 shipped.
|
||||
**Next action:** `/gsd-new-milestone` to define next milestone
|
||||
**What happened:** Quick task 9 — fixed queue panel scrollbar not following mouse on large queues by setting fixed height on track items.
|
||||
**Where we stopped:** Completed quick-9 plan. Needs human verification of scrollbar behavior.
|
||||
**Next action:** Verify scrollbar tracks mouse 1:1 on 20k+ queue, then `/gsd-new-milestone`
|
||||
|
||||
---
|
||||
*State initialized: 2026-02-27*
|
||||
Last activity: 2026-03-05 - v1.0 Consolidation milestone shipped
|
||||
Last activity: 2026-03-05 - Quick task 9: fix queue panel scroll bar
|
||||
*Last updated: 2026-03-05*
|
||||
|
||||
@@ -0,0 +1,168 @@
|
||||
---
|
||||
phase: quick-9
|
||||
plan: 01
|
||||
type: execute
|
||||
wave: 1
|
||||
depends_on: []
|
||||
files_modified:
|
||||
- frontend/src/components/queue-panel/queue-panel.ts
|
||||
autonomous: true
|
||||
must_haves:
|
||||
truths:
|
||||
- "Scrollbar tracks mouse position 1:1 when dragging DOWN on 20k+ track queue"
|
||||
- "Scrollbar still tracks mouse 1:1 when dragging UP"
|
||||
- "Queue items still display correctly (title, artist, position number)"
|
||||
artifacts:
|
||||
- path: "frontend/src/components/queue-panel/queue-panel.ts"
|
||||
provides: "Fixed-height queue track items for stable virtualizer scroll size"
|
||||
key_links:
|
||||
- from: "queue-panel .track-item CSS"
|
||||
to: "lit-virtualizer flow layout _scrollSize"
|
||||
via: "Fixed item height ensures stable average size calculation"
|
||||
pattern: "height:.*px.*overflow.*hidden"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Fix queue panel scrollbar not following mouse 1:1 when dragging down on large queues (20k+ tracks).
|
||||
|
||||
Purpose: The root cause is lit-virtualizer's flow layout dynamically recalculating `_scrollSize` based on measured item averages. With 20k items but only ~15-20 measured at any time, the initial item size estimate (100px default) vs actual size (~48px) causes the scroll height to shrink dramatically as items get measured during downward scrolling. This makes the scrollbar thumb "lag" behind the mouse because the scroll container height keeps changing underneath the drag. Going UP works because those items are already measured and stable.
|
||||
|
||||
The fix is to set a fixed, explicit height on `.track-item` elements so that all items have identical measured heights from the very first render. This makes `_scrollSize = items.length * (averageMargin + averageSize) + averageMargin` completely stable because the average never changes — it equals the actual size of every item.
|
||||
|
||||
Output: Stable scrollbar behavior on large queues.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@/home/caleb/.config/Claude/get-shit-done/workflows/execute-plan.md
|
||||
@/home/caleb/.config/Claude/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@frontend/src/components/queue-panel/queue-panel.ts
|
||||
@frontend/src/styles/tokens.css.ts
|
||||
|
||||
<interfaces>
|
||||
<!-- lit-virtualizer flow layout internals (read-only, in node_modules) -->
|
||||
<!-- DO NOT modify these files — understanding only -->
|
||||
|
||||
From node_modules/@lit-labs/virtualizer/layouts/flow.js:
|
||||
```javascript
|
||||
// _scrollSize is computed from average of MEASURED items only:
|
||||
_updateScrollSize() {
|
||||
const { averageMarginSize } = this._metricsCache;
|
||||
this._scrollSize = Math.max(1,
|
||||
this.items.length * (averageMarginSize + this._getAverageSize()) + averageMarginSize);
|
||||
}
|
||||
|
||||
// Initial estimate before any measurements:
|
||||
this._itemSize = { width: 100, height: 100 }; // <-- way off from actual ~48px
|
||||
|
||||
// Average comes from SizeCache which only has measured (visible) items:
|
||||
_getAverageSize() {
|
||||
return this._metricsCache.averageChildSize || this._itemSize[this._sizeDim];
|
||||
}
|
||||
```
|
||||
|
||||
From frontend/src/styles/tokens.css.ts:
|
||||
```typescript
|
||||
--yj-text-xs: 11px; // artist font
|
||||
--yj-text-sm: 12px; // position number font
|
||||
--yj-text-md: 13px; // title font
|
||||
```
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: Set fixed height on queue track items and contain overflow</name>
|
||||
<files>frontend/src/components/queue-panel/queue-panel.ts</files>
|
||||
<action>
|
||||
In the `queue-panel.ts` static styles, add a fixed `height` and `overflow: hidden` to the `.track-item` CSS rule. This ensures every queue item has an identical pixel height, which makes lit-virtualizer's `_scrollSize` calculation stable from the first render (the average of N identical measurements equals the measurement itself).
|
||||
|
||||
**Current `.track-item` CSS** (around line 273):
|
||||
```css
|
||||
.track-item {
|
||||
position: relative;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
padding: 8px 16px;
|
||||
gap: 12px;
|
||||
border-bottom: 1px solid var(--yj-hover-overlay, rgba(255, 255, 255, 0.05));
|
||||
cursor: default;
|
||||
user-select: none;
|
||||
width: 100%;
|
||||
box-sizing: border-box;
|
||||
}
|
||||
```
|
||||
|
||||
**Add these properties to `.track-item`:**
|
||||
```css
|
||||
height: 49px;
|
||||
overflow: hidden;
|
||||
```
|
||||
|
||||
Height calculation: The content is two text lines (13px title at ~1.2 line-height = ~16px, 11px artist at ~1.2 line-height = ~13px) with 2px gap = ~31px content. Add 8px + 8px vertical padding = 47px. Plus 1px border-bottom = 48px total box. Setting `height: 49px` gives 1px breathing room for sub-pixel rounding (the `border-bottom` is outside the height due to `box-sizing: border-box` including it — actually border-box INCLUDES the border in height, so 49px = 8px pad-top + ~32px content + 8px pad-bottom + 1px border = 49px total).
|
||||
|
||||
**IMPORTANT:** After setting this, verify the actual rendered height matches by loading the app with a queue of tracks and inspecting a `.track-item` in DevTools. If the actual measured height differs from 49px, adjust accordingly. The critical requirement is that ALL items have the SAME fixed height — the exact value matters less than uniformity.
|
||||
|
||||
Also add `overflow: hidden` on `.track-details` to ensure long titles/artists don't cause any height variation:
|
||||
```css
|
||||
.track-details {
|
||||
flex: 1;
|
||||
min-width: 0;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: 2px;
|
||||
overflow: hidden; /* add this */
|
||||
}
|
||||
```
|
||||
|
||||
**Do NOT:**
|
||||
- Change the flow layout or virtualizer configuration — the fix is pure CSS
|
||||
- Add `min-height` or `max-height` — use only `height` for exact sizing
|
||||
- Change padding, gap, or font sizes — only add the `height` and `overflow` properties
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd frontend && npx tsc --noEmit 2>&1 | head -20</automated>
|
||||
</verify>
|
||||
<done>
|
||||
- `.track-item` has explicit fixed `height: 49px` and `overflow: hidden`
|
||||
- `.track-details` has `overflow: hidden`
|
||||
- All queue items render at identical pixel heights
|
||||
- TypeScript compiles without errors
|
||||
</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking">
|
||||
<what-built>Fixed-height queue items to stabilize virtualizer scroll size estimation on large queues</what-built>
|
||||
<how-to-verify>
|
||||
1. Start the app with a large queue (20k+ tracks)
|
||||
2. Click the scrollbar thumb in the queue panel and drag it DOWNWARD slowly
|
||||
3. Verify the scrollbar follows your mouse position 1:1 (no lag, no fixed-speed movement)
|
||||
4. Drag the scrollbar UP — verify it still follows 1:1 (regression check)
|
||||
5. Scroll rapidly up and down — verify smooth, consistent behavior
|
||||
6. Verify track items still look correct (no clipped text, proper spacing)
|
||||
7. Inspect a `.track-item` in DevTools — confirm all visible items have identical height (49px or whatever the final value is)
|
||||
8. If the items look too cramped or too tall, adjust the `height` value and re-test
|
||||
</how-to-verify>
|
||||
<resume-signal>Type "approved" or describe any remaining scroll issues or visual problems</resume-signal>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
- Queue panel scrollbar tracks mouse 1:1 in both directions on 20k+ track queue
|
||||
- No visual regression in track item appearance
|
||||
- TypeScript compiles cleanly
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- Scrollbar follows mouse position proportionally when dragging in both directions
|
||||
- Works correctly on queues with 20k+ tracks
|
||||
- No visual layout changes to queue track items
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/quick/9-fix-queue-panel-scroll-bar-not-following/9-SUMMARY.md`
|
||||
</output>
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
phase: quick-9
|
||||
plan: 01
|
||||
subsystem: frontend/queue-panel
|
||||
tags: [bugfix, css, virtualizer, scrollbar]
|
||||
dependency-graph:
|
||||
requires: []
|
||||
provides: [stable-queue-scrollbar]
|
||||
affects: [queue-panel]
|
||||
tech-stack:
|
||||
patterns: [fixed-height-virtualizer-items]
|
||||
key-files:
|
||||
modified:
|
||||
- frontend/src/components/queue-panel/queue-panel.ts
|
||||
decisions:
|
||||
- Fixed height of 49px chosen (8px pad-top + ~32px content + 8px pad-bottom + 1px border = 49px with border-box)
|
||||
metrics:
|
||||
duration: 43s
|
||||
completed: "2026-03-05"
|
||||
---
|
||||
|
||||
# Quick Task 9: Fix Queue Panel Scroll Bar Not Following
|
||||
|
||||
**One-liner:** Fixed-height queue track items (49px) to stabilize lit-virtualizer scroll size estimation on large (20k+) queues, eliminating scrollbar thumb lag when dragging downward.
|
||||
|
||||
## What Was Done
|
||||
|
||||
### Task 1: Set fixed height on queue track items and contain overflow
|
||||
**Commit:** `ebde5e5`
|
||||
|
||||
Added `height: 49px` and `overflow: hidden` to `.track-item` CSS rule, and `overflow: hidden` to `.track-details` CSS rule in `queue-panel.ts`.
|
||||
|
||||
**Root cause:** lit-virtualizer's flow layout computes `_scrollSize` from the average of *measured* items only. With 20k items but only ~15-20 visible at any time, the initial estimate (100px default) vs actual size (~48px) caused the scroll container height to shrink dramatically during downward scrolling as items got measured. This made the scrollbar thumb "lag" behind the mouse because the scroll height kept changing underneath the drag.
|
||||
|
||||
**Fix:** Setting a fixed explicit height ensures every item's measured height is identical from the very first render. The formula `_scrollSize = items.length * (averageMargin + averageSize) + averageMargin` becomes completely stable because the average never changes — it equals the actual (fixed) size of every item.
|
||||
|
||||
**Files modified:**
|
||||
- `frontend/src/components/queue-panel/queue-panel.ts` — Added `height: 49px; overflow: hidden` to `.track-item`, added `overflow: hidden` to `.track-details`
|
||||
|
||||
### Task 2: Human Verification (checkpoint)
|
||||
**Status:** Needs human verification
|
||||
|
||||
Verification steps:
|
||||
1. Start the app with a large queue (20k+ tracks)
|
||||
2. Click the scrollbar thumb in the queue panel and drag it DOWNWARD slowly
|
||||
3. Verify the scrollbar follows mouse position 1:1 (no lag, no fixed-speed movement)
|
||||
4. Drag the scrollbar UP — verify it still follows 1:1 (regression check)
|
||||
5. Scroll rapidly up and down — verify smooth, consistent behavior
|
||||
6. Verify track items still look correct (no clipped text, proper spacing)
|
||||
7. Inspect a `.track-item` in DevTools — confirm all visible items have identical height (49px)
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
None — plan executed exactly as written.
|
||||
|
||||
## Verification
|
||||
|
||||
- [x] TypeScript compiles cleanly (`npx tsc --noEmit` passes)
|
||||
- [x] `.track-item` has explicit fixed `height: 49px` and `overflow: hidden`
|
||||
- [x] `.track-details` has `overflow: hidden`
|
||||
- [ ] Scrollbar tracks mouse 1:1 in both directions on 20k+ track queue (needs human verification)
|
||||
- [ ] No visual regression in track item appearance (needs human verification)
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- FOUND: `frontend/src/components/queue-panel/queue-panel.ts`
|
||||
- FOUND: commit `ebde5e5`
|
||||
- FOUND: `9-SUMMARY.md`
|
||||
Reference in New Issue
Block a user