refactor(docs): [SITE-SMOKE-01] verify example readiness and cleanup

scripts/docs-smoke/README.md

@@ -0,0 +1,75 @@
+# Documentation readiness smoke
+
+This generator keeps the existing `yarn build:test` / `node scripts/build-test.js`
+entrypoint and `docs/test/test.js` URL. Use the pinned Node 24.21.0 runtime and
+Yarn 1.22.22. Node runs the owned TypeScript modules using native type stripping;
+the command shim remains JavaScript and is included in strict `checkJs` checking.
+The root typecheck commands use `node node_modules/typescript/bin/tsc` explicitly:
+Yarn's shared `tsc` binary can point at the installed 5.1.6 compatibility alias.
+The main 5.9.3 compiler and older compatibility compilers retain distinct roles.
+
+| File                    | Ownership                                                                                                  |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `parser.ts`             | Markdown tokens, Run Code/fence adjacency, source locations and closing fences                             |
+| `generator.ts`          | Deterministic file discovery, syntax compilation without execution, dependency list and browser bundle     |
+| `runtime.ts`            | One sequential example frame, script loading, error/readiness observation, teardown and Mocha registration |
+| `../build-test.js`      | Original CLI path, argument validation and write/read-only check                                           |
+| `../tsconfig.docs.json` | Strict Node/DOM tools check, including the JavaScript shim                                                 |
+
+```sh
+yarn build:test
+yarn check:docs-smoke
+yarn typecheck:docs-tools
+node --test refactor/scripts/docs-smoke.test.mjs
+yarn test:browser test/browser/docs-smoke.spec.js
+```
+
+`docs/test/examples.json` records stable source file/line IDs, original code and
+the ordered script list from `docs/test/index.html`. No timestamps enter generated
+content. Generation validates every selected example before writing either output;
+`--check` compares both files without modifying them. Parse/syntax errors fail the
+command with a source location. This is not a transactional multi-file filesystem
+write if the filesystem itself fails during output.
+
+The scope stays Chinese JavaScript fences after Run Code markers, excluding
+`en`, `plugin`, `public` and `.vitepress`. There are 233 current cases in 11 files.
+CRLF is normalized to LF. New cases must be reviewed and the deliberate count
+assertion updated. JS syntax compilation does not execute snippets or validate
+their API semantics. TypeScript/editor declaration generation remains SITE-02.
+
+The browser bundle registers cases with the existing Mocha BDD page. Each case:
+
+1. Creates an iframe with its own ArtPlayer container and loads the page's runtime
+   scripts in order, excluding Mocha, Chai and the generated test script itself.
+2. Evaluates the snippet as a classic script in that frame, awaits its returned
+   promise if any, and waits for the currently created players' `ready` events.
+3. Observes thrown errors, unhandled rejections and media/player errors until that
+   readiness boundary plus one task turn. A 4500 ms deadline produces failure,
+   never success. Cases without players cover evaluation only.
+4. Detaches observer listeners, destroys frame players, removes the iframe and
+   restores local/session storage. Cleanup errors are failures and retain an
+   earlier failure in the error list. Concurrent calls are rejected.
+
+The iframe is an owned browsing context, **not a security sandbox**. It shares
+the parent origin. Run the test page on an isolated test origin with no concurrent
+same-origin work: storage restoration does not merge writes from other tabs.
+Unchanged browser storage is restored after each case, while frame-owned timers
+and globals disappear when the frame is removed. Arbitrary external resources
+that a snippet deliberately hands to another window are outside this ownership.
+
+Readiness is not playback, interaction or complete asynchronous feature acceptance.
+Delayed actions scheduled after this boundary are not verified; examples involving
+clicks, seek, SDKs, windows and full lifecycle behavior remain EX-03/package tests.
+The automated harness tests use actual core/media and three selected unchanged
+documentation snippets with controlled media. They do not certify all 233 examples
+or the remote SDK endpoints in the full manual page.
+
+Windows WebKit has the existing DPIP-MEDIA-01 dimension discrepancy: the same
+320x180 media can report 640x360 layout dimensions. The harness retains exact raw
+readings and only these documented pairs; it does not close intrinsic-size or
+real Safari/device acceptance. See `refactor/site-inventory.md` for broader ownership.
+
+Dependencies: root development-only `@types/node` 24.10.0 and
+`@types/markdown-it` 14.1.2 provide strict tools typing. Runtime parsing uses the
+existing MarkdownIt 14.1.0 and browser bundling uses the existing pinned esbuild.
+No player package runtime dependency changes.