refactor(vast): [PKG-VAST-04] retain published types and add accurate runtime declarations

packages/artplayer-plugin-vast/.npmignore

@@ -2,4 +2,5 @@ node_modules
 .DS_Store
 yarn.lock
 package-lock.json
-src
+src
+tsconfig.json

packages/artplayer-plugin-vast/ARCHITECTURE.md

@@ -1,7 +1,7 @@
 # VAST implementation and maintenance
 
-The runtime follows the accepted published-versus-workspace initialization decision.
-Public declaration reconciliation and real IMA validation remain separate release gates.
+The runtime and public types follow the accepted published-versus-workspace decisions.
+Real IMA validation and full distribution acceptance remain separate release gates.
 
 ## Module map
 
@@ -17,8 +17,13 @@ Public declaration reconciliation and real IMA validation remain separate releas
   active-ad request suppression; default mode delegates those behaviors to the SDK.
 - `src/view.ts` creates each mode's historical overlay styles and distinct per-module container
   IDs, including multiple instances initialized in the same millisecond.
-- `src/types.ts` describes the implementation context and SDK boundary. Public legacy
-  declarations in `types/` remain separate pending PKG-VAST-04 reconciliation.
+- `src/types.ts` imports shared fields from `types/runtime-api.d.ts` for the implementation
+  context, request configuration and result, and adds only private utilities/callback typing.
+- `types/artplayer-plugin-vast.d.ts` is the exact npm1.0.0 declaration compatibility surface.
+  `types/runtime-api.d.ts` is the accurate SDK/context/Promise source; runtime.d.ts/.d.cts
+  expose CJS types, while runtime.d.mts exposes native ESM types. All resolve to the same
+  runtime artifacts. CJS declarations intentionally duplicate a small export facade;
+  changes must keep runtime.d.ts and runtime.d.cts identical.
 
 Dependency direction is entry -> session -> SDK/view/types. The session passes the
 original `art` through the callback for compatibility; only template elements are
@@ -36,7 +41,7 @@ secondary cleanup failures are logged without replacing the original error.
 Explicit plugin `destroy()` releases the current ad session, resets active-ad state,
 and permits a later `init`/`playUrl`/`playRes` while the core remains alive. Core destroy
 and failed attachment are terminal: request methods are inert and `init()` returns
-null. Public declaration accuracy for this invalid-lifetime case belongs to04.
+null. The accurate runtime declaration includes that terminal null result.
 
 Each session has an owner identity. Its callbacks verify that identity and core
 liveness before changing visibility. Cleanup detaches the current owner and clears
@@ -73,7 +78,8 @@ resource ownership. Never use a retained disposed SDK as an active session.
 Both modes retain void request methods, async registration and SDK/callback rejection.
 The old `require(...).default(...)` call and current callable export remain available;
 this does not recreate the old namespace object's reflection shape. Contradictory
-public return declarations and the new second-argument declaration remain task04.
+historical return declarations remain unchanged at the root; `/runtime` supplies the
+accurate Promise, both mode-specific contexts and the second argument.
 See [the accepted decision](../../refactor/vast-compatibility-decision.md).
 
 Overlay IDs use the historical `art-` default prefix or `art-vast-` workspace prefix,
@@ -103,9 +109,17 @@ import, using an already destroyed host to verify registration without loading a
 Set `ARTPLAYER_VAST_ARTIFACT` and `ARTPLAYER_VAST_ESM_ARTIFACT` to test actual build
 files; otherwise it builds source via the repository helper. The live alias path
 uses the controlled SDK in `test/vast.test.js` and the browser registration case.
-Public alias declarations and complete installed entry validation remain04/06.
+Accurate alias types are exposed only by `/runtime`; the root remains a pure historical
+factory type. Installed root/legacy/runtime imports and strict SDK type dependency
+resolution are checked by `yarn test:vast-types-package`. This does not replace task06's
+complete browser/distribution acceptance.
 
 For state or cleanup changes start in session, for callback timing in entry, and for
 SDK request fields in sdk. Keep Node candidate assertions, historical observations,
 browser counterparts and [test maintenance](../../refactor/vast-validation.md) aligned.
