ArtPlayer/packages/artplayer-vitepress/README.md

# ArtPlayer documentation site

This workspace builds the static API documentation served at `/document/`.
The separate repository `docs/index.html` is the online player/editor; it is
not a VitePress page. Keep both URL surfaces compatible.

## Sources and generated files

| Source | Responsibility | Output or consumer |
| --- | --- | --- |
| `docs/index.md`, `docs/start`, `docs/component`, `docs/advanced` | Chinese API documentation | `/document/` |
| `docs/en` | English counterparts | `/document/en/` |
| `docs/plugin/danmuku.md`, `docs/en/plugin/danmuku.md` | Danmuku options, callbacks, commands, heatmap and types in both languages | `/document/plugin/danmuku.html`, `/document/en/plugin/danmuku.html` |
| `docs/plugin/hls-control.md`, `docs/en/plugin/hls-control.md` | HLS SDK setup, menus, lifecycle and types | `/document/plugin/hls-control.html`, `/document/en/plugin/hls-control.html` |
| `docs/plugin/dash-control.md`, `docs/en/plugin/dash-control.md` | DASH SDK generations, menus, lifecycle and types | `/document/plugin/dash-control.html`, `/document/en/plugin/dash-control.html` |
| `docs/plugin/audio-track.md`, `docs/en/plugin/audio-track.md` | Separate audio synchronization, ownership and update types | `/document/plugin/audio-track.html`, `/document/en/plugin/audio-track.html` |
| `docs/plugin/vtt-thumbnail.md`, `docs/en/plugin/vtt-thumbnail.md` | Sprite index format, timing boundaries, asynchronous registration and types | `/document/plugin/vtt-thumbnail.html`, `/document/en/plugin/vtt-thumbnail.html` |
| `docs/plugin/chapter.md`, `docs/en/plugin/chapter.md` | Chapter ranges, caller-data mutation, replacement updates, cleanup and types | `/document/plugin/chapter.html`, `/document/en/plugin/chapter.html` |
| `docs/plugin/ambilight.md`, `docs/en/plugin/ambilight.md` | Sampling options, start/stop ownership, pixel access and compatible type entries | `/document/plugin/ambilight.html`, `/document/en/plugin/ambilight.html` |
| `docs/plugin/document-pip.md`, `docs/en/plugin/document-pip.md` | Window ownership, video fallback, events and compatible async type views | `/document/plugin/document-pip.html`, `/document/en/plugin/document-pip.html` |
| `docs/plugin/asr.md`, `docs/en/plugin/asr.md` | PCM/WAV callbacks, subtitle rendering, audio routing, lifecycle and runtime types | `/document/plugin/asr.html`, `/document/en/plugin/asr.html` |
| `docs/plugin/auto-thumbnail.md`, `docs/en/plugin/auto-thumbnail.md` | Progressive JPEG extraction, limits, decoder ownership and asynchronous runtime types | `/document/plugin/auto-thumbnail.html`, `/document/en/plugin/auto-thumbnail.html` |
| `docs/plugin/multiple-subtitles.md`, `docs/en/plugin/multiple-subtitles.md` | Track loading, selection, shared subtitle configuration and compatible type views | `/document/plugin/multiple-subtitles.html`, `/document/en/plugin/multiple-subtitles.html` |
| `docs/.vitepress/config.js` | Navigation, base URL, output path, page head | Repository `docs/document/` |
| `docs/vite.config.ts` | Search plugin configuration | VitePress/Vite integration; real search acceptance remains pending |
| `docs/public/main.js` | Run Code links and first-visit language redirect | Copied into the built site |
| `docs/public/style.css` | Documentation presentation | Copied into the built site |

Edit Markdown and public sources here. Do not edit the generated repository
HTML directly. After adding a guide, rebuild the site, record its new HTML path
in `refactor/baselines/demo-additions.json` with its owner task and either the known
`introducedBy` commit or the pre-change HEAD as `introducedAfter` for a new page,
and run `node refactor/scripts/demos.mjs --check`. Preserve the frozen BASE-04
inventory. Also refresh and check the current site inventory; the two inventories
serve different purposes. Neither path check replaces browser navigation tests.

