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

packages/artplayer-plugin-ambilight/ARCHITECTURE.md

@@ -2,7 +2,8 @@
 
 Read the frozen published contracts in `refactor/baselines/ambilight-contract.md`
 before changing the public factory or distribution. Source is strict TypeScript;
-the existing public declaration remains the input contract until task 04.
+`types/artplayer-plugin-ambilight.d.ts` owns the public options and result contract.
+The runtime derives its option type from that declaration; do not duplicate it.
 
 | Module | Responsibility |
 | --- | --- |
@@ -42,5 +43,22 @@ and `yarn test:browser test/browser/ambilight-lifecycle.spec.js`. Historical tes
 in `test/ambilight.test.js` and `test/browser/ambilight.spec.js` intentionally retain
 the old failures. Candidate tests must remain separate. The browser suite runs real
 video/canvas with a lexical native RAF observer across published cores 5.1.7/5.4.0
-and candidate core in Chromium/Firefox/WebKit. Proxy/device, packed consumer and
-public type acceptance remain tasks 04-06; see `refactor/ambilight-validation.md`.
+and candidate core in Chromium/Firefox/WebKit. Proxy/device and complete packed
+browser/demo acceptance remain tasks 05-06; see `refactor/ambilight-validation.md`.
+
+Public types merge a callable value with a type-only namespace. An optional first
+overload permits omitted/undefined options; the required final overload preserves
+the published 1.1.0 `Parameters` extraction. Do not reorder these signatures. The
+runtime factory has a self-referencing `default` property to support both historical
+CommonJS forms. `.d.mts`/`.d.cts` forward to the same declaration for the actual ESM/
+CommonJS entry kinds; `typesVersions` supplies `/legacy` to older resolvers. The
+editor global is generated by `yarn build:ts` through the semantic plugin generator.
+
+Run `node --test refactor/scripts/ambilight-types.test.mjs` for public/editor/format
+contracts and `yarn test:ambilight-types-package` for offline tarball installations
+outside the workspace. The latter verifies two actual published plugin archives and
+candidate against the same packed candidate core, five compiler modes plus two
+candidate modes with interop disabled, and ten negative uses. Published 1.1.0 fails
+NodeNext ESM with its old declarations; candidate must not inherit that failure.
+Published 1.0.0 required all option fields; 1.1.0 already made them optional. Current
+inference follows 1.1.0 while retaining valid calls from both generations.