refactor(build): [SITE-BUILD-01] stage outputs and stabilize documentation builds

packages/artplayer-vitepress/README.md

@@ -40,9 +40,11 @@ yarn workspace artplayer-vitepress preview
 node refactor/scripts/site-inventory.mjs --check
 ```
 
-`build:docs` currently delegates through `npm run build` to this workspace's
-VitePress script. This does not install dependencies or create another lockfile;
-the command orchestration will be modernized in SITE-03.
+`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:
 
@@ -55,8 +57,9 @@ The repository generators have different ownership:
   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`: core language source bundles and copies to `docs/compiled/i18n/`.
-- `scripts/build-docs.js`: this VitePress build.
+- `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-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

packages/artplayer-vitepress/build/markdown.ts

@@ -0,0 +1,38 @@
+import type MarkdownIt from 'markdown-it'
+import assert from 'node:assert/strict'
+import { createHash } from 'node:crypto'
+
+export function stableCodeGroups(markdown: MarkdownIt): void {
+  const original = markdown.renderer.rules['container_code-group_open']
+  assert(original, 'Expected VitePress code-group renderer')
+  markdown.renderer.rules['container_code-group_open'] = (
+    tokens,
+    index,
+    options,
+    env: unknown,
+    renderer,
+  ) => {
+    const relative
+      = env
+        && typeof env === 'object'
+        && 'relativePath' in env
+        && typeof env.relativePath === 'string'
+        ? env.relativePath.replaceAll('\\', '/')
+        : ''
+    const prefix = createHash('sha256')
+      .update(`${relative}:${index}`)
+      .digest('hex')
+      .slice(0, 16)
+    const ids = new Map<string, string>()
+    return original(tokens, index, options, env, renderer)
+      .replace(/name="group-[^"]+"/g, `name="group-artplayer-${prefix}"`)
+      .replace(
+        /(id|for)="(tab-[^"]+)"/g,
+        (_match, attribute: string, id: string) => {
+          if (!ids.has(id))
+            ids.set(id, `tab-artplayer-${prefix}-${ids.size}`)
+          return `${attribute}="${ids.get(id)}"`
+        },
+      )
+  }
+}

packages/artplayer-vitepress/docs/.vitepress/config.js

@@ -1,3 +1,5 @@
+import { stableCodeGroups } from '../../build/markdown.ts'
+
 /**
  * @type {import('vitepress').UserConfig}
  */
@@ -180,6 +182,7 @@ const config = {
   },
   markdown: {
     lineNumbers: true,
+    config: stableCodeGroups,
   },
   head: [
     [

packages/artplayer-vitepress/package.json

@@ -1,5 +1,6 @@
 {
   "name": "artplayer-vitepress",
+  "type": "module",
   "version": "1.1.0",
   "scripts": {
     "dev": "vitepress dev docs",