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

2026-10-28 18:41:20 -08:00 · 2026-09-10 23:29:06 +08:00
1 parent 48660c4e12
commit bab80ff886
@@ -15,6 +15,7 @@ method; the update object is required. All implementation modules are TypeScript
 | `src/types.ts` | Internal aliases derived from the existing public declaration; no runtime imports |
 | `src/style.less` | Existing CSS classes and theme variables |
 | `types/artplayer-plugin-chapter.d.ts` | Consumer declaration and compatibility boundary |
+| `types/*.d.cts`, `types/*.d.mts` | CJS/ESM bridges sharing the same public types |

 Dependencies flow from the entry to normalization and rendering. Neither of those
 modules receives an ArtPlayer instance. Rendering accepts a progress container and
@@ -82,7 +83,9 @@ For UI, start at progress.ts/style.less and verify real mouse interaction. For e
 or cleanup changes, start at index.ts and rerun early destroy/multiple-instance tests.
 Any public declaration change also needs new/old compiler and tarball consumers.

-The public declaration is intentionally retained during the structural migration;
-PKG-CHAPTER-04 owns NodeNext ESM and legacy subpath declaration fixes. The frozen
+The public declaration remains available to old compilers and exports Chapters,
+Option and Result as types. Modern import/require conditions select format-specific
+bridges; typesVersions provides the legacy subpath to old resolvers. All bridges
+refer to one contract and runtime import paths stay unchanged. The frozen
 published baseline is under refactor/baselines; never overwrite it with candidate
 behavior. Physical device, full editor and final release checks remain separate tasks.
@@ -22,6 +22,10 @@ The registered name is `artplayerPluginChapter`. After metadata loads, use
 `update({})` to clear them. Update is synchronous and requires an options object.
 Chapter times are seconds; ranges must not overlap. `Infinity` as an end value uses the current duration.

+TypeScript users can import `Chapters`, `Option` and `Result` with `import type`.
+Modern ESM/CommonJS and `/legacy` share the same API; old TypeScript resolution
+keeps the original `.d.ts` entry and a legacy subpath fallback.
+
 The existing implementation sorts and fills the supplied array in place and replaces its Infinity end
 values. Pass a fresh array when you need to retain the original configuration. After switching media,
 call update with chapters appropriate to the new duration; initialization listens to metadata once.
@@ -19,19 +19,36 @@
  ],
  "exports": {
    ".": {
-      "types": "./types/artplayer-plugin-chapter.d.ts",
-      "import": "./dist/artplayer-plugin-chapter.mjs",
-      "require": "./dist/artplayer-plugin-chapter.js"
+      "import": {
+        "types": "./types/artplayer-plugin-chapter.d.mts",
+        "default": "./dist/artplayer-plugin-chapter.mjs"
+      },
+      "require": {
+        "types": "./types/artplayer-plugin-chapter.d.cts",
+        "default": "./dist/artplayer-plugin-chapter.js"
+      }
    },
    "./legacy": {
-      "types": "./types/artplayer-plugin-chapter.d.ts",
-      "import": "./dist/artplayer-plugin-chapter.legacy.js",
-      "require": "./dist/artplayer-plugin-chapter.legacy.js"
+      "import": {
+        "types": "./types/artplayer-plugin-chapter.d.cts",
+        "default": "./dist/artplayer-plugin-chapter.legacy.js"
+      },
+      "require": {
+        "types": "./types/artplayer-plugin-chapter.d.cts",
+        "default": "./dist/artplayer-plugin-chapter.legacy.js"
+      }
    }
  },
  "main": "./dist/artplayer-plugin-chapter.js",
  "module": "./dist/artplayer-plugin-chapter.mjs",
  "types": "./types/artplayer-plugin-chapter.d.ts",
  "legacy": "./dist/artplayer-plugin-chapter.legacy.js",