-Actual IMA/media/device validation remains05, public types04, and full distribution06.
+`yarn test:vast-types` verifies unchanged root bytes, historical type conflicts, negative
+runtime consumers and editor generation in TS5.9.3/4.3.5. `yarn build:ts artplayer-plugin-vast`
+regenerates the root-compatible editor global. Frozen workspace editor tests continue to
+exercise the SDK declaration bundler; they are labelled historical. Public migration
+is documented in [the accepted type decision](../../refactor/vast-type-decision.md).
+Actual IMA/media/device validation remains05 and full distribution06.

packages/artplayer-plugin-vast/README.md

@@ -25,8 +25,40 @@ artplayerPluginVast((context) => {
 The callback may be asynchronous. Core destruction releases the ad session and prevents
 later requests or recreation. Explicit plugin `destroy()` allows a new ad session while
 the core is alive. See the architecture guide for mode-specific fields and defaults.
-Public TypeScript declarations for the second argument are still being reconciled in
-PKG-VAST-04; these are JavaScript usage examples, not completed declaration acceptance.
+## TypeScript
+
+The root and `/legacy` declarations preserve npm 1.0.0's historical factory shape,
+including its required callback, `any` SDK fields and inaccurate synchronous result.
+Registration has always been asynchronous: await it even when using the old declarations.
+
+Use `/runtime` for accurate SDK types, Promise results, optional callbacks and the
+compatibility option. This entry uses the same JavaScript implementation:
+
+```ts
+import vast from 'artplayer-plugin-vast/runtime'
+
+vast(({ imaPlayer }) => {
+  // The default mode allocates this player before the callback.
+  imaPlayer.addEventListener('AdStarted', onAdStarted)
+})
+
+vast((context) => {
+  context.playerOptions.autoResize = false
+  context.init()?.addEventListener('AdStarted', onAdStarted)
+}, { compatibility: 'workspace-1.2' })
+```
+
+Code using unpublished workspace types should move its imports to `/runtime` as well.
+`ArtplayerPluginVastOption` describes the workspace callback; `ArtplayerPluginVastInstance`
+describes the awaited result with `destroy()`. A workspace resource getter can be null,
+and `init()` returns null after core destruction. Default data fields retain the last
+allocation after release; retaining their values does not keep that allocation alive.
+
+CommonJS TypeScript without interop can use
+`import vast = require('artplayer-plugin-vast/runtime')`. Both `vast` and `vast.default`
+are typed there. The old root declaration intentionally keeps its original factory
+type without adding a required `.default` member, so plain replacement functions and
+historical `Parameters`/`ReturnType` extraction remain compatible.
 
 ## Maintenance
 

packages/artplayer-plugin-vast/package.json

@@ -27,6 +27,16 @@
       "types": "./types/artplayer-plugin-vast.d.ts",
       "import": "./dist/artplayer-plugin-vast.legacy.js",
       "require": "./dist/artplayer-plugin-vast.legacy.js"
+    },
+    "./runtime": {
+      "import": {
+        "types": "./types/runtime.d.mts",
+        "default": "./dist/artplayer-plugin-vast.mjs"
+      },
+      "require": {
+        "types": "./types/runtime.d.cts",
+        "default": "./dist/artplayer-plugin-vast.js"
+      }
     }
   },
   "main": "./dist/artplayer-plugin-vast.js",
@@ -37,5 +47,15 @@
   "dependencies": {
     "@alugha/ima": "2.1.0",
     "@glomex/vast-ima-player": "^1.21.2"
+  },
+  "typesVersions": {
+    "*": {
+      "legacy": [
+        "types/artplayer-plugin-vast.d.ts"
+      ],
+      "runtime": [
+        "types/runtime.d.ts"
+      ]
+    }
   }
 }

packages/artplayer-plugin-vast/src/types.ts

@@ -1,30 +1,6 @@
-import type { google, ImaSdk } from '@alugha/ima'
-import type { Player, PlayerOptions } from '@glomex/vast-ima-player'
 import type Artplayer from 'artplayer'
+import type { WorkspaceContext } from '../types/runtime-api.js'
 
 export type Utilities = Pick<typeof Artplayer.utils, 'createElement' | 'setStyles'>
