refactor(ads): [PKG-ADS-04] reconcile public types and historical imports

packages/artplayer-plugin-ads/README.md

@@ -5,6 +5,57 @@ Ads plugin for ArtPlayer
 Implementation, resource ownership and regression commands:
 [maintenance guide](ARCHITECTURE.md).
 
+## Usage and TypeScript
+
+```ts
+import Artplayer from 'artplayer'
+import ads from 'artplayer-plugin-ads'
+
+new Artplayer({
+  container: '#player',
+  url: '/content.mp4',
+  plugins: [ads({ video: '/advertisement.mp4', url: '/details', playDuration: 5, totalDuration: 10 })],
+})
+```
+
+Use `html` for HTML or an image element string. When both are present, `video` takes
+precedence. `playDuration` controls when closing is allowed; `totalDuration` controls
+the countdown. Durations are numeric seconds. Plugin `play()` and `pause()` control
+only the countdown; `skip()` completes the advertisement once. All three return void.
+
+For accurate options without historical declaration mistakes, import the same runtime
+from `artplayer-plugin-ads/runtime`. Root and `/legacy` retain old input acceptance:
+the old `totalDuration: string` declaration compiles but strings still fail runtime
+validation; old workspace `source/type` fields are ignored. Use `video` or `html`.
+An `i18n` object must supply `close`, `countdown`, `detail` and `canBeClosed` together.
+
+CommonJS supports both `require('artplayer-plugin-ads')(options)` and
+`require('artplayer-plugin-ads').default(options)`. ESM uses the default export.
+## Migrating inferred option types
+
+The maintainer approved correcting conflicting historical inference on 2026-09-12.
+Existing option calls remain accepted, but `Parameters<typeof ads>[0].totalDuration`
+now reads as `number | string | undefined`; historical workspace `source/type` are
+optional. Code that assumed only one old declaration's field types may need adjustment.
+This does not make string durations or source/type runtime aliases valid.
+
+Prefer accurate options for new or migrated code:
+
+```ts
+import type { Option } from 'artplayer-plugin-ads'
+import ads from 'artplayer-plugin-ads/runtime'
+
+const option: Option = { video: '/advertisement.mp4', totalDuration: 10 }
+const duration: number | undefined = option.totalDuration
+const plugin = ads(option)
+```
+
+For a generic wrapper receiving historical input, narrow `totalDuration` before numeric
+operations and check `source/type` before reading them as required fields. Do not use a
+cast to hide string durations: the runtime validator rejects them. `LegacyOption` and
+`WorkspaceOption` remain available for code explicitly representing those historical
+declarations; `Option` describes the implemented configuration.
+
 ## Demo
 
 [https://artplayer.org](https://artplayer.org/?libs=./uncompiled/artplayer-plugin-ads/index.js&example=ads)