yellowjacket/.planning/quick/9-fix-queue-panel-scroll-bar-not-following/9-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, must_haves

phase	plan	type	wave	depends_on	files_modified	autonomous	must_haves
quick-9	01	execute	1		frontend/src/components/queue-panel/queue-panel.ts	true	truths artifacts key_links 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) path provides frontend/src/components/queue-panel/queue-panel.ts Fixed-height queue track items for stable virtualizer scroll size from to via pattern queue-panel .track-item CSS lit-virtualizer flow layout _scrollSize Fixed item height ensures stable average size calculation height:.*px.*overflow.*hidden

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.

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

@frontend/src/components/queue-panel/queue-panel.ts @frontend/src/styles/tokens.css.ts

From node_modules/@lit-labs/virtualizer/layouts/flow.js:

// _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:

--yj-text-xs: 11px;   // artist font
--yj-text-sm: 12px;   // position number font
--yj-text-md: 13px;   // title font

Task 1: Set fixed height on queue track items and contain overflow frontend/src/components/queue-panel/queue-panel.ts 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):

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

    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:

.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 cd frontend && npx tsc --noEmit 2>&1 | head -20
  • .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

Fixed-height queue items to stabilize virtualizer scroll size estimation on large queues 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 Type "approved" or describe any remaining scroll issues or visual problems - Queue panel scrollbar tracks mouse 1:1 in both directions on 20k+ track queue - No visual regression in track item appearance - TypeScript compiles cleanly

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

After completion, create `.planning/quick/9-fix-queue-panel-scroll-bar-not-following/9-SUMMARY.md`