-export type RequestConfig = Record<string, unknown>
-
-export interface CompatibilityOptions {
-  compatibility?: 'workspace-1.2'
-}
-
-export interface Context {
-  art: Artplayer
-  playUrl: (url: string, config?: RequestConfig) => void
-  playRes: (response: string, config?: RequestConfig) => void
-  init: () => Player | null
-  ima: ImaSdk
-  adsRenderingSettings: google.ima.AdsRenderingSettings
-  playerOptions: PlayerOptions
-  readonly imaPlayer: Player | null
-  readonly id: string | null
-  readonly $container: HTMLDivElement | null
-  readonly container: HTMLDivElement | null
-}
-
-export type Callback = (context: Context) => unknown
-export interface Result {
-  name: 'artplayerPluginVast'
-  destroy: () => void
-}
+export type { CompatibilityOptions, WorkspaceContext as Context, RequestConfig, RuntimeResult as Result } from '../types/runtime-api.js'
+export type Callback = (context: WorkspaceContext) => unknown

packages/artplayer-plugin-vast/types/artplayer-plugin-vast.d.ts

@@ -1,36 +1,20 @@
-import type { Player, PlayerOptions } from '@glomex/vast-ima-player'
-import type Artplayer from 'artplayer'
+import type Artplayer from 'artplayer';
 
-declare global {
-  interface Window {
-    artplayerPluginVast?: typeof artplayerPluginVast
-  }
-}
+export = artplayerPluginVast;
+export as namespace artplayerPluginVast;
 
-type PlayUrlFn = (url: string, config?: any) => void
-type PlayResFn = (res: string, config?: any) => void
+type Option = (params: {
+    art: Artplayer;
+    id: string;
+    ima: any;
+    imaPlayer: any;
+    $container: HTMLDivElement;
+    playUrl: (url: string) => void;
+    playRes: (res: string) => void;
+}) => void;
 
-interface VastPluginContext {
-  art: Artplayer
-  ima: any
-  imaPlayer: Player | null
-  playUrl: PlayUrlFn
-  playRes: PlayResFn
-  init: () => Player
-  adsRenderingSettings: any
-  playerOptions: PlayerOptions
-  container: HTMLDivElement | null
-}
+type Result = {
+    name: 'artplayerPluginVast';
+};
 
-export type ArtplayerPluginVastOption = (params: VastPluginContext) => void | Promise<void>
-
-export interface ArtplayerPluginVastInstance {
-  name: 'artplayerPluginVast'
-  destroy?: () => void
-}
-
-declare function artplayerPluginVast(
-  option: ArtplayerPluginVastOption,
-): (art: Artplayer) => ArtplayerPluginVastInstance
-
-export default artplayerPluginVast
+declare const artplayerPluginVast: (option: Option) => (art: Artplayer) => Result;

packages/artplayer-plugin-vast/types/runtime-api.d.ts

@@ -0,0 +1,54 @@
+import type { google, ImaSdk } from '@alugha/ima'
+import type { Player, PlayerOptions } from '@glomex/vast-ima-player'
+import type Artplayer from 'artplayer'
+
+export type RequestConfig = Record<string, unknown>
+
+export interface CompatibilityOptions {
+  compatibility?: 'workspace-1.2'
+}
+
+export interface Context {
+  art: Artplayer
+  ima: ImaSdk
+  adsRenderingSettings: google.ima.AdsRenderingSettings
+  playerOptions: PlayerOptions
+  playUrl: (url: string, config?: RequestConfig) => void
+  playRes: (response: string, config?: RequestConfig) => void
+  init: () => Player | null
+  readonly container: HTMLDivElement | null
+}
+
+/** Published data fields retain their last allocation after release. */
+export interface PublishedContext extends Context {
+  imaPlayer: Player
+  id: string
+  $container: HTMLDivElement
+}
+
+/** Resource getters are null before initialization and after release. */
+export interface WorkspaceContext extends Context {
+  readonly imaPlayer: Player | null
+  readonly id: string | null
+  readonly $container: HTMLDivElement | null
+}
+
+export type RuntimeContext = PublishedContext | WorkspaceContext
+export type RuntimeCallback<T extends RuntimeContext = RuntimeContext> = (context: T) => unknown
+
+export interface RuntimeResult {
+  name: 'artplayerPluginVast'
+  destroy: () => void
+}
+
+export type Registration = (art: Artplayer) => Promise<RuntimeResult>
+
+export interface RuntimeFactory {
+  (callback?: RuntimeCallback<PublishedContext>, options?: { compatibility?: undefined }): Registration
+  (callback: RuntimeCallback<WorkspaceContext> | undefined, options: { compatibility: 'workspace-1.2' }): Registration
+  (callback: RuntimeCallback | undefined, options: CompatibilityOptions): Registration
+  default: RuntimeFactory
+}
+
+export type ArtplayerPluginVastOption = RuntimeCallback<WorkspaceContext>
+export type ArtplayerPluginVastInstance = RuntimeResult

