docs(core): [SITE-04] document template and icon contracts

packages/artplayer-vitepress/docs/advanced/built-in.md

@@ -47,6 +47,41 @@ console.info(art.template.$video);
 
 :::
 
+`$container` 是调用方提供的 div；`$player` 是里面生成的播放器根节点，二者不是同一个元素。以下字段保存初始化时绑定的节点引用，不是每次读取时重新查询：
+
+| 字段 | 默认选择器或来源 |
+| --- | --- |
+| `$container` | 传入的 div 容器 |
+| `$player` | `.art-video-player` |
+| `$video` | `.art-video` |
+| `$track` | `track` |
+| `$poster` | `.art-poster` |
+| `$subtitle` | `.art-subtitle` |
+| `$danmuku` | `.art-danmuku` |
+| `$bottom` | `.art-bottom` |
+| `$progress` | `.art-progress` |
+| `$controls` | `.art-controls` |
+| `$controlsLeft` | `.art-controls-left` |
+| `$controlsCenter` | `.art-controls-center` |
+| `$controlsRight` | `.art-controls-right` |
+| `$layer` | `.art-layers` |
+| `$loading` | `.art-loading` |
+| `$notice` | `.art-notice` |
+| `$noticeInner` | `.art-notice-inner` |
+| `$mask` | `.art-mask` |
+| `$state` | `.art-state` |
+| `$setting` | `.art-settings` |
+| `$info` | `.art-info` |
+| `$infoPanel` | `.art-info-panel` |
+| `$infoClose` | `.art-info-close` |
+| `$contextmenu` | `.art-contextmenus` |
+
+`art.query(selector)` 与 `art.template.query(selector)` 是同一个已绑定函数，可以单独取出调用。查询范围始终是原始 $container 的后代；不会包含容器本身，也不会跟随移到容器外的播放器/媒体节点。找不到时返回 null，非法选择器沿用 querySelector 的异常。`art.video` 返回当前缓存的 `template.$video`，使用代理时可能是 canvas。原 $track 可能随被替换的视频一起脱离 DOM，不应假定所有引用始终连接在容器内。
+
+`template.art` 指回播放器；`$mini` 在创建迷你窗口后才可能存在，默认迷你节点挂在 document.body，不在原容器内。不要通过直接替换字段来重建播放器。`template.init()` 用于初始化：普通模式重写容器 HTML，再绑定节点和代理；重复调用不是受支持的重置界面流程。`template.destroy(removeHtml)` 只处理模板 DOM：true 清空容器内容，false 添加 art-destroy 类；完整资源清理请使用 `art.destroy(removeHtml?)`。
+
+模板字符串应从静态 `Artplayer.html` 读取。旧根声明中的 `art.template.html` 并非实际实例属性，读取通常为 undefined。`useSSR: true` 会保留并查询预先提供的结构，不会补齐缺失节点；模板应与当前播放器版本一致，浏览器端仍需完成实例化。runtime 类型保留可空节点，旧根类型仍保留历史的非空类型；类型断言不能修复不完整的 SSR 模板。
+
 ## `events`
 
 管理播放器所有的 `DOM` 事件，实质上是代理了 `addEventListener` 和 `removeEventListener`, 当使用以下方法来处理事件，播放器销毁时也会自动销毁该事件
@@ -157,6 +192,18 @@ console.info(art.icons.loading);
 
 :::
 
+下列27个默认名称共享相同读取行为：
+
+```text
+loading, state, play, pause, check, volume, volumeClose, screenshot, setting, pip, arrowLeft, arrowRight, playbackRate, aspectRatio, config, lock, flip, unlock, fullscreenOff, fullscreenOn, fullscreenWebOff, fullscreenWebOn, switchOn, switchOff, error, close, airplay
+```
+
+每次访问都会新建 `<i class="art-icon art-icon-NAME">` 包装节点，两个 `art.icons.play` 不是同一个对象。它不是已经挂到按钮上的图标引用；修改后来读取的包装节点不会修改现有按钮。旧根声明写作 HTMLDivElement，实际包装元素是 i；runtime 使用 HTMLElement。
+
+在构造选项 `icons` 中按名称覆盖默认内容，也可添加自定义名称。字符串作为 HTML 解析，应只使用可信内容；传入 HTMLElement 会把同一个元素移动到新包装内，不会克隆，多次读取可能将它从旧包装移走。需要多个独立副本时优先传入字符串或自行克隆后使用。
+
+名称和内容在初始化时浅拷贝保存；以后修改 `art.option.icons` 不会更换这份映射或已经渲染的界面。属性是只读 getter，默认不参与 Object.keys 枚举。未配置的普通自定义名称返回 undefined，请先检查再挂载。
+
 ## `i18n`
 
 管理播放器的 `i18n`