-  "browserslist": "last 1 Chrome version"
+  "browserslist": "last 1 Chrome version",
+  "typesVersions": {
+    "*": {
+      "legacy": [
+        "types/artplayer-plugin-chapter.d.ts"
+      ]
+    }
+  }
 }
@@ -1,4 +1,4 @@
 {
  "extends": "../../tsconfig.base.json",
-  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.mts", "src/**/*.cts", "types/**/*.d.ts", "../../types/assets.d.ts"]
+  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.mts", "src/**/*.cts", "types/**/*.d.ts", "types/**/*.d.mts", "types/**/*.d.cts", "../../types/assets.d.ts"]
 }
@@ -0,0 +1,11 @@
+import type * as Definition from './artplayer-plugin-chapter.js'
+
+declare const artplayerPluginChapter: typeof Definition.default
+
+declare namespace artplayerPluginChapter {
+  type Chapters = Definition.Chapters
+  type Option = Definition.Option
+  type Result = Definition.Result
+}
+
+export = artplayerPluginChapter
@@ -0,0 +1,2 @@
+export { default } from './artplayer-plugin-chapter.cjs'
+export type { Chapters, Option, Result } from './artplayer-plugin-chapter.js'
@@ -1,16 +1,16 @@
 import type Artplayer from 'artplayer'

-type Chapters = {
+export type Chapters = {
  start: number
  end: number
  title: string
 }[]

-interface Option {
+export interface Option {
  chapters?: Chapters
 }

-interface Result {
+export interface Result {
  name: 'artplayerPluginChapter'
  update: (option: Option) => void
 }
@@ -19,19 +19,34 @@
  ],
  "exports": {
    ".": {
-      "types": "./types/artplayer.d.ts",
-      "import": "./dist/artplayer.mjs",
-      "require": "./dist/artplayer.js"
+      "import": {
+        "types": "./types/artplayer.d.mts",
+        "default": "./dist/artplayer.mjs"
+      },
+      "require": {
+        "types": "./types/artplayer.d.cts",
+        "default": "./dist/artplayer.js"
+      }
    },
    "./legacy": {
-      "types": "./types/artplayer.d.ts",
-      "import": "./dist/artplayer.legacy.js",
-      "require": "./dist/artplayer.legacy.js"
+      "import": {
+        "types": "./types/artplayer.d.cts",
+        "default": "./dist/artplayer.legacy.js"
+      },
+      "require": {
+        "types": "./types/artplayer.d.cts",
+        "default": "./dist/artplayer.legacy.js"
+      }
    },
    "./i18n/*": {
-      "types": "./types/i18n.d.ts",
-      "import": "./dist/i18n/*.mjs",
-      "require": "./dist/i18n/*.js"
+      "import": {
+        "types": "./types/language.d.mts",
+        "default": "./dist/i18n/*.mjs"
+      },
+      "require": {
+        "types": "./types/language.d.cts",
+        "default": "./dist/i18n/*.js"
+      }
    }
  },
  "main": "./dist/artplayer.js",
@@ -40,7 +55,7 @@
  "typesVersions": {
    "*": {
      "i18n/*": [
-        "types/i18n.d.ts"
+        "types/legacy/language.d.ts"
      ],
      "legacy": [
        "types/artplayer.d.ts"
@@ -1,4 +1,4 @@
 {
  "extends": "../../tsconfig.base.json",
-  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.mts", "src/**/*.cts", "types/**/*.d.ts", "../../types/assets.d.ts"]
+  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.mts", "src/**/*.cts", "types/**/*.d.ts", "types/**/*.d.mts", "types/**/*.d.cts", "../../types/assets.d.ts"]
 }
@@ -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.
@@ -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
@@ -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'
@@ -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
-}
@@ -0,0 +1,4 @@
+import type { I18n } from './i18n.js'
+
+declare const language: NonNullable<I18n['en']>
+export = language
@@ -0,0 +1 @@
+export { default } from './language.cjs'
@@ -0,0 +1,4 @@
+import type { I18n } from '../i18n'
+
+declare const language: NonNullable<I18n['en']>
+export default language