ArtPlayer/packages/artplayer-plugin-multiple-subtitles/ARCHITECTURE.md

# Multiple subtitles maintenance

The public factory is `artplayerPluginMultipleSubtitles({ subtitles })`. Registration is
asynchronous and resolves to `{ name: 'multipleSubtitles', tracks, reset }`. `tracks(names)`
selects names in caller order, `tracks()` clears, and `reset()` restores the original order.
Both methods return undefined. Root and legacy declarations retain the historical synchronous
`LegacyResult` for existing extraction and replacement-function consumers. The additive
`artplayer-plugin-multiple-subtitles/runtime` entry describes the actual `Promise<Result>`
and selection methods. It shares the root implementation, not another plugin instance.
The factory has a writable `.default` self alias for historical CommonJS access.

## Current module boundaries

- `src/index.ts` composes registration, named selection and the unchanged public result.
- `src/request.ts` owns each fetch through byte decoding and delegates SRT/ASS conversion
  to the existing core utils. Failure aborts the request; registration failure closes siblings.
- `src/merge.ts` parses metadata and serializes selected cues without mutating parsed trees.
  It depends only on the vendor parser, not the player or browser resource APIs.
- `src/lifetime.ts` owns the destroy listener, request cancellation and resource callbacks.
  Its cancellation Promise also settles pending operations without AbortController support.
- `src/render.ts` owns generated Blob URLs and synchronous/async host installation outcomes.
  Reentrant selections and stale host rejections cannot release the latest selected resource.
- `src/caption.ts` owns a subtitleAfterUpdate listener. It unwraps internal timestamp markers
  in the custom HTML caption layer, preserving subsequent nodes and literal user text.
- `src/types.ts` describes selected tracks and narrow host/resource boundaries and reuses public
  runtime option/result types. The private host/resource types are not a published API.
- `src/parser.d.ts` describes the vendored parse result and discriminated cue nodes. Parsed
  timestamp values must remain numeric in both parsed and serialized trees.
- `src/parser.js` is vendored WebVTT parser/serializer code with a CC0 dedication. It is not
  owned plugin code to mechanically migrate to TypeScript. Keep it distinct from task 04.
  The pinned upstream reference and full adaptation check are in
  `../../refactor/baselines/multiple-subtitles-vendor/` and
  `../../refactor/scripts/multiple-subtitles-vendor.mjs`.
- `types/artplayer-plugin-multiple-subtitles.d.ts` owns public data types and the historical
  callable signature. Root/legacy `.d.mts` and `.d.cts` forward that signature; `runtime.d.*`
  forwards the precise asynchronous factory. Classic resolution uses typesVersions.
- `scripts/build-ts.js` generates the editor's global factory and named type namespace from
  this declaration through the semantic generator. Never edit the generated editor file.
- `../../docs/assets/example/multiple.subtitles.js` demonstrates the real plugin name,
  `tracks/reset`, name order and `.art-subtitle-chinese/.art-subtitle-japanese` CSS hooks.

All tracks download concurrently and decode through TextDecoder. Explicit type wins over
the URL extension; SRT/ASS conversion delegates to existing core utils. `onParser` appears
in declarations but is not called. Parsing runs in metadata mode. Each track's top-level
cue text receives a name-based div in a copied cue; merging concatenates cue arrays by track
order, whereas 1.0.0 merged by cue index and retained the first track's timestamps.

Each selection serializes VTT and allocates a text/vtt Blob before replacing the preceding
URL. It sets the live subtitle option's escape to false and calls subtitle.init with live
configuration plus URL/type/onVttLoad overrides. Allocation failure preserves the prior URL;
synchronous installation failure releases the new URL and restores the previous ownership.
Async host failure is observed and releases only the failed active installation, with a warning
while alive. The plugin cannot generically undo host side effects after asynchronous failure.
Registration does not await host media loading, and selection methods remain void.

