ArtPlayer/packages/artplayer-plugin-hls-control/ARCHITECTURE.md

# HLS control maintenance

The source entry is `src/index.ts`: `artplayerPluginHlsControl(option = {})` returns a
synchronous ArtPlayer plugin with `{ name: 'artplayerPluginHlsControl', update }`. `update()`
returns undefined. The consumer creates, attaches and destroys `art.hls`; this plugin does not
import Hls.js or own its media engine. Public declarations are authored in `types/`; implementation
imports their configuration/result types so there is one public contract. All five self-owned
modules are strict TypeScript, with unchecked indexed access enabled and no emitted compiler files.

| Module | Responsibility |
| --- | --- |
| `src/index.ts` | Core ready/restart/destroy hooks, current engine identity, refresh generation, selection event barrier |
| `src/mapping.ts` | Quality/audio labels, duplicate groups, selected item and Auto policy; no ArtPlayer/DOM dependencies |
| `src/menu.ts` | Existing controls/setting update/remove/check APIs, current callback ownership and stable menu reuse |
| `src/sdk-events.ts` | Optional SDK event capabilities, six subscriptions, setup rollback and listener release |
| `src/types.ts` | Internal SDK capabilities, menu models and the narrow host surface; no runtime code |

The entry depends on these three modules; they do not import the entry or each other.
SVG icons remain local build inputs. There is no cross-instance cache, timer, worker or fetch.

## Public types and editor generation

`types/artplayer-plugin-hls-control.d.ts` retains the historical path and TS 4.3.5 syntax.
Conditional `.d.cts`/`.d.mts` bridges preserve callable CommonJS/default ESM imports and named types;
legacy keeps the same JavaScript file and adds a `typesVersions` fallback for older resolution.
Do not change these runtime paths or add a runtime dependency on the Hls SDK to obtain its types.

Default `QualityLevel`/`AudioTrack` fields provide useful formatter inference. `Option<Level, Track>`
also accepts caller-supplied SDK types, including inference from an annotated callback. A formatter
still accepts the original object and optional index, returns a string and runs as a plain callback.
The optional factory overload permits omitted/undefined configuration. The required last overload
deliberately preserves old `Parameters<typeof artplayerPluginHlsControl>[0]['quality']` consumers;
do not remove it as redundant. `update()` stays synchronous and returns void.

The single ArtPlayer-to-Host assertion represents the externally attached SDK surface. `update`
still uses the historical errorHandle/media identity guard. The SDK subscription assertion follows
actual on/off function checks; guarded selector indices follow an equal-length check. These limited
boundaries are not proof that arbitrary external objects implement Hls. Keep runtime contract tests.

`scripts/plugin-editor-types.mjs` generates the HLS Monaco declaration from the authored public file.
It creates private definitions plus a callable global/named-type bridge, rejecting unsupported
imports/exports. `yarn build:ts` semantically checks that output with both compilers before writing it;
never hand-edit `docs/assets/ts/artplayer-plugin-hls-control.d.ts`. The generic defaults and both
overloads must survive generation. Other unconverted plugins still use their existing generator path.

## Refresh and selection

Registration does not require an Hls instance yet. The first ready/restart/manual update checks
`art.hls.media === art.template.$video` and binds SDK events. A plain compatible host without
`constructor.Events`, `on` and `off` retains manual/core-event updates. An engine replacement
releases only the plugin's own subscriptions. Core destroy detaches hooks and makes retained
updates/selectors inert; core remains responsible for DOM removal or preservation.

Supported SDK hooks are MANIFEST_PARSED, LEVELS_UPDATED, LEVEL_SWITCHED, AUDIO_TRACKS_UPDATED,
AUDIO_TRACK_SWITCHED and DESTROYING, using the SDK's actual exported event names. DESTROYING
retires that engine and removes owned menus; a subsequent callback cannot revive it.
If subscription setup throws, installed listeners are removed and a later update can retry.