@@ -589,3 +636,21 @@ art.notice.show = false;
 art.i18n.update({ en: { Play: 'Start' } });
 console.log(visible, art.i18n.get('Play'));
 ```
+
+## 模板与图标的 TypeScript 视图
+
+当前未发布重构的 `artplayer/runtime` 使用 `Template<Host>`、`Icons` 和媒体能力类型描述可空查询、未知图标和代理媒体。下面与根入口运行的是同一实现：
+
+```ts
+import Artplayer from 'artplayer/runtime';
+
+const art = new Artplayer({
+    container: '#player', url: '/video.mp4',
+    icons: { customMark: '<span aria-hidden="true">*</span>' },
+});
+const query = art.query;
+const player: HTMLDivElement | null = query('.art-video-player');
+const icon: HTMLElement | undefined = art.icons.customMark;
+if (player && icon) player.append(icon);
+console.log(Artplayer.html, art.video === art.template.$video);
+```

packages/artplayer-vitepress/docs/advanced/class.md

@@ -125,6 +125,8 @@ console.info(Artplayer.kindOf);
 console.info(Artplayer.html);
 ```
 
+这是当前版本的静态基础模板，包含播放器所需的 class 和媒体/控件节点，不是某个实例当前 DOM 的快照。通过 `useSSR: true` 复用预先插入的模板时，应保留完整结构并匹配版本；该选项不会让构造函数在无浏览器环境中运行。实际实例没有 `template.html` 属性，旧根类型为兼容保留的这个成员不能代替静态入口。
+
 ## `option`
 
 返回播放器的默认选项

packages/artplayer-vitepress/docs/en/advanced/built-in.md

