refactor(iframe): [PKG-IFRAME-04] preserve types across module consumers

packages/artplayer-tool-iframe/types/artplayer-tool-iframe.d.cts

@@ -0,0 +1,22 @@
+/* eslint-disable ts/no-redeclare -- Constructor, instance and named-type namespace intentionally merge. */
+import type * as Definition from './artplayer-tool-iframe.js'
+
+declare const ArtplayerToolIframe: typeof Definition.default
+type ArtplayerToolIframe = Definition.default
+
+declare namespace ArtplayerToolIframe {
+  type Option = Definition.Option
+  type Message<T = any> = Definition.Message<T>
+  type Callbacks = Definition.Callbacks
+  type Notification<T = unknown> = Definition.Notification<T>
+  type MessageCallback = Definition.MessageCallback
+  type OutboundMessage<T = unknown> = Definition.OutboundMessage<T>
+  type ProtocolMessage<T = unknown> = Definition.ProtocolMessage<T>
+  type Resolve<T> = Definition.Resolve<T>
+  type ResolverCallback<T> = Definition.ResolverCallback<T>
+  type RuntimeInstance = Definition.RuntimeInstance
+  type ResolverInstance = Definition.ResolverInstance
+  type RuntimeConstructor = Definition.RuntimeConstructor
+}
+
+export = ArtplayerToolIframe

packages/artplayer-tool-iframe/types/artplayer-tool-iframe.d.mts

@@ -0,0 +1,2 @@
+export { default } from './artplayer-tool-iframe.cjs'
+export type { Callbacks, Message, MessageCallback, Notification, Option, OutboundMessage, ProtocolMessage, Resolve, ResolverCallback, ResolverInstance, RuntimeConstructor, RuntimeInstance } from './artplayer-tool-iframe.js'

packages/artplayer-tool-iframe/types/artplayer-tool-iframe.d.ts

@@ -1,18 +1,76 @@
-interface Message {
+export interface Option {
+  iframe: HTMLIFrameElement
+  url: string
+}
+
+/** Historical open envelope. data remains required in the default class API. */
+export interface Message<T = any> {
   type: string
-  data: any
+  data: T
   id?: number
 }
 
+export interface Callbacks {
+  resove: (...args: any[]) => any
+  reject: (...args: any[]) => any
+}
+
+/** Public notifications omit the request id and all private session metadata. */
+export interface Notification<T = unknown> {
+  type: string
+  data: T
+}
+
+export type MessageCallback = (this: ArtplayerToolIframe, message: Notification) => void
+
+/** Actual outgoing calls allow an omitted data field. Custom message types remain valid. */
+export interface OutboundMessage<T = unknown> {
+  type: string
+  data?: T
+  id?: number
+}
+
+/** Known built-in envelopes; use Message/OutboundMessage for application protocols. */
+export type ProtocolMessage<T = unknown>
+  = | { type: 'inject', data?: undefined, id?: number }
+    | { type: 'commit', data: string, id: number }
+    | { type: 'response', data: T, id: number }
+    | { type: 'error', data: unknown, id: number }
+
+export type Resolve<T> = (value: T | PromiseLike<T>) => void
+export type ResolverCallback<T> = (resolve: Resolve<T>) => void
+
+/** Opt-in view. Response T is supplied by the application's protocol, not validated at runtime. */
+export interface RuntimeInstance extends Omit<ArtplayerToolIframe, 'messageCallback' | 'postMessage' | 'message'> {
+  messageCallback: MessageCallback | null
+  postMessage: <T = unknown>(message: OutboundMessage) => Promise<T>
+  message: (callback: MessageCallback) => void
+}
+
+/** For the existing serialized resolve(...) protocol; callback bodies must use that exact name. */
+export interface ResolverInstance extends Omit<RuntimeInstance, 'commit'> {
+  commit: <T>(callback: ResolverCallback<T>) => Promise<T>
+}
+
+/** Opt-in static async/optional-data view. There is no runtime self-default property. */
+export interface RuntimeConstructor {
+  new (option: Option): RuntimeInstance
+  readonly prototype: RuntimeInstance
+  readonly iframe: boolean
+  postMessage: (message: OutboundMessage) => void
+  onMessage: (event: MessageEvent<OutboundMessage>) => Promise<void>
+  inject: () => void
+}
+
 declare class ArtplayerToolIframe {
-  constructor(option: { iframe: HTMLIFrameElement, url: string })
+  constructor(option: Option)
 
   static iframe: boolean
   static postMessage(message: Message): void
   static onMessage(event: MessageEvent & { data: Message }): void
   static inject(): void
 
-  readonly promises: Record<number, { resove: (...args: any[]) => any, reject: (...args: any[]) => any }>
+  readonly promises: Record<number, Callbacks>
   readonly injected: boolean
   readonly destroyed: boolean
   readonly $iframe: HTMLIFrameElement