fix: Folder Library previews on hover via song_preview (parity with grid/list) by Elit3d · Pull Request #1026 · got-feedBack/feedBack

Elit3d · 2026-07-21T04:11:19Z

What

The Folders view didn't preview songs on hover. This brings it to parity with the
grid and list views.

Rather than add preview code to Folder Library, it wires the folder cards/rows
into the existing song_preview plugin — the same one that already handles
the grid and list. song_preview looks for #v3-songs [data-fn] elements
containing a [data-v3-play] descendant; the folder tree renders inside
#v3-songs, so once the cards carry that markup its observer picks them up with
zero changes to song_preview.

Changes:

_songCard / _songRow now emit the standard preview markup — data-fn (raw
filename; was data-filename, which song_preview never matched since it keys on
dataset.fn) plus a [data-v3-play] surface on the art wrap (cards) / thumb
(rows).
Removed the custom hover-preview implementation (dedicated <audio>, waveform
indicator, toolbar toggle, and the backend has_preview manifest read) that an
earlier iteration of this branch had added — song_preview owns preview now.
Test: plugins/folder_library/tests/song_preview_markup.test.js pins the
contract (both cards and rows carry data-fn + a data-v3-play surface) so a
future refactor can't silently drop preview coverage.

Credit to @topkoa for pointing out song_preview already exists as a plugin.

feedpak surface

This PR does not change how the app reads/writes feedpaks (manifest keys, pack files, folder layout)

Checklist

CHANGELOG.md [Unreleased] updated (user-visible changes)
Tests added/updated for new behaviour
Commits are DCO signed off (git commit -s) — not yet; run git rebase --signoff main

Summary by CodeRabbit

New Features
- Enabled consistent hover previews for songs shown in Folder Library grid cards and list rows using the app’s standard Song Preview markup contract.
Documentation
- Updated Folder Library docs to clarify that hover-preview is provided by the Song Preview plugin and to document the expected DOM/data markers.
- Updated the changelog entry under Unreleased → Changed.
Tests
- Added tests validating Folder Library emits the correct hover-preview surface markers for both cards and rows (including raw filenames and minimal metadata).
Chores
- Bumped Folder Library version to 1.9.0.

coderabbitai · 2026-07-21T04:11:27Z

📝 Walkthrough

Walkthrough

Folder Library cards and rows now emit standard data-fn and data-v3-play markers for Song Preview hover playback. Rendering helpers are exposed for tests, documentation and changelog entries are updated, and the plugin version advances to 1.9.0.

Changes

Folder Library hover preview

Layer / File(s)	Summary
Preview markup and test surface `plugins/folder_library/screen.js`	Song cards and rows now expose raw filenames through `data-fn`, mark previewable artwork surfaces with `data-v3-play`, and expose rendering helpers through `__test`.
Markup contract tests `plugins/folder_library/tests/song_preview_markup.test.js`	Mock-DOM tests verify card and row markers, raw filenames, preview surfaces, helper exposure, and rendering with filename-only data.
Documentation and release metadata `CHANGELOG.md`, `plugins/folder_library/CLAUDE.md`, `plugins/folder_library/README.md`, `plugins/folder_library/plugin.json`	Documentation identifies Song Preview as the hover-preview provider, roadmap and usage content are updated, the changelog records the feature, and the plugin version is bumped to 1.9.0.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

got-feedBack/feedBack#1022: Both changes update Folder Library rendering and tests for the Song Preview markup contract.

Suggested reviewers: byrongamatos, topkoa

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main change: Folder Library hover previews now use song_preview and match grid/list behavior.
Description check	✅ Passed	The description includes the required What, feedpak surface, and Checklist sections and covers the main implementation and testing details.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch fix/folder-library-hover-preview

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

Elit3d · 2026-07-21T18:21:08Z

@coderabbitai review

coderabbitai · 2026-07-21T18:21:15Z

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Implement optional audio preview when hovering over songs in the Folders view. Features include: - Toolbar toggle button (off by default) to enable/disable hover preview - ~0.5s dwell delay to avoid accidental audio playback while scrolling - Dedicated <audio> element (never touches main player) - Equalizer indicator animation overlay on song art while playing - Per-surface localStorage persistence - Automatic fallback through preview.ogg → stems/full.ogg → stems/audio.mp3 Bump Folder Library from 1.8.0 to 1.9.0. Remove 'auto play on hover' from roadmap as it's now implemented. Signed-off-by: Kyle <kyle.j.t@live.co.uk>

