Architecture and Repository Structure

Architecture and Repository Structure

Runtime architecture

DarkOneJSP3 replaces the six numbered Panel Stack Splitter instances used by DarkOne2021 with six numbered JSplitter controllers:

Column
└─ DOJSP3.Root
   ├─ DOJSP3.Main
   │  ├─ DOJSP3.InfoStack
   │  ├─ DOJSP3.ArtSpectrum
   │  └─ DOJSP3.Playlist
   └─ DOJSP3.Controls
      ├─ DOJSP3.ControlsLeft
      ├─ DOJSP3.QuickSearch
      ├─ DOJSP3.DisplayStack
      └─ DOJSP3.ControlsRight

JSplitter controllers locate child panels by exact DOJSP3.* Columns UI custom titles. These titles are runtime identifiers, not decorative labels. Use the complete Layout and Panel Map when creating or repairing the hierarchy.

Component-host boundary

JScript Panel 3 and JSplitter use separate notification domains. Same-component notifications are used where possible, but they cannot be relied upon to cross between the two hosts.

The shared bottom-area appearance therefore uses:

js_data\darkonejsp3.bottom-area-state.txt

• The three bottom JScript panels read and apply the file once during initialisation.
• They use JScript Panel notifications for live panel-to-panel updates.
• The Bottom Controls JSplitter is the sole continuous state poller, at 100 ms.
• It relays changed state to the Display/Waveform controller inside the JSplitter domain.

Coordinated factory reset uses a second short-lived bridge:

js_data\darkonejsp3.reset-command.txt

The Bottom Controls host checks reset commands every 500 ms, validates each command ID and age, rebroadcasts the reset within the JSplitter domain, then removes or clears the processed file. Runtime bridge files are user state and are excluded from release archives.

Playback Queue bridge

The recommended scripted Queue Viewer uses a separate bidirectional bridge owned by the always-running DOJSP3.Root controller:

js_data\darkonejsp3.queue-state.json
js_data\darkonejsp3.queue-command.json
js_data\darkonejsp3.queue-command-result.json

JSplitter publishes plman.GetPlaybackQueueContents() directly, so the project Queue Viewer receives only real queue entries rather than discovering them by scanning every playlist row. The state advertises whether mutation is writable and which operations are supported.

The JScript Panel writes generation-bound commands for remove, multi-remove, clear and reorder operations. DOJSP3.Root validates the active session and queue generation before applying them through JSplitter, then republishes the authoritative queue and acknowledges the command. Stale commands are rejected rather than applied to a changed queue. Duplicate occurrences are addressed by queue position. Before a reorder flushes the native playback queue, the bridge snapshots each entry's playlist source coordinates and handle. Playlist-backed entries are rebuilt with their source association intact, while entries whose original playlist source has disappeared are restored safely by handle.

The generic Enhanced Sample Library Queue Viewer does not depend on these files. Outside DarkOneJSP3 it remains read-only and uses its bounded %queue_indexes% fallback scanner. Runtime bridge files are generated state and are excluded from release archives.

Colour representation and native picker boundary

DarkOneJSP3 keeps saved and rendered colours in one opaque ARGB representation. Native colour-picker methods use host-specific integer conventions, so the shared colour helper normalises the current value only at the API boundary:

• JScript Panel receives the 32-bit colour as a signed integer.
• Returned signed or unsigned values are accepted only when they are finite, whole numbers inside the supported 32-bit range.
• The result is converted back to the established opaque ARGB form before properties, runtime state or rendering are updated.
• Cancelling or returning the unchanged value leaves the current mode intact.
• Native picker exceptions are logged with context and do not modify state.

The DarkOne Tools popup hierarchy is managed as one lifecycle protected by try/finally, ensuring every native popup object is disposed exactly once after selection, cancellation or failure. Current panel entries import the canonical shared helper directly; a validated local fallback remains for older saved entry text.

Principal migration changes

• Panel Stack Splitter title-format scripts became JavaScript controllers.
• Numeric child indexes became stable DOJSP3.* custom-title identifiers.
• PSS global variables became persistent JSplitter or JScript Panel properties.
• $movepanel and $showpanel operations became PanelObject.Move and PanelObject.Show calls.
• GDI resources moved to JScript Panel 3 DirectWrite and Direct2D handling.
• ActiveX and WScript dependencies were removed.
• State remains owned by the relevant panel instead of being duplicated in the root controller.
• Compatibility mirrors have canonical sources and are checked by maintenance tooling.
• Composite surfaces explicitly resolve inherited colours where native child-window transparency cannot provide a uniform result.

Rendering and allocation model

The rendering model reduces recurring native calls, temporary object allocation and Direct2D bitmap churn without changing user-facing layout behaviour:

• JS Playlist caches selection and playback state outside the row paint path, reuses visible row objects during sequential scrolling and retains resolved column geometry until layout inputs change.
• Control panels reuse button and volume-knob objects during resizing instead of reconstructing the complete control system for each size callback.
• Dot Matrix values draw directly from cached Direct2D sprite sheets rather than rebuilding composite bitmaps whenever time, bitrate or track number changes.
• InfoStack caches visible tabs, labels, rectangles and resolved colours until configuration or layout invalidates the model.
• The recommended project Queue Viewer enumerates and mutates the queue through the direct JSplitter bridge; the standalone sample retains bounded incremental scanning, early completion for non-empty queues and constant-time visible selection lookup.
• Album Art creates blurred artwork only when a blur-using layout actually requests it and safely cancels or disposes pending resources.

Shared Display calls are validated against the methods actually exported by Object_DisplaySystem.js, preventing stale compatibility calls from surviving refactors.

Repository structure

assets/
├── darkonejsp3-logo.png                    Repository artwork
├── darkonejsp3-social.jpg                  Promotional artwork used by the Wiki
├── darkonejsp3-screenshot-albumnotes.webp   Album Notes and InfoStack screenshot
└── darkonejsp3-screenshot-main.webp         Main interface screenshot

DarkOneJSP3/
├── docs/                  Documentation, changelog, credits and guides
├── fcl/                   Current maintainer-exported Columns UI layout
├── images/                DarkOne artwork and display/icon sheets
├── jscript/               DarkOne JScript Panel 3 wrappers and modules
├── jsplitter/             JSplitter controllers, loaders and shared helpers
├── reference/             Original DarkOne2021 migration reference
├── shared/                Shared project scripts and reset support
├── tools/                 Validator and compatibility-mirror utilities
├── build-info.json        Release metadata
└── darkonejsp3-layout-manifest.json
                           Supported layout and package manifest

user-components-x64/
└── foo_jscript_panel3/
    ├── licenses/          Retained third-party licence notices
    └── samples/           Standalone enhanced sample library

Ownership boundary

The standalone sample implementations and their reusable runtime utilities live inside the JScript Panel component tree. DarkOneJSP3 adds layout coordination, InfoStack integration, project-specific controls and coordinated factory resets on top of the same samples.

Further reading

• Migration from DarkOne2021
• Enhanced Sample Library
• Validation and Maintenance
• Repository source