The generated site lives in `docs/document/`. The current inventory contains 48 Markdown pages: 24 Chinese
and 24 English. Danmuku, HLS, DASH, Audio Track, VTT Thumbnail, Chapter, Ambilight, Document PiP, ASR, Auto Thumbnail and Multiple Subtitles have dedicated guides and navigation in both languages. Other plugins currently
use their package README, architecture notes and linked editor examples;
navigation links alone are not complete API documentation.

Auto Thumbnail and Multiple Subtitles preserve their original runnable examples.
Both registrars are asynchronous, but their Promises cover different work: Auto
Thumbnail installs subscriptions before extraction, while Multiple Subtitles
downloads and merges tracks without waiting for host subtitle loading. Their
guides explain these boundaries, retained historical declarations and opt-in
runtime types. Navigation verification does not prove decoded thumbnail pixels
or native subtitle display; keep those package-specific checks separate.

Document PiP keeps its required root factory and void historical result types;
the guide explains the accurate opt-in views without inventing a runtime subpath.
ASR documents the actual `/runtime` entry, nonterminal stop, direct/capture audio
ownership, CORS and trusted HTML rendering. Its embedded `asr.local` demo uses
simulated subtitles and never claims to run a recognition service. Preserve both
original examples and the distinction between navigation and media verification.

Chapter and Ambilight guides preserve their original demo code and explicitly
document the mutation, lifecycle and historical type boundaries. Keep their
language pairs together; the content mapping is in `refactor/site-content-review.md`.
Run Code markers need visible text as well as the existing className/data-libs
hooks. Navigation checks verify exact code forwarding, not playback in the editor.
The documented core version in the shared navigation is 6.0.0, marked unreleased.

VTT Thumbnail guides preserve the original vtt.thumbnail demo. The document-vtt
suite checks actual screenshot crop pixels, a shared time boundary, a gap and
cleanup using the original video, controlled VTT/SVG resources and real progress
hover on both cores. The exact endpoint uses public setBar with a MouseEvent to
avoid pointer pixel rounding while satisfying the core's event contract.
This does not establish physical touch or full playback acceptance.

Audio Track guide examples match the actual audio.track demo. The dedicated
document-audio browser suite substitutes local Range-served media, then checks
native video pixels and AAC playback, pause, offset seek, volume/rate, source
updates and teardown with both core generations. The navigation suite separately
checks both generated guide URLs and the Run Code destination. Tests do not
measure physical audibility or replace the package's full device matrix.

Danmuku guides describe the refactor branch and explicitly distinguish unpublished
`/runtime` declarations from current CDN releases. Preserve old Chinese heading
anchors when editing. Rebuild site assets (the English route inventory), the
LLM corpus and VitePress after changing these pages. The generated readiness smoke
excludes plugin pages; `test/browser/document-danmuku.spec.js` extracts and runs
both guides separately with the local distribution and real sample media. These
checks cover readiness and cleanup, not every interaction or complete playback.
The translation CLI
does not select plugin pages; maintain the two Danmuku guides together manually.
SITE-DANMUKU-01 covers this guide; full bilingual package coverage remains SITE-04.

Site-owned browser behavior now lives in `browser/`; its README maps the shared
loader, desktop editor, mobile entry and Run Code/language navigation. `docs/public/main.js` is a
generated input to VitePress. Run root `yarn build:site-assets` after changes, or
`yarn check:site-assets` for drift. Desktop common.js and bootstrap.js are generated
from typed modules, with Monaco models/emit, Run ordering, file imports, preferences
and page cleanup separated by responsibility. No player package APIs move here.

## Related tooling

Run commands from the repository root with its pinned Node version and Yarn
Classic 1.22.22. Maintain the root lockfile only.

```sh
yarn workspace artplayer-vitepress dev
yarn build:docs
yarn workspace artplayer-vitepress preview
node refactor/scripts/site-inventory.mjs --check
```

`build:docs` uses the current pinned Yarn executable to run this workspace's
VitePress script into a temporary directory. A successful build replaces the
generated site, with backups for caught replacement failures. See
[build maintenance](../../scripts/site-build/README.md) for module ownership,
failure recovery and the explicit limits of directory replacement.

The repository generators have different ownership:

- `scripts/build-types.mjs`: core public declaration sources to existing `types/`.
- `scripts/build-ts.js`: standalone editor declarations and the editor library list.
  Checked TS modules in `scripts/editor-declarations/` validate all selected
  declarations together with current and historical compilers before writing.
  Use `yarn check:editor-types` for drift checks; see that module's README.
