Can't store multiple Widgets

Can't store multiple Widgets

Issue found of: April 6th, 2024.

Issue

Whilst using the SoundCloud API, I ran into a really annoying issue that actually took me several hours to debug.
SC.Widget(songIFrame) doesn't return a new instance of a widget for the said iframe but (my best guess) sets the internal field widget of SC to the new value and returns a reference to that field.
This is an issue if you want to have multiple players at once and, for example, change their volumes.
Instead of simply being able to store the widget once and use that value later, you have to set the widget field's value to the iframe you wanna affect and then set the volume of the updated widget.
Here's how the code should look like:

const song = document.createElement('iframe');
song.src = `https://w.soundcloud.com/player/?url=${encodeURIComponent(element.Content)}`;

const songWidget = SC.Widget(song);
volumeSlider.addEventListener('input', (event) => {
    songWidget.setVolume(event.target.value);
});

Here's a workaround you have to do in order to make it work:

const song = document.createElement('iframe');
song.src = `https://w.soundcloud.com/player/?url=${encodeURIComponent(element.Content)}`;

volumeSlider.addEventListener('input', (event) => {
    SC.Widget(song).setVolume(event.target.value);
});

You can find the full implementation here.

Reasons to fix

It is fairly unintuitive and hard to use.
Some things might not be doable with the current implementation.

Solution

In order to keep the functionality of old codebases, simply add a new function, eg. SC.WidgetInstance(), that would return the actual instance of a widget instead of returning a reference to some field inside of SC.
This way, the API would be fully compatible with previously written code whilst allowing for a new, intuitive approach for multiple widgets.

Start by reviewing the SC.Widget usage in the linked implementation at index.js line 77 and the repository's existing public API entry points. Determine how widget references are currently created and retained, then verify that a separate instance API supports multiple iframes while preserving existing SC.Widget behavior. Done means independent widget controls work without the workaround described.