artplayer.d.ts remains the shared API definition and old TypeScript entry. Its relative declarations describe the existing player; they are not a claim that the runtime has already migrated to TypeScript.

Conditional exports select artplayer.d.mts for ESM and artplayer.d.cts for CJS and legacy. The CJS bridge uses export = for the real module.exports constructor and carries existing named types in its namespace. The ESM bridge re-exports that constructor and the same type identities. Do not copy the class into a second declaration: instance, ready callback and plugin types must remain consistent.

Languages use language.d.mts / language.d.cts for modern resolution and legacy/language.d.ts for old typesVersions resolution. The value shape comes from I18n's existing dictionary value type (I18n['en'], also compatible with TS 4.3.5). i18n.d.ts contains dictionary definitions without suppressed module augmentation. The editor's global language module is generated separately as docs/assets/ts/artplayer-i18n.d.ts so it cannot contaminate npm consumers.

Top-level types and historical .d.ts filenames remain available; runtime paths and exports do not change. See TypeScript's declaration module format and conditional resolution rules: https://www.typescriptlang.org/docs/handbook/modules/reference.html

When changing types, run yarn typecheck, yarn test:baseline and yarn test:package:release. They cover default/named types, core/legacy constructors, chapter/legacy factories, language data, invalid inputs, NodeNext/Bundler and old TS 4.3.5 consumers. Run yarn build:ts to refresh editor declarations. Full editor behavior and other core declaration/runtime mismatches have CORE-07/SITE tasks.

Configuration migration boundary

Option retains its historical required URL and component read types. OptionInput is an additive constructor input: URL is optional and numeric component HTML is accepted. The constructor keeps its old overload and adds OptionInput; Component.add/update similarly retain their old signatures and add ComponentInput. Internal ResolvedOption uses the expanded input with defaults filled. It is not a new public runtime export. This preserves assignments such as const url: string = option.url for existing Option consumers while matching the verified JS input forms (BASE-TYPE-06).

Use OptionInput for newly typed configurations that omit URL or use numeric HTML. test/types/options-source.ts and declaration-inputs.ts cover those forms positively; declaration-legacy.ts preserves old reads and historically legal return assumptions. Do not change runtime validation to match a narrower declaration. The additions, retained conflicts and follow-up owners are detailed in COMPATIBILITY.md. CORE-07 coordinates the differences; it does not close every conflicting old return signature. CORE-21 remains responsible for the generated/public declaration strategy.

Internal media migration

CORE-06 uses src/media/types.ts and src/media/hosts.ts for native media, canvas shims and minimal playback/layout dependencies. These types are not exported by the package. Public art.video keeps its historical declaration and runtime identity; do not cast an internal canvas to HTMLVideoElement merely to satisfy that public declaration. Optional capability checks belong to their consumers. Full constructor type integration is tracked by CORE-20; proxy package migration validates each real adapter separately. Source type fixtures and real canvas integration live in test/types/media-hosts.ts and test/browser/media-hosts.spec.js.