- `scripts/build-test.js`: extracts Chinese core Run Code blocks into `docs/test/test.js`; plugin and English pages are excluded.
  The TS implementation in `scripts/docs-smoke/` produces deterministic readiness
  smoke cases with owned frames, error observation and cleanup. It does not prove
  complete playback or plugin behavior. See its maintenance README and SITE-SMOKE-01.
- `scripts/build-i18n.js`: typed standalone language builds, staged before replacing
  distribution and `docs/compiled/i18n/` together; legacy globals and paths remain.
- `scripts/build-docs.js`: this VitePress build through pinned Yarn and staged output.
- `scripts/build-console.mjs`: owned desktop console TS entry/view and shared log
  lifecycle, keeping the original React/Parcel runtime. Run `build:console` after
  edits and `check:console` for drift. See [console maintenance](../../scripts/site-vendor/console/README.md).
- `scripts/build-llm.js`: offline source-preserving `docs/llms.txt` and fingerprint
  manifest. `yarn check:llm` checks drift in CI; `ci:build` regenerates after types.
- `scripts/trans-docs.js`: local plan by default; explicit `--remote` creates a
  reviewable draft, `--validate <draft>` checks edited drafts, and `--apply <draft>`
  replaces selected English files with stale-input and rollback checks. Remote
  translation is never part of CI. See [tool maintenance](../../scripts/documentation/README.md)
  for the migration from destructive translation, module boundaries and limits.

## Browser boundaries and ownership

The editor's `prod` choice is stored in localStorage and changes the core script
only. The `libs` query still selects plugin scripts independently. `example`
takes precedence over `code`. Editor Run dispatches the example cleanup event,
destroys existing players, then evaluates the code. Preserve these contracts
when moving its JS to TypeScript; use an isolated origin for automated tests.

The mobile page preserves the query during redirect but has its own loader and
uses the development core. The ESM, i18n, iframe and generated smoke pages each
have separate dependencies. See the repository
[site inventory](../../refactor/site-inventory.md) for the full entrypoint map,
source fingerprints, asset provenance and assigned follow-up work.

Generated `main.js` installs one document click listener under
`window['run-code-init']`; its lifetime is the page. Run Code opens the separate
editor and recognizes localhost, 127.0.0.1 and IPv6 loopback. First-language
navigation preserves existing English counterparts and explicit later choices;
unavailable storage keeps the requested page. See `browser/README.md` for the
current rules and verified scope. Full site/search acceptance remains SITE-05.

## Delivery and remaining acceptance

SITE-07 now checks frozen Monaco/vConsole files and generates verbatim upstream
texts under `docs/licenses/` with `build:site-notices` / `check:site-notices`.
See `scripts/site-vendor/README.md`: vConsole sources/notices and its destruction
fix now have separate evidence. The notices index explicitly
does not clear the console bundle, fonts, media or the rest of the site.

`scripts/projects.js` excludes this workspace from the 21 library builds.
VitePress emits the static site; CI-02 stages `docs/`, refreshes old demo entries,
and validates that separate Pages artifact before deployment. The manifest currently has neither library
entrypoints nor `private: true`; that absence is not npm publication intent.
REL-01 must explicitly classify its release handling. Its independent planned
major still advances from 1.1.0 to 2.0.0 under the agreed version policy.

SITE-02/03 own generators and browser source organization; SITE-04 owns bilingual
API completeness; SITE-05 owns build, links and real search; SITE-07 owns vendor
provenance and distribution notices; EX-03 owns complete demo execution. Three
release review rounds and remote CI/Pages evidence remain separate requirements.

The HLS guides at `docs/plugin/hls-control.md` and `docs/en/plugin/hls-control.md`
share the exact runnable `docs/assets/example/hls.control.js` source at repository
root. `test/browser/document-hls.spec.js` enforces that parity and checks the
source lifecycle with frozen real SDKs. `document-site.spec.js` checks both sidebar
links and the two-library Run Code destination. Preserve the native-HLS capability
boundary and SDK ownership explanation when editing either language.

The DASH guides use the same exact-example rule with `docs/assets/example/dash.control.js`
and `test/browser/document-dash.spec.js`. Their formatter has one argument, unlike
the optional HLS list index. Preserve the distinction between SDK 4 qualityIndex
and SDK 5 representation IDs, nullable language fields, and synchronous update.