Move audio member selection logic from frontend to backend. The frontend was probing multiple candidate audio files with error/retry logic, often resulting in 404s. Now the backend resolves the best available audio file (preview.ogg, stems/full.ogg, or any stem) during metadata extraction and includes it in song metadata as `audio_member`. The frontend makes a single, guaranteed request instead of multiple probes. Simplifies the preview flow and improves reliability. Signed-off-by: Kyle <kyle.j.t@live.co.uk>

Make the hover-preview feature opt-out instead of opt-in (defaults to on). Increase dwell delay from 500ms to 800ms to prevent accidental triggers while clicking/dragging. Replace 4-bar equalizer indicator with 9-bar waveform with staggered animation and fade-in entrance. Add guards to prevent preview during drag operations. Update button styling and all user-facing docs to reflect new defaults. Signed-off-by: Kyle <kyle.j.t@live.co.uk>

Remove audio member resolution from folder_library and delegate hover-preview audio to the canonical song_preview plugin endpoint. This separates concerns: folder_library now only builds the preview URL with the filename, while song_preview handles manifest resolution (preview: key, stem fallback) and Range support. Changes: - Remove _audio_member() resolver and audio_member field from pack metadata - Update _previewUrl() to point to /api/plugins/song_preview/audio?file=<filename> - Add _previewMissing cache to avoid re-requesting packs with no preview - Add HEAD probe to check preview availability before playing - Add test coverage for _previewUrl with special character encoding Signed-off-by: Kyle <kyle.j.t@live.co.uk>

Expose a has_preview boolean from pack manifests and use it to gate hover previews. backend: plugins/folder_library/routes.py now (optionally) reads sloppak.load_manifest to set m['has_preview'] (guarded so plugin still loads without sloppak). frontend: plugins/folder_library/screen.js skips preview requests when song.has_preview is false and removes the HEAD-probe + previewMissing cache. docs: plugins/folder_library/CLAUDE.md updated to document has_preview and the preview behavior. This prevents unnecessary HEAD/audio 404s and console noise. Signed-off-by: Kyle <kyle.j.t@live.co.uk>

Remove the developer note about manually bumping plugin.json version when changing screen.js Signed-off-by: Kyle <kyle.j.t@live.co.uk>

Folder Library now uses the standard data-fn/data-v3-play markup so the song_preview plugin handles hover-previews, the same way it does for grid and list views. Removes ~200 lines of preview-specific code: dedicated audio element, indicator rendering, toolbar toggle, and backend manifest checking. The preview experience is now unified across all library surfaces. Signed-off-by: Kyle <kyle.j.t@live.co.uk>

Elit3d requested review from byrongamatos and topkoa July 21, 2026 04:12

Elit3d added 7 commits July 23, 2026 00:51

Remove outdated screen.js caching note

51fe217

Remove the developer note about manually bumping plugin.json version when changing screen.js Signed-off-by: Kyle <kyle.j.t@live.co.uk>

Elit3d force-pushed the fix/folder-library-hover-preview branch from b467261 to 9157e2e Compare July 23, 2026 05:00

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: Folder Library previews on hover via song_preview (parity with grid/list)#1026

fix: Folder Library previews on hover via song_preview (parity with grid/list)#1026
Elit3d wants to merge 7 commits into
mainfrom
fix/folder-library-hover-preview

Elit3d commented Jul 21, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 21, 2026 •

edited

Loading

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

Elit3d commented Jul 21, 2026

Uh oh!

coderabbitai Bot commented Jul 21, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

Elit3d commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

feedpak surface

Checklist

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

Elit3d commented Jul 21, 2026

Uh oh!

coderabbitai Bot commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Elit3d commented Jul 21, 2026 •

edited

Loading

coderabbitai Bot commented Jul 21, 2026 •

edited

Loading

coderabbitai Bot commented Jul 21, 2026 •

edited

Loading