refactor(core): CORE-10 type playback properties and add compatible controls view

packages/artplayer/types/COMPATIBILITY.md

@@ -33,16 +33,33 @@ art.on('subtitleBeforeUpdate', (cues: VTTCue[]) => {
 
 ## Retained conflicts and owners
 
-| Surface                   | Actual runtime                                                                | Retained historical declaration                         | Follow-up                |
-| ------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------ |
-| 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 |
-| debounce/throttle         | Wrapper returns undefined; debounce ignores its old context argument          | Callback return type                                    | CORE-21, BASE-TYPE-05    |
-| def with string key       | Native defineProperty returns the target                                      | void, arbitrary descriptor input accepted               | CORE-21, BASE-TYPE-05    |
-| setting.find              | Item or null                                                                  | Item or undefined                                       | CORE-14/21, BASE-TYPE-07 |
-| setting.add/update/remove | Item/item/undefined                                                           | Setting registry                                        | CORE-14/21, BASE-TYPE-07 |
-| subtitle update events    | VTTCue array                                                                  | Scalar contextual inference unless explicitly annotated | CORE-15/21, BASE-TYPE-07 |
-| notice.show getter        | Boolean visibility                                                            | Historical message/false union                          | CORE-18/21, BASE-TYPE-07 |
+CORE-10 adds an accurate method view without wrapping or replacing the player:
+
+```ts
+import type { PlaybackControls } from 'artplayer'
+
+const playback: PlaybackControls = art
+const pending = playback.toggle()
+if (pending)
+  pending.catch(error => console.error(error))
+```
+
+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.
+
+| Surface                                    | Actual runtime                                                                | Retained historical declaration                         | Follow-up                |
+| ------------------------------------------ | ----------------------------------------------------------------------------- | ------------------------------------------------------- | ------------------------ |
+| 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 |
+| debounce/throttle                          | Wrapper returns undefined; debounce ignores its old context argument          | Callback return type                                    | CORE-21, BASE-TYPE-05    |
+| def with string key                        | Native defineProperty returns the target                                      | void, arbitrary descriptor input accepted               | CORE-21, BASE-TYPE-05    |
+| setting.find                               | Item or null                                                                  | Item or undefined                                       | CORE-14/21, BASE-TYPE-07 |
+| setting.add/update/remove                  | Item/item/undefined                                                           | Setting registry                                        | CORE-14/21, BASE-TYPE-07 |
+| subtitle update events                     | VTTCue array                                                                  | Scalar contextual inference unless explicitly annotated | CORE-15/21, BASE-TYPE-07 |
+| 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
@@ -52,6 +69,11 @@ 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
 return types to call Promise methods on synchronous results or chain settings.
 
+CORE-10 records BASE-TYPE-08 from real published/candidate descriptors. Reading
+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.
+
 ## Evidence and maintenance
 
 declaration-legacy.ts is a compile-only regression fixture, not recommended runtime

packages/artplayer/types/README.md

@@ -47,6 +47,12 @@ signature. CORE-21 remains responsible for the generated/public declaration stra
 
 ## Internal media migration
 
+`PlaybackControls` is an optional accurate view of play/pause/toggle. Assign the
+existing player directly (`const playback: PlaybackControls = art`); it preserves
+object identity and reports toggle's Promise-or-void branches. It is exported from
+the root and shared type entry in all five supported consumer modes. Historical
+`art.toggle(): void` remains available; see COMPATIBILITY.md for the distinction.
+
 CORE-06 uses src/media/types.ts and src/media/hosts.ts for native media, canvas
 shims and minimal playback/layout dependencies. These types are not exported by
 the package. Public art.video keeps its historical declaration and runtime identity;

packages/artplayer/types/artplayer.d.cts

@@ -14,6 +14,7 @@ declare namespace Artplayer {
   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

packages/artplayer/types/artplayer.d.mts

@@ -1,2 +1,2 @@
 export { default } from './artplayer.cjs'
-export type { Config, Emitter, Events, I18n, Icons, Option, OptionInput, Player, PluginFactory, Plugins, Setting, SettingOption, Subtitle, SubtitleUpdateEvents, Template, Utils } from './artplayer.js'
+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

@@ -5,6 +5,7 @@ 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'
@@ -20,6 +21,7 @@ export type {
   Icons,
   Option,
   OptionInput,
+  PlaybackControls,
   Player,
   PluginFactory,
   Plugins,

packages/artplayer/types/playback.d.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
+}