feat(auto-thumbnail): [PKG-AUTO-THUMB-08] add compatible runtime type entry

packages/artplayer-plugin-auto-thumbnail/ARCHITECTURE.md

@@ -46,7 +46,17 @@ for video processing.
   cleanup handles every frame without accumulating per-frame cleanup closures.
 - `src/types.ts` defines internal configuration, sheet data, the minimal host and
   guarded extraction-job callbacks. `guard` retains argument/result types and the
-  inactive undefined result. No public declarations are generated from this file.
+  inactive undefined result. It shares the opt-in `runtime-api.d.ts` option type;
+  the entry's Promise result is checked against that public result. No public
+  declarations are generated from this file.
+
+The original `types/artplayer-plugin-auto-thumbnail.d.ts` remains byte-equivalent
+to npm 1.1.0 after newline normalization. `types/runtime-api.d.ts` owns the precise
+option/result/factory contracts; `runtime.d.mts`, `runtime.d.cts`, and `runtime.d.ts`
+adapt module resolution without adding runtime code or a factory `.default` alias.
+The root editor declaration is generated semantically by `yarn build:ts`; its
+historical synchronous callable shape is retained, without mixing default and
+export-assignment syntax. See README for the optional accurate import.
 
 Only the entry module receives ArtPlayer. Extraction receives a guarded job and a
 configuration snapshot. These internal modules do not add public player fields,