Explicit update rebuilds selectors using current options. SDK events reuse current selectors
when engine, display surfaces, title, labels and values are unchanged, updating selection through
the normal core check APIs. An unavailable selection clears obsolete defaults/labels. Empty lists
or disabled display surfaces remove their respective entries, and later updates can restore them.

Selection writes the SDK property, then notice, then controls.check and setting.check, returning
the selected HTML. SDK events emitted synchronously during the write are deferred until this
operation finishes. A formatter or core callback that replaces the engine, destroys the player or
starts a newer refresh cannot commit the older refresh. Formatting/SDK write failures remain
synchronous; selection does not introduce a Promise. The SDK's own event exception handling still
applies to automatic event-driven formatting.

## Compatibility and intentional corrections

- Keep names `hls-quality`/`hls-audio`, right-side controls, existing SVGs, settings width 200,
  title/tooltip defaults, factory/global name and root/legacy distribution paths.
- Pass original SDK objects to getName: selected-label calls have one argument; list-label calls
  also receive the index. Do not bind a new `this` or claim the index is always present.
- Auto uses `autoLevelEnabled === true`; hosts without this capability fall back to currentLevel.
  Quality's Auto value remains -1. Audio does not acquire a new synthetic Auto option.
- Duplicate labels still collapse into one group. If a later duplicate is selected, its value
  represents that group so the real selection is not lost. Quality sorts by represented index;
  audio retains group order. Undefined labels remain distinct.
- Old SDK callbacks after replacement/destroy, lingering empty menus and an Auto label derived
  from the currently decoded automatic level were defects, not guarantees to preserve.

The plugin owns its two reserved menu names. Applications should use distinct names for unrelated
entries. Hls instances and third-party SDK listeners remain owned by their callers. No minimum
core/SDK version has been newly imposed; the tested historical core is 5.4.0 and SDK is 1.5.17.

## Documentation and example ownership

The bilingual `artplayer-vitepress/docs/{en/,}plugin/hls-control.md` guides contain
the exact `docs/assets/example/hls.control.js` setup. The example selects Hls.js
versus native HLS once per player, installs controls only for the Hls.js path,
releases each replaced SDK and registers one final player cleanup listener.
`test/hls-example.test.js` guards the previously duplicated destroy calls and the
invalid native-fallback plugin registration. `document-hls.spec.js` checks exact
example parity and real SDK playback/replacement against published/candidate core;
its WebKit no-MSE branch is capability evidence, not native HLS playback.

Update both guides whenever changing the example. Run the Node regression,
`yarn test:browser document-hls.spec.js document-site.spec.js --workers=1`,
`yarn build:llm`, `yarn build:docs`, and refresh/check the site inventory.
Full source-topology, native-device and intermittent Firefox acceptance remain
separate tasks. The native crash checkpoint now has xul.dll exception metadata;
it still does not have a resolved stack or proven cause.

## Validation and next changes

Use the repository's pinned Node and Yarn:

```sh
node --test test/hls-control.test.js
node --test refactor/scripts/hls-types.test.mjs
yarn test:browser hls-control.spec.js
yarn test:browser hls-editor-types.spec.js
yarn test:browser hls-sdk.spec.js
yarn build artplayer-plugin-hls-control
yarn build:ts
yarn ci:check
```

ARTPLAYER_TEST_HLS accepts platform-delimited paths to built main/legacy/ESM files for additional
Node contracts. ARTPLAYER_HLS_ARTIFACT selects a built browser main/legacy file; invalid paths fail,
and test attachments record its bytes. These checks do not replace isolated tarball installation.
Use the local demo at `http://localhost:8082` with example `hls.control` during example work.

Windows Playwright WebKit lacks MSE; explicit capability/error cleanup runs there, while playback
cases are marked skipped. The SDK suite uses frozen Hls.js 1.5.17/1.7.2, real native workers and local
media to test replacement, detach/reattach and reordered audio groups with published/current core.
Worker messages and termination are observed without substituting worker output. Grouped playlists
reuse generated video/audio segments; the Commentary track intentionally reuses the English tone.
The fixed releases are two tested points, not a supported version range or new minimum version.
Safari/native HLS, external network/device evidence, updated example and isolated package verification
remain PKG-HLS-05/06 work. See
[refactor validation](../../refactor/hls-validation.md). Keep these gaps visible in release reviews.

