refactor(core): [CORE-21] generate compatible public and editor declarations

packages/artplayer/.npmignore

@@ -4,3 +4,5 @@ yarn.lock
 package-lock.json
 src
 tsconfig.json
+
+/public/

packages/artplayer/ARCHITECTURE.md

@@ -4,6 +4,65 @@ ArtPlayer keeps its existing constructor, player mixins, plugins and DOM/CSS hoo
 The production entry is `src/index.ts`. All owned core production modules use
 TypeScript; libs/screenfull.js remains an audited third-party source file.
 
+## Public declaration sources
+
+`public/` owns the TypeScript sources for the historical package declarations.
+They deliberately form a separate dependency graph from `src/`: implementation
+classes, resource ownership details and browser-only imports must not leak into
+consumer declarations. `scripts/build-types.mjs` emits only declarations into
+the existing `types/` paths, using the pinned compiler and preserving the shared
+default/CJS/ESM/legacy/i18n identities. `public/` is excluded from npm packages.
+
+Run `yarn build:types` after editing public sources and `yarn check:types` to verify
+generated files without writing. CI and isolated package builds use the same
+generator. Read `types/COMPATIBILITY.md` before changing a public return or callback:
+the historical facade retains old acceptance while the optional runtime facade
+describes actual results. Runtime and public source views are checked
+separately; generating a declaration does not prove runtime correspondence.
+
+`public/runtime/` contains the precise media/player, utility, plugin, template/icon,
+subtitle/notice, event and component/setting views introduced by CORE-21.
+Their generic host parameters let tests compare the public contracts with the
+corresponding minimal implementation hosts. `public/runtime.ts` assembles them;
+`artplayer/runtime` and `artplayer/runtime/legacy` select precise declarations
+while resolving to the same JS files as the existing matching entrypoints.
+`artplayer/runtime/types` is the shared type-only augmentation path.
+`src/events/core-types.ts` consumes the generated
+event view: custom legacy channels remain available while builtin cue/error/blur
+payloads are corrected. Declaration-only imports add no runtime dependency.
+
+`test/types/runtime-*.ts` separates source correspondence from generated declaration
+consumption. The latter runs with TypeScript 5.9.3 and the dev-only 5.1.6 alias in
+four module-resolution modes; the existing root consumers still run with 4.3.5.
+Keep old entry declarations independent of these modern accessor types.
+Old plugin factories have explicit input overloads, and declared legacy plugin
+results/custom events flow into the new view. No wrapper or runtime conversion
+is introduced. A returned precise instance must not be assigned to the legacy
+instance type: some legacy return assumptions intentionally remain inaccurate.
+Constructor PluginFactory uses PluginHost with an optional plugins registry;
+plugins.add callbacks receive the completed Artplayer view. ControlInput requires
+top/left/right because Control.add validates position before component registration.
+`runtime/construction.ts` describes early callback hosts. ProxyHost exposes safe
+initial fields and the event bus before Template returns; it does not expose the
+video/query/proxy getters. Layer/control/contextmenu hosts mark subsequent
+components optional. customType and setting mounted are deferred, so they receive
+the completed player. Pending views preserve Player directly because mapped types
+would otherwise collapse different getter/setter types. Browser tests compare
+the exact initialized fields against published and candidate construction.
+The container remains an HTMLDivElement; a general HTMLElement is rejected by
+the existing tag validation. TypeScript does not model arbitrary user mutations
+or guarantee every subsystem remains usable after explicit destroy.
+
+`scripts/editor-types.mjs` bundles the historical public dependency graph with
+the pinned dts-bundle-generator and TypeScript, then uses the TypeScript AST to
+give the existing UMD global its constructor and named types. Definitions have a
+private namespace to avoid circular aliases. Both old/current compilers validate
+the standalone result before build:ts writes it; a CI test rejects drift.
+The browser editor test uses the actual vendored Monaco worker and generated core
+declaration to compile and execute a player example. Plugin/editor UI generation
+modernization remains SITE-02; this core flow does not concatenate modern accessors
+into the legacy editor or publish an additional JS implementation.
+
 ## Entry and bootstrap (CORE-20)
 
 The typed entry checks subsystem composition. Seven leaf
@@ -52,7 +111,7 @@ still propagate. Its controlled tests do not certify an actual Apple receiver.
 test/initialization.test.js compares frozen CORE-19 functions with the new code;
 test/types/core-initialization.ts checks raw storage, mutable config and nullable DOM
 results. Internal PiP consumers accept the native element/null/boolean getter and
-boolean setter; the public declaration compatibility work remains in CORE-21.
+boolean setter; the optional runtime entry exposes the same precise contract.
 The auto-playback consumer owns the legacy unvalidated record assumption locally;
 Storage does not promise that arbitrary persisted values are PlaybackTimes.
 
@@ -87,8 +146,8 @@ as the legacy declaration class. template/types.ts names the PlayerTemplate cont
 canonical template nodes plus a native/media-like proxy. The entry makes one scoped
 assertion for caller-provided SSR/proxy inputs. This is a compatibility precondition,
 not runtime validation; no eager missing-node rejection or synthesized nodes are added.
-Template itself and query helpers keep nullable results. Complete public declaration
-generation and consumer views remain CORE-21 work.
+Template itself and query helpers keep nullable results. Generated runtime declarations
+retain these nullable views; the old root preserves historical consumer acceptance.
 
 events/core-types.ts names known core/native payloads while leaving extension event
 names open. CoreEmission narrows a module's emitted names against that shared map.
@@ -205,7 +264,7 @@ overwriting newer messages. Public art/timer fields and destroy/show methods rem
 False/empty assignment only hides the notice; the old pending expiry still clears
 its text. Manual notice.destroy cancels the timer without hiding or permanently
 disabling a live instance. The source getter is boolean; the legacy public message
-read type remains tracked by BASE-TYPE-07 for compatible coordination in CORE-21.
+read type is retained at the old root; the runtime entry exposes the boolean getter.
 
 `src/plugins/fastForward.ts` wires the unchanged plugin result and input events.
 `src/input/long-press.ts` owns one press at a time in the current source scope,
@@ -404,8 +463,9 @@ screen rotation is tested below; final installed-artifact acceptance remains a C
 plugins/autoOrientation.ts composes the mobile-only builtin, retaining its name/state
 getter and mismatch rule. It rejects unready geometry and scopes the two ArtPlayer event
 subscriptions. orientation-types.ts models the minimal host and optional platform lock.
-The builtin registry currently bridges its generic JS host at this one assembly boundary;
-the complete constructor host remains for CORE-21, without widening the implementation.
+The builtin registry bridges its host at this one assembly boundary. Public construction
+callbacks use the phase-specific hosts in public/runtime/construction.ts without widening
+the implementation's minimal orientation host.
 
 display/orientation-web.ts owns delayed rotation and its four inline style properties.
 Each new fullscreen session cancels the previous timer. Repeated entry reapplies dimensions
@@ -525,8 +585,8 @@ Destruction's synchronous WebKit failure follows the normal lifecycle error coll
 late cleanup is best effort. Platform UI remains the browser's responsibility.
 
 The internal PipProperty reflects the branch-dependent getter. Historical public boolean
-declarations remain unchanged pending BASE-TYPE-10 / CORE-21; this is an explicit legacy
-declaration discrepancy, not a reason to convert native JS consumers to boolean.
+declarations remain unchanged at the old root; the runtime entry exposes Element|null|boolean
+reads and boolean writes. Native JS return values retain their identity.
 Run `node --test test/display-pip.test.js` and
 `yarn test:browser test/browser/display-pip.spec.js test/browser/display-pip-webkit.spec.js`.
 The actual native test records capabilities and, when supported, a native window, media
@@ -590,7 +650,8 @@ Track load errors notify only while that node is current; all owned load/error/c
 callbacks are cleared on replacement or destroy. HTTP errors reject before conversion.
 Constructor and URL-setter calls report through notice and consume their otherwise
 unobservable rejected promises; explicit init/switch calls keep rejection semantics.
-Public cue event inference remains tracked by BASE-TYPE-07 / CORE-21. Browser-engine
+The runtime entry infers cue arrays; the old root retains scalar inference and its
+explicit array-listener overloads for compatibility. Browser-engine
 tests do not certify physical iOS/Safari fullscreen or every proxy implementation.
 
 ## Settings (CORE-14)
@@ -666,9 +727,9 @@ trusted keyboard input/change ordering, pointer switch callbacks, touch selectio
 and actual builtin autoOrientation transforms with a local video. Mobile UA/viewport
 and touch emulation are not certification on physical mobile devices.
 
-Public Setting return declaration discrepancies remain tracked by BASE-TYPE-07 for
-the compatible public facade at CORE-21. The source manager has precise item/null/void
-returns and does not change runtime behavior to match incorrect legacy declarations.
+The runtime entry and source manager expose precise item/null/void Setting returns.
+The old root retains historical return declarations for existing consumers; the manager
+does not change runtime behavior to match those declarations.
 
 Tests: setting-model.test.js, setting-layout.test.js, setting-resources.test.js,
 types/setting-model.ts, types/setting-manager.ts and
@@ -701,7 +762,7 @@ click/mounted/beforeUnmount use art as this; index 0 still follows the old index
 rule; equal indexes insert before their predecessor. update mutates the cached option
 before remove, so the newly supplied beforeUnmount runs on the old node. Component
 add/update may return a div; Control add/update still return undefined. Source types
-model that distinction; historical public declaration conflicts remain CORE-21 work.
+and the runtime entry model that distinction; historical root declarations are retained.
 A name of `__proto__` now creates a normal own DOM alias without replacing the registry
 prototype. Other historical aliases and shadowing behavior are not broadly renamed.
 
@@ -766,7 +827,7 @@ construction still fails with the original browser-only error.
 `icons/defaults.ts` owns SVG inputs; `icons/index.ts` creates the per-instance registry.
 Each read creates a fresh i.art-icon wrapper. Custom DOM nodes move into that wrapper;
 they are not cloned. Public declarations historically say HTMLDivElement, while source
-uses the actual HTMLElement shape. This mismatch remains tracked for CORE-21.
+and the runtime entry use the actual HTMLElement shape. Custom icon keys may be absent.
 
 `i18n/index.ts` owns selected language, deep updates and key fallback. Standalone
 language modules keep default exports and artplayer-i18n-* aliases through publish.ts.