@@ -47,6 +47,41 @@ This is the definition of all `DOM` elements: [artplayer/types/template.d.ts](ht
 
 :::
 
+`$container` is the div supplied by the caller; `$player` is the generated player root inside it. They are different elements. These fields retain node references bound during initialization rather than performing a new query on every read:
+
+| Field | Default selector or source |
+| --- | --- |
+| `$container` | Supplied div container |
+| `$player` | `.art-video-player` |
+| `$video` | `.art-video` |
+| `$track` | `track` |
+| `$poster` | `.art-poster` |
+| `$subtitle` | `.art-subtitle` |
+| `$danmuku` | `.art-danmuku` |
+| `$bottom` | `.art-bottom` |
+| `$progress` | `.art-progress` |
+| `$controls` | `.art-controls` |
+| `$controlsLeft` | `.art-controls-left` |
+| `$controlsCenter` | `.art-controls-center` |
+| `$controlsRight` | `.art-controls-right` |
+| `$layer` | `.art-layers` |
+| `$loading` | `.art-loading` |
+| `$notice` | `.art-notice` |
+| `$noticeInner` | `.art-notice-inner` |
+| `$mask` | `.art-mask` |
+| `$state` | `.art-state` |
+| `$setting` | `.art-settings` |
+| `$info` | `.art-info` |
+| `$infoPanel` | `.art-info-panel` |
+| `$infoClose` | `.art-info-close` |
+| `$contextmenu` | `.art-contextmenus` |
+
+`art.query(selector)` and `art.template.query(selector)` are the same bound function and can be extracted for later calls. Queries always search descendants of the original $container, excluding the container itself. They do not follow player/media nodes moved outside it. Missing matches return null; invalid selectors retain querySelector errors. `art.video` returns the cached `template.$video`, which can be a canvas with a proxy. The original $track can become detached with a replaced video, so stored references need not remain connected inside the container.
+
+`template.art` references the player. Optional `$mini` can appear after creating a mini window; the default mini node is attached to document.body outside the original container. Do not rebuild the player by replacing these fields. `template.init()` initializes the template: ordinary mode replaces container HTML, then binds nodes and the proxy. Repeating it is not a supported interface-reset workflow. `template.destroy(removeHtml)` only handles template DOM: true empties the container, false adds art-destroy. Use `art.destroy(removeHtml?)` for complete resource cleanup.
+
+Read the template string from static `Artplayer.html`. The old root declaration's `art.template.html` is not an actual instance member and normally reads as undefined. `useSSR: true` preserves and queries supplied markup without filling missing nodes. Keep that markup complete and version-matched; instantiation still requires a browser. Runtime types retain nullable nodes while root types retain historical non-null shapes. A type assertion cannot repair incomplete SSR markup.
+
 ## `events`
 
 Manages all `DOM` events for the player. It essentially proxies `addEventListener` and `removeEventListener`. When using the following methods to handle events, the events will also be automatically destroyed when the player is destroyed.
@@ -157,6 +192,18 @@ console.info(art.icons.loading);
 
 :::
 
+These 27 default names share the same read behavior:
+
+```text
+loading, state, play, pause, check, volume, volumeClose, screenshot, setting, pip, arrowLeft, arrowRight, playbackRate, aspectRatio, config, lock, flip, unlock, fullscreenOff, fullscreenOn, fullscreenWebOff, fullscreenWebOn, switchOn, switchOff, error, close, airplay
+```
+
+Every read creates a new `<i class="art-icon art-icon-NAME">` wrapper, so two reads of `art.icons.play` are different objects. This is not a reference to the icon already mounted in a button; modifying a later wrapper does not change the existing button. Root declarations retain HTMLDivElement, although the wrapper is an i element; runtime types use HTMLElement.
+
+Supply constructor `icons` options to replace default content or add custom names. Strings are parsed as HTML and should contain trusted markup. An HTMLElement is moved into the new wrapper rather than cloned; a later read may move it out of its previous wrapper. Use strings or your own cloned elements when independent copies are needed.
+
+Names and values are shallow-copied at initialization. Later changes to `art.option.icons` do not replace that mapping or the rendered interface. Properties are read-only getters and are non-enumerable by default. An unconfigured ordinary custom name returns undefined; check it before appending.
+
 ## `i18n`
 
 Manages the player's `i18n`.
@@ -590,3 +637,21 @@ art.notice.show = false;
 art.i18n.update({ en: { Play: 'Start' } });
 console.log(visible, art.i18n.get('Play'));
 ```
+
+## TypeScript template and icon views
+
+The unpublished refactor's `artplayer/runtime` uses `Template<Host>`, `Icons` and media-capability types for nullable queries, unknown icons and proxy media. This example uses the same implementation as the root entry:
+
+```ts
+import Artplayer from 'artplayer/runtime';
+
+const art = new Artplayer({
+    container: '#player', url: '/video.mp4',
+    icons: { customMark: '<span aria-hidden="true">*</span>' },
+});
+const query = art.query;
+const player: HTMLDivElement | null = query('.art-video-player');
+const icon: HTMLElement | undefined = art.icons.customMark;
+if (player && icon) player.append(icon);
+console.log(Artplayer.html, art.video === art.template.$video);
+```

packages/artplayer-vitepress/docs/en/advanced/class.md

@@ -125,6 +125,8 @@ Returns the `html` string required by the player.
 console.info(Artplayer.html);
 ```
 
+This is the current version's static base markup, including required classes and media/control nodes, not a snapshot of an instance's current DOM. When reusing preinserted markup through `useSSR: true`, keep its complete structure and version aligned. The option does not make construction work outside a browser. Actual template instances have no `html` member; the historical root type retains that member for compatibility, but it does not replace the static entry.
+
 ## `option`
 
 Returns the default options of the player.