docs(site): [SITE-04] cross-check existing plugin guide semantics

docs/llms.txt

@@ -5079,6 +5079,8 @@ Named types include `Option`, `UpdateOption`, the old `Result`, `RuntimeResult`
 
 Actual desktop tests cover audio/video playback, pause, seeking, updates and destruction. They do not establish support for every mobile device, proxy player, audio format or long-running synchronization combination. Check browser decoding capabilities and the project's validation records for the applicable scope.
 
+Windows WebKit MP4/AAC starvation remains an open native-media validation issue: a stalled video does not reliably emit waiting in that reproduction. Passing source-switch ordering checks does not close that separate case.
+
 
 ===== packages/artplayer-vitepress/docs/en/plugin/auto-thumbnail.md =====
 
@@ -5548,7 +5550,7 @@ https://unpkg.com/artplayer-plugin-danmuku/dist/artplayer-plugin-danmuku.js
 
 ## Comment structure
 
-Only `text` is required. Leading and trailing whitespace is removed; empty comments are ignored.
+Only `text` is required. Empty or whitespace-only comments are ignored. Direct `emit()` and loaded rows retain the original text, including surrounding spaces; only the input panel trims its submitted text.
 
 ```js
 ({
@@ -5563,6 +5565,8 @@ Only `text` is required. Leading and trailing whitespace is removed; empty comme
 
 Explicit `time: 0` is preserved. Negative times are clamped to zero. Other than 0, 1 and 2, comment modes are ignored.
 
+Normalization fills time, mode, color and style on the supplied object before calling `filter`. The queue then receives a shallow copy; its style object is still shared. Copy reusable inputs when these mutations matter. The optional string `id` becomes the displayed element's `data-id`; it does not deduplicate comments. Text is rendered through `textContent`, not as HTML.
+
 ## All options
 
 Pass an option object to the factory. At runtime, `{}` is valid and all fields have defaults.
@@ -5601,7 +5605,7 @@ The historical root declarations still require `danmuku`; existing TypeScript pr
 ```
 
 `OPACITY`, `FONT_SIZE`, `MARGIN` and `SPEED` override slider definitions with `min`, `max` and `steps`.
-Each step can contain `name`, `value`, `hide` and `show`; margin values are pairs such as `[10, '50%']`.
+Each step can contain `name`, `value`, `hide` and `show`. `hide` suppresses its label; the retained `show` field is not read by the renderer. Margin values are pairs such as `[10, '50%']`.
 `COLOR` replaces the palette with an array of CSS color strings; an empty array uses the built-in palette.
 
 ## Array, XML and asynchronous input
@@ -5796,6 +5800,10 @@ Use `$ref.textContent` when adding text in a `visible` handler.
 
 ## TypeScript
 
+The `/runtime` `Owner` type describes the internal return object for existing advanced integrations. Its `art`, `option`, `queue` and `states` are live objects; `readys` is the current candidate list. `speed`, `fontSize`, `marginTop/marginBottom` and `isRotate` are computed views. Do not mutate queue state to simulate public commands.
+
+Owner's additional `start/stop` methods control comment scheduling and emit their events; `continue/suspend` resume or pause existing displayed items; `update` schedules work. These methods synchronously return Owner and do not control video playback. `resize` adjusts displayed items, while `seek` cancels old display preparation and schedules again; both return `undefined`. Owner's `destroy` cleans scheduling, nodes and input tasks and emits its destroy event, but does not fully uninstall the settings panel and heatmap. Use `art.destroy()` for complete cleanup. These additional commands are absent from the registered result.
+
 The root and `/legacy` entrypoints keep the npm 5.3.0 declaration shapes for compatibility, including historical inaccuracies about return values.
 The current branch adds `/runtime` for accurate types while loading the same runtime factory:
 