@@ -833,7 +894,7 @@ Public PluginFactory and Plugins are type-only contracts. Augment `artplayer/typ
 for a common plugin-result/event interface across old TS, NodeNext CJS/ESM and Bundler;
 augmenting the CJS root alias directly is not equivalent. The new subpath has only
 a types condition and typesVersions fallback: runtime require/import must reject it.
-Public add's legacy return signature remains tracked by BASE-TYPE-04/CORE-21; internal
+The old root retains add's legacy return signature. Runtime-entry and internal
 registration types preserve known synchronous/Promise results and use a union for
 unknown results. The Promise distinction retains instanceof semantics: foreign
 Promises and ordinary thenables are stored synchronously, not assimilated.
@@ -1084,8 +1145,9 @@ reads template.$video on each access, as before.
 The typed construction facade checks these host requirements while retaining the
 original staged initialization. Do not assume these types validate every third-party proxy.
 Public art.video remains the original object and retains its existing declaration
-for consumer compatibility. A public proxy typing extension requires separate
-consumer checks; internal code must not use that old declaration to hide a canvas.
+at the old root for consumer compatibility. The runtime entry exposes MediaSurface
+and a construction-stage ProxyHost, checked in installed consumers; internal code
+must not use the old declaration to hide a canvas.
 
 `test/media-hosts.test.js` covers structural media methods, receiver/return values,
 event and mutex order, property descriptors and live getters. `test/types/media-hosts.ts`
@@ -1103,7 +1165,8 @@ compatibility surface; see [types/README.md](./types/README.md).
 Public return discrepancies remain after CORE-07. It adds unescape/ArtPlayerError,
 optional sleep and a symbol/PropertyKey def overload; old string def and debounce/throttle return declarations
 remain for source compatibility. The old debounce context argument is ignored at runtime.
-BASE-TYPE-05 remains open through CORE-21; use the actual source types internally.
+The runtime entry exposes the actual target identity and timer void returns;
+use the actual source types internally.
 Lifecycle-owned timer cancellation is part of CORE-04/17 and the existing BASE-PERF-01
 finding, not a claim that a standalone debounce can know when its owner is destroyed.
 
@@ -1214,5 +1277,5 @@ core files in docs/compiled when committing a shippable core change.
 For new utility behavior, extend the same old/new contract tests. Clearly separate
 intentional defect corrections from preserved behavior. For timers or Blob URLs,
 also identify the owner and verify cleanup in the consuming module. Remaining
-public declaration convergence, accessibility and release validation are recorded
+ecosystem declaration work, accessibility and release validation are recorded
 in refactor/tasks.json and should extend this map as they land.

packages/artplayer/package.json

@@ -31,6 +31,29 @@
     "./types": {
       "types": "./types/artplayer.d.ts"
     },
+    "./runtime": {
+      "import": {
+        "types": "./types/runtime.d.mts",
+        "default": "./dist/artplayer.mjs"
+      },
+      "require": {
+        "types": "./types/runtime.d.cts",
+        "default": "./dist/artplayer.js"
+      }
+    },
+    "./runtime/types": {
+      "types": "./types/runtime.d.ts"
+    },
+    "./runtime/legacy": {
+      "import": {
+        "types": "./types/runtime.d.cts",
+        "default": "./dist/artplayer.legacy.js"
+      },
+      "require": {
+        "types": "./types/runtime.d.cts",
+        "default": "./dist/artplayer.legacy.js"
+      }
+    },
     "./legacy": {
       "import": {
         "types": "./types/artplayer.d.cts",
@@ -60,6 +83,15 @@
       "types": [
         "types/artplayer.d.ts"
       ],
+      "runtime": [
+        "types/runtime.d.ts"
+      ],
+      "runtime/types": [
+        "types/runtime.d.ts"
+      ],
+      "runtime/legacy": [
+        "types/runtime.d.ts"
+      ],
       "i18n/*": [
         "types/legacy/language.d.ts"
       ],

packages/artplayer/public/artplayer.cts

@@ -0,0 +1,29 @@
+import type * as Definition from './artplayer.js'
+
+declare const Artplayer: typeof Definition.default
+// eslint-disable-next-line ts/no-redeclare -- CJS constructor value and instance type share the export.
+type Artplayer = Definition.default
+
+// eslint-disable-next-line ts/no-redeclare, ts/no-namespace -- Namespace merging carries named types on the existing CJS export.
+declare namespace Artplayer {
+  type Config = Definition.Config
+  type Emitter<Events extends { [Name in keyof Events]: readonly unknown[] } = Record<PropertyKey, unknown[]>> = Definition.Emitter<Events>
+  type Events = Definition.Events
+  type I18n = Definition.I18n
+  type Icons = Definition.Icons
+  type Option = Definition.Option
+  type OptionInput = Definition.OptionInput
+  type Player = Definition.Player
+  type PlaybackControls = Definition.PlaybackControls
+  type PluginFactory<Host = Artplayer, Result = unknown> = Definition.PluginFactory<Host, Result>
+  type Plugins = Definition.Plugins
+  type Setting = Definition.Setting
+  type SettingOption = Definition.SettingOption
+  type Subtitle = Definition.Subtitle
+  type SubtitleUpdateEvents = Definition.SubtitleUpdateEvents
+  type Template = Definition.Template
+  type Utils = Definition.Utils
+}
+
+// eslint-disable-next-line no-restricted-syntax -- Preserve the real CommonJS constructor export.
+export = Artplayer

packages/artplayer/public/artplayer.mts

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

packages/artplayer/public/artplayer.ts

@@ -0,0 +1,216 @@
+import type { Component } from './component'
+import type { Config } from './config'
+import type { Emitter } from './emitter'
+import type { Events, SubtitleUpdateEvents } from './events'
+import type { I18n } from './i18n'
+import type { Icons } from './icons'
+import type { Option, OptionInput } from './option'
+import type { PlaybackControls } from './playback'
+import type { Player } from './player'
+import type { PluginFactory, Plugins } from './plugin'
+import type { Setting, SettingOption } from './setting'
+import type { Subtitle } from './subtitle'
+import type { Template } from './template'
+import type { Utils } from './utils'
+
+export type {
+  Config,
+  Emitter,
+  Events,
+  I18n,
+  Icons,
+  Option,
+  OptionInput,
+  PlaybackControls,
+  Player,
+  PluginFactory,
+  Plugins,
+  Setting,
+  SettingOption,
+  Subtitle,
+  SubtitleUpdateEvents,
+  Template,
+  Utils,
+}
+
+declare class Artplayer extends Player {
+  constructor(option: Option, readyCallback?: (this: Artplayer, art: Artplayer) => unknown)
+  constructor(option: OptionInput, readyCallback?: (this: Artplayer, art: Artplayer) => unknown)
+
+  static readonly instances: Artplayer[]
+  static readonly version: string
+  static readonly env: 'development' | 'production'
+  static readonly build: string
+  static readonly config: Config
+  static readonly utils: Utils
+  static readonly scheme: Record<keyof Option, unknown>
+  static readonly Emitter: new <Events extends { [Name in keyof Events]: readonly unknown[] } = Record<PropertyKey, unknown[]>>(...args: unknown[]) => Emitter<Events>
+  static readonly validator: <T extends object>(option: T, scheme: object) => T
+  static readonly kindOf: (item: unknown) => string
+  static readonly html: Artplayer['template']['html']
+  static readonly option: Option
+
+  static STYLE: string
+  static DEBUG: boolean
+  static CONTEXTMENU: boolean
+  static NOTICE_TIME: number
+  static SETTING_WIDTH: number
+  static SETTING_ITEM_WIDTH: number
+  static SETTING_ITEM_HEIGHT: number
+  static RESIZE_TIME: number
+  static SCROLL_TIME: number
+  static SCROLL_GAP: number
+  static AUTO_PLAYBACK_MAX: number
+  static AUTO_PLAYBACK_MIN: number
+  static AUTO_PLAYBACK_TIMEOUT: number
+  static RECONNECT_TIME_MAX: number
+  static RECONNECT_SLEEP_TIME: number
+  static CONTROL_HIDE_TIME: number
+  static DBCLICK_TIME: number
+  static DBCLICK_FULLSCREEN: boolean
+  static MOBILE_DBCLICK_PLAY: boolean
+  static MOBILE_CLICK_PLAY: boolean
+  static AUTO_ORIENTATION_TIME: number
+  static INFO_LOOP_TIME: number
+  static FAST_FORWARD_VALUE: number
+  static FAST_FORWARD_TIME: number
+  static TOUCH_MOVE_RATIO: number
+  static VOLUME_STEP: number
+  static SEEK_STEP: number
+  static PLAYBACK_RATE: number[]
+  static ASPECT_RATIO: string[]
+  static FLIP: string[]
+  static FULLSCREEN_WEB_IN_BODY: boolean
+  static LOG_VERSION: boolean
+  static USE_RAF: boolean
+  static REMOVE_SRC_WHEN_DESTROY: boolean
+
+  readonly id: number
+  readonly option: Option
+  readonly isLock: boolean
+  readonly isReady: boolean
+  readonly isFocus: boolean
+  readonly isInput: boolean
+  readonly isRotate: boolean
+  readonly isDestroy: boolean
+
+  flv?: unknown
+  m3u8?: unknown
+  hls?: unknown
+  ts?: unknown
+  mpd?: unknown
+  torrent?: unknown
+
+  on<T extends keyof Events>(name: T, fn: (...args: Events[T]) => unknown, ctx?: object): this
+  on<T extends keyof SubtitleUpdateEvents>(name: T, fn: (...args: SubtitleUpdateEvents[T]) => unknown, ctx?: object): this
+  on(name: string, fn: (...args: unknown[]) => unknown, ctx?: object): this
+
+  once<T extends keyof Events>(name: T, fn: (...args: Events[T]) => unknown, ctx?: object): this
+  once<T extends keyof SubtitleUpdateEvents>(name: T, fn: (...args: SubtitleUpdateEvents[T]) => unknown, ctx?: object): this
+  once(name: string, fn: (...args: unknown[]) => unknown, ctx?: object): this
+
+  emit<T extends keyof Events>(name: T, ...args: Events[T]): this
+  emit<T extends keyof SubtitleUpdateEvents>(name: T, ...args: SubtitleUpdateEvents[T]): this
+  emit(name: string, ...args: unknown[]): this
+
+  off<T extends keyof Events>(name: T, callback?: (...args: Events[T]) => unknown): this
+  off<T extends keyof SubtitleUpdateEvents>(name: T, callback?: (...args: SubtitleUpdateEvents[T]) => unknown): this
+  off(name: string, callback?: (...args: unknown[]) => unknown): this
+
+  query: Artplayer['template']['query']
+  proxy: Artplayer['events']['proxy']
+  video: Artplayer['template']['$video']
+
+  e: { [K in keyof Events]?: { fn: (...args: Events[K]) => unknown, ctx: unknown }[] }
+
+  destroy(removeHtml?: boolean): void
+  reset(): void
+
+  readonly template: {
+    get html(): string
+    query: <T extends Element = Element>(selector: string) => T | null
+  } & Template
+
+  readonly events: {
+    proxy: {
+      (target: EventTarget, eventName: string, handler: (event: Event) => void, options?: boolean | AddEventListenerOptions): () => void
+      (target: EventTarget, eventName: string[], handler: (event: Event) => void, options?: boolean | AddEventListenerOptions): Array<() => void>
+    }
+    hover: (element: HTMLElement, mouseenter?: (event: Event) => any, mouseleave?: (event: Event) => any) => void
+    remove: (destroyEvent: () => void) => void
+    destroy: () => void
+    bindGlobalEvents: (source?: { window?: Window, document?: Document }) => void
+  }
+
+  readonly storage: {
+    name: string
+    settings: Record<string, unknown>
+    get: {
+      (key: string): unknown
+      (): Record<string, unknown>
+    }
+    set: (key: string, value: unknown) => void
+    del: (key: string) => void
+    clear: () => void
+  }
+
+  readonly icons: Icons
+
+  readonly i18n: {
+    languages: I18n
+    language: Partial<Record<string, string>>
+    init: () => void
+    get: (key: string) => string
+    update: (language: Partial<I18n>) => void
+  }
+
+  readonly notice: {
+    timer: number | null
+    get show(): string | Error | false | ''
+    set show(msg: string | Error | false | '')
+    destroy: () => void
+  }
+
+  readonly layers: Record<string, HTMLElement | undefined> & Component
+  readonly controls: Record<string, HTMLElement | undefined> & Component
+  readonly contextmenu: Record<string, HTMLElement | undefined> & Component
+
+  readonly subtitle: {
+    get url(): string
+    set url(url: string)
+    get textTrack(): TextTrack | undefined
+    get activeCues(): VTTCue[]
+    get cues(): VTTCue[]
+    style: (name: string | Partial<CSSStyleDeclaration>, value?: string) => void
+    switch: (url: string, option?: Subtitle) => Promise<string>
+    init: (subtitle: Subtitle) => Promise<string | null | undefined>
+  } & Component
+
+  readonly info: Component
+  readonly loading: Component
+
+  readonly hotkey: {
+    keys: Record<string, ((event: KeyboardEvent) => any)[]>
+    add: (key: string, callback: (this: Artplayer, event: KeyboardEvent) => any) => Artplayer['hotkey']
+    remove: (key: string, callback: (event: KeyboardEvent) => any) => Artplayer['hotkey']
+  }
+
+  readonly mask: Component
+
+  readonly setting: {
+    option: SettingOption[]
+    updateStyle: (width?: number) => void
+    /** Legacy return signature; a missing runtime entry is null. */
+    find: (name: string) => SettingOption | undefined
+    /** Legacy return signature; runtime returns the formatted input item. */
+    add: (setting: Setting) => Artplayer['setting']
+    /** Legacy return signature; runtime returns the updated or added item. */
+    update: (settings: Setting) => Artplayer['setting']
+    /** Legacy return signature; runtime returns undefined. */
+    remove: (name: string) => Artplayer['setting']
+  } & Component
+
+  readonly plugins: Plugins
+}
+
+export default Artplayer

packages/artplayer/public/component.ts

@@ -0,0 +1,143 @@
+import type Artplayer from './artplayer'
+
+/** Input accepted by the existing HTML renderer, including numeric content. */
+export interface ComponentInput extends Omit<ComponentOption, 'html'> {
+  html?: string | HTMLElement | number
+}
+
+export interface Selector {
+  /**
+   * Whether the default is selected
+   */
+  default?: boolean
+
+  /**
+   * Html string of selector
+   */
+  html: string | HTMLElement
+
+  /**
+   * Value of selector item
+   */
+  value?: string | number
+
+  /**
+   * Allow custom properties
+   */
+  [key: string]: any
+}
+
+export interface Component {
+  /**
+   * Component self-increasing id
+   */
+  readonly id: number
+
+  /**
+   * Component parent name
+   */
+  readonly name: string | undefined
+
+  /**
+   * Component parent element
+   */
+  readonly $parent: HTMLElement | undefined
+
+  /**
+   * Whether to show component parent
+   */
+  get show(): boolean
+
+  /**
+   * Whether to show component parent
+   */
+  set show(state: boolean)
+
+  /**
+   * Toggle the component parent
+   */
+  toggle: () => void
+
+  /**
+   * Dynamic add a component
+   */
+  add: {
+    (option: ComponentOption | ((art: Artplayer) => ComponentOption)): HTMLElement | undefined
+    (option: ComponentInput | ((art: Artplayer) => ComponentInput)): HTMLElement | undefined
+  }
+
+  /**
+   * Dynamic remove a component by name
+   */
+  remove: (name: string) => void
+
+  /**
+   * Dynamic update a component
+   */
+  update: {
+    (option: ComponentOption): HTMLElement | undefined
+    (option: ComponentInput): HTMLElement | undefined
+  }
+}
+
+export interface ComponentOption {
+  /**
+   * Html string or html element of component
+   */
+  html?: string | HTMLElement
+
+  /**
+   * Whether to disable component
+   */
+  disable?: boolean
+
+  /**
+   * Unique name for component
+   */
+  name?: string
+
+  /**
+   * Component sort index
+   */
+  index?: number
+
+  /**
+   * Component style object
+   */
+  style?: Partial<CSSStyleDeclaration>
+
+  /**
+   * Component click event
+   */
+  click?: (this: Artplayer, component: Component, event: Event) => void
+
+  /**
+   * When the component was mounted
+   */
+  mounted?: (this: Artplayer, element: HTMLElement) => void
+
+  /**
+   * When the component was before unmount
+   */
+  beforeUnmount?: (this: Artplayer, element: HTMLElement) => void
+
+  /**
+   * Component tooltip, use in controls
+   */
+  tooltip?: string
+
+  /**
+   * Component position, use in controls
+   */
+  position?: 'top' | 'left' | 'right' | (string & Record<never, never>)
+
+  /**
+   * Custom selector list, use in controls
+   */
+  selector?: Selector[]
+
+  /**
+   * When selector item click, use in controls
+   */
+  onSelect?: (this: Artplayer, selector: Selector, element: HTMLElement, event: Event) => void
+}

packages/artplayer/public/config.ts

@@ -0,0 +1,81 @@
+export interface Config {
+  readonly properties: readonly [
+    'audioTracks',
+    'autoplay',
+    'buffered',
+    'controller',
+    'controls',
+    'crossOrigin',
+    'currentSrc',
+    'currentTime',
+    'defaultMuted',
+    'defaultPlaybackRate',
+    'duration',
+    'ended',
+    'error',
+    'loop',
+    'mediaGroup',
+    'muted',
+    'networkState',
+    'paused',
+    'playbackRate',
+    'played',
+    'preload',
+    'readyState',
+    'seekable',
+    'seeking',
+    'src',
+    'startDate',
+    'textTracks',
+    'videoTracks',
+    'volume',
+  ]
+  readonly methods: readonly ['addTextTrack', 'canPlayType', 'load', 'play', 'pause']
+  readonly events: readonly [
+    'abort',
+    'canplay',
+    'canplaythrough',
+    'durationchange',
+    'emptied',
+    'ended',
+    'error',
+    'loadeddata',
+    'loadedmetadata',
+    'loadstart',
+    'pause',
+    'play',
+    'playing',
+    'progress',
+    'ratechange',
+    'seeked',
+    'seeking',
+    'stalled',
+    'suspend',
+    'timeupdate',
+    'volumechange',
+    'waiting',
+  ]
+  readonly prototypes: readonly [
+    'width',
+    'height',
+    'videoWidth',
+    'videoHeight',
+    'poster',
+    'webkitDecodedFrameCount',
+    'webkitDroppedFrameCount',
+    'playsInline',
+    'webkitSupportsFullscreen',
+    'webkitDisplayingFullscreen',
+    'onenterpictureinpicture',
+    'onleavepictureinpicture',
+    'disablePictureInPicture',
+    'cancelVideoFrameCallback',
+    'requestVideoFrameCallback',
+    'getVideoPlaybackQuality',
+    'requestPictureInPicture',
+    'webkitEnterFullScreen',
+    'webkitEnterFullscreen',
+    'webkitExitFullScreen',
+    'webkitExitFullscreen',
+  ]
+}

packages/artplayer/public/cssVar.ts

@@ -0,0 +1,45 @@
+export interface CssVar {
+  '--art-theme': string
+  '--art-font-color': string
+  '--art-background-color': string
+  '--art-text-shadow-color': string
+  '--art-transition-duration': string
+  '--art-padding': string
+  '--art-border-radius': string
+  '--art-progress-height': string
+  '--art-progress-color': string
+  '--art-progress-top-gap': string
+  '--art-hover-color': string
+  '--art-loaded-color': string
+  '--art-state-size': string
+  '--art-state-opacity': number
+  '--art-bottom-height': string
+  '--art-bottom-offset': string
+  '--art-bottom-gap': string
+  '--art-highlight-width': string
+  '--art-highlight-color': string
+  '--art-control-height': string
+  '--art-control-opacity': number
+  '--art-control-icon-size': string
+  '--art-control-icon-scale': number
+  '--art-volume-height': string
+  '--art-volume-handle-size': string
+  '--art-lock-size': string
+  '--art-indicator-scale': number
+  '--art-indicator-size': string
+  '--art-fullscreen-web-index': 9999
+  '--art-settings-icon-size': string
+  '--art-settings-max-height': string
+  '--art-selector-max-height': string
+  '--art-contextmenus-min-width': string
+  '--art-subtitle-font-size': string
+  '--art-subtitle-gap': string
+  '--art-subtitle-bottom': string
+  '--art-subtitle-border': string
+  '--art-widget-background': string
+  '--art-tip-background': string
+  '--art-scrollbar-size': string
+  '--art-scrollbar-background': string
+  '--art-scrollbar-background-hover': string
+  '--art-mini-progress-height': string
+}

packages/artplayer/public/emitter.ts

@@ -0,0 +1,8 @@
+/** The event bus exposed by Artplayer.Emitter; no new runtime export. */
+export interface Emitter<Events extends { [Name in keyof Events]: readonly unknown[] } = Record<PropertyKey, unknown[]>> {
+  e?: { [Name in keyof Events]?: { fn: (...args: [...Events[Name]]) => unknown, ctx: unknown }[] }
+  on: <Name extends keyof Events, Context>(name: Name, fn: (this: Context, ...args: [...Events[Name]]) => unknown, ctx?: Context) => this
+  once: <Name extends keyof Events, Context>(name: Name, fn: (this: Context, ...args: [...Events[Name]]) => unknown, ctx?: Context) => this
+  emit: <Name extends keyof Events>(name: Name, ...args: [...Events[Name]]) => this
+  off: <Name extends keyof Events>(name: Name, fn?: (...args: [...Events[Name]]) => unknown) => this
+}

packages/artplayer/public/events.ts

@@ -0,0 +1,106 @@
+import type { AspectRatio, Flip } from './player'
+import type { Subtitle } from './subtitle'
+
+export type Bar = 'loaded' | 'played' | 'hover'
+
+/** Actual built-in subtitle update payloads; legacy Events keeps its scalar types. */
+export interface SubtitleUpdateEvents {
+  subtitleBeforeUpdate: [cues: VTTCue[]]
+  subtitleAfterUpdate: [cues: VTTCue[]]
+}
+
+export interface Events {
+  'document:click': [event: Event]
+  'document:mouseup': [event: Event]
+  'document:keydown': [event: Event]
+  'document:touchend': [event: Event]
+  'document:touchcancel': [event: Event]
+  'document:touchmove': [event: Event]
+  'document:mousemove': [event: Event]
+  'document:pointerup': [event: Event]
+  'document:contextmenu': [event: Event]
+  'document:pointermove': [event: Event]
+  'document:visibilitychange': [event: Event]
+  'document:webkitfullscreenchange': [event: Event]
+
+  'window:resize': [event: Event]
+  'window:scroll': [event: Event]
+  'window:orientationchange': [event: Event]
+
+  'video:abort': [event: Event]
+  'video:canplay': [event: Event]
+  'video:canplaythrough': [event: Event]
+  'video:complete': [event: Event]
+  'video:durationchange': [event: Event]
+  'video:emptied': [event: Event]
+  'video:encrypted': [event: Event]
+  'video:ended': [event: Event]
+  'video:error': [error: Error]
+  'video:loadeddata': [event: Event]
+  'video:loadedmetadata': [event: Event]
+  'video:loadstart': [event: Event]
+  'video:pause': [event: Event]
+  'video:play': [event: Event]
+  'video:playing': [event: Event]
+  'video:progress': [event: Event]
+  'video:ratechange': [event: Event]
+  'video:seeked': [event: Event]
+  'video:seeking': [event: Event]
+  'video:stalled': [event: Event]
+  'video:suspend': [event: Event]
+  'video:timeupdate': [event: Event]
+  'video:volumechange': [event: Event]
+  'video:waiting': [event: Event]
+
+  'info': [state: boolean]
+  'layer': [state: boolean]
+  'loading': [state: boolean]
+  'mask': [state: boolean]
+  'subtitle': [state: boolean]
+  'contextmenu': [state: boolean]
+  'control': [state: boolean]
+  'setting': [state: boolean]
+  'hotkey': [event: KeyboardEvent]
+
+  'destroy': []
+
+  'subtitleOffset': [offset: number]
+  /** Legacy contextual type; annotate listeners with VTTCue[] for the runtime payload. */
+  'subtitleBeforeUpdate': [cue: VTTCue]
+  /** Legacy contextual type; annotate listeners with VTTCue[] for the runtime payload. */
+  'subtitleAfterUpdate': [cue: VTTCue]
+  'subtitleLoad': [cues: VTTCue[], option: Subtitle]
+
+  'focus': [event: Event]
+  'blur': [event: Event]
+  'dblclick': [event: Event]
+  'click': [event: Event]
+  'hover': [state: boolean, event: Event]
+  'mousemove': [event: Event]
+
+  'resize': []
+  'view': [state: boolean]
+  'lock': [state: boolean]
+  'aspectRatio': [aspectRatio: AspectRatio]
+  'autoHeight': [height: number]
+  'autoSize': [size: { width: number, height: number }]
+  'ready': []
+  'airplay': []
+  'raf': []
+
+  'error': [error: Error, reconnectTime: number]
+  'flip': [flip: Flip]
+  'fullscreen': [state: boolean]
+  'fullscreenError': [event: Event]
+  'fullscreenWeb': [state: boolean]
+  'mini': [state: boolean]
+  'pause': []
+  'pip': [state: boolean]
+  'play': []
+  'screenshot': [dataUri: string]
+  'seek': [currentTime: number, time: number]
+  'restart': [url: string]
+  'muted': [state: boolean]
+  'setBar': [type: Bar, percentage: number, event?: Event | undefined]
+  'keydown': [event: KeyboardEvent]
+}

packages/artplayer/public/i18n.ts

@@ -0,0 +1,56 @@
+type I18nKeys
+  = | 'en'
+    | 'zh-cn'
+    | 'zh-tw'
+    | 'pl'
+    | 'cs'
+    | 'es'
+    | 'fa'
+    | 'fr'
+    | 'id'
+    | 'ru'
+    | 'tr'
+    | 'ar'
+    | 'vi'
+    | (string & Record<never, never>)
+
+interface I18nValue {
+  'Video Info': string
+  'Close': string
+  'Video Load Failed': string
+  'Volume': string
+  'Play': string
+  'Pause': string
+  'Rate': string
+  'Mute': string
+  'Video Flip': string
+  'Horizontal': string
+  'Vertical': string
+  'Reconnect': string
+  'Show Setting': string
+  'Hide Setting': string
+  'Screenshot': string
+  'Play Speed': string
+  'Aspect Ratio': string
+  'Default': string
+  'Normal': string
+  'Open': string
+  'Switch Video': string
+  'Switch Subtitle': string
+  'Fullscreen': string
+  'Exit Fullscreen': string
+  'Web Fullscreen': string
+  'Exit Web Fullscreen': string
+  'Mini Player': string
+  'PIP Mode': string
+  'Exit PIP Mode': string
+  'PIP Not Supported': string
+  'Fullscreen Not Supported': string
+  'Subtitle Offset': string
+  'Last Seen': string
+  'Jump Play': string
+  'AirPlay': string
+  'AirPlay Not Available': string
+}
+
+export type I18n = Partial<Record<I18nKeys, Partial<I18nValue>>>

packages/artplayer/public/icons.ts

@@ -0,0 +1,30 @@
+export interface Icons {
+  readonly loading: HTMLDivElement
+  readonly state: HTMLDivElement
+  readonly play: HTMLDivElement
+  readonly pause: HTMLDivElement
+  readonly check: HTMLDivElement
+  readonly volume: HTMLDivElement
+  readonly volumeClose: HTMLDivElement
+  readonly screenshot: HTMLDivElement
+  readonly setting: HTMLDivElement
+  readonly pip: HTMLDivElement
+  readonly arrowLeft: HTMLDivElement
+  readonly arrowRight: HTMLDivElement
+  readonly playbackRate: HTMLDivElement
+  readonly aspectRatio: HTMLDivElement
+  readonly config: HTMLDivElement
+  readonly lock: HTMLDivElement
+  readonly flip: HTMLDivElement
+  readonly unlock: HTMLDivElement
+  readonly fullscreenOff: HTMLDivElement
+  readonly fullscreenOn: HTMLDivElement
+  readonly fullscreenWebOff: HTMLDivElement
+  readonly fullscreenWebOn: HTMLDivElement
+  readonly switchOn: HTMLDivElement
+  readonly switchOff: HTMLDivElement
+  readonly error: HTMLDivElement
+  readonly close: HTMLDivElement
+  readonly airplay: HTMLDivElement
+  readonly [key: string]: HTMLDivElement
+}

packages/artplayer/public/language.cts

@@ -0,0 +1,5 @@
+import type { I18n } from './i18n.js'
+
+declare const language: NonNullable<I18n['en']>
+// eslint-disable-next-line no-restricted-syntax -- Preserve the language object's CommonJS value export.
+export = language

packages/artplayer/public/language.mts

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

packages/artplayer/public/legacy/language.ts

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

packages/artplayer/public/option.ts

@@ -0,0 +1,331 @@
+import type Artplayer from './artplayer'
+import type { ComponentInput, ComponentOption } from './component'
+import type { CssVar } from './cssVar'
+import type { I18n } from './i18n'
+import type { Icons } from './icons'
+import type { PluginFactory } from './plugin'
+import type { Quality } from './quality'
+import type { Setting } from './setting'
+import type { Subtitle } from './subtitle'
+
+export type CustomType
+  = | 'flv'
+    | 'm3u8'
+    | 'hls'
+    | 'ts'
+    | 'mpd'
+    | 'torrent'
+    | (string & Record<never, never>)
+
+export interface Thumbnails {
+  /**
+   * The thumbnail image url
+   */
+  url: string
+
+  /**
+   * The thumbnail item number
+   */
+  number?: number
+
+  /**
+   * The thumbnail column size
+   */
+  column?: number
+
+  /**
+   * The thumbnail width
+   */
+  width?: number
+
+  /**
+   * The thumbnail height
+   */
+  height?: number
+
+  /**
+   * The thumbnail scale
+   */
+  scale?: number
+}
+
+/** Constructor input; Option retains its historical required URL/read types. */
+export interface OptionInput extends Omit<Option, 'url' | 'controls' | 'layers' | 'contextmenu'> {
+  url?: string
+  controls?: ComponentInput[]
+  layers?: ComponentInput[]
+  contextmenu?: ComponentInput[]
+}
+
+export interface Option {
+  /**
+   * The player id
+   */
+  id?: string
+
+  /**
+   * The container mounted by the player
+   */
+  container: string | HTMLDivElement
+
+  /**
+   * Video url
+   */
+  url: string
+
+  /**
+   * Video poster image url
+   */
+  poster?: string
+
+  /**
+   * Video url type
+   */
+  type?: CustomType
+
+  /**
+   * Player color theme
+   */
+  theme?: string
+
+  /**
+   * Player language
+   */
+  lang?: keyof I18n
+
+  /**
+   * Player default volume
+   */
+  volume?: number
+
+  /**
+   * Whether live broadcast mode
+   */
+  isLive?: boolean
+
+  /**
+   * Whether video muted
+   */
+  muted?: boolean
+
+  /**
+   * Whether video auto play
+   */
+  autoplay?: boolean
+
+  /**
+   * Whether player auto resize
+   */
+  autoSize?: boolean
+
+  /**
+   * Whether player auto run mini mode
+   */
+  autoMini?: boolean
+
+  /**
+   * Whether video auto loop
+   */
+  loop?: boolean
+
+  /**
+   * Whether show video flip button
+   */
+  flip?: boolean
+
+  /**
+   * Whether show video playback rate button
+   */
+  playbackRate?: boolean
+
+  /**
+   * Whether show video aspect ratio button
+   */
+  aspectRatio?: boolean
+
+  /**
+   * Whether show video screenshot button
+   */
+  screenshot?: boolean
+
+  /**
+   * Whether show video setting button
+   */
+  setting?: boolean
+
+  /**
+   * Whether to enable player hotkey
+   */
+  hotkey?: boolean
+
+  /**
+   * Whether show video pip button
+   */
+  pip?: boolean
+
+  /**
+   * Do you want to run only one player at a time
+   */
+  mutex?: boolean
+
+  /**
+   * Whether use backdrop in UI
+   */
+  backdrop?: boolean
+
+  /**
+   * Whether show video window fullscreen button
+   */
+  fullscreen?: boolean
+
+  /**
+   * Whether show video web fullscreen button
+   */
+  fullscreenWeb?: boolean
+
+  /**
+   * Whether to enable player subtitle offset
+   */
+  subtitleOffset?: boolean
+
+  /**
+   * Whether to enable player mini progress bar
+   */
+  miniProgressBar?: boolean
+
+  /**
+   * Whether use SSR function
+   */
+  useSSR?: boolean
+
+  /**
+   * Whether use playsInline in mobile
+   */
+  playsInline?: boolean
+
+  /**
+   * Whether use lock in mobile
+   */
+  lock?: boolean
+
+  /**
+   * Whether use gesture in mobile
+   */
+  gesture?: boolean
+
+  /**
+   * Whether use fast forward in mobile
+   */
+  fastForward?: boolean
+
+  /**
+   * Whether use auto playback
+   */
+  autoPlayback?: boolean
+
+  /**
+   * Whether use auto orientation in mobile
+   */
+  autoOrientation?: boolean
+
+  /**
+   * Whether use airplay
+   */
+  airplay?: boolean
+
+  /**
+   * Custom video proxy
+   */
+  proxy?: (this: Artplayer, art: Artplayer) => HTMLCanvasElement | HTMLVideoElement | undefined
+
+  /**
+   * Custom plugin list
+   */
+  plugins?: PluginFactory[]
+
+  /**
+   * Custom layer list
+   */
+  layers?: ComponentOption[]
+
+  /**
+   * Custom contextmenu list
+   */
+  contextmenu?: ComponentOption[]
+
+  /**
+   * Custom control list
+   */
+  controls?: ComponentOption[]
+
+  /**
+   * Custom setting list
+   */
+  settings?: Setting[]
+
+  /**
+   * Custom video quality list
+   */
+  quality?: Quality[]
+
+  /**
+   * Custom highlight list
+   */
+  highlight?: {
+    /**
+     * The highlight time
+     */
+    time: number
+
+    /**
+     * The highlight text
+     */
+    text: string
+  }[]
+
+  /**
+   * Custom thumbnail
+   */
+  thumbnails?: Thumbnails
+
+  /**
+   * Custom subtitle option
+   */
+  subtitle?: Subtitle
+
+  /**
+   * Other video attribute
+   */
+  moreVideoAttr?: Partial<Readonly<{
+    [K in keyof HTMLVideoElement as HTMLVideoElement[K] extends (...args: unknown[]) => unknown
+      ? never
+      : K]: HTMLVideoElement[K]
+  }>>
+
+  /**
+   * Custom i18n
+   */
+  i18n?: I18n
+
+  /**
+   * Custom default icons
+   */
+  icons?: {
+    [key in keyof Icons]?: HTMLElement | string
+  }
+
+  /**
+   * Custom css variables
+   */
+  cssVar?: Partial<CssVar>
+
+  /**
+   * Custom video type function
+   */
+  customType?: Partial<
+    Record<
+      CustomType,
+      (this: Artplayer, video: HTMLVideoElement, url: string, art: Artplayer) => unknown | Promise<unknown>
+    >
+  >
+}

packages/artplayer/public/playback.ts

@@ -0,0 +1,6 @@
+/** Accurate playback method view; assign an existing player without a runtime wrapper. */
+export interface PlaybackControls {
+  play: () => Promise<void>
+  pause: () => void
+  toggle: () => Promise<void> | void
+}

packages/artplayer/public/player.ts

@@ -0,0 +1,113 @@
+import type { CssVar } from './cssVar'
+import type { CustomType, Thumbnails } from './option'
+import type { Quality } from './quality'
+
+export type AspectRatio = 'default' | '4:3' | '16:9' | (`${number}:${number}` & Record<never, never>)
+export type PlaybackRate = 0.5 | 0.75 | 1.0 | 1.25 | 1.5 | 1.75 | 2.0 | (number & Record<never, never>)
+export type Flip = 'normal' | 'horizontal' | 'vertical' | (string & Record<never, never>)
+export type State = 'standard' | 'mini' | 'pip' | 'fullscreen' | 'fullscreenWeb'
+
+export declare class Player {
+  get aspectRatio(): AspectRatio
+  set aspectRatio(ratio: AspectRatio)
+
+  get state(): State
+  set state(state: State)
+
+  get type(): CustomType
+  set type(name: CustomType)
+
+  get playbackRate(): PlaybackRate
+  set playbackRate(rate: PlaybackRate)
+
+  get currentTime(): number
+  set currentTime(time: number)
+
+  get duration(): number
+  get played(): number
+  get playing(): boolean
+
+  get flip(): Flip
+  set flip(state: Flip)
+
+  get fullscreen(): boolean
+  set fullscreen(state: boolean)
+
+  get fullscreenWeb(): boolean
+  set fullscreenWeb(state: boolean)
+
+  get loaded(): number
+  get loadedTime(): number
+
+  get mini(): boolean
+  set mini(state: boolean)
+
+  get pip(): boolean
+  set pip(state: boolean)
+
+  get poster(): string
+  set poster(url: string)
+
+  get rect(): DOMRect
+  get bottom(): number
+  get height(): number
+  get left(): number
+  get right(): number
+  get top(): number
+  get width(): number
+  get x(): number
+  get y(): number
+
+  set seek(time: number)
+  get seek(): number
+
+  set forward(time: number)
+  get forward(): number
+
+  set backward(time: number)
+  get backward(): number
+
+  get url(): string
+  set url(url: string)
+
+  get volume(): number
+  set volume(percentage: number)
+
+  get muted(): boolean
+  set muted(state: boolean)
+
+  get theme(): string
+  set theme(theme: string)
+
+  get subtitleOffset(): number
+  set subtitleOffset(time: number)
+
+  get switch(): string
+  set switch(url: string)
+
+  get quality(): Quality[]
+  set quality(quality: Quality[])
+
+  get thumbnails(): Thumbnails
+  set thumbnails(thumbnails: Thumbnails)
+
+  pause(): void
+  play(): Promise<void>
+  /** Legacy signature; runtime preserves pause's synchronous result or play's Promise. */
+  toggle(): void
+
+  attr(key: string, value?: unknown): unknown
+  cssVar<T extends keyof CssVar>(key: T, value?: CssVar[T]): CssVar[T]
+
+  switchUrl(url: string): Promise<void>
+  switchQuality(url: string): Promise<void>
+
+  getDataURL(): Promise<string>
+  getBlobUrl(): Promise<string>
+  screenshot(name?: string): Promise<string>
+
+  airplay(): void
+  autoSize(): void
+  autoHeight(): void
+  reset(): void
+}

packages/artplayer/public/plugin.ts

@@ -0,0 +1,10 @@
+import type Artplayer from './artplayer'
+
+export type PluginFactory<Host = Artplayer, Result = unknown> = (this: Host, art: Host) => Result
+
+/** Augment this interface with installed plugin results; augmentation does not register a plugin. */
+export interface Plugins {
+  /** Legacy signature: synchronous factories return this registry; Promise factories return a Promise of it. */
+  add: (plugin: PluginFactory) => Promise<Plugins>
+  [name: string]: unknown
+}

packages/artplayer/public/quality.ts

@@ -0,0 +1,16 @@
+export interface Quality {
+  /**
+   * Whether the default is selected
+   */
+  default?: boolean
+
+  /**
+   * Html string of quality
+   */
+  html: string | HTMLElement
+
+  /**
+   * Video quality url
+   */
+  url: string
+}

packages/artplayer/public/runtime.cts

@@ -0,0 +1,54 @@
+import type * as Definition from './runtime.js'
+
+declare const Artplayer: typeof Definition.default
+// eslint-disable-next-line ts/no-redeclare -- CJS constructor value and instance type share the export.
+type Artplayer = Definition.default
+
+// eslint-disable-next-line ts/no-redeclare, ts/no-namespace -- Named types share the existing CommonJS export.
+declare namespace Artplayer {
+  type ArtplayerConstructor = Definition.ArtplayerConstructor
+  type OptionInput = Definition.OptionInput
+  type Option = Definition.Option
+  type Events = Definition.Events
+  type Plugins = Definition.Plugins
+  type PluginFactory<Result = unknown> = Definition.PluginFactory<Result>
+  type PluginHost = Definition.PluginHost
+  type ProxyHost = Definition.ProxyHost
+  type CustomTypeHost = Definition.CustomTypeHost
+  type LayerHost = Definition.LayerHost
+  type ControlHost = Definition.ControlHost
+  type ContextmenuHost = Definition.ContextmenuHost
+  type PluginRegistration<Result, Registry> = Definition.PluginRegistration<Result, Registry>
+  type Component = Definition.Component
+  type Controls = Definition.Controls
+  type Setting = Definition.Setting
+  type Subtitle = Definition.Subtitle
+  type Notice = Definition.Notice
+  type Utils = Definition.Utils
+  type MediaSurface = Definition.MediaSurface
+  type NativeMedia = Definition.NativeMedia
+  type CanvasMedia = Definition.CanvasMedia
+  type Player<Media extends MediaSurface = MediaSurface> = Definition.Player<Media>
+  type Template<Host = Artplayer, Media extends MediaSurface = MediaSurface> = Definition.Template<Host, Media>
+  type Icons = Definition.Icons
+  type Config = Definition.Config
+  type EventRegistry = Definition.EventRegistry
+  type Storage = Definition.Storage
+  type I18n<Host = Artplayer> = Definition.I18n<Host>
+  type Hotkey<Host = Artplayer> = Definition.Hotkey<Host>
+  type Languages = Definition.Languages
+  type Dictionary = Definition.Dictionary
+  type QualityItem = Definition.QualityItem
+  type SettingItem<Host = Artplayer> = Definition.SettingItem<Host>
+  type ComponentInput<Host = Artplayer> = Definition.ComponentInput<Host>
+  type ComponentOption<Host = Artplayer> = Definition.ComponentOption<Host>
+  type ControlInput<Host = Artplayer> = Definition.ControlInput<Host>
+  type ControlOption<Host = Artplayer> = Definition.ControlOption<Host>
+  type SelectorItem = Definition.SelectorItem
+  type SubtitleCue = Definition.SubtitleCue
+  type SubtitleOption = Definition.SubtitleOption
+  type Emitter<Events extends { [Name in keyof Events]: readonly unknown[] } = Record<PropertyKey, unknown[]>> = Definition.Emitter<Events>
+}
+
+// eslint-disable-next-line no-restricted-syntax -- Preserve the actual CommonJS constructor export.
+export = Artplayer

packages/artplayer/public/runtime.mts

@@ -0,0 +1,2 @@
+export { default } from './runtime.cjs'
+export type * from './runtime.js'

packages/artplayer/public/runtime.ts

@@ -0,0 +1,125 @@
+import type LegacyArtplayer from './artplayer'
+import type { Emitter } from './emitter'
+import type { OptionInput as LegacyOptionInput } from './option'
+import type { PluginFactory as LegacyPluginFactory, Plugins as LegacyPlugins } from './plugin'
+import type { ComponentInput, Component as ComponentView, ControlInput, Controls as ControlsView } from './runtime/component'
+import type { ContextmenuHost, ControlHost, CustomTypeHost, LayerHost, PluginHost, ProxyHost } from './runtime/construction'
+import type { Events } from './runtime/events'
+import type { MediaSurface } from './runtime/media'
+import type { OptionInput as OptionInputView, Option as OptionView } from './runtime/option'
+import type { Player } from './runtime/player'
+import type { PluginFactory as FactoryView, PluginRegistration, Plugins as PluginsView } from './runtime/plugin'
+import type { Config, EventRegistry, Hotkey, I18n, Scheme, Storage, ValidatorPath } from './runtime/services'
+import type { Setting as SettingView } from './runtime/setting'
+import type { Notice as NoticeView, Subtitle as SubtitleView } from './runtime/subtitle'
+import type { Icons, Template } from './runtime/template'
+import type { Utils } from './runtime/utils'
+
+export type { Emitter } from './emitter'
+export type { ComponentInput, ComponentOption, ControlInput, ControlOption, SelectorItem } from './runtime/component'
+export type { ContextmenuHost, ControlHost, CustomTypeHost, LayerHost, PluginHost, ProxyHost } from './runtime/construction'
+export type { Events } from './runtime/events'
+export type { CanvasMedia, MediaSurface, NativeMedia } from './runtime/media'
+export type { Player, QualityItem } from './runtime/player'
+export type { PluginRegistration } from './runtime/plugin'
+export type { Config, Dictionary, EventRegistry, Hotkey, I18n, Languages, Storage } from './runtime/services'
+export type { SettingItem } from './runtime/setting'
+export type { SubtitleCue, SubtitleOption } from './runtime/subtitle'
+export type { Icons, Template } from './runtime/template'
+export type { Utils } from './runtime/utils'
+
+export type PluginFactory<Result = unknown> = FactoryView<PluginHost, Result>
+export interface OptionInput extends Omit<OptionInputView<Artplayer>, 'plugins' | 'proxy' | 'customType' | 'layers' | 'controls' | 'contextmenu'> {
+  plugins?: PluginFactory[]
+  proxy?: (this: ProxyHost, art: ProxyHost) => MediaSurface
+  customType?: Record<string, ((this: CustomTypeHost, video: MediaSurface, url: string, art: CustomTypeHost) => unknown) | undefined>
+  layers?: ComponentInput<LayerHost>[]
+  controls?: ControlInput<ControlHost>[]
+  contextmenu?: ComponentInput<ContextmenuHost>[]
+}
+export interface Option extends OptionView<Artplayer> {}
+export interface Component extends ComponentView<Artplayer> {}
+export interface Controls extends ControlsView<Artplayer> {}
+export interface Setting extends SettingView<Artplayer> {}
+export interface Subtitle extends SubtitleView, Omit<Component, keyof SubtitleView> {}
+export interface Notice extends NoticeView { art: Artplayer }
+
+/** Augment with installed results. Factories are not wrapped or converted. */
+export interface PluginAdd<Registry> {
+  <Result>(plugin: FactoryView<Artplayer, Result>): PluginRegistration<Result, Registry>
+  <Result>(plugin: LegacyPluginFactory<LegacyArtplayer, Result>): PluginRegistration<Result, Registry>
+}
+
+type LegacyPluginResults = {
+  [Name in keyof LegacyPlugins as string extends Name ? never : number extends Name ? never : Name extends keyof PluginsView<Artplayer> ? never : Name]: LegacyPlugins[Name]
+}
+
+export interface Plugins extends Omit<PluginsView<Artplayer>, 'add'>, LegacyPluginResults {
+  add: PluginAdd<this>
+  [name: string]: unknown
+}
+
+/** Public view of the existing constructor; this interface emits no runtime fields. */
+interface Artplayer extends Player, Emitter<Events> {
+  constructor: ArtplayerConstructor
+  id: number
+  option: Option
+  isLock: boolean
+  isReady: boolean
+  isFocus: boolean
+  isInput: boolean
+  isRotate: boolean
+  isDestroy: boolean
+  flv?: unknown
+  m3u8?: unknown
+  hls?: unknown
+  ts?: unknown
+  mpd?: unknown
+  torrent?: unknown
+  template: Template<Artplayer>
+  events: EventRegistry
+  storage: Storage
+  icons: Icons
+  i18n: I18n<Artplayer>
+  notice: Notice
+  /** The descriptor installer has no public instance members. */
+  player: object
+  layers: Component
+  controls: Controls
+  contextmenu: Component & { init: () => void }
+  subtitle: Subtitle
+  info: Component & { init: () => void }
+  loading: Component
+  hotkey: Hotkey<Artplayer>
+  mask: Component
+  setting: Setting
+  plugins: Plugins
+  readonly query: Template<Artplayer>['query']
+  readonly proxy: EventRegistry['proxy']
+  readonly video: MediaSurface
+  reset: () => void
+  destroy: (removeHtml?: boolean) => void
+}
+
+type StaticOptions = Pick<typeof LegacyArtplayer, Extract<keyof typeof LegacyArtplayer, Uppercase<string>>>
+
+export interface ArtplayerConstructor extends StaticOptions {
+  new (option: OptionInput, readyCallback?: (this: Artplayer, art: Artplayer) => unknown): Artplayer
+  new (option: LegacyOptionInput, readyCallback?: (this: Artplayer, art: Artplayer) => unknown): Artplayer
+  readonly prototype: Artplayer
+  readonly instances: Artplayer[]
+  readonly version: string
+  readonly config: Config
+  readonly utils: Utils
+  readonly scheme: Record<keyof Option, Scheme>
+  readonly Emitter: new <Events extends { [Name in keyof Events]: readonly unknown[] } = Record<PropertyKey, unknown[]>>(...args: unknown[]) => Emitter<Events>
+  readonly validator: <T>(option: T, scheme: Scheme, paths?: ValidatorPath) => T
+  readonly kindOf: (value: unknown) => string
+  readonly html: string
+  readonly option: Option
+}
+
+// eslint-disable-next-line ts/no-redeclare -- One existing constructor value and its instance view.
+declare const Artplayer: ArtplayerConstructor
+
+export default Artplayer

packages/artplayer/public/runtime/component.ts

@@ -0,0 +1,65 @@
+export type EventCleanup = () => void
+
+export interface SelectorItem {
+  html: string | HTMLElement | number
+  value?: string | number
+  default?: boolean
+  readonly $control_option?: SelectorItem[]
+  readonly $control_item?: HTMLDivElement
+  readonly $control_value?: HTMLDivElement
+}
+
+export interface ComponentOption<Host> {
+  html?: string | HTMLElement | number
+  disable?: boolean
+  name?: string
+  index?: number
+  style?: Partial<CSSStyleDeclaration>
+  tooltip?: string | number
+  position?: string
+  selector?: SelectorItem[]
+  click?: (this: Host, component: Component<Host>, event: Event) => unknown
+  mounted?: (this: Host, element: HTMLDivElement) => unknown
+  beforeUnmount?: (this: Host, element: HTMLDivElement) => unknown
+  onSelect?: (this: Host, item: SelectorItem, element: HTMLDivElement, event: Event) => unknown
+}
+
+export type ComponentInput<Host> = ComponentOption<Host> | ((art: Host) => ComponentOption<Host>)
+
+export interface ControlOption<Host> extends Omit<ComponentOption<Host>, 'position'> {
+  position: 'top' | 'left' | 'right'
+}
+
+export type ControlInput<Host> = ControlOption<Host> | ((art: Host) => ControlOption<Host>)
+
+export interface ComponentEntry<Host> {
+  $ref: HTMLDivElement
+  events: EventCleanup[]
+  option: ComponentOption<Host>
+}
+
+export interface Component<Host> {
+  id: number
+  art: Host
+  name?: string
+  $parent?: HTMLElement
+  cache: Map<string, ComponentEntry<Host>>
+  show: boolean
+  toggle: () => void
+  add: (input: ComponentInput<Host>) => HTMLDivElement | undefined
+  remove: (name: string) => void
+  update: (option: ComponentOption<Host>) => ReturnType<this['add']>
+  selector?: (option: ComponentOption<Host>, element: HTMLDivElement, events: EventCleanup[]) => void
+}
+
+export interface Controls<Host> extends Omit<Component<Host>, 'add' | 'update' | 'selector'> {
+  isHover: boolean
+  timer: number
+  setting?: HTMLDivElement
+  thumbnails?: HTMLDivElement
+  init: () => void
+  add: (input: ControlInput<Host>) => undefined
+  update: (option: ComponentOption<Host>) => undefined
+  check: (target?: SelectorItem) => void
+  selector: (option: ComponentOption<Host>, element: HTMLDivElement, events: EventCleanup[]) => void
+}

packages/artplayer/public/runtime/construction.ts

@@ -0,0 +1,19 @@
+import type { Emitter } from '../emitter'
+import type Artplayer from '../runtime'
+import type { Events } from './events'
+import type { Player } from './player'
+
+/** Safe fields before Template returns; video/query/proxy getters are not usable yet. */
+export interface ProxyHost extends Emitter<Events>, Pick<Artplayer, 'constructor' | 'id' | 'option' | 'isLock' | 'isReady' | 'isFocus' | 'isInput' | 'isRotate' | 'isDestroy' | 'destroy'> {}
+
+// Mapped types collapse distinct getter/setter types; preserve Player directly.
+type Pending<Names extends keyof Artplayer> = Player & Omit<Artplayer, Names | keyof Player> & Partial<Pick<Artplayer, Names>>
+type AfterPlayer = 'layers' | 'controls' | 'contextmenu' | 'subtitle' | 'info' | 'loading' | 'hotkey' | 'mask' | 'setting' | 'plugins'
+
+/** URL assignment awaits its owned delay before invoking customType. */
+export type CustomTypeHost = Artplayer
+export type LayerHost = Pending<AfterPlayer>
+export type ControlHost = Pending<Exclude<AfterPlayer, 'layers'>>
+export type ContextmenuHost = Pending<Exclude<AfterPlayer, 'layers' | 'controls'>>
+/** Constructor factories run before the Plugins registry is assigned to the player. */
+export type PluginHost = Pending<'plugins'>

packages/artplayer/public/runtime/events.ts

@@ -0,0 +1,26 @@
+import type { Events as LegacyEvents } from '../events'
+import type { SubtitleCue, SubtitleOption } from './subtitle'
+
+type NativeEvents = { [Name in Extract<keyof LegacyEvents, `video:${string}`>]: [event: Event] }
+
+interface BuiltinEvents {
+  [name: `video:${string}`]: [event: Event]
+  'document:keydown': [KeyboardEvent]
+  'document:mousemove': [MouseEvent]
+  'document:mouseup': [MouseEvent]
+  'mousemove': [MouseEvent]
+  'click': [MouseEvent]
+  'blur': [Event]
+  'error': [error: unknown, attempt: number]
+  'fullscreenError': [error: unknown]
+  'aspectRatio': [string]
+  'flip': [string]
+  'seek': [time: number, requestedTime: number | string]
+  'setBar': [type: string, percentage: number, event?: MouseEvent | TouchEvent]
+  'subtitleBeforeUpdate': [cues: SubtitleCue[]]
+  'subtitleAfterUpdate': [cues: SubtitleCue[]]
+  'subtitleLoad': [cues: SubtitleCue[], option: SubtitleOption | null]
+}
+
+/** Legacy custom event augmentation is retained; builtin payload corrections take precedence. */
+export interface Events extends Omit<LegacyEvents, keyof BuiltinEvents>, NativeEvents, BuiltinEvents, Record<PropertyKey, unknown[]> {}

packages/artplayer/public/runtime/media.ts

@@ -0,0 +1,41 @@
+export type MediaState = Pick<HTMLMediaElement, 'currentTime' | 'duration' | 'paused' | 'ended' | 'readyState'> & {
+  readonly playing?: boolean
+}
+
+export interface PlaybackMethods<PlayResult = unknown, PauseResult = unknown> {
+  play: () => PlayResult
+  pause: () => PauseResult
+}
+
+export interface OptionalMediaCapabilities {
+  readonly textTracks?: ArrayLike<TextTrack>
+  readonly error?: unknown
+  requestPictureInPicture?: () => Promise<PictureInPictureWindow>
+  requestVideoFrameCallback?: (callback: VideoFrameRequestCallback) => number
+  cancelVideoFrameCallback?: (handle: number) => void
+  webkitEnterFullscreen?: () => void
+  webkitExitFullscreen?: () => void
+  readonly webkitSupportsFullscreen?: boolean
+  webkitShowPlaybackTargetPicker?: () => void
+  webkitSupportsPresentationMode?: (mode: string) => boolean
+  webkitSetPresentationMode?: (mode: string) => void
+  readonly webkitPresentationMode?: string
+  readonly webkitDisplayingFullscreen?: boolean
+}
+
+export type NativeMedia = Omit<HTMLVideoElement, keyof OptionalMediaCapabilities> & OptionalMediaCapabilities
+
+export type CanvasMedia = HTMLCanvasElement & MediaState & PlaybackMethods & OptionalMediaCapabilities & {
+  src: string | null
+  readonly currentSrc: string | null
+  readonly videoWidth: number
+  readonly videoHeight: number
+  readonly buffered: TimeRanges
+  volume: number
+  muted: boolean
+  playbackRate: number
+  load: () => unknown
+}
+
+/** Check optional capabilities before calling them on a native or proxy surface. */
+export type MediaSurface = NativeMedia | CanvasMedia

packages/artplayer/public/runtime/option.ts

@@ -0,0 +1,28 @@
+import type { OptionInput as LegacyOptionInput, Thumbnails } from '../option'
+import type { ComponentInput, ControlInput } from './component'
+import type { MediaSurface } from './media'
+import type { PluginFactory } from './plugin'
+import type { Languages } from './services'
+import type { SettingItem } from './setting'
+import type { SubtitleOption } from './subtitle'
+
+/** Callback receivers are the unchanged player instance selected by this view. */
+export interface OptionInput<Host> extends Omit<LegacyOptionInput, 'container' | 'proxy' | 'plugins' | 'layers' | 'controls' | 'contextmenu' | 'settings' | 'customType' | 'i18n' | 'icons'> {
+  container: string | HTMLDivElement
+  proxy?: (this: Host, art: Host) => MediaSurface | undefined
+  plugins?: PluginFactory<Host>[]
+  layers?: ComponentInput<Host>[]
+  controls?: ControlInput<Host>[]
+  contextmenu?: ComponentInput<Host>[]
+  settings?: SettingItem<Host>[]
+  customType?: Record<string, ((this: Host, video: MediaSurface, url: string, art: Host) => unknown) | undefined>
+  i18n?: Languages
+  icons?: Record<string, string | HTMLElement | undefined>
+}
+
+/** Defaults are merged once; later setters may replace thumbnails with a partial input. */
+export interface Option<Host> extends Omit<Required<OptionInput<Host>>, 'proxy' | 'subtitle' | 'thumbnails'> {
+  proxy: OptionInput<Host>['proxy']
+  subtitle: SubtitleOption
+  thumbnails: Thumbnails
+}

packages/artplayer/public/runtime/player.ts

@@ -0,0 +1,78 @@
+import type { Thumbnails } from '../option'
+import type { State } from '../player'
+import type { MediaSurface } from './media'
+
+export interface QualityItem {
+  html: string | HTMLElement
+  url: string
+  default?: boolean
+}
+
+/** Player-facing descriptors; native/proxy method results retain their identity. */
+export interface Player<Media extends MediaSurface = MediaSurface> {
+  get currentTime(): number
+  set currentTime(time: number | string)
+  readonly duration: number
+  get seek(): undefined
+  set seek(time: number | string)
+  get forward(): undefined
+  set forward(time: number)
+  get backward(): undefined
+  set backward(time: number)
+  get switch(): undefined
+  set switch(url: string)
+  get quality(): undefined
+  set quality(items: QualityItem[])
+  get url(): string | null
+  set url(value: string)
+  get state(): State
+  set state(value: string)
+  get pip(): Element | null | boolean
+  set pip(value: boolean)
+  /** The descriptor may be absent before metadata installs the available mode. */
+  fullscreen?: boolean
+  fullscreenWeb: boolean
+  mini: boolean
+  volume: number
+  muted: boolean
+  playbackRate: number
+  aspectRatio: string
+  flip: string
+  poster: string
+  theme: string
+  type: string
+  subtitleOffset: number
+  thumbnails: Thumbnails
+  readonly loaded: number
+  readonly loadedTime: number
+  readonly played: number
+  readonly playing: boolean
+  readonly rect: DOMRect
+  readonly bottom: number
+  readonly height: number
+  readonly left: number
+  readonly right: number
+  readonly top: number
+  readonly width: number
+  readonly x: number
+  readonly y: number
+  play: () => Promise<Awaited<ReturnType<Media['play']>>>
+  pause: () => ReturnType<Media['pause']>
+  toggle: () => Promise<Awaited<ReturnType<Media['play']>>> | ReturnType<Media['pause']>
+  switchUrl: (url: string) => Promise<void>
+  switchQuality: (url: string) => Promise<void>
+  autoSize: () => void
+  autoHeight: () => void
+  airplay: () => void
+  getDataURL: () => Promise<string>
+  getBlobUrl: () => Promise<string>
+  screenshot: (name?: string) => Promise<string>
+  attr: {
+    (key: PropertyKey): unknown
+    (key: PropertyKey, value: unknown): unknown
+  }
+  cssVar: {
+    (key: string): string
+    (key: string, value: unknown): string | void
+  }
+}

packages/artplayer/public/runtime/plugin.ts

@@ -0,0 +1,13 @@
+export type PluginFactory<Host, Result = unknown> = (this: Host, art: Host) => Result
+
+export type PluginRegistration<Result, Registry>
+  = unknown extends Result ? Registry | Promise<Registry>
+    : Result extends Promise<unknown> ? Promise<Registry> : Registry
+
+/** The same registry is returned immediately or after its Promise factory settles. */
+export interface Plugins<Host> {
+  art: Host
+  id: number
+  add: <Result>(plugin: PluginFactory<Host, Result>) => PluginRegistration<Result, this>
+  next: (plugin: PluginFactory<Host>, result: unknown) => this
+}

packages/artplayer/public/runtime/services.ts

@@ -0,0 +1,57 @@
+export interface Config {
+  properties: string[]
+  methods: string[]
+  events: string[]
+  prototypes: string[]
+}
+
+export type Disposer = () => void
+export type Listener = EventListenerOrEventListenerObject | null
+
+export interface EventRegistry {
+  destroyEvents: Set<Disposer>
+  proxy: {
+    (target: EventTarget, name: string, callback: Listener, option?: boolean | AddEventListenerOptions | null): Disposer
+    (target: EventTarget, name: string[], callback: Listener, option?: boolean | AddEventListenerOptions | null): Disposer[]
+    (target: EventTarget, name: string | string[], callback: Listener, option?: boolean | AddEventListenerOptions | null): Disposer | Disposer[]
+  }
+  hover: (target: EventTarget, mouseenter?: (event: Event) => unknown, mouseleave?: (event: Event) => unknown) => void
+  remove: (dispose: Disposer) => void
+  destroy: () => void
+  bindGlobalEvents: (source?: { window?: Window, document?: Document }) => void
+}
+
+export interface Storage {
+  name: string
+  settings: Record<PropertyKey, unknown>
+  get: (key?: PropertyKey) => unknown
+  set: (key: PropertyKey, value: unknown) => void
+  del: (key: PropertyKey) => void
+  clear: () => void
+}
+
+export type Dictionary = Record<string, string | undefined>
+export type Languages = Record<string, Dictionary | undefined>
+
+export interface I18n<Host> {
+  art: Host
+  languages: Languages
+  language: Dictionary
+  init: () => void
+  get: (key: string) => string
+  update: (value: Languages) => void
+}
+
+export type HotkeyCallback<Host> = (this: Host, event: KeyboardEvent) => unknown
+
+export interface Hotkey<Host> {
+  art: Host
+  keys: Record<string, HotkeyCallback<Host>[]>
+  init: () => void
+  add: (key: string, callback: HotkeyCallback<Host>) => this
+  remove: (key: string, callback: HotkeyCallback<Host>) => this
+}
+
+export type ValidatorPath = (string | number)[]
+export type Validator = (value: unknown, type: string, paths: ValidatorPath) => unknown
+export type Scheme = string | Validator | Scheme[] | { [key: string]: Scheme }

packages/artplayer/public/runtime/setting.ts

@@ -0,0 +1,58 @@
+export type SettingContent = string | HTMLElement | number
+export type SettingRange = [value?: number, min?: number, max?: number, step?: number]
+export type SettingCallback<Host> = (this: Host, item: SettingItem<Host>, element: HTMLDivElement, event: Event) => unknown
+
+export interface SettingItem<Host> {
+  name?: string
+  html?: SettingContent
+  icon?: SettingContent
+  tooltip?: SettingContent
+  width?: number
+  value?: string | number
+  default?: boolean
+  switch?: boolean
+  range?: SettingRange
+  selector?: SettingItem<Host>[]
+  mounted?: (this: Host, element: HTMLDivElement, item: SettingItem<Host>) => unknown
+  onClick?: SettingCallback<Host>
+  onSwitch?: SettingCallback<Host>
+  onRange?: SettingCallback<Host>
+  onChange?: SettingCallback<Host>
+  onSelect?: SettingCallback<Host>
+  readonly $parent?: SettingItem<Host>
+  readonly $parents?: SettingItem<Host>[]
+  readonly $option?: SettingItem<Host>[]
+  readonly $events?: (() => void)[]
+  readonly $formatted?: boolean
+  readonly $item?: HTMLDivElement
+  readonly $icon?: HTMLDivElement
+  readonly $html?: HTMLDivElement
+  readonly $tooltip?: HTMLDivElement
+  readonly $switch?: HTMLDivElement
+  readonly $range?: HTMLInputElement
+}
+
+export interface Setting<Host> {
+  id: number
+  art: Host
+  name: string
+  $parent: HTMLElement
+  cache: Map<SettingItem<Host>[], HTMLDivElement>
+  active: SettingItem<Host>[] | null
+  option: SettingItem<Host>[]
+  readonly builtin: SettingItem<Host>[]
+  show: boolean
+  toggle: () => void
+  traverse: (callback: (item: SettingItem<Host>) => void, option?: SettingItem<Host>[]) => void
+  check: (target?: SettingItem<Host> | null) => void
+  format: (option?: SettingItem<Host>[], parent?: SettingItem<Host>, parents?: SettingItem<Host>[], names?: string[]) => void
+  find: (name?: string) => SettingItem<Host> | null
+  resize: () => void
+  inactivate: (item: SettingItem<Host>) => void
+  remove: (name: string) => void
+  update: (item: SettingItem<Host>) => SettingItem<Host>
+  add: <Item extends SettingItem<Host>>(item: Item, option?: SettingItem<Host>[]) => Item
+  createHeader: (item: SettingItem<Host>) => void
+  createItem: (item: SettingItem<Host>, isUpdate?: boolean) => void
+  render: (option?: SettingItem<Host>[]) => void
+}

packages/artplayer/public/runtime/subtitle.ts

@@ -0,0 +1,38 @@
+import type { Subtitle as SubtitleInput } from '../subtitle'
+
+export type SubtitleOption = Required<SubtitleInput>
+
+export interface SubtitleCue extends TextTrackCue {
+  text: string
+  originalStartTime?: number
+  originalEndTime?: number
+}
+
+export interface SubtitleTrack extends HTMLTrackElement { offset?: number }
+
+export interface Subtitle {
+  name: string
+  option: SubtitleOption | null
+  destroyEvent: () => unknown
+  url: string
+  readonly textTrack: TextTrack | undefined
+  readonly activeCues: SubtitleCue[]
+  readonly cues: SubtitleCue[]
+  show: boolean
+  toggle: () => void
+  style: {
+    (styles: Partial<CSSStyleDeclaration>): HTMLDivElement
+    (key: string, value: string | number): HTMLDivElement
+  }
+  update: () => void
+  switch: (url: string, option?: SubtitleInput) => Promise<string | null | undefined>
+  init: (option: SubtitleOption) => Promise<string | null | undefined>
+  createTrack: (kind: string, url: string) => void
+}
+
+export interface Notice {
+  timer: number | null
+  get show(): boolean
+  set show(value: string | Error | false)
+  destroy: () => void
+}

packages/artplayer/public/runtime/template.ts

@@ -0,0 +1,42 @@
+import type { MediaSurface } from './media'
+
+/** Query results remain nullable for caller-supplied SSR templates. */
+export interface Template<Host, Media extends MediaSurface = MediaSurface> {
+  art: Host
+  $container: HTMLDivElement
+  $player: HTMLDivElement | null
+  $video: Media
+  $track: HTMLTrackElement | null
+  $poster: HTMLDivElement | null
+  $subtitle: HTMLDivElement | null
+  $danmuku: HTMLDivElement | null
+  $bottom: HTMLDivElement | null
+  $progress: HTMLDivElement | null
+  $controls: HTMLDivElement | null
+  $controlsLeft: HTMLDivElement | null
+  $controlsCenter: HTMLDivElement | null
+  $controlsRight: HTMLDivElement | null
+  $layer: HTMLDivElement | null
+  $loading: HTMLDivElement | null
+  $notice: HTMLDivElement | null
+  $noticeInner: HTMLDivElement | null
+  $mask: HTMLDivElement | null
+  $state: HTMLDivElement | null
+  $setting: HTMLDivElement | null
+  $info: HTMLDivElement | null
+  $infoPanel: HTMLDivElement | null
+  $infoClose: HTMLDivElement | null
+  $contextmenu: HTMLDivElement | null
+  $mini?: HTMLElement
+  query: <ElementType extends Element = Element>(selector: string) => ElementType | null
+  init: () => void
+  destroy: (removeHtml: boolean) => void
+}
+
+export type IconName = 'loading' | 'state' | 'play' | 'pause' | 'check' | 'volume' | 'volumeClose'
+  | 'screenshot' | 'setting' | 'pip' | 'arrowLeft' | 'arrowRight' | 'playbackRate' | 'aspectRatio'
+  | 'config' | 'lock' | 'flip' | 'unlock' | 'fullscreenOff' | 'fullscreenOn' | 'fullscreenWebOff'
+  | 'fullscreenWebOn' | 'switchOn' | 'switchOff' | 'error' | 'close' | 'airplay'
+
+/** Default getters create fresh icon wrappers; unknown custom keys may be absent. */
+export type Icons = Readonly<Record<IconName, HTMLElement>> & { readonly [name: string]: HTMLElement | undefined }

packages/artplayer/public/runtime/utils.ts

@@ -0,0 +1,67 @@
+interface StyledElement { style: CSSStyleDeclaration }
+interface EventPathSource {
+  target: EventTarget | null
+  composedPath?: () => EventTarget[]
+}
+type StackFrame = ((...args: never[]) => unknown) | (abstract new (...args: never[]) => object)
+
+export interface Utils {
+  isBrowser: boolean
+  userAgent: string
+  isMobile: boolean
+  isSafari: boolean
+  isIOS: boolean
+  isIOS13: boolean
+  query: <T extends Element = Element>(selector: string, parent?: ParentNode) => T | null
+  queryAll: <T extends Element = Element>(selector: string, parent?: ParentNode) => T[]
+  addClass: (target: Pick<Element, 'classList'>, className: string) => void
+  removeClass: (target: Pick<Element, 'classList'>, className: string) => void
+  hasClass: (target: Pick<Element, 'classList'>, className: string) => boolean
+  append: (parent: Element, child: unknown) => Element | ChildNode | null
+  remove: <T extends Node>(child: T) => T
+  replaceElement: <T extends Node>(newChild: T, oldChild: Node) => T
+  siblings: (target: Element) => Element[]
+  inverseClass: (target: Element, className: string) => void
+  createElement: {
+    <K extends keyof HTMLElementTagNameMap>(tag: K): HTMLElementTagNameMap[K]
+    (tag: string): HTMLElement
+  }
+  setStyle: <T extends StyledElement>(element: T, key: PropertyKey, value: unknown) => T
+  setStyles: <T extends StyledElement>(element: T, styles: object) => T
+  getStyle: {
+    (element: Element, key: string, numberType?: true): number
+    (element: Element, key: string, numberType: false): string
+    (element: Element, key: string, numberType: boolean): number | string
+  }
+  setStyleText: (id: string, cssText: string) => void
+  getRect: (element: Pick<Element, 'getBoundingClientRect'>) => DOMRect
+  tooltip: (target: Element, message: string | number, position?: string) => void
+  isInViewport: (target: Pick<Element, 'getBoundingClientRect'>, offset?: number) => boolean
+  includeFromEvent: (event: EventPathSource, target: EventTarget | null | undefined) => boolean
+  getSafeAreaInsets: () => { top: number, right: number, bottom: number, left: number }
+  srtToVtt: (text: string) => string
+  vttToBlob: (text: string) => string
+  assToVtt: (text: string) => string
+  getExt: (url: string) => string
+  download: (url: string, name: string) => void
+  loadImg: (url: string, scale?: number) => Promise<HTMLImageElement>
+  errorHandle: <T>(condition: T, message?: string) => T
+  silencePromise: <T>(value: T) => T extends Promise<infer Result> ? Promise<Result | undefined> : T
+  def: <T extends object>(object: T, name: PropertyKey, descriptor: PropertyDescriptor & object & ThisType<T>) => T
+  has: (object: object, name: PropertyKey) => boolean
+  get: (object: object, name: PropertyKey) => PropertyDescriptor | undefined
+  mergeDeep: <T extends object[]>(...objects: T) => T[number]
+  sleep: (milliseconds?: number) => Promise<void>
+  /** The wrapper preserves its call receiver; the old context argument is ignored. */
+  debounce: <Receiver, Args extends unknown[]>(callback: (this: Receiver, ...args: Args) => unknown, duration: number, context?: object) => (this: Receiver, ...args: Args) => void
+  throttle: <Receiver, Args extends unknown[]>(callback: (this: Receiver, ...args: Args) => unknown, duration: number) => (this: Receiver, ...args: Args) => void
+  clamp: (number: number, a: number, b: number) => number
+  secondToTime: (second: number) => string
+  escape: (text: string) => string
+  unescape: (text: string) => string
+  capitalize: (text: string) => string
+  ArtPlayerError: new (message?: string, context?: StackFrame) => Error
+  getIcon: (key?: string, html?: string | HTMLElement) => HTMLElement
+  getComposedPath: (event: EventPathSource) => EventTarget[]
+  supportsFlex: () => boolean
+}

packages/artplayer/public/setting.ts

@@ -0,0 +1,95 @@
+import type Artplayer from './artplayer'
+
+export interface SettingOption extends Omit<Setting, 'html' | 'icon' | 'tooltip'> {
+  html: string
+  icon: string | undefined
+  tooltip: string | undefined
+  $item: HTMLDivElement
+  $icon: HTMLDivElement | undefined
+  $html: HTMLDivElement
+  $tooltip: HTMLDivElement | undefined
+  $switch: HTMLDivElement | undefined
+  $range: HTMLInputElement | undefined
+  $parent: SettingOption | undefined
+  $parents: SettingOption[]
+  $option: SettingOption[]
+  $events: Array<() => void>
+  $formatted: boolean
+}
+
+export interface Setting {
+  /**
+   * Html string or html element of setting name
+   */
+  html: string | HTMLElement
+
+  /**
+   * Html string or html element of setting icon
+   */
+  icon?: string | HTMLElement
+
+  /**
+   * The width of setting
+   */
+  width?: number
+
+  /**
+   * The tooltip of setting
+   */
+  tooltip?: string | HTMLElement
+
+  /**
+   * Whether the default is selected
+   */
+  default?: boolean
+
+  /**
+   * Custom selector list
+   */
+  selector?: Setting[]
+
+  /**
+   * When the setting was mounted
+   */
+  mounted?: (this: Artplayer, panel: HTMLDivElement, item: Setting) => void
+
+  /**
+   * When selector item click
+   */
+  onSelect?: (this: Artplayer, item: SettingOption, element: HTMLDivElement, event: Event) => void
+
+  /**
+   * Custom switch item
+   */
+  switch?: boolean
+
+  /**
+   * When switch item click
+   */
+  onSwitch?: (this: Artplayer, item: SettingOption, element: HTMLDivElement, event: Event) => void
+
+  /**
+   * Custom range item
+   */
+  range?: [value?: number, min?: number, max?: number, step?: number]
+
+  /**
+   * When range item change
+   */
+  onRange?: (this: Artplayer, item: SettingOption, element: HTMLDivElement, event: Event) => void
+
+  /**
+   * When range item change in real time
+   */
+  onChange?: (this: Artplayer, item: SettingOption, element: HTMLDivElement, event: Event) => void
+
+  /**
+   * When range item change in real time
+   */
+  onClick?: (this: Artplayer, item: SettingOption, element: HTMLDivElement, event: Event) => void
+
+  /**
+   * Allow custom properties
+   */
+  [key: string]: any
+}

packages/artplayer/public/subtitle.ts

@@ -0,0 +1,36 @@
+export interface Subtitle {
+  /**
+   * The subtitle url
+   */
+  url?: string
+
+  /**
+   * The subtitle name
+   */
+  name?: string
+
+  /**
+   * The subtitle type
+   */
+  type?: 'vtt' | 'srt' | 'ass' | (string & Record<never, never>)
+
+  /**
+   * The subtitle style object
+   */
+  style?: Partial<CSSStyleDeclaration>
+
+  /**
+   * The subtitle encoding, default utf-8
+   */
+  encoding?: string
+
+  /**
+   * Whether use escape, default true
+   */
+  escape?: boolean
+
+  /**
+   * Change the vtt text
+   */
+  onVttLoad?: (vtt: string) => string
+}

packages/artplayer/public/template.ts

@@ -0,0 +1,27 @@
+export interface Template {
+  readonly html: string
+  readonly $container: HTMLDivElement
+  readonly $player: HTMLDivElement
+  readonly $video: HTMLVideoElement
+  readonly $track: HTMLTrackElement
+  readonly $poster: HTMLDivElement
+  readonly $subtitle: HTMLDivElement
+  readonly $danmuku: HTMLDivElement
+  readonly $bottom: HTMLDivElement
+  readonly $progress: HTMLDivElement
+  readonly $controls: HTMLDivElement
+  readonly $controlsLeft: HTMLDivElement
+  readonly $controlsCenter: HTMLDivElement
+  readonly $controlsRight: HTMLDivElement
+  readonly $layer: HTMLDivElement
+  readonly $loading: HTMLDivElement
+  readonly $notice: HTMLDivElement
+  readonly $noticeInner: HTMLDivElement
+  readonly $mask: HTMLDivElement
+  readonly $state: HTMLDivElement
+  readonly $setting: HTMLDivElement
+  readonly $info: HTMLDivElement
+  readonly $infoPanel: HTMLDivElement
+  readonly $infoClose: HTMLDivElement
+  readonly $contextmenu: HTMLDivElement
+}

packages/artplayer/public/utils.ts

@@ -0,0 +1,73 @@
+export interface Utils {
+  isBrowser: boolean
+  userAgent: string
+  isMobile: boolean
+  isSafari: boolean
+  isIOS: boolean
+  isIOS13: boolean
+
+  query: <T extends Element = Element>(selector: string, parent?: Document | HTMLElement) => T | null
+  queryAll: <T extends Element = Element>(selector: string, parent?: Document | HTMLElement) => T[]
+  addClass: (target: HTMLElement, className: string) => void
+  removeClass: (target: HTMLElement, className: string) => void
+  hasClass: (target: HTMLElement, className: string) => boolean
+  append: (target: HTMLElement, child: HTMLElement | string) => Element | ChildNode
+  remove: (target: HTMLElement) => HTMLElement
+  replaceElement: (newChild: HTMLElement, oldChild: HTMLElement) => HTMLElement
+  siblings: (target: HTMLElement) => HTMLElement[]
+  inverseClass: (target: HTMLElement, className: string) => void
+  createElement: <K extends keyof HTMLElementTagNameMap>(tag: K) => HTMLElementTagNameMap[K]
+  setStyle: <T extends keyof CSSStyleDeclaration>(
+    element: HTMLElement,
+    key: T,
+    value: string | CSSStyleDeclaration[T],
+  ) => HTMLElement
+  setStyles: (element: HTMLElement, styles: Partial<CSSStyleDeclaration>) => HTMLElement
+  getStyle: {
+    (element: HTMLElement, key: keyof CSSStyleDeclaration, numberType?: true): number
+    (element: HTMLElement, key: keyof CSSStyleDeclaration, numberType: false): string
+  }
+  setStyleText: (id: string, cssText: string) => void
+  getRect: (el: HTMLElement) => { top: number, left: number, width: number, height: number }
+  tooltip: (target: HTMLElement, msg: string, pos?: string) => void
+  isInViewport: (target: HTMLElement, offset?: number) => boolean
+  includeFromEvent: (event: Event, target: HTMLElement) => boolean
+  getSafeAreaInsets: () => { top: number, right: number, bottom: number, left: number }
+
+  srtToVtt: (srtText: string) => string
+  vttToBlob: (vttText: string) => string
+  assToVtt: (assText: string) => string
+
+  getExt: (url: string) => string
+  download: (url: string, name: string) => void
+  loadImg: (url: string, scale?: number) => Promise<HTMLImageElement>
+
+  errorHandle: <T extends boolean>(condition: T, msg: string) => T extends true ? T : never
+  silencePromise: <T>(value: T) => T extends Promise<infer R> ? Promise<R | undefined> : T
+  def: {
+    /** Historical string-key signature; runtime returns obj. */
+    (obj: object, name: string, value: unknown): void
+    <T>(obj: T, name: PropertyKey, value: PropertyDescriptor & ThisType<T>): T
+  }
+  has: (obj: object, name: PropertyKey) => boolean
+  get: (obj: object, name: PropertyKey) => PropertyDescriptor | undefined
+  mergeDeep: <T extends object[]>(...args: T) => T[number]
+
+  sleep: (ms?: number) => Promise<void>
+  /** Historical return type; runtime discards the callback result and ignores context. */
+  debounce: <F extends (...args: any[]) => any>(func: F, wait: number, context?: object) => (...args: Parameters<F>) => ReturnType<F>
+  /** Historical return type; runtime discards the callback result. */
+  throttle: <F extends (...args: any[]) => any>(func: F, wait: number) => (...args: Parameters<F>) => ReturnType<F>
+
+  clamp: (num: number, a: number, b: number) => number
+  secondToTime: (second: number) => string
+  escape: (str: string) => string
+  unescape: (str: string) => string
+  capitalize: (str: string) => string
+
+  ArtPlayerError: new (message?: string, context?: ((...args: never[]) => unknown) | (abstract new (...args: never[]) => object)) => Error
+
+  getIcon: (key?: string, html?: string | HTMLElement) => HTMLElement
+  getComposedPath: (event: Event) => EventTarget[]
+  supportsFlex: () => boolean
+}

packages/artplayer/src/control/types.ts

@@ -24,7 +24,7 @@ export interface UIEvents {
   'setting': [boolean]
   'aspectRatio': [string]
   'flip': [string]
-  'blur': []
+  'blur': [Event]
   'resize': []
 }
 

packages/artplayer/src/events/core-types.ts

@@ -1,29 +1,8 @@
-import type { UIEvents } from '../control/types'
+import type { Events } from '../../types/runtime/events'
 
 // The emitter stays open to extension names. Known native events retain their
 // payloads so subsystem subscriptions are checked against the assembled player.
-export interface CoreEvents extends UIEvents, Record<PropertyKey, unknown[]> {
-  [name: `video:${string}`]: [event: Event]
-  'ready': []
-  'error': [error: unknown, attempt: number]
-  'fullscreenError': [error: unknown]
-  'destroy': []
-  'restart': [string]
-  'focus': [Event]
-  'lock': [boolean]
-  'view': [boolean]
-  'subtitleOffset': [number]
-  'seek': [time: number, requestedTime: number | string]
-  'document:click': [Event]
-  'document:contextmenu': [Event]
-  'document:keydown': [KeyboardEvent]
-  'document:touchmove': [Event]
-  'document:touchend': [Event]
-  'document:touchcancel': [Event]
-  'window:resize': [Event]
-  'window:orientationchange': [Event]
-  'window:scroll': [Event]
-}
+export interface CoreEvents extends Events {}
 
 export interface CoreEmission<Names extends keyof CoreEvents = keyof CoreEvents> {
   emit: <Name extends Names>(name: Name, ...args: [...CoreEvents[Name]]) => unknown

packages/artplayer/src/setting/types.ts

@@ -34,7 +34,7 @@ export interface SettingItem extends TreeItem {
 }
 
 export interface SettingEvents {
-  'blur': []
+  'blur': [Event]
   'focus': [event: Event]
   'resize': []
   'video:ratechange': [Event]

packages/artplayer/tsconfig.json

@@ -9,6 +9,9 @@
     "types/**/*.d.mts",
     "types/**/*.d.cts",
     "../../types/assets.d.ts",
-    "../../types/option-validator.d.ts"
+    "../../types/option-validator.d.ts",
+    "public/**/*.ts",
+    "public/**/*.mts",
+    "public/**/*.cts"
   ]
 }

packages/artplayer/types/COMPATIBILITY.md

@@ -46,10 +46,10 @@ if (pending)
 
 The original `art.toggle(): void` declaration remains accepted by historical
 consumers. The optional view exposes `Promise<void> | void`; play rejection and
-the original object identity remain unchanged. BASE-TYPE-04 stays open for the
-remaining plugins.add conflict and CORE-21's full facade review.
+the original object identity remain unchanged. CORE-21 also provides a complete
+optional precise entry for these differences, described below.
 
-| Surface                                    | Actual runtime                                                                | Retained historical declaration                         | Follow-up                |
+| Surface                                    | Actual runtime                                                                | Retained historical declaration                         | Owning task / finding    |
 | ------------------------------------------ | ----------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------ |
 | plugins.add                                | Registry for a synchronous factory; Promise of registry for a Promise factory | Always Promise                                          | CORE-08/21, BASE-TYPE-04 |
 | toggle                                     | Pause result or original play Promise, including rejection                    | void                                                    | CORE-10/21, BASE-TYPE-04 |
@@ -61,9 +61,9 @@ remaining plugins.add conflict and CORE-21's full facade review.
 | notice.show getter                         | Boolean visibility                                                            | Historical message/false union                          | CORE-18/21, BASE-TYPE-07 |
 | seek/forward/backward/switch/quality reads | Undefined: these descriptors only have setters                                | Numeric/string/quality-array getters                    | CORE-21, BASE-TYPE-08    |
 
-These remain open declaration work, not release waivers. CORE-21 must resolve the
-public/generated facade strategy against both actual returns and historical source
-consumers. Migrated implementation modules must use their accurate internal types.
+These historical declarations remain intentionally compatible. The runtime entry
+below provides their accurate counterparts; it does not change the implementation
+to make historical inaccuracies true. Migrated modules use accurate internal types.
 For existing application code, awaiting plugins.add or toggle works for synchronous
 and Promise results; ignore timer results, guard setting.find with a truthiness
 check, and explicitly annotate cue-array listeners. Do not rely on the inaccurate
@@ -74,6 +74,49 @@ these command properties returns undefined; use currentTime, option and media
 state for observations. Source interfaces model undefined reads independently
 of setter inputs. Historical public getter declarations are not removed here.
 
+## Precise entry and compiler boundary
+
+Use `artplayer/runtime` for precise types on the existing modern JS constructor,
+or `artplayer/runtime/legacy` for the existing legacy JS constructor. Both share
+the `artplayer/runtime/types` augmentation entry and the same public TypeScript
+source graph. Existing root/legacy/types/i18n imports retain their old acceptance
+and TypeScript 4.3.5 support. The precise entry is tested with 5.1.6 and 5.9.3;
+unrelated getter/setter types require the TypeScript 5.1 language feature.
+
+```ts
+import Artplayer from 'artplayer/runtime'
+
+const art = new Artplayer({ container: '#player' })
+const registered = art.plugins.add(() => ({ name: 'example' })) // same registry
+art.seek = 12
+const seekRead: undefined = art.seek
+const visible: boolean = art.notice.show
+const item = art.setting.find('quality') // item or null
+```
+
+Precise timer wrappers return void, def requires object target/descriptor and
+returns the target, settings return their actual item/null/void values, and
+subtitle update callbacks infer cue arrays. Media/proxy method return types are
+kept distinct. Command reads are undefined; native PiP reads Element|null while
+fallbacks read boolean. Template nodes may be null, icons are HTMLElement wrappers,
+template.html is absent, and only the constructor exposes html. env/build are
+not fabricated. Containers must be div elements and new controls need a supported
+position. The old fields and wrong signatures remain available only in the legacy
+type view; precise instances are not asserted assignable to that inaccurate view.
+
+Constructor input overloads accept old typed plugins without wrapping factories.
+Named plugin result/custom event augmentation flows from the old shared types to
+the new view; new augmentation should target artplayer/runtime/types. Constructor
+plugin callbacks see plugins as optional until its registry is assigned. Other
+early construction hosts similarly expose only initialized components; customType,
+setting mounted and ready callbacks run after construction. The actual input
+factory, callback receiver and player identities are unchanged.
+
+The docs global keeps the legacy view for its bundled Monaco compiler. build:ts
+follows the public type graph and generates a standalone UMD declaration; modern
+runtime declarations are not merged into it. This is independent of the npm
+declaration generator and does not add runtime code.
+
 ## Evidence and maintenance
 
 declaration-legacy.ts is a compile-only regression fixture, not recommended runtime

packages/artplayer/types/README.md

@@ -1,8 +1,36 @@
 # 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.
+The TypeScript files in `../public/` are the source for these declarations.
+`yarn build:types` uses the pinned TypeScript compiler to emit the existing `.d.ts`,
+`.d.mts` and `.d.cts` paths; `yarn check:types` verifies them without writing.
+Do not hand-edit generated declarations. The generator rejects dependencies on
+implementation files and emits no JavaScript. Public source files are excluded
+from the npm package.
+
+`artplayer.d.ts` remains the shared API definition and old TypeScript entry.
+This facade preserves historical consumer acceptance; COMPATIBILITY.md explains
+the retained inaccuracies and the optional precise view.
+
+CORE-21 generates precise modules in `runtime/` and assembles them in runtime.d.ts.
+Choose `import Artplayer from 'artplayer/runtime'` for the precise view, or
+`artplayer/runtime/legacy` for the existing legacy JS build with the same precise
+types. These views require the modern accessor syntax tested with TypeScript
+5.1.6 and 5.9.3. Their JS targets are identical to the corresponding existing
+entrypoints; no constructor or instance wrapper is created.
+
+Use the type-only `artplayer/runtime/types` entry to augment precise Plugins and
+Events. Legacy custom event/plugin result augmentation is also retained. Existing
+root entrypoints do not import the modern views, preserving TypeScript 4.3.5.
+Old typed plugin factories remain accepted by explicit input overloads; precise
+instances do not pretend to satisfy inaccurate legacy return declarations.
+PluginFactory uses PluginHost: its plugins field is optional because constructor
+factories execute before that registry is assigned. Inline plugins.add callbacks
+receive the completed player. New controls require a top/left/right position;
+updates may retain the existing position. ProxyHost exposes safe initial fields
+before Template returns. Layer/control/contextmenu hosts mark later components
+optional; customType and setting mounted run after a delay and receive the full
+instance. These hosts retain distinct Player getter/setter types. Container inputs
+and template.$container remain HTMLDivElement because only div is supported.
 
 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
@@ -17,15 +45,18 @@ 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
+Top-level types and historical .d.ts filenames remain available; existing 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.
+TS 4.3.5 consumers. Run `yarn build:ts` to refresh editor declarations. The core
+editor bundle comes from the public dependency graph and is checked standalone
+with both compilers. editor-types.test.js rejects stale or invalid output, and
+editor-types.spec.js exercises the real Monaco worker and typed example playback.
+Plugin/editor UI modernization remains in SITE tasks.
 
 ## Configuration migration boundary
 
@@ -42,8 +73,8 @@ test/types/options-source.ts and declaration-inputs.ts cover those forms positiv
 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](./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.
+CORE-07 introduced compatible additions. CORE-21 supplies the generated precise
+runtime entry for remaining conflicts while preserving historical root signatures.
 
 ## Internal media migration
 
@@ -58,7 +89,7 @@ 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
+type integration was completed in 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.
 

packages/artplayer/types/artplayer.d.cts

@@ -1,13 +1,14 @@
+// Generated from public/artplayer.cts by yarn build:types. Do not edit.
+/* eslint-disable ts/no-redeclare -- Constructor, instance and named types share the export. */
 import type * as Definition from './artplayer.js'
 
 declare const Artplayer: typeof Definition.default
-// eslint-disable-next-line ts/no-redeclare -- CJS constructor value and instance type share the export.
 type Artplayer = Definition.default
-
-// eslint-disable-next-line ts/no-redeclare -- Namespace merging carries named types on export =.
 declare namespace Artplayer {
   type Config = Definition.Config
-  type Emitter<Events extends { [Name in keyof Events]: readonly unknown[] } = Record<PropertyKey, unknown[]>> = Definition.Emitter<Events>
+  type Emitter<Events extends {
+    [Name in keyof Events]: readonly unknown[];
+  } = Record<PropertyKey, unknown[]>> = Definition.Emitter<Events>
   type Events = Definition.Events
   type I18n = Definition.I18n
   type Icons = Definition.Icons
@@ -24,5 +25,4 @@ declare namespace Artplayer {
   type Template = Definition.Template
   type Utils = Definition.Utils
 }
-
 export = Artplayer

packages/artplayer/types/artplayer.d.mts

@@ -1,2 +1,3 @@
+// Generated from public/artplayer.mts by yarn build:types. Do not edit.
 export { default } from './artplayer.cjs'
 export type { Config, Emitter, Events, I18n, Icons, Option, OptionInput, PlaybackControls, Player, PluginFactory, Plugins, Setting, SettingOption, Subtitle, SubtitleUpdateEvents, Template, Utils } from './artplayer.js'

packages/artplayer/types/artplayer.d.ts

@@ -1,3 +1,4 @@
+// Generated from public/artplayer.ts by yarn build:types. Do not edit.
 import type { Component } from './component'
 import type { Config } from './config'
 import type { Emitter } from './emitter'
@@ -13,30 +14,10 @@ import type { Subtitle } from './subtitle'
 import type { Template } from './template'
 import type { Utils } from './utils'
 
-export type {
-  Config,
-  Emitter,
-  Events,
-  I18n,
-  Icons,
-  Option,
-  OptionInput,
-  PlaybackControls,
-  Player,
-  PluginFactory,
-  Plugins,
-  Setting,
-  SettingOption,
-  Subtitle,
-  SubtitleUpdateEvents,
-  Template,
-  Utils,
-}
-
-export default class Artplayer extends Player {
+export type { Config, Emitter, Events, I18n, Icons, Option, OptionInput, PlaybackControls, Player, PluginFactory, Plugins, Setting, SettingOption, Subtitle, SubtitleUpdateEvents, Template, Utils }
+declare class Artplayer extends Player {
   constructor(option: Option, readyCallback?: (this: Artplayer, art: Artplayer) => unknown)
   constructor(option: OptionInput, readyCallback?: (this: Artplayer, art: Artplayer) => unknown)
-
   static readonly instances: Artplayer[]
   static readonly version: string
   static readonly env: 'development' | 'production'
@@ -44,12 +25,14 @@ export default class Artplayer extends Player {
   static readonly config: Config
   static readonly utils: Utils
   static readonly scheme: Record<keyof Option, unknown>
-  static readonly Emitter: new <Events extends { [Name in keyof Events]: readonly unknown[] } = Record<PropertyKey, unknown[]>>(...args: unknown[]) => Emitter<Events>
+  static readonly Emitter: new <Events extends {
+    [Name in keyof Events]: readonly unknown[];
+  } = Record<PropertyKey, unknown[]>>(...args: unknown[]) => Emitter<Events>
+
   static readonly validator: <T extends object>(option: T, scheme: object) => T
   static readonly kindOf: (item: unknown) => string
   static readonly html: Artplayer['template']['html']
   static readonly option: Option
-
   static STYLE: string
   static DEBUG: boolean
   static CONTEXTMENU: boolean
@@ -84,7 +67,6 @@ export default class Artplayer extends Player {
   static LOG_VERSION: boolean
   static USE_RAF: boolean
   static REMOVE_SRC_WHEN_DESTROY: boolean
-
   readonly id: number
   readonly option: Option
   readonly isLock: boolean
@@ -93,39 +75,36 @@ export default class Artplayer extends Player {
   readonly isInput: boolean
   readonly isRotate: boolean
   readonly isDestroy: boolean
-
   flv?: unknown
   m3u8?: unknown
   hls?: unknown
   ts?: unknown
   mpd?: unknown
   torrent?: unknown
-
   on<T extends keyof Events>(name: T, fn: (...args: Events[T]) => unknown, ctx?: object): this
   on<T extends keyof SubtitleUpdateEvents>(name: T, fn: (...args: SubtitleUpdateEvents[T]) => unknown, ctx?: object): this
   on(name: string, fn: (...args: unknown[]) => unknown, ctx?: object): this
-
   once<T extends keyof Events>(name: T, fn: (...args: Events[T]) => unknown, ctx?: object): this
   once<T extends keyof SubtitleUpdateEvents>(name: T, fn: (...args: SubtitleUpdateEvents[T]) => unknown, ctx?: object): this
   once(name: string, fn: (...args: unknown[]) => unknown, ctx?: object): this
-
   emit<T extends keyof Events>(name: T, ...args: Events[T]): this
   emit<T extends keyof SubtitleUpdateEvents>(name: T, ...args: SubtitleUpdateEvents[T]): this
   emit(name: string, ...args: unknown[]): this
-
   off<T extends keyof Events>(name: T, callback?: (...args: Events[T]) => unknown): this
   off<T extends keyof SubtitleUpdateEvents>(name: T, callback?: (...args: SubtitleUpdateEvents[T]) => unknown): this
   off(name: string, callback?: (...args: unknown[]) => unknown): this
-
   query: Artplayer['template']['query']
   proxy: Artplayer['events']['proxy']
   video: Artplayer['template']['$video']
-
-  e: { [K in keyof Events]?: { fn: (...args: Events[K]) => unknown, ctx: unknown }[] }
+  e: {
+    [K in keyof Events]?: {
+      fn: (...args: Events[K]) => unknown
+      ctx: unknown
+    }[];
+  }
 
   destroy(removeHtml?: boolean): void
   reset(): void
-
   readonly template: {
     get html(): string
     query: <T extends Element = Element>(selector: string) => T | null
@@ -139,7 +118,10 @@ export default class Artplayer extends Player {
     hover: (element: HTMLElement, mouseenter?: (event: Event) => any, mouseleave?: (event: Event) => any) => void
     remove: (destroyEvent: () => void) => void
     destroy: () => void
-    bindGlobalEvents: (source?: { window?: Window, document?: Document }) => void
+    bindGlobalEvents: (source?: {
+      window?: Window
+      document?: Document
+    }) => void
   }
 
   readonly storage: {
@@ -155,7 +137,6 @@ export default class Artplayer extends Player {
   }
 
   readonly icons: Icons
-
   readonly i18n: {
     languages: I18n
     language: Partial<Record<string, string>>
@@ -174,7 +155,6 @@ export default class Artplayer extends Player {
   readonly layers: Record<string, HTMLElement | undefined> & Component
   readonly controls: Record<string, HTMLElement | undefined> & Component
   readonly contextmenu: Record<string, HTMLElement | undefined> & Component
-
   readonly subtitle: {
     get url(): string
     set url(url: string)
@@ -188,7 +168,6 @@ export default class Artplayer extends Player {
 
   readonly info: Component
   readonly loading: Component
-
   readonly hotkey: {
     keys: Record<string, ((event: KeyboardEvent) => any)[]>
     add: (key: string, callback: (this: Artplayer, event: KeyboardEvent) => any) => Artplayer['hotkey']
@@ -196,7 +175,6 @@ export default class Artplayer extends Player {
   }
 
   readonly mask: Component
-
   readonly setting: {
     option: SettingOption[]
     updateStyle: (width?: number) => void
@@ -212,3 +190,4 @@ export default class Artplayer extends Player {
 
   readonly plugins: Plugins
 }
+export default Artplayer

packages/artplayer/types/component.d.ts

@@ -1,63 +1,52 @@
+// Generated from public/component.ts by yarn build:types. Do not edit.
 import type Artplayer from './artplayer'
-
 /** Input accepted by the existing HTML renderer, including numeric content. */
 export interface ComponentInput extends Omit<ComponentOption, 'html'> {
   html?: string | HTMLElement | number
 }
-
 export interface Selector {
   /**
    * Whether the default is selected
    */
   default?: boolean
-
   /**
    * Html string of selector
    */
   html: string | HTMLElement
-
   /**
    * Value of selector item
    */
   value?: string | number
-
   /**
    * Allow custom properties
    */
   [key: string]: any
 }
-
 export interface Component {
   /**
    * Component self-increasing id
    */
   readonly id: number
-
   /**
    * Component parent name
    */
   readonly name: string | undefined
-
   /**
    * Component parent element
    */
   readonly $parent: HTMLElement | undefined
-
   /**
    * Whether to show component parent
    */
   get show(): boolean
-
   /**
    * Whether to show component parent
    */
   set show(state: boolean)
-
   /**
    * Toggle the component parent
    */
   toggle: () => void
-
   /**
    * Dynamic add a component
    */
@@ -65,12 +54,10 @@ export interface Component {
     (option: ComponentOption | ((art: Artplayer) => ComponentOption)): HTMLElement | undefined
     (option: ComponentInput | ((art: Artplayer) => ComponentInput)): HTMLElement | undefined
   }
-
   /**
    * Dynamic remove a component by name
    */
   remove: (name: string) => void
-
   /**
    * Dynamic update a component
    */
@@ -79,63 +66,51 @@ export interface Component {
     (option: ComponentInput): HTMLElement | undefined
   }
 }
-
 export interface ComponentOption {
   /**
    * Html string or html element of component
    */
   html?: string | HTMLElement
-
   /**
    * Whether to disable component
    */
   disable?: boolean
-
   /**
    * Unique name for component
    */
   name?: string
-
   /**
    * Component sort index
    */
   index?: number
-
   /**
    * Component style object
    */
   style?: Partial<CSSStyleDeclaration>
-
   /**
    * Component click event
    */
   click?: (this: Artplayer, component: Component, event: Event) => void
-
   /**
    * When the component was mounted
    */
   mounted?: (this: Artplayer, element: HTMLElement) => void
-
   /**
    * When the component was before unmount
    */
   beforeUnmount?: (this: Artplayer, element: HTMLElement) => void
-
   /**
    * Component tooltip, use in controls
    */
   tooltip?: string
-
   /**
    * Component position, use in controls
    */
   position?: 'top' | 'left' | 'right' | (string & Record<never, never>)
-
   /**
    * Custom selector list, use in controls
    */
   selector?: Selector[]
-
   /**
    * When selector item click, use in controls
    */

packages/artplayer/types/config.d.ts

@@ -1,3 +1,4 @@
+// Generated from public/config.ts by yarn build:types. Do not edit.
 export interface Config {
   readonly properties: readonly [
     'audioTracks',

packages/artplayer/types/cssVar.d.ts

@@ -1,3 +1,4 @@
+// Generated from public/cssVar.ts by yarn build:types. Do not edit.
 export interface CssVar {
   '--art-theme': string
   '--art-font-color': string

packages/artplayer/types/emitter.d.ts

@@ -1,6 +1,14 @@
+// Generated from public/emitter.ts by yarn build:types. Do not edit.
 /** The event bus exposed by Artplayer.Emitter; no new runtime export. */
-export interface Emitter<Events extends { [Name in keyof Events]: readonly unknown[] } = Record<PropertyKey, unknown[]>> {
-  e?: { [Name in keyof Events]?: { fn: (...args: [...Events[Name]]) => unknown, ctx: unknown }[] }
+export interface Emitter<Events extends {
+  [Name in keyof Events]: readonly unknown[];
+} = Record<PropertyKey, unknown[]>> {
+  e?: {
+    [Name in keyof Events]?: {
+      fn: (...args: [...Events[Name]]) => unknown
+      ctx: unknown
+    }[];
+  }
   on: <Name extends keyof Events, Context>(name: Name, fn: (this: Context, ...args: [...Events[Name]]) => unknown, ctx?: Context) => this
   once: <Name extends keyof Events, Context>(name: Name, fn: (this: Context, ...args: [...Events[Name]]) => unknown, ctx?: Context) => this
   emit: <Name extends keyof Events>(name: Name, ...args: [...Events[Name]]) => this

packages/artplayer/types/events.d.ts

@@ -1,14 +1,13 @@
+// Generated from public/events.ts by yarn build:types. Do not edit.
 import type { AspectRatio, Flip } from './player'
 import type { Subtitle } from './subtitle'
 
 export type Bar = 'loaded' | 'played' | 'hover'
-
 /** Actual built-in subtitle update payloads; legacy Events keeps its scalar types. */
 export interface SubtitleUpdateEvents {
   subtitleBeforeUpdate: [cues: VTTCue[]]
   subtitleAfterUpdate: [cues: VTTCue[]]
 }
-
 export interface Events {
   'document:click': [event: Event]
   'document:mouseup': [event: Event]
@@ -22,11 +21,9 @@ export interface Events {
   'document:pointermove': [event: Event]
   'document:visibilitychange': [event: Event]
   'document:webkitfullscreenchange': [event: Event]
-
   'window:resize': [event: Event]
   'window:scroll': [event: Event]
   'window:orientationchange': [event: Event]
-
   'video:abort': [event: Event]
   'video:canplay': [event: Event]
   'video:canplaythrough': [event: Event]
@@ -51,7 +48,6 @@ export interface Events {
   'video:timeupdate': [event: Event]
   'video:volumechange': [event: Event]
   'video:waiting': [event: Event]
-
   'info': [state: boolean]
   'layer': [state: boolean]
   'loading': [state: boolean]
@@ -61,33 +57,31 @@ export interface Events {
   'control': [state: boolean]
   'setting': [state: boolean]
   'hotkey': [event: KeyboardEvent]
-
   'destroy': []
-
   'subtitleOffset': [offset: number]
   /** Legacy contextual type; annotate listeners with VTTCue[] for the runtime payload. */
   'subtitleBeforeUpdate': [cue: VTTCue]
   /** Legacy contextual type; annotate listeners with VTTCue[] for the runtime payload. */
   'subtitleAfterUpdate': [cue: VTTCue]
   'subtitleLoad': [cues: VTTCue[], option: Subtitle]
-
   'focus': [event: Event]
   'blur': [event: Event]
   'dblclick': [event: Event]
   'click': [event: Event]
   'hover': [state: boolean, event: Event]
   'mousemove': [event: Event]
-
   'resize': []
   'view': [state: boolean]
   'lock': [state: boolean]
   'aspectRatio': [aspectRatio: AspectRatio]
   'autoHeight': [height: number]
-  'autoSize': [size: { width: number, height: number }]
+  'autoSize': [size: {
+    width: number
+    height: number
+  }]
   'ready': []
   'airplay': []
   'raf': []
-
   'error': [error: Error, reconnectTime: number]
   'flip': [flip: Flip]
   'fullscreen': [state: boolean]

packages/artplayer/types/i18n.d.ts

@@ -1,19 +1,5 @@
-type I18nKeys
-  = | 'en'
-    | 'zh-cn'
-    | 'zh-tw'
-    | 'pl'
-    | 'cs'
-    | 'es'
-    | 'fa'
-    | 'fr'
-    | 'id'
-    | 'ru'
-    | 'tr'
-    | 'ar'
-    | 'vi'
-    | (string & Record<never, never>)
-
+// Generated from public/i18n.ts by yarn build:types. Do not edit.
+type I18nKeys = 'en' | 'zh-cn' | 'zh-tw' | 'pl' | 'cs' | 'es' | 'fa' | 'fr' | 'id' | 'ru' | 'tr' | 'ar' | 'vi' | (string & Record<never, never>)
 interface I18nValue {
   'Video Info': string
   'Close': string
@@ -52,5 +38,5 @@ interface I18nValue {
   'AirPlay': string
   'AirPlay Not Available': string
 }
-
 export type I18n = Partial<Record<I18nKeys, Partial<I18nValue>>>
+export {}

packages/artplayer/types/icons.d.ts

@@ -1,3 +1,4 @@
+// Generated from public/icons.ts by yarn build:types. Do not edit.
 export interface Icons {
   readonly loading: HTMLDivElement
   readonly state: HTMLDivElement

packages/artplayer/types/language.d.cts

@@ -1,3 +1,4 @@
+// Generated from public/language.cts by yarn build:types. Do not edit.
 import type { I18n } from './i18n.js'
 
 declare const language: NonNullable<I18n['en']>

packages/artplayer/types/language.d.mts

@@ -1 +1,2 @@
+// Generated from public/language.mts by yarn build:types. Do not edit.
 export { default } from './language.cjs'

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

@@ -1,3 +1,4 @@
+// Generated from public/legacy/language.ts by yarn build:types. Do not edit.
 import type { I18n } from '../i18n'
 
 declare const language: NonNullable<I18n['en']>

packages/artplayer/types/option.d.ts

@@ -1,3 +1,4 @@
+// Generated from public/option.ts by yarn build:types. Do not edit.
 import type Artplayer from './artplayer'
 import type { ComponentInput, ComponentOption } from './component'
 import type { CssVar } from './cssVar'
@@ -8,47 +9,33 @@ import type { Quality } from './quality'
 import type { Setting } from './setting'
 import type { Subtitle } from './subtitle'
 
-export type CustomType
-  = | 'flv'
-    | 'm3u8'
-    | 'hls'
-    | 'ts'
-    | 'mpd'
-    | 'torrent'
-    | (string & Record<never, never>)
-
+export type CustomType = 'flv' | 'm3u8' | 'hls' | 'ts' | 'mpd' | 'torrent' | (string & Record<never, never>)
 export interface Thumbnails {
   /**
    * The thumbnail image url
    */
   url: string
-
   /**
    * The thumbnail item number
    */
   number?: number
-
   /**
    * The thumbnail column size
    */
   column?: number
-
   /**
    * The thumbnail width
    */
   width?: number
-
   /**
    * The thumbnail height
    */
   height?: number
-
   /**
    * The thumbnail scale
    */
   scale?: number
 }
-
 /** Constructor input; Option retains its historical required URL/read types. */
 export interface OptionInput extends Omit<Option, 'url' | 'controls' | 'layers' | 'contextmenu'> {
   url?: string
@@ -56,218 +43,175 @@ export interface OptionInput extends Omit<Option, 'url' | 'controls' | 'layers'
   layers?: ComponentInput[]
   contextmenu?: ComponentInput[]
 }
-
 export interface Option {
   /**
    * The player id
    */
   id?: string
-
   /**
    * The container mounted by the player
    */
   container: string | HTMLDivElement
-
   /**
    * Video url
    */
   url: string
-
   /**
    * Video poster image url
    */
   poster?: string
-
   /**
    * Video url type
    */
   type?: CustomType
-
   /**
    * Player color theme
    */
   theme?: string
-
   /**
    * Player language
    */
   lang?: keyof I18n
-
   /**
    * Player default volume
    */
   volume?: number
-
   /**
    * Whether live broadcast mode
    */
   isLive?: boolean
-
   /**
    * Whether video muted
    */
   muted?: boolean
-
   /**
    * Whether video auto play
    */
   autoplay?: boolean
-
   /**
    * Whether player auto resize
    */
   autoSize?: boolean
-
   /**
    * Whether player auto run mini mode
    */
   autoMini?: boolean
-
   /**
    * Whether video auto loop
    */
   loop?: boolean
-
   /**
    * Whether show video flip button
    */
   flip?: boolean
-
   /**
    * Whether show video playback rate button
    */
   playbackRate?: boolean
-
   /**
    * Whether show video aspect ratio button
    */
   aspectRatio?: boolean
-
   /**
    * Whether show video screenshot button
    */
   screenshot?: boolean
-
   /**
    * Whether show video setting button
    */
   setting?: boolean
-
   /**
    * Whether to enable player hotkey
    */
   hotkey?: boolean
-
   /**
    * Whether show video pip button
    */
   pip?: boolean
-
   /**
    * Do you want to run only one player at a time
    */
   mutex?: boolean
-
   /**
    * Whether use backdrop in UI
    */
   backdrop?: boolean
-
   /**
    * Whether show video window fullscreen button
    */
   fullscreen?: boolean
-
   /**
    * Whether show video web fullscreen button
    */
   fullscreenWeb?: boolean
-
   /**
    * Whether to enable player subtitle offset
    */
   subtitleOffset?: boolean
-
   /**
    * Whether to enable player mini progress bar
    */
   miniProgressBar?: boolean
-
   /**
    * Whether use SSR function
    */
   useSSR?: boolean
-
   /**
    * Whether use playsInline in mobile
    */
   playsInline?: boolean
-
   /**
    * Whether use lock in mobile
    */
   lock?: boolean
-
   /**
    * Whether use gesture in mobile
    */
   gesture?: boolean
-
   /**
    * Whether use fast forward in mobile
    */
   fastForward?: boolean
-
   /**
    * Whether use auto playback
    */
   autoPlayback?: boolean
-
   /**
    * Whether use auto orientation in mobile
    */
   autoOrientation?: boolean
-
   /**
    * Whether use airplay
    */
   airplay?: boolean
-
   /**
    * Custom video proxy
    */
   proxy?: (this: Artplayer, art: Artplayer) => HTMLCanvasElement | HTMLVideoElement | undefined
-
   /**
    * Custom plugin list
    */
   plugins?: PluginFactory[]
-
   /**
    * Custom layer list
    */
   layers?: ComponentOption[]
-
   /**
    * Custom contextmenu list
    */
   contextmenu?: ComponentOption[]
-
   /**
    * Custom control list
    */
   controls?: ComponentOption[]
-
   /**
    * Custom setting list
    */
   settings?: Setting[]
-
   /**
    * Custom video quality list
    */
   quality?: Quality[]
-
   /**
    * Custom highlight list
    */
@@ -276,56 +220,41 @@ export interface Option {
      * The highlight time
      */
     time: number
-
     /**
      * The highlight text
      */
     text: string
   }[]
-
   /**
    * Custom thumbnail
    */
   thumbnails?: Thumbnails
-
   /**
    * Custom subtitle option
    */
   subtitle?: Subtitle
-
   /**
    * Other video attribute
    */
   moreVideoAttr?: Partial<Readonly<{
-    [K in keyof HTMLVideoElement as HTMLVideoElement[K] extends (...args: unknown[]) => unknown
-      ? never
-      : K]: HTMLVideoElement[K]
+    [K in keyof HTMLVideoElement as HTMLVideoElement[K] extends (...args: unknown[]) => unknown ? never : K]: HTMLVideoElement[K];
   }>>
-
   /**
    * Custom i18n
    */
   i18n?: I18n
-
   /**
    * Custom default icons
    */
   icons?: {
-    [key in keyof Icons]?: HTMLElement | string
+    [key in keyof Icons]?: HTMLElement | string;
   }
-
   /**
    * Custom css variables
    */
   cssVar?: Partial<CssVar>
-
   /**
    * Custom video type function
    */
-  customType?: Partial<
-    Record<
-      CustomType,
-      (this: Artplayer, video: HTMLVideoElement, url: string, art: Artplayer) => unknown | Promise<unknown>
-    >
-  >
+  customType?: Partial<Record<CustomType, (this: Artplayer, video: HTMLVideoElement, url: string, art: Artplayer) => unknown | Promise<unknown>>>
 }

packages/artplayer/types/playback.d.ts

@@ -1,3 +1,4 @@
+// Generated from public/playback.ts by yarn build:types. Do not edit.
 /** Accurate playback method view; assign an existing player without a runtime wrapper. */
 export interface PlaybackControls {
   play: () => Promise<void>

packages/artplayer/types/player.d.ts

@@ -1,3 +1,4 @@
+// Generated from public/player.ts by yarn build:types. Do not edit.
 import type { CssVar } from './cssVar'
 import type { CustomType, Thumbnails } from './option'
 import type { Quality } from './quality'
@@ -6,48 +7,34 @@ export type AspectRatio = 'default' | '4:3' | '16:9' | (`${number}:${number}` &
 export type PlaybackRate = 0.5 | 0.75 | 1.0 | 1.25 | 1.5 | 1.75 | 2.0 | (number & Record<never, never>)
 export type Flip = 'normal' | 'horizontal' | 'vertical' | (string & Record<never, never>)
 export type State = 'standard' | 'mini' | 'pip' | 'fullscreen' | 'fullscreenWeb'
-
 export declare class Player {
   get aspectRatio(): AspectRatio
   set aspectRatio(ratio: AspectRatio)
-
   get state(): State
   set state(state: State)
-
   get type(): CustomType
   set type(name: CustomType)
-
   get playbackRate(): PlaybackRate
   set playbackRate(rate: PlaybackRate)
-
   get currentTime(): number
   set currentTime(time: number)
-
   get duration(): number
   get played(): number
   get playing(): boolean
-
   get flip(): Flip
   set flip(state: Flip)
-
   get fullscreen(): boolean
   set fullscreen(state: boolean)
-
   get fullscreenWeb(): boolean
   set fullscreenWeb(state: boolean)
-
   get loaded(): number
   get loadedTime(): number
-
   get mini(): boolean
   set mini(state: boolean)
-
   get pip(): boolean
   set pip(state: boolean)
-
   get poster(): string
   set poster(url: string)
-
   get rect(): DOMRect
   get bottom(): number
   get height(): number
@@ -57,55 +44,39 @@ export declare class Player {
   get width(): number
   get x(): number
   get y(): number
-
   set seek(time: number)
   get seek(): number
-
   set forward(time: number)
   get forward(): number
-
   set backward(time: number)
   get backward(): number
-
   get url(): string
   set url(url: string)
-
   get volume(): number
   set volume(percentage: number)
-
   get muted(): boolean
   set muted(state: boolean)
-
   get theme(): string
   set theme(theme: string)
-
   get subtitleOffset(): number
   set subtitleOffset(time: number)
-
   get switch(): string
   set switch(url: string)
-
   get quality(): Quality[]
   set quality(quality: Quality[])
-
   get thumbnails(): Thumbnails
   set thumbnails(thumbnails: Thumbnails)
-
   pause(): void
   play(): Promise<void>
   /** Legacy signature; runtime preserves pause's synchronous result or play's Promise. */
   toggle(): void
-
   attr(key: string, value?: unknown): unknown
   cssVar<T extends keyof CssVar>(key: T, value?: CssVar[T]): CssVar[T]
-
   switchUrl(url: string): Promise<void>
   switchQuality(url: string): Promise<void>
-
   getDataURL(): Promise<string>
   getBlobUrl(): Promise<string>
   screenshot(name?: string): Promise<string>
-
   airplay(): void
   autoSize(): void
   autoHeight(): void

packages/artplayer/types/plugin.d.ts

@@ -1,7 +1,7 @@
+// Generated from public/plugin.ts by yarn build:types. Do not edit.
 import type Artplayer from './artplayer'
 
 export type PluginFactory<Host = Artplayer, Result = unknown> = (this: Host, art: Host) => Result
-
 /** Augment this interface with installed plugin results; augmentation does not register a plugin. */
 export interface Plugins {
   /** Legacy signature: synchronous factories return this registry; Promise factories return a Promise of it. */

packages/artplayer/types/quality.d.ts

@@ -1,14 +1,13 @@
+// Generated from public/quality.ts by yarn build:types. Do not edit.
 export interface Quality {
   /**
    * Whether the default is selected
    */
   default?: boolean
-
   /**
    * Html string of quality
    */
   html: string | HTMLElement
-
   /**
    * Video quality url
    */

packages/artplayer/types/runtime.d.cts

@@ -0,0 +1,53 @@
+// Generated from public/runtime.cts by yarn build:types. Do not edit.
+/* eslint-disable ts/no-redeclare -- Constructor, instance and named types share the export. */
+import type * as Definition from './runtime.js'
+
+declare const Artplayer: typeof Definition.default
+type Artplayer = Definition.default
+declare namespace Artplayer {
+  type ArtplayerConstructor = Definition.ArtplayerConstructor
+  type OptionInput = Definition.OptionInput
+  type Option = Definition.Option
+  type Events = Definition.Events
+  type Plugins = Definition.Plugins
+  type PluginFactory<Result = unknown> = Definition.PluginFactory<Result>
+  type PluginHost = Definition.PluginHost
+  type ProxyHost = Definition.ProxyHost
+  type CustomTypeHost = Definition.CustomTypeHost
+  type LayerHost = Definition.LayerHost
+  type ControlHost = Definition.ControlHost
+  type ContextmenuHost = Definition.ContextmenuHost
+  type PluginRegistration<Result, Registry> = Definition.PluginRegistration<Result, Registry>
+  type Component = Definition.Component
+  type Controls = Definition.Controls
+  type Setting = Definition.Setting
+  type Subtitle = Definition.Subtitle
+  type Notice = Definition.Notice
+  type Utils = Definition.Utils
+  type MediaSurface = Definition.MediaSurface
+  type NativeMedia = Definition.NativeMedia
+  type CanvasMedia = Definition.CanvasMedia
+  type Player<Media extends MediaSurface = MediaSurface> = Definition.Player<Media>
+  type Template<Host = Artplayer, Media extends MediaSurface = MediaSurface> = Definition.Template<Host, Media>
+  type Icons = Definition.Icons
+  type Config = Definition.Config
+  type EventRegistry = Definition.EventRegistry
+  type Storage = Definition.Storage
+  type I18n<Host = Artplayer> = Definition.I18n<Host>
+  type Hotkey<Host = Artplayer> = Definition.Hotkey<Host>
+  type Languages = Definition.Languages
+  type Dictionary = Definition.Dictionary
+  type QualityItem = Definition.QualityItem
+  type SettingItem<Host = Artplayer> = Definition.SettingItem<Host>
+  type ComponentInput<Host = Artplayer> = Definition.ComponentInput<Host>
+  type ComponentOption<Host = Artplayer> = Definition.ComponentOption<Host>
+  type ControlInput<Host = Artplayer> = Definition.ControlInput<Host>
+  type ControlOption<Host = Artplayer> = Definition.ControlOption<Host>
+  type SelectorItem = Definition.SelectorItem
+  type SubtitleCue = Definition.SubtitleCue
+  type SubtitleOption = Definition.SubtitleOption
+  type Emitter<Events extends {
+    [Name in keyof Events]: readonly unknown[];
+  } = Record<PropertyKey, unknown[]>> = Definition.Emitter<Events>
+}
+export = Artplayer

packages/artplayer/types/runtime.d.mts

@@ -0,0 +1,3 @@
+// Generated from public/runtime.mts by yarn build:types. Do not edit.
+export { default } from './runtime.cjs'
+export type * from './runtime.js'

packages/artplayer/types/runtime.d.ts

@@ -0,0 +1,130 @@
+// Generated from public/runtime.ts by yarn build:types. Do not edit.
+/* eslint-disable ts/no-redeclare -- Constructor, instance and named types share the export. */
+import type LegacyArtplayer from './artplayer'
+import type { Emitter } from './emitter'
+import type { OptionInput as LegacyOptionInput } from './option'
+import type { PluginFactory as LegacyPluginFactory, Plugins as LegacyPlugins } from './plugin'
+import type { ComponentInput, Component as ComponentView, ControlInput, Controls as ControlsView } from './runtime/component'
+import type { ContextmenuHost, ControlHost, CustomTypeHost, LayerHost, PluginHost, ProxyHost } from './runtime/construction'
+import type { Events } from './runtime/events'
+import type { MediaSurface } from './runtime/media'
+import type { OptionInput as OptionInputView, Option as OptionView } from './runtime/option'
+import type { Player } from './runtime/player'
+import type { PluginFactory as FactoryView, PluginRegistration, Plugins as PluginsView } from './runtime/plugin'
+import type { Config, EventRegistry, Hotkey, I18n, Scheme, Storage, ValidatorPath } from './runtime/services'
+import type { Setting as SettingView } from './runtime/setting'
+import type { Notice as NoticeView, Subtitle as SubtitleView } from './runtime/subtitle'
+import type { Icons, Template } from './runtime/template'
+import type { Utils } from './runtime/utils'
+
+export type { Emitter } from './emitter'
+export type { ComponentInput, ComponentOption, ControlInput, ControlOption, SelectorItem } from './runtime/component'
+export type { ContextmenuHost, ControlHost, CustomTypeHost, LayerHost, PluginHost, ProxyHost } from './runtime/construction'
+export type { Events } from './runtime/events'
+export type { CanvasMedia, MediaSurface, NativeMedia } from './runtime/media'
+export type { Player, QualityItem } from './runtime/player'
+export type { PluginRegistration } from './runtime/plugin'
+export type { Config, Dictionary, EventRegistry, Hotkey, I18n, Languages, Storage } from './runtime/services'
+export type { SettingItem } from './runtime/setting'
+export type { SubtitleCue, SubtitleOption } from './runtime/subtitle'
+export type { Icons, Template } from './runtime/template'
+export type { Utils } from './runtime/utils'
+export type PluginFactory<Result = unknown> = FactoryView<PluginHost, Result>
+export interface OptionInput extends Omit<OptionInputView<Artplayer>, 'plugins' | 'proxy' | 'customType' | 'layers' | 'controls' | 'contextmenu'> {
+  plugins?: PluginFactory[]
+  proxy?: (this: ProxyHost, art: ProxyHost) => MediaSurface
+  customType?: Record<string, ((this: CustomTypeHost, video: MediaSurface, url: string, art: CustomTypeHost) => unknown) | undefined>
+  layers?: ComponentInput<LayerHost>[]
+  controls?: ControlInput<ControlHost>[]
+  contextmenu?: ComponentInput<ContextmenuHost>[]
+}
+export interface Option extends OptionView<Artplayer> {
+}
+export interface Component extends ComponentView<Artplayer> {
+}
+export interface Controls extends ControlsView<Artplayer> {
+}
+export interface Setting extends SettingView<Artplayer> {
+}
+export interface Subtitle extends SubtitleView, Omit<Component, keyof SubtitleView> {
+}
+export interface Notice extends NoticeView {
+  art: Artplayer
+}
+/** Augment with installed results. Factories are not wrapped or converted. */
+export interface PluginAdd<Registry> {
+  <Result>(plugin: FactoryView<Artplayer, Result>): PluginRegistration<Result, Registry>
+  <Result>(plugin: LegacyPluginFactory<LegacyArtplayer, Result>): PluginRegistration<Result, Registry>
+}
+type LegacyPluginResults = {
+  [Name in keyof LegacyPlugins as string extends Name ? never : number extends Name ? never : Name extends keyof PluginsView<Artplayer> ? never : Name]: LegacyPlugins[Name];
+}
+export interface Plugins extends Omit<PluginsView<Artplayer>, 'add'>, LegacyPluginResults {
+  add: PluginAdd<this>
+  [name: string]: unknown
+}
+/** Public view of the existing constructor; this interface emits no runtime fields. */
+interface Artplayer extends Player, Emitter<Events> {
+  constructor: ArtplayerConstructor
+  id: number
+  option: Option
+  isLock: boolean
+  isReady: boolean
+  isFocus: boolean
+  isInput: boolean
+  isRotate: boolean
+  isDestroy: boolean
+  flv?: unknown
+  m3u8?: unknown
+  hls?: unknown
+  ts?: unknown
+  mpd?: unknown
+  torrent?: unknown
+  template: Template<Artplayer>
+  events: EventRegistry
+  storage: Storage
+  icons: Icons
+  i18n: I18n<Artplayer>
+  notice: Notice
+  /** The descriptor installer has no public instance members. */
+  player: object
+  layers: Component
+  controls: Controls
+  contextmenu: Component & {
+    init: () => void
+  }
+  subtitle: Subtitle
+  info: Component & {
+    init: () => void
+  }
+  loading: Component
+  hotkey: Hotkey<Artplayer>
+  mask: Component
+  setting: Setting
+  plugins: Plugins
+  readonly query: Template<Artplayer>['query']
+  readonly proxy: EventRegistry['proxy']
+  readonly video: MediaSurface
+  reset: () => void
+  destroy: (removeHtml?: boolean) => void
+}
+type StaticOptions = Pick<typeof LegacyArtplayer, Extract<keyof typeof LegacyArtplayer, Uppercase<string>>>
+export interface ArtplayerConstructor extends StaticOptions {
+  new (option: OptionInput, readyCallback?: (this: Artplayer, art: Artplayer) => unknown): Artplayer
+  new (option: LegacyOptionInput, readyCallback?: (this: Artplayer, art: Artplayer) => unknown): Artplayer
+  readonly prototype: Artplayer
+  readonly instances: Artplayer[]
+  readonly version: string
+  readonly config: Config
+  readonly utils: Utils
+  readonly scheme: Record<keyof Option, Scheme>
+  readonly Emitter: new <Events extends {
+    [Name in keyof Events]: readonly unknown[];
+  } = Record<PropertyKey, unknown[]>>(...args: unknown[]) => Emitter<Events>
+  readonly validator: <T>(option: T, scheme: Scheme, paths?: ValidatorPath) => T
+  readonly kindOf: (value: unknown) => string
+  readonly html: string
+  readonly option: Option
+}
+declare const Artplayer: ArtplayerConstructor
+export default Artplayer

packages/artplayer/types/runtime/component.d.ts

@@ -0,0 +1,58 @@
+// Generated from public/runtime/component.ts by yarn build:types. Do not edit.
+export type EventCleanup = () => void
+export interface SelectorItem {
+  html: string | HTMLElement | number
+  value?: string | number
+  default?: boolean
+  readonly $control_option?: SelectorItem[]
+  readonly $control_item?: HTMLDivElement
+  readonly $control_value?: HTMLDivElement
+}
+export interface ComponentOption<Host> {
+  html?: string | HTMLElement | number
+  disable?: boolean
+  name?: string
+  index?: number
+  style?: Partial<CSSStyleDeclaration>
+  tooltip?: string | number
+  position?: string
+  selector?: SelectorItem[]
+  click?: (this: Host, component: Component<Host>, event: Event) => unknown
+  mounted?: (this: Host, element: HTMLDivElement) => unknown
+  beforeUnmount?: (this: Host, element: HTMLDivElement) => unknown
+  onSelect?: (this: Host, item: SelectorItem, element: HTMLDivElement, event: Event) => unknown
+}
+export type ComponentInput<Host> = ComponentOption<Host> | ((art: Host) => ComponentOption<Host>)
+export interface ControlOption<Host> extends Omit<ComponentOption<Host>, 'position'> {
+  position: 'top' | 'left' | 'right'
+}
+export type ControlInput<Host> = ControlOption<Host> | ((art: Host) => ControlOption<Host>)
+export interface ComponentEntry<Host> {
+  $ref: HTMLDivElement
+  events: EventCleanup[]
+  option: ComponentOption<Host>
+}
+export interface Component<Host> {
+  id: number
+  art: Host
+  name?: string
+  $parent?: HTMLElement
+  cache: Map<string, ComponentEntry<Host>>
+  show: boolean
+  toggle: () => void
+  add: (input: ComponentInput<Host>) => HTMLDivElement | undefined
+  remove: (name: string) => void
+  update: (option: ComponentOption<Host>) => ReturnType<this['add']>
+  selector?: (option: ComponentOption<Host>, element: HTMLDivElement, events: EventCleanup[]) => void
+}
+export interface Controls<Host> extends Omit<Component<Host>, 'add' | 'update' | 'selector'> {
+  isHover: boolean
+  timer: number
+  setting?: HTMLDivElement
+  thumbnails?: HTMLDivElement
+  init: () => void
+  add: (input: ControlInput<Host>) => undefined
+  update: (option: ComponentOption<Host>) => undefined
+  check: (target?: SelectorItem) => void
+  selector: (option: ComponentOption<Host>, element: HTMLDivElement, events: EventCleanup[]) => void
+}

packages/artplayer/types/runtime/construction.d.ts

@@ -0,0 +1,18 @@
+// Generated from public/runtime/construction.ts by yarn build:types. Do not edit.
+import type { Emitter } from '../emitter'
+import type Artplayer from '../runtime'
+import type { Events } from './events'
+import type { Player } from './player'
+/** Safe fields before Template returns; video/query/proxy getters are not usable yet. */
+export interface ProxyHost extends Emitter<Events>, Pick<Artplayer, 'constructor' | 'id' | 'option' | 'isLock' | 'isReady' | 'isFocus' | 'isInput' | 'isRotate' | 'isDestroy' | 'destroy'> {
+}
+type Pending<Names extends keyof Artplayer> = Player & Omit<Artplayer, Names | keyof Player> & Partial<Pick<Artplayer, Names>>
+type AfterPlayer = 'layers' | 'controls' | 'contextmenu' | 'subtitle' | 'info' | 'loading' | 'hotkey' | 'mask' | 'setting' | 'plugins'
+/** URL assignment awaits its owned delay before invoking customType. */
+export type CustomTypeHost = Artplayer
+export type LayerHost = Pending<AfterPlayer>
+export type ControlHost = Pending<Exclude<AfterPlayer, 'layers'>>
+export type ContextmenuHost = Pending<Exclude<AfterPlayer, 'layers' | 'controls'>>
+/** Constructor factories run before the Plugins registry is assigned to the player. */
+export type PluginHost = Pending<'plugins'>
+export {}

packages/artplayer/types/runtime/events.d.ts

@@ -0,0 +1,29 @@
+// Generated from public/runtime/events.ts by yarn build:types. Do not edit.
+import type { Events as LegacyEvents } from '../events'
+import type { SubtitleCue, SubtitleOption } from './subtitle'
+
+type NativeEvents = {
+  [Name in Extract<keyof LegacyEvents, `video:${string}`>]: [event: Event];
+}
+interface BuiltinEvents {
+  [name: `video:${string}`]: [event: Event]
+  'document:keydown': [KeyboardEvent]
+  'document:mousemove': [MouseEvent]
+  'document:mouseup': [MouseEvent]
+  'mousemove': [MouseEvent]
+  'click': [MouseEvent]
+  'blur': [Event]
+  'error': [error: unknown, attempt: number]
+  'fullscreenError': [error: unknown]
+  'aspectRatio': [string]
+  'flip': [string]
+  'seek': [time: number, requestedTime: number | string]
+  'setBar': [type: string, percentage: number, event?: MouseEvent | TouchEvent]
+  'subtitleBeforeUpdate': [cues: SubtitleCue[]]
+  'subtitleAfterUpdate': [cues: SubtitleCue[]]
+  'subtitleLoad': [cues: SubtitleCue[], option: SubtitleOption | null]
+}
+/** Legacy custom event augmentation is retained; builtin payload corrections take precedence. */
+export interface Events extends Omit<LegacyEvents, keyof BuiltinEvents>, NativeEvents, BuiltinEvents, Record<PropertyKey, unknown[]> {
+}
+export {}

packages/artplayer/types/runtime/media.d.ts

@@ -0,0 +1,37 @@
+// Generated from public/runtime/media.ts by yarn build:types. Do not edit.
+export type MediaState = Pick<HTMLMediaElement, 'currentTime' | 'duration' | 'paused' | 'ended' | 'readyState'> & {
+  readonly playing?: boolean
+}
+export interface PlaybackMethods<PlayResult = unknown, PauseResult = unknown> {
+  play: () => PlayResult
+  pause: () => PauseResult
+}
+export interface OptionalMediaCapabilities {
+  readonly textTracks?: ArrayLike<TextTrack>
+  readonly error?: unknown
+  requestPictureInPicture?: () => Promise<PictureInPictureWindow>
+  requestVideoFrameCallback?: (callback: VideoFrameRequestCallback) => number
+  cancelVideoFrameCallback?: (handle: number) => void
+  webkitEnterFullscreen?: () => void
+  webkitExitFullscreen?: () => void
+  readonly webkitSupportsFullscreen?: boolean
+  webkitShowPlaybackTargetPicker?: () => void
+  webkitSupportsPresentationMode?: (mode: string) => boolean
+  webkitSetPresentationMode?: (mode: string) => void
+  readonly webkitPresentationMode?: string
+  readonly webkitDisplayingFullscreen?: boolean
+}
+export type NativeMedia = Omit<HTMLVideoElement, keyof OptionalMediaCapabilities> & OptionalMediaCapabilities
+export type CanvasMedia = HTMLCanvasElement & MediaState & PlaybackMethods & OptionalMediaCapabilities & {
+  src: string | null
+  readonly currentSrc: string | null
+  readonly videoWidth: number
+  readonly videoHeight: number
+  readonly buffered: TimeRanges
+  volume: number
+  muted: boolean
+  playbackRate: number
+  load: () => unknown
+}
+/** Check optional capabilities before calling them on a native or proxy surface. */
+export type MediaSurface = NativeMedia | CanvasMedia

packages/artplayer/types/runtime/option.d.ts

@@ -0,0 +1,27 @@
+// Generated from public/runtime/option.ts by yarn build:types. Do not edit.
+import type { OptionInput as LegacyOptionInput, Thumbnails } from '../option'
+import type { ComponentInput, ControlInput } from './component'
+import type { MediaSurface } from './media'
+import type { PluginFactory } from './plugin'
+import type { Languages } from './services'
+import type { SettingItem } from './setting'
+import type { SubtitleOption } from './subtitle'
+/** Callback receivers are the unchanged player instance selected by this view. */
+export interface OptionInput<Host> extends Omit<LegacyOptionInput, 'container' | 'proxy' | 'plugins' | 'layers' | 'controls' | 'contextmenu' | 'settings' | 'customType' | 'i18n' | 'icons'> {
+  container: string | HTMLDivElement
+  proxy?: (this: Host, art: Host) => MediaSurface | undefined
+  plugins?: PluginFactory<Host>[]
+  layers?: ComponentInput<Host>[]
+  controls?: ControlInput<Host>[]
+  contextmenu?: ComponentInput<Host>[]
+  settings?: SettingItem<Host>[]
+  customType?: Record<string, ((this: Host, video: MediaSurface, url: string, art: Host) => unknown) | undefined>
+  i18n?: Languages
+  icons?: Record<string, string | HTMLElement | undefined>
+}
+/** Defaults are merged once; later setters may replace thumbnails with a partial input. */
+export interface Option<Host> extends Omit<Required<OptionInput<Host>>, 'proxy' | 'subtitle' | 'thumbnails'> {
+  proxy: OptionInput<Host>['proxy']
+  subtitle: SubtitleOption
+  thumbnails: Thumbnails
+}

packages/artplayer/types/runtime/player.d.ts

@@ -0,0 +1,78 @@
+// Generated from public/runtime/player.ts by yarn build:types. Do not edit.
+import type { Thumbnails } from '../option'
+import type { State } from '../player'
+import type { MediaSurface } from './media'
+
+export interface QualityItem {
+  html: string | HTMLElement
+  url: string
+  default?: boolean
+}
+/** Player-facing descriptors; native/proxy method results retain their identity. */
+export interface Player<Media extends MediaSurface = MediaSurface> {
+  get currentTime(): number
+  set currentTime(time: number | string)
+  readonly duration: number
+  get seek(): undefined
+  set seek(time: number | string)
+  get forward(): undefined
+  set forward(time: number)
+  get backward(): undefined
+  set backward(time: number)
+  get switch(): undefined
+  set switch(url: string)
+  get quality(): undefined
+  set quality(items: QualityItem[])
+  get url(): string | null
+  set url(value: string)
+  get state(): State
+  set state(value: string)
+  get pip(): Element | null | boolean
+  set pip(value: boolean)
+  /** The descriptor may be absent before metadata installs the available mode. */
+  fullscreen?: boolean
+  fullscreenWeb: boolean
+  mini: boolean
+  volume: number
+  muted: boolean
+  playbackRate: number
+  aspectRatio: string
+  flip: string
+  poster: string
+  theme: string
+  type: string
+  subtitleOffset: number
+  thumbnails: Thumbnails
+  readonly loaded: number
+  readonly loadedTime: number
+  readonly played: number
+  readonly playing: boolean
+  readonly rect: DOMRect
+  readonly bottom: number
+  readonly height: number
+  readonly left: number
+  readonly right: number
+  readonly top: number
+  readonly width: number
+  readonly x: number
+  readonly y: number
+  play: () => Promise<Awaited<ReturnType<Media['play']>>>
+  pause: () => ReturnType<Media['pause']>
+  toggle: () => Promise<Awaited<ReturnType<Media['play']>>> | ReturnType<Media['pause']>
+  switchUrl: (url: string) => Promise<void>
+  switchQuality: (url: string) => Promise<void>
+  autoSize: () => void
+  autoHeight: () => void
+  airplay: () => void
+  getDataURL: () => Promise<string>
+  getBlobUrl: () => Promise<string>
+  screenshot: (name?: string) => Promise<string>
+  attr: {
+    (key: PropertyKey): unknown
+    (key: PropertyKey, value: unknown): unknown
+  }
+  cssVar: {
+    (key: string): string
+    (key: string, value: unknown): string | void
+  }
+}

packages/artplayer/types/runtime/plugin.d.ts

@@ -0,0 +1,10 @@
+// Generated from public/runtime/plugin.ts by yarn build:types. Do not edit.
+export type PluginFactory<Host, Result = unknown> = (this: Host, art: Host) => Result
+export type PluginRegistration<Result, Registry> = unknown extends Result ? Registry | Promise<Registry> : Result extends Promise<unknown> ? Promise<Registry> : Registry
+/** The same registry is returned immediately or after its Promise factory settles. */
+export interface Plugins<Host> {
+  art: Host
+  id: number
+  add: <Result>(plugin: PluginFactory<Host, Result>) => PluginRegistration<Result, this>
+  next: (plugin: PluginFactory<Host>, result: unknown) => this
+}

packages/artplayer/types/runtime/services.d.ts

@@ -0,0 +1,55 @@
+// Generated from public/runtime/services.ts by yarn build:types. Do not edit.
+export interface Config {
+  properties: string[]
+  methods: string[]
+  events: string[]
+  prototypes: string[]
+}
+export type Disposer = () => void
+export type Listener = EventListenerOrEventListenerObject | null
+export interface EventRegistry {
+  destroyEvents: Set<Disposer>
+  proxy: {
+    (target: EventTarget, name: string, callback: Listener, option?: boolean | AddEventListenerOptions | null): Disposer
+    (target: EventTarget, name: string[], callback: Listener, option?: boolean | AddEventListenerOptions | null): Disposer[]
+    (target: EventTarget, name: string | string[], callback: Listener, option?: boolean | AddEventListenerOptions | null): Disposer | Disposer[]
+  }
+  hover: (target: EventTarget, mouseenter?: (event: Event) => unknown, mouseleave?: (event: Event) => unknown) => void
+  remove: (dispose: Disposer) => void
+  destroy: () => void
+  bindGlobalEvents: (source?: {
+    window?: Window
+    document?: Document
+  }) => void
+}
+export interface Storage {
+  name: string
+  settings: Record<PropertyKey, unknown>
+  get: (key?: PropertyKey) => unknown
+  set: (key: PropertyKey, value: unknown) => void
+  del: (key: PropertyKey) => void
+  clear: () => void
+}
+export type Dictionary = Record<string, string | undefined>
+export type Languages = Record<string, Dictionary | undefined>
+export interface I18n<Host> {
+  art: Host
+  languages: Languages
+  language: Dictionary
+  init: () => void
+  get: (key: string) => string
+  update: (value: Languages) => void
+}
+export type HotkeyCallback<Host> = (this: Host, event: KeyboardEvent) => unknown
+export interface Hotkey<Host> {
+  art: Host
+  keys: Record<string, HotkeyCallback<Host>[]>
+  init: () => void
+  add: (key: string, callback: HotkeyCallback<Host>) => this
+  remove: (key: string, callback: HotkeyCallback<Host>) => this
+}
+export type ValidatorPath = (string | number)[]
+export type Validator = (value: unknown, type: string, paths: ValidatorPath) => unknown
+export type Scheme = string | Validator | Scheme[] | {
+  [key: string]: Scheme
+}

packages/artplayer/types/runtime/setting.d.ts

@@ -0,0 +1,57 @@
+// Generated from public/runtime/setting.ts by yarn build:types. Do not edit.
+export type SettingContent = string | HTMLElement | number
+export type SettingRange = [value?: number, min?: number, max?: number, step?: number]
+export type SettingCallback<Host> = (this: Host, item: SettingItem<Host>, element: HTMLDivElement, event: Event) => unknown
+export interface SettingItem<Host> {
+  name?: string
+  html?: SettingContent
+  icon?: SettingContent
+  tooltip?: SettingContent
+  width?: number
+  value?: string | number
+  default?: boolean
+  switch?: boolean
+  range?: SettingRange
+  selector?: SettingItem<Host>[]
+  mounted?: (this: Host, element: HTMLDivElement, item: SettingItem<Host>) => unknown
+  onClick?: SettingCallback<Host>
+  onSwitch?: SettingCallback<Host>
+  onRange?: SettingCallback<Host>
+  onChange?: SettingCallback<Host>
+  onSelect?: SettingCallback<Host>
+  readonly $parent?: SettingItem<Host>
+  readonly $parents?: SettingItem<Host>[]
+  readonly $option?: SettingItem<Host>[]
+  readonly $events?: (() => void)[]
+  readonly $formatted?: boolean
+  readonly $item?: HTMLDivElement
+  readonly $icon?: HTMLDivElement
+  readonly $html?: HTMLDivElement
+  readonly $tooltip?: HTMLDivElement
+  readonly $switch?: HTMLDivElement
+  readonly $range?: HTMLInputElement
+}
+export interface Setting<Host> {
+  id: number
+  art: Host
+  name: string
+  $parent: HTMLElement
+  cache: Map<SettingItem<Host>[], HTMLDivElement>
+  active: SettingItem<Host>[] | null
+  option: SettingItem<Host>[]
+  readonly builtin: SettingItem<Host>[]
+  show: boolean
+  toggle: () => void
+  traverse: (callback: (item: SettingItem<Host>) => void, option?: SettingItem<Host>[]) => void
+  check: (target?: SettingItem<Host> | null) => void
+  format: (option?: SettingItem<Host>[], parent?: SettingItem<Host>, parents?: SettingItem<Host>[], names?: string[]) => void
+  find: (name?: string) => SettingItem<Host> | null
+  resize: () => void
+  inactivate: (item: SettingItem<Host>) => void
+  remove: (name: string) => void
+  update: (item: SettingItem<Host>) => SettingItem<Host>
+  add: <Item extends SettingItem<Host>>(item: Item, option?: SettingItem<Host>[]) => Item
+  createHeader: (item: SettingItem<Host>) => void
+  createItem: (item: SettingItem<Host>, isUpdate?: boolean) => void
+  render: (option?: SettingItem<Host>[]) => void
+}

packages/artplayer/types/runtime/subtitle.d.ts

@@ -0,0 +1,37 @@
+// Generated from public/runtime/subtitle.ts by yarn build:types. Do not edit.
+import type { Subtitle as SubtitleInput } from '../subtitle'
+
+export type SubtitleOption = Required<SubtitleInput>
+export interface SubtitleCue extends TextTrackCue {
+  text: string
+  originalStartTime?: number
+  originalEndTime?: number
+}
+export interface SubtitleTrack extends HTMLTrackElement {
+  offset?: number
+}
+export interface Subtitle {
+  name: string
+  option: SubtitleOption | null
+  destroyEvent: () => unknown
+  url: string
+  readonly textTrack: TextTrack | undefined
+  readonly activeCues: SubtitleCue[]
+  readonly cues: SubtitleCue[]
+  show: boolean
+  toggle: () => void
+  style: {
+    (styles: Partial<CSSStyleDeclaration>): HTMLDivElement
+    (key: string, value: string | number): HTMLDivElement
+  }
+  update: () => void
+  switch: (url: string, option?: SubtitleInput) => Promise<string | null | undefined>
+  init: (option: SubtitleOption) => Promise<string | null | undefined>
+  createTrack: (kind: string, url: string) => void
+}
+export interface Notice {
+  timer: number | null
+  get show(): boolean
+  set show(value: string | Error | false)
+  destroy: () => void
+}

packages/artplayer/types/runtime/template.d.ts

@@ -0,0 +1,39 @@
+// Generated from public/runtime/template.ts by yarn build:types. Do not edit.
+import type { MediaSurface } from './media'
+/** Query results remain nullable for caller-supplied SSR templates. */
+export interface Template<Host, Media extends MediaSurface = MediaSurface> {
+  art: Host
+  $container: HTMLDivElement
+  $player: HTMLDivElement | null
+  $video: Media
+  $track: HTMLTrackElement | null
+  $poster: HTMLDivElement | null
+  $subtitle: HTMLDivElement | null
+  $danmuku: HTMLDivElement | null
+  $bottom: HTMLDivElement | null
+  $progress: HTMLDivElement | null
+  $controls: HTMLDivElement | null
+  $controlsLeft: HTMLDivElement | null
+  $controlsCenter: HTMLDivElement | null
+  $controlsRight: HTMLDivElement | null
+  $layer: HTMLDivElement | null
+  $loading: HTMLDivElement | null
+  $notice: HTMLDivElement | null
+  $noticeInner: HTMLDivElement | null
+  $mask: HTMLDivElement | null
+  $state: HTMLDivElement | null
+  $setting: HTMLDivElement | null
+  $info: HTMLDivElement | null
+  $infoPanel: HTMLDivElement | null
+  $infoClose: HTMLDivElement | null
+  $contextmenu: HTMLDivElement | null
+  $mini?: HTMLElement
+  query: <ElementType extends Element = Element>(selector: string) => ElementType | null
+  init: () => void
+  destroy: (removeHtml: boolean) => void
+}
+export type IconName = 'loading' | 'state' | 'play' | 'pause' | 'check' | 'volume' | 'volumeClose' | 'screenshot' | 'setting' | 'pip' | 'arrowLeft' | 'arrowRight' | 'playbackRate' | 'aspectRatio' | 'config' | 'lock' | 'flip' | 'unlock' | 'fullscreenOff' | 'fullscreenOn' | 'fullscreenWebOff' | 'fullscreenWebOn' | 'switchOn' | 'switchOff' | 'error' | 'close' | 'airplay'
+/** Default getters create fresh icon wrappers; unknown custom keys may be absent. */
+export type Icons = Readonly<Record<IconName, HTMLElement>> & {
+  readonly [name: string]: HTMLElement | undefined
+}

packages/artplayer/types/runtime/utils.d.ts

@@ -0,0 +1,75 @@
+// Generated from public/runtime/utils.ts by yarn build:types. Do not edit.
+interface StyledElement {
+  style: CSSStyleDeclaration
+}
+interface EventPathSource {
+  target: EventTarget | null
+  composedPath?: () => EventTarget[]
+}
+type StackFrame = ((...args: never[]) => unknown) | (abstract new (...args: never[]) => object)
+export interface Utils {
+  isBrowser: boolean
+  userAgent: string
+  isMobile: boolean
+  isSafari: boolean
+  isIOS: boolean
+  isIOS13: boolean
+  query: <T extends Element = Element>(selector: string, parent?: ParentNode) => T | null
+  queryAll: <T extends Element = Element>(selector: string, parent?: ParentNode) => T[]
+  addClass: (target: Pick<Element, 'classList'>, className: string) => void
+  removeClass: (target: Pick<Element, 'classList'>, className: string) => void
+  hasClass: (target: Pick<Element, 'classList'>, className: string) => boolean
+  append: (parent: Element, child: unknown) => Element | ChildNode | null
+  remove: <T extends Node>(child: T) => T
+  replaceElement: <T extends Node>(newChild: T, oldChild: Node) => T
+  siblings: (target: Element) => Element[]
+  inverseClass: (target: Element, className: string) => void
+  createElement: {
+    <K extends keyof HTMLElementTagNameMap>(tag: K): HTMLElementTagNameMap[K]
+    (tag: string): HTMLElement
+  }
+  setStyle: <T extends StyledElement>(element: T, key: PropertyKey, value: unknown) => T
+  setStyles: <T extends StyledElement>(element: T, styles: object) => T
+  getStyle: {
+    (element: Element, key: string, numberType?: true): number
+    (element: Element, key: string, numberType: false): string
+    (element: Element, key: string, numberType: boolean): number | string
+  }
+  setStyleText: (id: string, cssText: string) => void
+  getRect: (element: Pick<Element, 'getBoundingClientRect'>) => DOMRect
+  tooltip: (target: Element, message: string | number, position?: string) => void
+  isInViewport: (target: Pick<Element, 'getBoundingClientRect'>, offset?: number) => boolean
+  includeFromEvent: (event: EventPathSource, target: EventTarget | null | undefined) => boolean
+  getSafeAreaInsets: () => {
+    top: number
+    right: number
+    bottom: number
+    left: number
+  }
+  srtToVtt: (text: string) => string
+  vttToBlob: (text: string) => string
+  assToVtt: (text: string) => string
+  getExt: (url: string) => string
+  download: (url: string, name: string) => void
+  loadImg: (url: string, scale?: number) => Promise<HTMLImageElement>
+  errorHandle: <T>(condition: T, message?: string) => T
+  silencePromise: <T>(value: T) => T extends Promise<infer Result> ? Promise<Result | undefined> : T
+  def: <T extends object>(object: T, name: PropertyKey, descriptor: PropertyDescriptor & object & ThisType<T>) => T
+  has: (object: object, name: PropertyKey) => boolean
+  get: (object: object, name: PropertyKey) => PropertyDescriptor | undefined
+  mergeDeep: <T extends object[]>(...objects: T) => T[number]
+  sleep: (milliseconds?: number) => Promise<void>
+  /** The wrapper preserves its call receiver; the old context argument is ignored. */
+  debounce: <Receiver, Args extends unknown[]>(callback: (this: Receiver, ...args: Args) => unknown, duration: number, context?: object) => (this: Receiver, ...args: Args) => void
+  throttle: <Receiver, Args extends unknown[]>(callback: (this: Receiver, ...args: Args) => unknown, duration: number) => (this: Receiver, ...args: Args) => void
+  clamp: (number: number, a: number, b: number) => number
+  secondToTime: (second: number) => string
+  escape: (text: string) => string
+  unescape: (text: string) => string
+  capitalize: (text: string) => string
+  ArtPlayerError: new (message?: string, context?: StackFrame) => Error
+  getIcon: (key?: string, html?: string | HTMLElement) => HTMLElement
+  getComposedPath: (event: EventPathSource) => EventTarget[]
+  supportsFlex: () => boolean
+}
+export {}

packages/artplayer/types/setting.d.ts

@@ -1,3 +1,4 @@
+// Generated from public/setting.ts by yarn build:types. Do not edit.
 import type Artplayer from './artplayer'
 
 export interface SettingOption extends Omit<Setting, 'html' | 'icon' | 'tooltip'> {
@@ -16,78 +17,63 @@ export interface SettingOption extends Omit<Setting, 'html' | 'icon' | 'tooltip'
   $events: Array<() => void>
   $formatted: boolean
 }
-
 export interface Setting {
   /**
    * Html string or html element of setting name
    */
   html: string | HTMLElement
-
   /**
    * Html string or html element of setting icon
    */
   icon?: string | HTMLElement
-
   /**
    * The width of setting
    */
   width?: number
-
   /**
    * The tooltip of setting
    */
   tooltip?: string | HTMLElement
-
   /**
    * Whether the default is selected
    */
   default?: boolean
-
   /**
    * Custom selector list
    */
   selector?: Setting[]
-
   /**
    * When the setting was mounted
    */
   mounted?: (this: Artplayer, panel: HTMLDivElement, item: Setting) => void
-
   /**
    * When selector item click
    */
   onSelect?: (this: Artplayer, item: SettingOption, element: HTMLDivElement, event: Event) => void
-
   /**
    * Custom switch item
    */
   switch?: boolean
-
   /**
    * When switch item click
    */
   onSwitch?: (this: Artplayer, item: SettingOption, element: HTMLDivElement, event: Event) => void
-
   /**
    * Custom range item
    */
   range?: [value?: number, min?: number, max?: number, step?: number]
-
   /**
    * When range item change
    */
   onRange?: (this: Artplayer, item: SettingOption, element: HTMLDivElement, event: Event) => void
-
   /**
    * When range item change in real time
    */
   onChange?: (this: Artplayer, item: SettingOption, element: HTMLDivElement, event: Event) => void
-
   /**
    * When range item change in real time
    */
   onClick?: (this: Artplayer, item: SettingOption, element: HTMLDivElement, event: Event) => void
-
   /**
    * Allow custom properties
    */

packages/artplayer/types/subtitle.d.ts

@@ -1,34 +1,29 @@
+// Generated from public/subtitle.ts by yarn build:types. Do not edit.
 export interface Subtitle {
   /**
    * The subtitle url
    */
   url?: string
-
   /**
    * The subtitle name
    */
   name?: string
-
   /**
    * The subtitle type
    */
   type?: 'vtt' | 'srt' | 'ass' | (string & Record<never, never>)
-
   /**
    * The subtitle style object
    */
   style?: Partial<CSSStyleDeclaration>
-
   /**
    * The subtitle encoding, default utf-8
    */
   encoding?: string
-
   /**
    * Whether use escape, default true
    */
   escape?: boolean
-
   /**
    * Change the vtt text
    */

packages/artplayer/types/template.d.ts

@@ -1,3 +1,4 @@
+// Generated from public/template.ts by yarn build:types. Do not edit.
 export interface Template {
   readonly html: string
   readonly $container: HTMLDivElement

packages/artplayer/types/utils.d.ts

@@ -1,3 +1,4 @@
+// Generated from public/utils.ts by yarn build:types. Do not edit.
 export interface Utils {
   isBrowser: boolean
   userAgent: string
@@ -5,7 +6,6 @@ export interface Utils {
   isSafari: boolean
   isIOS: boolean
   isIOS13: boolean
-
   query: <T extends Element = Element>(selector: string, parent?: Document | HTMLElement) => T | null
   queryAll: <T extends Element = Element>(selector: string, parent?: Document | HTMLElement) => T[]
   addClass: (target: HTMLElement, className: string) => void
@@ -17,31 +17,34 @@ export interface Utils {
   siblings: (target: HTMLElement) => HTMLElement[]
   inverseClass: (target: HTMLElement, className: string) => void
   createElement: <K extends keyof HTMLElementTagNameMap>(tag: K) => HTMLElementTagNameMap[K]
-  setStyle: <T extends keyof CSSStyleDeclaration>(
-    element: HTMLElement,
-    key: T,
-    value: string | CSSStyleDeclaration[T],
-  ) => HTMLElement
+  setStyle: <T extends keyof CSSStyleDeclaration>(element: HTMLElement, key: T, value: string | CSSStyleDeclaration[T]) => HTMLElement
   setStyles: (element: HTMLElement, styles: Partial<CSSStyleDeclaration>) => HTMLElement
   getStyle: {
     (element: HTMLElement, key: keyof CSSStyleDeclaration, numberType?: true): number
     (element: HTMLElement, key: keyof CSSStyleDeclaration, numberType: false): string
   }
   setStyleText: (id: string, cssText: string) => void
-  getRect: (el: HTMLElement) => { top: number, left: number, width: number, height: number }
+  getRect: (el: HTMLElement) => {
+    top: number
+    left: number
+    width: number
+    height: number
+  }
   tooltip: (target: HTMLElement, msg: string, pos?: string) => void
   isInViewport: (target: HTMLElement, offset?: number) => boolean
   includeFromEvent: (event: Event, target: HTMLElement) => boolean
-  getSafeAreaInsets: () => { top: number, right: number, bottom: number, left: number }
-
+  getSafeAreaInsets: () => {
+    top: number
+    right: number
+    bottom: number
+    left: number
+  }
   srtToVtt: (srtText: string) => string
   vttToBlob: (vttText: string) => string
   assToVtt: (assText: string) => string
-
   getExt: (url: string) => string
   download: (url: string, name: string) => void
   loadImg: (url: string, scale?: number) => Promise<HTMLImageElement>
-
   errorHandle: <T extends boolean>(condition: T, msg: string) => T extends true ? T : never
   silencePromise: <T>(value: T) => T extends Promise<infer R> ? Promise<R | undefined> : T
   def: {
@@ -52,21 +55,17 @@ export interface Utils {
   has: (obj: object, name: PropertyKey) => boolean
   get: (obj: object, name: PropertyKey) => PropertyDescriptor | undefined
   mergeDeep: <T extends object[]>(...args: T) => T[number]
-
   sleep: (ms?: number) => Promise<void>
   /** Historical return type; runtime discards the callback result and ignores context. */
   debounce: <F extends (...args: any[]) => any>(func: F, wait: number, context?: object) => (...args: Parameters<F>) => ReturnType<F>
   /** Historical return type; runtime discards the callback result. */
   throttle: <F extends (...args: any[]) => any>(func: F, wait: number) => (...args: Parameters<F>) => ReturnType<F>
-
   clamp: (num: number, a: number, b: number) => number
   secondToTime: (second: number) => string
   escape: (str: string) => string
   unescape: (str: string) => string
   capitalize: (str: string) => string
-
   ArtPlayerError: new (message?: string, context?: ((...args: never[]) => unknown) | (abstract new (...args: never[]) => object)) => Error
-
   getIcon: (key?: string, html?: string | HTMLElement) => HTMLElement
   getComposedPath: (event: Event) => EventTarget[]
   supportsFlex: () => boolean