@@ -90,6 +100,8 @@ Use the root Yarn toolchain:
 
 ```sh
 yarn test:auto-thumbnail
+yarn test:auto-thumbnail-types
+yarn test:auto-thumbnail-types-package
 yarn exec tsc -p packages/artplayer-plugin-auto-thumbnail/tsconfig.json --noEmit
 yarn test:browser test/browser/auto-thumbnail-lifecycle.spec.js
 yarn test:browser test/browser/auto-thumbnail-pixels.spec.js
@@ -101,7 +113,10 @@ regression tests. `ARTPLAYER_AUTO_THUMBNAIL_ARTIFACT` selects an actual bundle.
 Historical contract/failure tests remain separate and continue to reproduce old
 defects; their passing status does not mean those defects should remain.
 
-This is an intermediate `PKG-AUTO-THUMB-03` implementation. Native lifecycle
+The public type entry is tracked independently as `PKG-AUTO-THUMB-08`, split from
+04 so that declaration work can proceed without weakening the unfinished 03
+pixel gate. Task04 still depends on both 03 and 08. The source/runtime remains an
+intermediate `PKG-AUTO-THUMB-03` implementation. Native lifecycle
 validation does not prove correct pixels. The attached renderer now has native
 pixel checks for all five cells when native frame callbacks are available,
 including the unique first frame, real black content, changing colors, spatial

packages/artplayer-plugin-auto-thumbnail/README.md

@@ -9,3 +9,49 @@ Auto thumbnail plugin for ArtPlayer
 ## License
 
 MIT © Harvey Zhao
+
+## TypeScript
+
+The root and `/legacy` entries retain the declarations published in 1.1.0,
+including the historical synchronous result type. The implementation actually
+returns a Promise when registering the plugin. For accurate types, opt into
+`/runtime`, which uses the same JavaScript implementation:
+
+```ts
+import Artplayer from 'artplayer'
+import autoThumbnail from 'artplayer-plugin-auto-thumbnail/runtime'
+import type { Option, Result } from 'artplayer-plugin-auto-thumbnail/runtime'
+
+const option: Option = { width: 160, number: 100, scale: 1 }
+const art = new Artplayer({
+  container: '#player',
+  url: '/video.mp4',
+  plugins: [autoThumbnail(option)],
+})
+```
+
+The registrar has type `(art: Artplayer) => Promise<Result>`. It resolves with
+`{ name: 'artplayerPluginAutoThumbnail' }` after subscribing to player events,
+before extraction completes. Generated sheets arrive progressively through the
+player's thumbnails configuration. Awaiting registration does not wait for them.
+The options object is required; use `{}` for defaults. `height` is accepted by
+the runtime type for historical callers but remains ignored: the video aspect
+ratio determines sheet height. Numeric strings retain their old JavaScript
+coercion behavior but are not advertised as numeric TypeScript options.
+
+The runtime entry supports default ESM imports and CommonJS
+`import autoThumbnail = require('artplayer-plugin-auto-thumbnail/runtime')`.
+It exports the `Option`, `Result`, and `Factory` types. The factory has no
+`.default` self alias and the result has no extraction-completion or destroy API.
+Node10 resolution uses `typesVersions`; modern resolution uses separate ESM/CJS
+declarations. The old root's NodeNext namespace behavior is preserved; `/runtime`
+provides a direct default-import type without changing that old declaration.
+
+Versions 1.0.x used `export =` declarations and advertised `height` instead of
+`number`; 1.1.0 had already changed these types. This refactor retains the actual
+1.1.0 root declaration rather than introducing another conflicting root shape.
+Consumers needing the older ignored `height` option can use `/runtime`.
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for module ownership, tests, and remaining
+browser extraction limitations. This type entry does not resolve the documented
+Windows WebKit first-frame issue.

packages/artplayer-plugin-auto-thumbnail/package.json

@@ -27,11 +27,31 @@
       "types": "./types/artplayer-plugin-auto-thumbnail.d.ts",
       "import": "./dist/artplayer-plugin-auto-thumbnail.legacy.js",
       "require": "./dist/artplayer-plugin-auto-thumbnail.legacy.js"
+    },
+    "./runtime": {
+      "import": {
+        "types": "./types/runtime.d.mts",
+        "default": "./dist/artplayer-plugin-auto-thumbnail.mjs"
+      },
+      "require": {
+        "types": "./types/runtime.d.cts",
+        "default": "./dist/artplayer-plugin-auto-thumbnail.js"
+      }
     }
   },
   "main": "./dist/artplayer-plugin-auto-thumbnail.js",
   "module": "./dist/artplayer-plugin-auto-thumbnail.mjs",
   "types": "./types/artplayer-plugin-auto-thumbnail.d.ts",
   "legacy": "./dist/artplayer-plugin-auto-thumbnail.legacy.js",
-  "browserslist": "last 1 Chrome version"
+  "browserslist": "last 1 Chrome version",
+  "typesVersions": {
+    "*": {
+      "legacy": [
+        "types/artplayer-plugin-auto-thumbnail.d.ts"
+      ],
+      "runtime": [
+        "types/runtime.d.ts"
+      ]
+    }
+  }
 }

packages/artplayer-plugin-auto-thumbnail/src/index.ts

@@ -1,10 +1,11 @@
+import type { Result } from '../types/runtime-api'
 import type { Cleanup, ThumbnailHost, ThumbnailOptions } from './types'
 import extract from './extraction'
 import { readOptions } from './options'
 import createSession, { cleanupAll } from './session'
 
 export default function artplayerPluginAutoThumbnail(option: ThumbnailOptions) {
-  return async (art: ThumbnailHost) => {
+  return async (art: ThumbnailHost): Promise<Result> => {
     const report = (error: unknown) => console.warn('ArtPlayer auto-thumbnail failed:', error)
     const session = createSession((config) => {
       art.thumbnails = config

packages/artplayer-plugin-auto-thumbnail/src/types.ts

@@ -1,11 +1,5 @@
-// Internal contracts only. Public declarations retain their historical entrypoint.
-export interface ThumbnailOptions {
-  url?: string
-  width?: number
-  number?: number
-  scale?: number
-  height?: number
-}
+// Root declarations retain their historical shape; the opt-in runtime view is shared.
+export type { Option as ThumbnailOptions } from '../types/runtime-api'
 
 export interface ExtractionConfig {
   url: string

packages/artplayer-plugin-auto-thumbnail/types/runtime-api.d.ts

@@ -0,0 +1,21 @@
+// Support both the core's ESM/default and CommonJS export= declarations.
+type CoreModule = typeof import('artplayer')
+type Artplayer = CoreModule extends { default: { prototype: infer Instance } }
+  ? Instance
+  : CoreModule extends { prototype: infer Instance } ? Instance : never
+
+export interface Option {
+  url?: string
+  width?: number
+  number?: number
+  scale?: number
+  /** Historical option; sheet height is derived from the video's aspect ratio. */
+  height?: number
+}
+
+export interface Result {
+  name: 'artplayerPluginAutoThumbnail'
+}
+
+/** Registration resolves before frame extraction and progressive sheet updates. */
+export type Factory = (option: Option) => (art: Artplayer) => Promise<Result>

packages/artplayer-plugin-auto-thumbnail/types/runtime.d.cts

@@ -0,0 +1,10 @@
+import type { Factory } from './runtime-api.js'
+
+declare const artplayerPluginAutoThumbnail: Factory
+// eslint-disable-next-line ts/no-redeclare -- Ambient merge exposes types on the CommonJS factory.
+declare namespace artplayerPluginAutoThumbnail {
+  type Option = import('./runtime-api.js').Option
+  type Result = import('./runtime-api.js').Result
+  type Factory = import('./runtime-api.js').Factory
+}
+export = artplayerPluginAutoThumbnail

packages/artplayer-plugin-auto-thumbnail/types/runtime.d.mts

@@ -0,0 +1,5 @@
+import type { Factory } from './runtime-api.js'
+
+declare const artplayerPluginAutoThumbnail: Factory
+export default artplayerPluginAutoThumbnail
+export type { Factory, Option, Result } from './runtime-api.js'

packages/artplayer-plugin-auto-thumbnail/types/runtime.d.ts

@@ -0,0 +1,10 @@
+import type { Factory } from './runtime-api.js'
+
+declare const artplayerPluginAutoThumbnail: Factory
+// eslint-disable-next-line ts/no-redeclare -- Ambient merge exposes types on the CommonJS factory.
+declare namespace artplayerPluginAutoThumbnail {
+  type Option = import('./runtime-api.js').Option
+  type Result = import('./runtime-api.js').Result
+  type Factory = import('./runtime-api.js').Factory
+}
+export = artplayerPluginAutoThumbnail