refactor(ambilight): [PKG-AMBILIGHT-04] preserve published types and dual CommonJS exports

packages/artplayer-plugin-ambilight/types/artplayer-plugin-ambilight.d.cts

@@ -0,0 +1,4 @@
+// eslint-disable-next-line ts/no-require-imports -- Preserve the CommonJS export-assignment namespace.
+import artplayerPluginAmbilight = require('./artplayer-plugin-ambilight.js')
+
+export = artplayerPluginAmbilight

packages/artplayer-plugin-ambilight/types/artplayer-plugin-ambilight.d.mts

@@ -0,0 +1,2 @@
+export { default } from './artplayer-plugin-ambilight.js'
+export type { Callable, Factory, Option, Result } from './artplayer-plugin-ambilight.js'

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

@@ -1,19 +1,40 @@
+/* eslint-disable ts/no-redeclare -- Callable and public type namespace intentionally merge. */
 import type Artplayer from 'artplayer'
 
-interface Option {
-  blur?: string
-  opacity?: number
-  frequency?: number
-  zIndex?: number
-  duration?: number
+declare namespace artplayerPluginAmbilight {
+  interface Option {
+    /** CSS blur radius. @default '50px' */
+    blur?: string
+    /** Grid cell opacity. @default 0.5 */
+    opacity?: number
+    /** Maximum sampling frequency in frames per second. @default 10 */
+    frequency?: number
+    /** Historical input retained for compatibility; runtime uses a fixed z-index of 9. */
+    zIndex?: number
+    /** Background color transition duration in seconds. @default 0.3 */
+    duration?: number
+  }
+
+  interface Result {
+    name: 'artplayerPluginAmbilight'
+    /** Start sampling; does nothing after the player is destroyed. */
+    start: () => void
+    /** Stop sampling while retaining the last colors. */
+    stop: () => void
+  }
+
+  interface Callable {
+    (option?: Option): (art: Artplayer) => Result
+    /** Keep Parameters extraction identical to the published 1.1.0 signature. */
+    (option: Option): (art: Artplayer) => Result
+  }
+
+  interface Factory extends Callable {
+    /** Same function, including historical require(package).default calls. */
+    readonly default: Factory
+  }
 }
 
-interface Result {
-  name: 'artplayerPluginAmbilight'
-  start: () => void
-  stop: () => void
-}
-
-declare const artplayerPluginAmbilight: (option: Option) => (art: Artplayer) => Result
-
-export default artplayerPluginAmbilight
+declare const artplayerPluginAmbilight: artplayerPluginAmbilight.Factory
+export = artplayerPluginAmbilight
+export as namespace artplayerPluginAmbilight