Destroy cancels pending requests, settles registration with an inert result, releases owned
URLs and removes its listener. Retained methods become no-ops; restart does not refetch tracks.
Do not restore the shared escape option on normal destroy: another consumer may now own it.
The historical failure suite deliberately retains the old outcomes; the candidate lifecycle
suite verifies their fixes. Preserve parser best-effort behavior independently: invalid-header
diagnostics can coexist with usable cues, and metadata is intentionally read after download.

Inline timestamp nodes keep their numeric values. The merge layer puts them in valid VTT
class spans (`c.artplayer-multiple-subtitles-timestamp`), including nested timestamps. Native
getCueAsHTML retains the processing instructions. ArtPlayer's HTML layer does not interpret
those tags, so caption.ts removes only the leading instruction within the generated marker
and unwraps its remaining children. HTML does not pair `<c.class>` with `</c>`; removing the
whole element would incorrectly discard following caption text. The original cue stays intact.
This keeps the existing whole-cue display behavior; it does not add karaoke highlighting.

The vendor entity decoder still leaves extra semicolons after standard named entities. Nine
historical implementations reproduce it; MULTI-SUB-ENTITY-01 remains open for task 05. Do not
silently alter vendor source or declare entity rendering correct because timestamp tests pass.

## Vendor boundary and validation

The comparison revision is w3c/webvtt.js `380cfcce34ba8b472d3a31474874eb72a0e5f460`.
This is not proof of the original acquisition commit. Its execution body matches local
code after replacing the IIFE/global exports with named ESM exports and normalizing format.
Older shipped sources keep the IIFE. Preserve the CC0 source header and complete
THIRD_PARTY_NOTICES; the normal build places notices in all standalone bundle headers.

Use the pinned Node and Yarn 1.22.22:

```sh
yarn test:multiple-subtitles
yarn test:multiple-subtitles-types-package
yarn build:ts artplayer-plugin-multiple-subtitles
yarn test:browser test/browser/multiple-subtitles-history.spec.js
yarn test:browser test/browser/multiple-subtitles-lifecycle.spec.js
yarn build artplayer-plugin-multiple-subtitles
```

Historical tests read verified npm bytes and frozen Git inputs. For current normal behavior,
set ARTPLAYER_MULTIPLE_SUBTITLES_CANDIDATE=1; optionally set
ARTPLAYER_MULTIPLE_SUBTITLES_ARTIFACT to an actual main/legacy file, then run
`node --test test/multiple-subtitles.test.js`. These tests use controlled subtitle hosts;
they do not prove native rendering or the online editor. The separate historical browser suite
uses actual 1.2.0 main with published/candidate cores: SRT display and selection, pending native
fetch after destroy, and native Blob readability/late reset allocations. It covers Chromium,
Firefox and Windows WebKit; it is not all historical cores, ASS display or physical Safari.
The failure unit suite uses real current core converters and TextDecoder for SRT/ASS/encodings.
Candidate lifecycle and merge suites cover cancellation, failures, resource ownership,
reentrancy and immutable serialization. The candidate browser suite adds real video source
switching, HTTP rejection and Blob revocation. For main/legacy validation, set the artifact
environment variable above before running it; source builds are used when it is absent.
The package tsconfig checks only authored TS and declarations, with strict/noUncheckedIndexedAccess
and allowJs=false. TS 5.9.3/5.1.6 positive and negative fixtures cover internal runtime types.
Do not remove cancellation/index boundary assertions by changing historical optional inputs.
Public declaration tests check exact old extraction/replacement signatures, accurate runtime
types and negative uses with TS 5.9.3 and 4.3.5. The package test packs core and plugin, installs
outside the workspace and checks Node10/NodeNext/Bundler modes plus real CJS/ESM identities.
Historical 1.0.0/1.1.0 export-assignment declarations and 1.2.0 default-module declarations
disagree on raw `import = require` extraction. Task 04 retains that unresolved boundary;
default-import compatibility must not be presented as proof of every historical module form.
Tasks 05/06 still own complete core/device combinations and demo acceptance.
See `../../refactor/baselines/multiple-subtitles-contract.md` for exact historical differences.