Replace positional-boolean constructor signature with an options object

[maboa]

Problem

The current HyperaudioLite constructor takes seven positional arguments, five of which are booleans:

new HyperaudioLite(transcriptId, mediaElementId,
  minimizedMode, autoScroll, doubleClick, webMonetization, playOnClick);

This is the classic "boolean parameter trap":

• The call site is opaque — new HyperaudioLite("a", "b", false, true, false, false, true) tells you nothing about what's enabled.
• Argument order is easy to get wrong. Swapping autoScroll and doubleClick silently changes behaviour.
• The two leading ID strings are ambiguous — which is the transcript and which is the player? Easy to swap.
• Every new option is a breaking change for existing callers or has to be appended awkwardly to the end.
• Defaults can't be expressed — every caller types out every flag, even when they want the default.

Proposed direction

Single options-object constructor:

new HyperaudioLite({
  transcript: "hypertranscript",
  player: "hyperplayer",
  autoScroll: true,
  playOnClick: true,
});

Benefits:

• Self-documenting at call sites — the named options are visible.
• Order-independent.
• Additive — new options never break existing callers.
• Defaults can apply when an option is omitted, so most calls become short.
• Naming inconsistencies get standardized (autoScroll vs autoscroll, etc.).

Backwards-compatible migration

The constructor can sniff the first argument and dispatch:

constructor(...args) {
  let options;
  if (typeof args[0] === 'object' && args[0] !== null) {
    // New form
    options = args[0];
  } else {
    // Old form — positional
    const [transcriptId, mediaElementId, minimizedMode, autoScroll,
           doubleClick, webMonetization, playOnClick] = args;
    options = { transcript: transcriptId, player: mediaElementId,
                minimizedMode, autoScroll, doubleClick, webMonetization,
                playOnClick };
    console.warn('HyperaudioLite: positional-argument signature is ' +
                 'deprecated. Pass an options object instead — see README.');
  }
  // ...rest of init uses options.*
}

Both call shapes keep working through one minor-version release. The positional branch could be dropped in 3.0.0.

Things to decide

• Default values. Picking sensible defaults so common cases don't need to set anything explicitly (e.g. autoScroll: true by default? README examples are currently inconsistent across files).
• Property names. Suggested rename: hypertranscript/hyperplayer → transcript/player in the options object (the existing names are values, not categories). Also standardize on camelCase: autoScroll, not autoscroll.
• Throttle the deprecation warning so it fires at most once per page load, not per instance.

Migration impact

Every example HTML file (index.html, active.html, soundcloud.html, spotify.html, vimeo.html, videojs.html, vidstack.html, youtube.html, youtube-multiplayer.html, multiplayer.html) instantiates HLE and would be updated to the new form as part of the same PR. README's install snippet too.

Downstream projects (the Hyperaudio Lite Editor, etc.) keep working via the deprecated positional branch until they migrate.

Related

• Make BasePlayer abstract instead of HTML5-defaulted #214 — similar design-hygiene refactor (BasePlayer abstract). Worth doing in the same release window if it lands.