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

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
+}