packages/artplayer-plugin-vast/types/runtime.d.cts

@@ -0,0 +1,19 @@
+import type { RuntimeFactory } from './runtime-api.js'
+
+declare const artplayerPluginVast: RuntimeFactory
+// eslint-disable-next-line ts/no-redeclare -- Ambient merge exposes types on the CommonJS factory.
+declare namespace artplayerPluginVast {
+  type ArtplayerPluginVastInstance = import('./runtime-api.js').ArtplayerPluginVastInstance
+  type ArtplayerPluginVastOption = import('./runtime-api.js').ArtplayerPluginVastOption
+  type CompatibilityOptions = import('./runtime-api.js').CompatibilityOptions
+  type Context = import('./runtime-api.js').Context
+  type PublishedContext = import('./runtime-api.js').PublishedContext
+  type Registration = import('./runtime-api.js').Registration
+  type RequestConfig = import('./runtime-api.js').RequestConfig
+  type RuntimeCallback<T extends RuntimeContext = RuntimeContext> = import('./runtime-api.js').RuntimeCallback<T>
+  type RuntimeContext = import('./runtime-api.js').RuntimeContext
+  type RuntimeFactory = import('./runtime-api.js').RuntimeFactory
+  type RuntimeResult = import('./runtime-api.js').RuntimeResult
+  type WorkspaceContext = import('./runtime-api.js').WorkspaceContext
+}
+export = artplayerPluginVast

packages/artplayer-plugin-vast/types/runtime.d.mts

@@ -0,0 +1,5 @@
+import type { RuntimeFactory } from './runtime-api.js'
+
+declare const artplayerPluginVast: RuntimeFactory
+export default artplayerPluginVast
+export type { ArtplayerPluginVastInstance, ArtplayerPluginVastOption, CompatibilityOptions, Context, PublishedContext, Registration, RequestConfig, RuntimeCallback, RuntimeContext, RuntimeFactory, RuntimeResult, WorkspaceContext } from './runtime-api.js'

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

@@ -0,0 +1,19 @@
+import type { RuntimeFactory } from './runtime-api.js'
+
+declare const artplayerPluginVast: RuntimeFactory
+// eslint-disable-next-line ts/no-redeclare -- Ambient merge exposes types on the CommonJS factory.
+declare namespace artplayerPluginVast {
+  type ArtplayerPluginVastInstance = import('./runtime-api.js').ArtplayerPluginVastInstance
+  type ArtplayerPluginVastOption = import('./runtime-api.js').ArtplayerPluginVastOption
+  type CompatibilityOptions = import('./runtime-api.js').CompatibilityOptions
+  type Context = import('./runtime-api.js').Context
+  type PublishedContext = import('./runtime-api.js').PublishedContext
+  type Registration = import('./runtime-api.js').Registration
+  type RequestConfig = import('./runtime-api.js').RequestConfig
+  type RuntimeCallback<T extends RuntimeContext = RuntimeContext> = import('./runtime-api.js').RuntimeCallback<T>
+  type RuntimeContext = import('./runtime-api.js').RuntimeContext
+  type RuntimeFactory = import('./runtime-api.js').RuntimeFactory
+  type RuntimeResult = import('./runtime-api.js').RuntimeResult
+  type WorkspaceContext = import('./runtime-api.js').WorkspaceContext
+}
+export = artplayerPluginVast