fix(types): [PKG-FACTORY-01] preserve published factory compatibility

packages/artplayer-plugin-ambilight/README.md

@@ -20,11 +20,44 @@ const option: Option = { blur: '50px', opacity: 0.5, frequency: 10, duration: 0.
 const plugins = [artplayerPluginAmbilight(option)]
 ```
 
-Options can be omitted. `require('artplayer-plugin-ambilight')` and the historical
-`require('artplayer-plugin-ambilight').default` refer to the same factory. The
-`/legacy` entry remains available. The historical `zIndex` input is accepted but
-ignored; the grid uses 9. Option fields stay optional as in version 1.1.0; code
-extracting their types should account for `undefined`.
+Root and `/legacy` types preserve the latest published 1.1.0 contract: the options
+argument is required, its fields are optional, and an ordinary replacement factory
+does not need a `default` property. Pass `{}` to use defaults with these types.
+The historical `zIndex` input is accepted but ignored; the grid uses 9.
+
+For accurate optional invocation and module interop, use `/runtime`:
+
+```ts
+import ambilight from 'artplayer-plugin-ambilight/runtime'
+
+const plugins = [ambilight(), ambilight(undefined), ambilight.default({})]
+```
+
+It reuses the root implementation. Existing JavaScript calls with omitted options,
+`require('artplayer-plugin-ambilight')` and
+`require('artplayer-plugin-ambilight').default` still work. Start/stop remain
+synchronous and `/legacy` keeps the historical build.
+
+### Earlier TypeScript declarations
+
+Version 1.0.0 used `export =` and required every option field; 1.1.0 changed to a
+default export and optional fields. The root follows 1.1.0 rather than combining
+incompatible factory signatures. Earlier TypeScript `import = require` callers
+can switch only their module path:
+
+```ts
+import ambilight = require('artplayer-plugin-ambilight/runtime')
+
+ambilight({ blur: '50px', opacity: 0.5, frequency: 10, zIndex: 9, duration: 0.3 })
+```
+
+Code reading an option field as a required value should supply a fallback, for
+example `option.blur ?? '50px'`. This optional-field change already existed in
+1.1.0. NodeNext ESM sees the historical root declaration as a CommonJS namespace;
+that type shape is preserved, including its previous direct-call diagnostics.
+Use `/runtime` for an accurate callable default import in native ESM. Node10
+TypeScript default imports of `/runtime` require `esModuleInterop`; `import =
+require` also works with interop disabled. The runtime does not add any dependency.
 
 ## Demo