@@ -5812,7 +5820,13 @@ art.on('artplayerPluginDanmuku:error', onError);
 ```
 
 The explicit `EventMap` describes payloads; it does not augment the core's historical event declarations automatically.
-The factory also exposes the existing `icons` object for customization. Package `README.md` and `ARCHITECTURE.md` describe module ownership, maintenance commands and remaining device/combination validation.
+The factory also exposes the existing `icons` object for customization.
+
+Root named types are `Mode`, `Danmuku`, `Slider`, `Danmu`, `Option` and `Result`. `/runtime` exposes `Mode`, `State`, `Margin`, `Point`, `Danmu`, `NormalizedDanmu`, `Item`, `Input`, `SliderStep`, `Slider`, `Heatmap`, `NormalizedOption`, `RuntimeOption`, `Owner`, `RuntimeResult`, `Icons`, `RuntimeFactory` and `EventMap`. `Item` adds `$state/$index/$ref/$restTime/$lastStartTime`; nodes are reused and `$ref` becomes null when recycled. A node received by a visible handler does not permanently belong to that comment.
+
+`icons` contains `$on/$off/$config/$style`, the three pairs `$mode_0_off/$mode_0_on` through `$mode_2_off/$mode_2_on`, and `$check_on/$check_off`. Applications can reuse these SVG strings in their own interfaces. The built-in panel reads bundled icons directly; changing the factory icons object does not replace its icons.
+
+Package `README.md` and `ARCHITECTURE.md` describe module ownership, maintenance commands and remaining device/combination validation.
 
 
 ===== packages/artplayer-vitepress/docs/en/plugin/dash-control.md =====
@@ -5844,7 +5858,7 @@ For script tags, load ArtPlayer, dash.js and `dist/artplayer-plugin-dash-control
 The example matches the [online DASH example](https://artplayer.org/?libs=https://cdnjs.cloudflare.com/ajax/libs/dashjs/5.2.1/modern/umd/dash.all.min.js%0A./uncompiled/artplayer-plugin-dash-control/index.js&example=dash.control). Replace the site's container and media URL in your application.
 
 <div className="run-code" data-libs="https://cdnjs.cloudflare.com/ajax/libs/dashjs/5.2.1/modern/umd/dash.all.min.js
-./uncompiled/artplayer-plugin-dash-control/index.js"></div>
+./uncompiled/artplayer-plugin-dash-control/index.js">▶ Run Code</div>
 
 ```js
 // npm i dashjs
@@ -5960,7 +5974,7 @@ art.plugins.artplayerPluginDashControl.update();
 
 Automatic refresh preserves an open, plugin-owned quality or audio settings panel. Explicit `update()` keeps its existing rebuild behavior. Reserve `dash-quality` and `dash-audio` for the plugin's menu names.
 
-If an asynchronous SDK getter or formatter fails, the plugin warns, stops that observation and clears its menus. Fix the formatter/SDK state and call `update()` to recover. Explicit update and synchronous selection errors keep their normal throwing behavior.
+If a synchronous SDK getter or formatter throws during an asynchronous refresh scheduled by an SDK event, the plugin warns, stops that observation and clears its menus. Fix the formatter/SDK state and call `update()` to recover. Getters and formatters must return synchronously; the plugin does not await their Promises. Explicit update and synchronous selection errors keep their normal throwing behavior.
 
 ## SDK ownership and source switching
 
@@ -5992,6 +6006,8 @@ const plugin = dashControl<Level, Track>({
 
 `Option`, `Config`, `QualityLevel`, `AudioTrack` and `Result` are exported from the root. Root and legacy paths remain available. If using actual SDK declarations, dash.js 4.5.2 exposes `BitrateInfo` for quality; 5.2.1 uses `Representation`. Its declarations have different compiler/module-resolution requirements, so test your actual SDK and TypeScript combination. Describe the externally attached `art.dash` in your application's integration types.
 
+The registered result contains only the fixed `name: 'artplayerPluginDashControl'` and `update()`. Ordinary factory calls may omit the options, while the last declaration overload keeps its parameter required: `Parameters<typeof dashControl>[0]` remains `Option`, without `undefined`. This package has no `/runtime` subpath or factory `.default` self-alias.
+
 ## Validation scope
 
 The refactor tests fixed dash.js 4.5.2 and 5.2.1 with local adaptive media and old/new core combinations. Those are tested points, not a new blanket support range. The plugin includes a targeted 4.5.2 paused-seek recovery for stale empty-buffer metrics while preserving the caller's SDK settings and media time. Windows Playwright WebKit lacks the MSE path used by these tests; it is not Safari/device playback acceptance. Test your own MPDs, DRM and target devices before adopting the unpublished refactor.
@@ -6125,7 +6141,7 @@ For script tags, load ArtPlayer, Hls.js and the plugin's `dist/artplayer-plugin-
 The example uses the site's player container and the same source as the [online HLS example](https://artplayer.org/?libs=https://cdnjs.cloudflare.com/ajax/libs/hls.js/1.5.17/hls.min.js%0A./uncompiled/artplayer-plugin-hls-control/index.js&example=hls.control). Replace the container and stream URL in your application.
 
 <div className="run-code" data-libs="https://cdnjs.cloudflare.com/ajax/libs/hls.js/1.5.17/hls.min.js
-./uncompiled/artplayer-plugin-hls-control/index.js"></div>
+./uncompiled/artplayer-plugin-hls-control/index.js">▶ Run Code</div>
 
 ```js
 // npm i hls.js
@@ -6260,6 +6276,8 @@ const plugin = hlsControl<Level, Track>({
 
 Public `Option`, `Config`, `QualityLevel`, `AudioTrack` and `Result` types are exported from the root entry. The root and legacy import paths remain available. The types do not pretend every ArtPlayer instance already owns an Hls.js engine; describe `art.hls` in your application's integration types.
 
+The registered result contains only the fixed `name: 'artplayerPluginHlsControl'` and `update()`. Ordinary factory calls may omit the options, while the last declaration overload keeps its parameter required: `Parameters<typeof hlsControl>[0]` remains `Option`, without `undefined`. This package has no `/runtime` subpath or factory `.default` self-alias.
+
 ## Validation scope
 
 The refactor tests Hls.js 1.5.17 and 1.7.2 with local media and real workers; these are tested points, not a newly declared supported range. Firefox grouped-stream crashes and a separate switching stall remain under investigation. Windows Playwright WebKit lacks the MSE path used in those tests; it does not establish Safari/iOS native-HLS acceptance. Verify your actual streams and target devices before adopting the unpublished refactor.
@@ -6809,6 +6827,8 @@ For historical compatibility, start and end times are rounded down to whole seco
 
 Desktop hover selects a cue using the progress percentage multiplied by the video duration. Gaps hide the preview, and previews near the edges are aligned inward. The mobile path responds to progress dragging with an input event and hides about 500ms after the last drag update. Desktop coverage does not establish real touch-device support.
 
+The selected position must be strictly inside the progress bar. Desktop progress at exactly 0 or 1 hides the preview. Those mobile endpoints do not draw a new preview, but an existing preview still hides on its timer. The plugin uses control name `vtt-thumbnail` and CSS class `art-control-thumbnails`; preserve these existing hooks.
+
 ## Asynchronous registration, errors and cleanup
 
 Registration fetches and parses the VTT and actually returns a Promise. Its success result contains only `name: 'artplayerPluginVttThumbnail'`. Installation through the constructor's plugins array is asynchronous; do not assume that the result is registered immediately after construction.