fix(types): PKG-CHAPTER-04 preserve CJS ESM and legacy consumer contracts

packages/artplayer/types/README.md

@@ -0,0 +1,28 @@
+# Declaration entrypoints
+
+`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.

packages/artplayer/types/artplayer.d.cts

@@ -0,0 +1,20 @@
+import type * as Definition from './artplayer.js'
+
+declare const Artplayer: typeof Definition.default
+type Artplayer = Definition.default
+
+declare namespace Artplayer {
+  type Config = Definition.Config
+  type Events = Definition.Events
+  type I18n = Definition.I18n
+  type Icons = Definition.Icons
+  type Option = Definition.Option
+  type Player = Definition.Player
+  type Setting = Definition.Setting
+  type SettingOption = Definition.SettingOption
+  type Subtitle = Definition.Subtitle
+  type Template = Definition.Template
+  type Utils = Definition.Utils
+}
+
+export = Artplayer

packages/artplayer/types/artplayer.d.mts

@@ -0,0 +1,2 @@
+export { default } from './artplayer.cjs'
+export type { Config, Events, I18n, Icons, Option, Player, Setting, SettingOption, Subtitle, Template, Utils } from './artplayer.js'

packages/artplayer/types/i18n.d.ts

@@ -54,9 +54,3 @@ interface I18nValue {
 }
 
 export type I18n = Partial<Record<I18nKeys, Partial<I18nValue>>>
-
-declare module 'artplayer/i18n/*' {
-  const lang: Partial<I18nValue>
-  // @ts-expect-error TS2666
-  export default lang
-}

packages/artplayer/types/language.d.cts

@@ -0,0 +1,4 @@
+import type { I18n } from './i18n.js'
+
+declare const language: NonNullable<I18n['en']>
+export = language

packages/artplayer/types/language.d.mts

@@ -0,0 +1 @@
+export { default } from './language.cjs'

packages/artplayer/types/legacy/language.d.ts

@@ -0,0 +1,4 @@
+import type { I18n } from '../i18n'
+
+declare const language: NonNullable<I18n['en']>
+export default language