Actual Hls.js 1.5.17 declaration consumers pass TS 5.9.3. TS 4.3.5 reports two existing SDK DOM type
errors (MediaDecodingConfiguration and MediaCapabilitiesDecodingInfo), reproduced with the SDK alone.
The plugin introduces no additional errors; do not hide those SDK diagnostics with skipLibCheck or
claim every SDK/compiler combination passes. Standalone plugin consumers pass both compilers.

For unresolved Firefox grouped-stream diagnostics, use
`node refactor/scripts/hls-sdk-diagnostic.mjs --host direct --transport route --iterations 5`.
`--host published|candidate --plugin` adds an actual core and the candidate plugin;
`--observe-workers` uses the same native-worker observer as the integration suite. Each run retains
its own report and trace files. See the HLS-SDK-01 in-progress record: one target crash and a separate
group-switch stall remain unclassified. Passing diagnostic repetitions are not release evidence.

The diagnostic runner records host-side failure/crash phases. Optional
`--capture-before-destroy` saves media/SDK events outside the page before teardown;
it adds an evaluate and may change timing, so it is off by default. Direct ordinary
HTTP without ArtPlayer/plugin or a Worker observer still reproduced crashes with
both reset-first and SDK-first teardown. A passing no-worker control does not
replace worker acceptance. See the 2026-09-14 HTTP teardown checkpoint in refactor.

For the separate grouped-playback stall, `--switch-boundary switched|selected|immediate`
compares completed SDK audio switching, selected UI/getter state, and same-call audio/level
selection. The default remains switched. `--prefill` adds a controlled fully buffered
fixture condition; it is not a player workaround. Both diagnostic and integration paths
now require the clock and frame count to advance at the target height after high/low
switches. Keep the original 7000ms height assertion and the failed trace even when a
later control passes. Diagnostic private SDK fields are read-only, version-specific;
never read load-level getters after SDK destruction. See the 2026-09-15 switch-boundary
checkpoint in refactor for the reproduced empty-buffer failure and remaining attribution.

`--sequence 1.5.17,1.5.17,1.7.2` runs frozen SDK versions in separate contexts within
one Firefox browser instance. It cannot be combined with explicit `--version` or
`--iterations`; every result records and checks its actual SDK version. A first-case
direct-video 1.5.17 run also reported a page crash while awaiting the high-group
transition, before any explicit destroy. Keep playback and teardown evidence distinct;
neither the previous SDK nor ArtPlayer is a necessary precondition for that occurrence.
See the 2026-09-15 SDK sequence checkpoint for exact scope and remaining native diagnostics.

## Package file boundary

The package .npmignore excludes src and tsconfig.json. The implementation config
extends the repository root and must not ship to consumers. PKG-HLS-PACK-01
compares real Yarn archives before/after the exclusion: all distribution and
declaration bytes must remain identical, with every historical entry retained.
See ../../refactor/changes/2026-09-15-PKG-HLS-PACK-01-config.md.

## Shared installed browser scope

hls-control.spec.js uses a frozen SDK without workers; hls-sdk.spec.js uses the frozen SDK version matrix and real workers. Both select verified installed plugin bytes and retain published plugin controls.

Use `yarn test:package --browser` and the shared scope rules in
../../scripts/browser-validation/README.md. Missing, stale or changed installation
inputs fail without source fallback. Attachments distinguish selected installed,
source and published inputs. Source mode retains existing explicit artifact use.
The generic Node/type consumer remains core/chapter-only. Module forms, physical
devices, editor demos and release readiness retain their separate package gates.
See ../../refactor/changes/2026-09-15-CI-01-adaptive-installed.md for actual results.