Enhanced Sample Library

Enhanced Sample Library

Purpose

The user-components-x64 tree supplied with DarkOneJSP3 is a standalone, upgraded JScript Panel 3 sample suite. The enhanced samples no longer require the DarkOneJSP3 project directory and can be used by other foobar2000 themes.

Installation outside DarkOneJSP3

1. Close foobar2000.
2. Back up the installed foo_jscript_panel3\samples directory and helpers.txt.
3. Merge the supplied user-components-x64\foo_jscript_panel3 tree into the active profile's user-components-x64 location.
4. Load the desired top-level sample .txt file in a JScript Panel 3 instance.

The DarkOneJSP3 folder and its Columns UI layout are not required for standalone sample use.

Compatibility design

• Existing sample filenames, module filenames, constructors and import paths are retained.
• helpers.txt carries guarded performance and UI-cadence fallbacks for older saved playlist entries.
• Current enhanced entries import reusable files from samples\shared rather than %fb2k_profile_path%DarkOneJSP3\shared.
• Existing DARKONEJSP3.*, JSPLAYLIST.* and SMOOTH.* property keys remain intact.
• The neutral JSP3Enhanced.Reset.Properties notification and legacy DarkOneJSP3.Reset.Properties notification are both supported.
• darkonejsp3_reset.js remains a generated self-contained legacy adapter for saved entries created before the standalone refactor.
• enhanced_page_background is the neutral _panel option; darkonejsp3_page_background remains a supported alias.
• The component-local colour helper mirrors the canonical picker behaviour: native methods reported as host objects are supported, picker arguments are normalised to the required signed 32-bit form, returned values are range-checked, and cancellation or native failure is non-destructive.
• The standalone Queue Viewer remains read-only and deliberately uses its JScript Panel %queue_indexes% discovery path. DarkOneJSP3 enables its direct, writable JSplitter bridge only from the project-specific wrapper, so the generic component sample keeps no project-folder runtime dependency.

Included enhanced panels

The standalone library provides upgraded implementations used directly by DarkOneJSP3, including:

• Album Art — Enhanced
• Album Notes and MusicBrainz metadata panels
• JS Playlist
• Smooth Playlist Manager
• Queue Viewer
• Properties
• Last.fm Biography
• Last.fm Artist Information
• Shared colour, reset, performance and UI-cadence utilities

Album Art enhancements

Album Art wheel navigation uses an 80 ms trailing debounce. Rapid wheel input updates a pending artwork type but decodes and converts only the final selection after scrolling settles. Keyboard and context-menu choices remain immediate.

Pending wheel work is cancelled when metadata changes or the script unloads. During unload, active normal and blurred Direct2D bitmaps are explicitly disposed. Blurred artwork is generated lazily only when a blur-using layout paints, and repeated blur requests are coalesced into one deferred operation.

Existing compatible panel entries receive the runtime improvement from the shared samples\js\albumart.js file. Loading the current Album Art.txt entry also updates the displayed sample name and version.

Rendering and efficiency improvements

The standalone library uses the same rendering and efficiency improvements as DarkOneJSP3:

• JS Playlist: caches selection and playback state, reuses visible rows during sequential scrolling, and caches column geometry and group-header measurements.
• Smooth Playlist Manager: avoids querying PlaylistCount from the paint path and uses callback-maintained state.
• Queue Viewer: uses constant-time selection lookup, short yielding scan slices, targeted refreshes for common queue changes and %queue_total% early completion when a non-empty queue is discovered.
• Album Art: retains the 80 ms wheel debounce, adds lazy blur generation and disposes active and pending bitmap resources explicitly.

These changes are automatic and do not require new panel properties. Older compatible entry text continues to import the enhanced shared implementations.

DarkOneJSP3 integration

DarkOneJSP3 uses these same standalone samples. Its project-specific code adds layout coordination, InfoStack integration and coordinated factory-reset commands, but the sample implementations and shared runtime utilities are owned by the JScript Panel component tree.

Validation

The release validator stages user-components-x64 by itself, with no DarkOneJSP3 directory, and resolves every distributed sample entry import. It also checks legacy helpers.txt fallbacks, neutral and legacy reset notifications, property compatibility, the optional page-background alias, generic context-menu routing without the colour helper loaded, native colour-picker conversion and return validation, Album Art wheel behaviour, lazy blur lifecycle and explicit bitmap disposal. It also validates native-call-free playlist painting, row/geometry reuse, Queue Viewer fallback scan budgets and read-only standalone behaviour, and current Display API usage.

Benefits for other themes

• Existing sample filenames and internal import paths are retained.
• Older saved entry scripts receive guarded helper and reset compatibility.
• Existing property keys remain valid.
• Other themes can use the upgraded panels without installing the DarkOneJSP3 layout.
• DarkOneJSP3 and third-party themes can share one maintained implementation instead of diverging forks.

Upgrade warning

The package replaces files inside the installed JScript Panel sample tree. Back up locally modified samples and helpers.txt before merging the library, especially when another theme ships its own modified copies.

Related pages

• Installation and Upgrading
• Configuration Guide
• Troubleshooting