Validation and Maintenance

Validation and Maintenance

DarkOneJSP3 includes a modular release validator and a compatibility-mirror synchronisation utility. These tools are intended for maintainers, contributors and users diagnosing an incomplete package.

Run the validator

From the package or repository root containing both DarkOneJSP3 and user-components-x64:

python DarkOneJSP3/tools/validate_release.py .

What the validator checks

The validator covers, among other things:

• required package, documentation, controller, wrapper, sample and bitmap files;
• build metadata and layout-manifest version agreement;
• exact custom titles and layout-manifest source resolution;
• local @import resolution, JavaScript syntax and combined preprocessor execution order;
• Python maintenance-tool compilation;
• standalone enhanced-sample staging without the DarkOneJSP3 directory;
• current and legacy reset protocol behaviour and malformed-scope rejection;
• isolated JScript Panel and JSplitter reset propagation through the command bridge;
• first-paint bottom-area persistence and one-time JScript initialisation;
• the complete six-mode bottom-background matrix across both component hosts;
• transparent inherited-background resolution and Display cache consistency;
• 100 ms visible-state polling and 500 ms reset-command cadence with one continuous poller;
• divider-only update efficiency and single-application repaint behaviour;
• end-to-end execution of the real DarkOne Tools popup hierarchy for both bottom-area Custom commands;
• signed native picker arguments, finite 32-bit return validation, selected-colour persistence, cancellation and failure preservation;
• contextual picker diagnostics and exactly-once disposal of every generated popup object through success, cancellation and failure paths;
• runtime write failures, retries, migration and command acknowledgement;
• Album Art wheel debounce, lazy blur generation, cancellation and bitmap disposal;
• JS Playlist selection/playback caching, visible-row reuse, cached column geometry and native-call-free row painting;
• control-panel object reuse during resizing and Display font/value-measurement caching;
• direct Dot Matrix sprite rendering without mutable composite bitmap rebuilding;
• direct Queue Viewer state publication and writable command serialisation, processed-command acknowledgement/removal, bounded failed-publication retry, acknowledged-generation waiting, single/multi removal, clear, all four reorder variants across mixed playlist-backed/detached queues, stale-generation rejection, duplicate occurrences, pre-flush playlist-source snapshot preservation, plus standalone fallback scan budgets and read-only behaviour;
• InfoStack render-model caching and Playlist Manager paint-path state reuse;
• real display_system call validation against methods exported by Object_DisplaySystem.js;
• compatibility-mirror and generated-adapter synchronisation;
• playlist rendering, scrolling and refresh-cadence safeguards;
• Album Notes source, identity, cache and request-state behaviour;
• documentation headings, links, current version and installation paths;
• rejection of runtime bridge files, temporary files, backups, empty files and case collisions.

Native menu and picker validation

The validator exercises the actual darkOneToolsMenu() command path instead of calling a helper in isolation. Mock popup objects construct the complete nested menu, return the live background and divider Custom command IDs, invoke a native picker mock and record disposal. The test suite covers successful selection, cancellation, unchanged results and thrown native errors, and requires every created popup object to be disposed exactly once.

Picker mocks deliberately reject unsigned values outside the native signed 32-bit range, reproducing the host Overflow failure that a permissive ordinary JavaScript function would otherwise hide.

Runtime files and package hygiene

The following files are generated by the running theme and must not be committed to source or included in release archives:

js_data\darkonejsp3.bottom-area-state.txt
js_data\darkonejsp3.reset-command.txt
js_data\darkonejsp3.queue-state.json
js_data\darkonejsp3.queue-command.json
js_data\darkonejsp3.queue-command-result.json

The repository .gitignore and validator both enforce this boundary.

Compatibility mirrors

Some files intentionally provide legacy aliases or component-local mirrors. One canonical source is used, and the synchronisation utility plus validator ensure generated or mirrored copies remain consistent where required.

python DarkOneJSP3/tools/sync_mirrors.py

Run the synchronisation utility only as part of deliberate source maintenance, then review all generated changes before committing them.

FCL policy

Routine validation, hardening, hotfixes and tooling must not patch, regenerate or otherwise modify:

DarkOneJSP3/fcl/DarkOneJSP3.fcl

The layout map is authoritative. The included FCL is an optional maintainer-exported convenience snapshot containing the default DarkOneJSP3 scripted-queue layout and the alternative DarkOneJSP3 Native Queue layout. FCL changes should be deliberate manual exports rather than validator or maintenance-tool output.

Contribution checklist

Before opening a focused pull request:

1. Keep the change narrowly scoped.
2. Preserve author headers, credits and third-party licence notices.
3. Update documentation and fixed module-version metadata when applicable.
4. Run the validator from the complete package root.
5. Confirm affected panels in a live foobar2000 installation.
6. Include relevant console output and reproduction steps.
7. Do not include runtime bridge files, temporary files, backups or generated caches.

Source documents

• Validation report
• Release validator
• Mirror synchronisation utility
• Issue tracker