docs(08): capture phase context
This commit is contained in:
@@ -0,0 +1,89 @@
|
||||
# Phase 8: Frontend Performance & UX - Context
|
||||
|
||||
**Gathered:** 2026-03-04
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
Make the app feel smooth and visually consistent — large libraries (10k+ tracks) render without jank during scrolling, view switching, and search filtering, and the UI follows a coherent visual language across all components. This is the final phase of the consolidation milestone.
|
||||
|
||||
Performance work targets: Lit `repeat()` directive with stable keys for DOM reuse, `queueMicrotask()` debouncing for store notifications during rapid updates. Visual work targets: audit and fix spacing, colors, typography, and icon sizing inconsistencies.
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
### Visual consistency scope
|
||||
- Full audit of every component — check for hardcoded colors, inconsistent spacing, mismatched typography, and icon sizing
|
||||
- Systematic pass, not just known issues
|
||||
|
||||
### Spacing units
|
||||
- Converge all components to px-based spacing (not em/rem)
|
||||
- The sidebar currently uses em-based spacing (padding: 0.5em, gap: 0.6em) — convert to px
|
||||
- Track-list and cover-grid already use px — these are the reference pattern
|
||||
|
||||
### Icon sizing
|
||||
- Define a CSS custom properties scale: --yj-icon-sm, --yj-icon-md, --yj-icon-lg (and apply consistently)
|
||||
- Replace ad-hoc values (0.9em in sidebar, 12px in track-list favorites, 24px in now-playing) with scale tokens
|
||||
|
||||
### Typography
|
||||
- Define a type scale via CSS custom properties (--yj-text-xs through --yj-text-lg)
|
||||
- Apply everywhere — eliminate meaningless variations (e.g., 12px vs 13px in sort labels should pick one)
|
||||
- Album name scaling with card size (11-16px tiers in cover-grid) should map to the type scale tokens
|
||||
|
||||
### Store notification debouncing
|
||||
- Apply queueMicrotask() debouncing to library store only — it's the only store with rapid-fire updates (scan events)
|
||||
- Queue, player, playlist stores stay with immediate synchronous notifications (user-driven, not rapid)
|
||||
- Coalesce ALL library store notifications (data fetches, cover size changes, scroll position) through one debounced notify()
|
||||
- Transparent to subscribers — same subscribe() API, debouncing is an internal optimization
|
||||
- No partial progress during scan — one coalesced update after all data loads is acceptable
|
||||
|
||||
### Large library rendering
|
||||
- Reference identity check is sufficient for detecting data changes (lastTracksRef !== cached pattern already exists)
|
||||
- No deep equality checking
|
||||
- Debounce search input ~150ms before triggering filter/rank computation on large datasets
|
||||
- Aim for instant view switches — no loading skeletons needed (virtualizer only renders visible items, data is pre-cached via eagerFetch)
|
||||
- Full optimization pass on per-row rendering: repeat() keys + reduce per-row allocations (cache class strings, pre-compute column values, minimize template computation in renderTrackRow)
|
||||
|
||||
### Rendering strategy
|
||||
- Switch from .items/.renderItem pattern to repeat(items, keyFn, renderFn) directive in all virtualizer-based components
|
||||
- Stable key strategy:
|
||||
- track-list: FilePath (unique per track)
|
||||
- cover-grid: album.ID (already has gridKeyFunction — convert to repeat())
|
||||
- queue-panel: QueueTrack.id (unique per queue entry, handles duplicate tracks)
|
||||
- playlist-view: uses track-list component (inherits FilePath key)
|
||||
- Apply to ALL lit-virtualizer components, not just library views
|
||||
|
||||
### Claude's Discretion
|
||||
- Exact px values for the icon scale (--yj-icon-sm: 14px? 16px? Claude decides)
|
||||
- Exact px values for the type scale (--yj-text-xs through --yj-text-lg ranges)
|
||||
- Which specific visual inconsistencies to fix during the audit — Claude identifies them
|
||||
- Whether to extract CSS custom property definitions into a shared file or keep them in :root
|
||||
- Search debounce exact timing (guideline: ~150ms, but Claude can adjust based on feel)
|
||||
- How to handle cover-grid's dynamic text sizing tiers (size-small class, cardTextHeight) within the type scale
|
||||
|
||||
</decisions>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
- The cover-grid already has a gridKeyFunction using `a-${entry.album.ID}` — this should be migrated to the repeat() directive pattern rather than the .keyFunction property
|
||||
- QueueTrack has an `id` field that uniquely identifies each queue entry even when the same track appears multiple times — use this as the queue repeat() key
|
||||
- The library store's notify() currently does `this.subscribers.forEach((callback) => callback())` — the queueMicrotask wrapper should coalesce multiple notify() calls within the same microtask tick into a single subscriber notification round
|
||||
- Track-list's renderTrackRow does class string concatenation and column mapping on every render call — the full optimization pass should address this
|
||||
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
None — discussion stayed within phase scope
|
||||
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: 08-frontend-performance-ux*
|
||||
*Context gathered: 2026-03-04*
|
||||
Reference in New Issue
Block a user