/index.js`，不能假设所有插件同时更新。正常构建产生分发文件，不手改 compiled/uncompiled/dist 或生成的 test.js。
chapter 试点可使用 `http://localhost:8082/?libs=./uncompiled/artplayer-plugin-chapter/index.js&example=chapter`，测试前确认核心及插件已构建。这是已有路由的用法，不表示当前服务已启动或页面已通过。
@@ -49,3 +49,9 @@ chapter 试点可使用 `http://localhost:8082/?libs=./uncompiled/artplayer-plug
| REVIEW-02/03 | 分别复查真实浏览器覆盖与待发布内容的一致性 |
页面行为和媒体验证按 [测试规范](testing.md) 留证，发布结论按 [多轮复盘](release-reviews.md) 核对。该清单不新增重复实施任务；真实状态以 tasks.json 为准。
+
+## BASE-04 已落地的记录
+
+[完整路径台账](baselines/demo-inventory.json) 已覆盖 29 个示例、36 个 HTML 和 22 包，包括生成文档、独立 upscaler 与站点验证页面。源脚本/菜单参数与 editor prod/ts/code/log 规则已有记录；这些官方入口尚未运行，运行时实际存储值和网络来源仍待 EX-03 采集。
+
+独立发布包夹具的 DOM/CSS、Tab/热键、设置与网页全屏已在内置浏览器两次实测，见 [覆盖及问题](baselines/dom-coverage.md)。它没有运行 Monaco，不代表编辑器 Run 或官方 chapter demo 通过。thumbnail 无菜单示例依赖不在当前 workspace 的旧插件，已交 SITE-01/EX-03 核实。
diff --git a/refactor/fixtures/dom.html b/refactor/fixtures/dom.html
new file mode 100644
index 000000000..3498ff73d
--- /dev/null
+++ b/refactor/fixtures/dom.html
@@ -0,0 +1,22 @@
+
+
+ArtPlayer published DOM baseline
+
+Published DOM and input baseline
+Use Probe control, ArrowRight, Typing probe + ArrowRight, settings Baseline selector / High, and web fullscreen + Escape. Then inspect narrow layout and save.
+Tab start
+
+Inspect narrow container
+Save DOM baseline
+Loading published player
+User layer ', style: { top: '12px', left: '12px' } }],
+ settings: [{ name: 'compat-setting', html: 'Baseline selector', selector: [{ html: 'Low', default: true }, { html: 'High' }], onSelect(item, element, event) {
+ check('DOM.setting-select', this === art && item.html === 'High' && element.classList.contains('art-current') && event.isTrusted)
+ report.observations.selected = { html: item.html, defaults: item.$parent.selector.map(value => value.default) }
+ return item.html
+ } }],
+ plugins: [artplayerPluginChapter({ chapters: [{ start: 0, end: 10, title: 'First' }, { start: 10, end: Infinity, title: 'Second' }] })],
+ })
+ let ready = false
+ art.once('ready', () => {
+ check('DOM.version-template', Artplayer.version === '5.4.0' && art.query('.art-video') === art.video)
+ art.cssVar('--art-theme', 'rgb(1, 2, 3)')
+ check('DOM.user-style', getComputedStyle(art.query('.user-hook')).color === 'rgb(12, 34, 56)' && art.cssVar('--art-theme').trim() === 'rgb(1, 2, 3)')
+ const chapters = [...art.query('.art-chapters').children].map(el => ({ class: el.className, start: Number(el.dataset.start), end: Number(el.dataset.end), title: el.dataset.title }))
+ check('DOM.chapter-markup', chapters.length === 2 && chapters[0].title === 'First' && chapters[1].title === 'Second')
+ report.snapshot = {
+ template: Artplayer.html, tree: tree(art.template.$player),
+ cssVariables: [...new Set(Artplayer.STYLE.match(/--art-[\w-]+/g))].sort(),
+ cssClasses: [...new Set(Artplayer.STYLE.match(/\.art-[\w-]+/g))].sort(),
+ chapters,
+ controlAttributes: [...art.template.$player.querySelectorAll('.art-control')].map(el => ({ class: el.className, tag: el.tagName, tabIndex: el.tabIndex, role: el.getAttribute('role'), ariaLabel: el.getAttribute('aria-label'), tooltip: el.getAttribute('data-tooltip'), title: el.getAttribute('title') })),
+ chapterStylePresent: Boolean(document.getElementById('artplayer-plugin-chapter')),
+ }
+ report.observations.wide = layout()
+ ready = true
+ })
+ let beforeKey
+ let hotkeys = 0
+ document.addEventListener('keydown', event => {
+ beforeKey = { time: art.currentTime, hotkeys, focused: art.isFocus, target: event.target.tagName, code: event.code, trusted: event.isTrusted }
+ }, true)
+ art.on('hotkey', () => hotkeys++)
+ document.addEventListener('keydown', event => {
+ if (!ready) return
+ const after = { ...beforeKey, afterTime: art.currentTime, afterHotkeys: hotkeys, activeTag: document.activeElement.tagName, activeLabel: document.activeElement.getAttribute('aria-label') }
+ report.interactions.push(after)
+ if (event.code === 'ArrowRight' && beforeKey.target !== 'INPUT') check('DOM.keyboard-seek', beforeKey.trusted && beforeKey.focused && hotkeys === beforeKey.hotkeys + 1 && Math.abs(art.currentTime - beforeKey.time - Artplayer.SEEK_STEP) < 0.05)
+ if (event.code === 'ArrowRight' && beforeKey.target === 'INPUT') check('DOM.input-ignores-hotkey', beforeKey.trusted && beforeKey.focused && hotkeys === beforeKey.hotkeys && art.currentTime === beforeKey.time)
+ })
+ document.addEventListener('focusin', event => report.interactions.push({ focus: event.target.tagName, label: event.target.getAttribute('aria-label'), id: event.target.id }))
+ art.on('fullscreenWeb', value => {
+ if (value) check('DOM.fullscreen-web-enter', art.template.$player.parentElement === document.body && art.template.$player.classList.contains('art-fullscreen-web'))
+ else check('DOM.fullscreen-web-exit', art.template.$player.parentElement === art.template.$container && !art.template.$player.classList.contains('art-fullscreen-web'))
+ })
+ document.querySelector('#narrow').onclick = () => {
+ document.querySelector('.player').style.cssText = 'width:320px;height:180px'
+ requestAnimationFrame(() => {
+ report.observations.narrow = layout()
+ check('DOM.narrow-container', report.observations.narrow.width === 320 && report.observations.narrow.height === 180)
+ })
+ }
+ document.querySelector('#finish').onclick = async () => {
+ try {
+ const previous = art.controls.compat
+ const updateResult = art.controls.update({ name: 'compat', html: 'Updated control' })
+ const replacement = art.controls.compat
+ check('DOM.control-update', updateResult === undefined && replacement instanceof HTMLElement && !previous.isConnected && art.template.$player.querySelectorAll('.art-control-compat').length === 1)
+ art.controls.remove('compat')
+ check('DOM.control-remove', !replacement.isConnected && !art.controls.compat)
+ art.setting.update({ name: 'compat-setting', html: 'Updated selector' })
+ check('DOM.setting-update', art.setting.find('compat-setting').html === 'Updated selector')
+ art.setting.remove('compat-setting')
+ check('DOM.setting-remove', !art.setting.find('compat-setting'))
+ art.layers.remove('compat')
+ check('DOM.layer-remove', !art.query('.user-hook'))
+ art.destroy()
+ check('DOM.destroy', document.querySelector('.player').children.length === 0 && Artplayer.instances.length === 0)
+ }
+ catch (error) {
+ report.errors.push(error.message)
+ if (Artplayer.instances.includes(art)) art.destroy()
+ }
+ report.checks.sort((a, b) => a.id.localeCompare(b.id))
+ document.querySelector('#result').textContent = JSON.stringify(report, null, 2)
+ const response = await fetch('/reports/dom', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(report) })
+ status.textContent = response.ok ? `Saved ${report.checks.length} checks; errors ${report.errors.length}` : `Save failed: ${response.status}`
+ document.querySelector('#finish').disabled = true
+ }
+})()
diff --git a/refactor/plan.md b/refactor/plan.md
index fd5a1447f..b3c967daf 100644
--- a/refactor/plan.md
+++ b/refactor/plan.md
@@ -4,7 +4,7 @@
基线：`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 214 项，范围 22 个包及工作区/示例。
-状态：todo 194 / doing 0 / blocked 0 / done 20 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 193 / doing 0 / blocked 0 / done 21 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
前置依赖是启动条件；验收是完成条件。任务可以继续拆分，但不能复用或悄悄删除旧 ID。
@@ -63,7 +63,7 @@
| BASE-HARNESS-01 | workspace]*\bsrc=["']([^"']+)["']/g)].map(match => match[1]),
+ status: 'not-run', owner: source.includes('googlebc') ? 'SITE-01' : 'EX-03' }
+ })
+ return { schemaVersion: 1, task: 'BASE-04', sourceCommit: '94893929', capturedAt: new Date().toISOString(),
+ note: 'Historical source inventory, not browser or network evidence. ScriptSources excludes comments but does not resolve inline scripts, import maps or dynamic SDK loading. Hashes use LF and describe this capture; check validates coverage, not current content identity.',
+ examples, pages,
+ packages: inventory.packages.map(pkg => ({ name: pkg.name, examples: examples.filter(example => example.libs.some(lib => lib.includes(`/${pkg.name}/`))).map(example => example.name), status: 'not-run', owner: pkg.name === 'artplayer-vitepress' ? 'SITE-01' : 'EX-03' })),
+ editor: { source: 'docs/assets/js/common.js', sha256Lf: hash(read('docs/assets/js/common.js')), storage: ['prod', 'ts', 'code', 'log'], isolation: 'Use separate test origin; record keys, do not erase user browser data.', core: { prodTrue: './compiled/artplayer.js', otherwise: './uncompiled/artplayer/index.js' }, pluginSources: 'URL libs parameter; independent of prod toggle', execution: 'Run evaluates editor text; TS mode alone is not strict tsc validation.', runtimeStatus: 'not-run' },
+ }
+}
+export function validateDemoInventory(inventory) {
+ assert.equal(inventory.schemaVersion, 1)
+ assert.deepEqual(inventory.examples.map(item => item.source).sort(), fs.readdirSync(path.join(root, 'docs/assets/example')).filter(name => name.endsWith('.js')).map(name => `docs/assets/example/${name}`).sort(), 'Demo file coverage drift')
+ assert.deepEqual(inventory.pages.map(item => item.source).sort(), htmlFiles(), 'HTML route coverage drift')
+ assert.deepEqual(inventory.examples.flatMap(item => item.menuLinks).sort(), menuLinks().sort(), 'Editor link coverage drift')
+ assert.deepEqual(inventory.packages.map(item => item.name).sort(), JSON.parse(read('refactor/package-inventory.json')).packages.map(item => item.name).sort(), 'Package demo coverage drift')
+ const names = new Set(inventory.examples.map(item => item.name))
+ for (const pkg of inventory.packages) for (const name of pkg.examples) assert(names.has(name), `Unknown example: ${name}`)
+ assert(inventory.examples.find(item => item.name === 'thumbnail').note.includes('absent'), 'Missing historical plugin exception')
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+ const filename = path.join(refactorDir, 'baselines/demo-inventory.json')
+ if (process.argv.includes('--capture')) {
+ assert(!fs.existsSync(filename), 'Do not overwrite the historical inventory; reconcile changes explicitly')
+ const inventory = captureDemoInventory()
+ validateDemoInventory(inventory)
+ fs.writeFileSync(filename, `${JSON.stringify(inventory, null, 2)}\n`)
+ }
+ else {
+ assert(process.argv.slice(2).every(arg => arg === '--check'), 'Use --capture or --check')
+ const inventory = JSON.parse(fs.readFileSync(filename, 'utf8'))
+ validateDemoInventory(inventory)
+ console.log(`Demo coverage: ${inventory.examples.length} examples, ${inventory.pages.length} HTML paths, ${inventory.packages.length} packages; no browser pass implied`)
+ }
+}
diff --git a/refactor/scripts/demos.test.mjs b/refactor/scripts/demos.test.mjs
new file mode 100644
index 000000000..9557ee544
--- /dev/null
+++ b/refactor/scripts/demos.test.mjs
@@ -0,0 +1,21 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import path from 'node:path'
+import test from 'node:test'
+import { validateDemoInventory } from './demos.mjs'
+import { refactorDir } from './releases.mjs'
+
+test('Demo inventory rejects missing files, routes and ecosystem packages', () => {
+ const inventory = JSON.parse(fs.readFileSync(path.join(refactorDir, 'baselines/demo-inventory.json'), 'utf8'))
+ validateDemoInventory(inventory)
+ for (const mutate of [
+ value => value.examples.pop(),
+ value => value.pages.pop(),
+ value => value.examples.find(item => item.menuLinks.length).menuLinks.pop(),
+ value => value.packages.pop(),
+ ]) {
+ const changed = structuredClone(inventory)
+ mutate(changed)
+ assert.throws(() => validateDemoInventory(changed))
+ }
+})
diff --git a/refactor/scripts/dom.mjs b/refactor/scripts/dom.mjs
new file mode 100644
index 000000000..c755aa8a4
--- /dev/null
+++ b/refactor/scripts/dom.mjs
@@ -0,0 +1,78 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { validatePublishedCapture } from './api.mjs'
+import { hash, refactorDir } from './releases.mjs'
+
+export const domChecks = [
+ 'DOM.chapter-markup', 'DOM.control-click', 'DOM.control-remove', 'DOM.control-update',
+ 'DOM.destroy', 'DOM.fullscreen-web-enter', 'DOM.fullscreen-web-exit', 'DOM.input-ignores-hotkey',
+ 'DOM.keyboard-seek', 'DOM.layer-remove', 'DOM.narrow-container', 'DOM.setting-remove',
+ 'DOM.setting-select', 'DOM.setting-update', 'DOM.user-style', 'DOM.version-template',
+]
+
+export function validateDomReport(report) {
+ assert.equal(report.kind, 'dom')
+ assert.deepEqual(report.errors, [], 'DOM capture failed')
+ assert.deepEqual(report.unhandled, [], 'Unexpected DOM rejection')
+ assert.deepEqual(report.checks, domChecks.map(id => ({ id, passed: true })), 'Missing DOM checks')
+ validatePublishedCapture(report, 'dom')
+ assert.equal(report.capture.media['video.mp4'], hash(fs.readFileSync(path.resolve(refactorDir, '../docs/assets/sample/video.mp4'))), 'DOM media changed')
+ const s = report.snapshot
+ assert(s.template.includes('art-video-player') && s.tree.children.length && s.cssVariables.length > 0 && s.cssClasses.length > 0, 'Incomplete DOM/CSS snapshot')
+ assert.equal(s.chapterStylePresent, true)
+ assert(s.controlAttributes.length >= 8)
+ assert.deepEqual(report.observations.selected, { html: 'High', defaults: [false, true] })
+ for (const [name, width, height] of [['wide', 640, 360], ['narrow', 320, 180]]) {
+ assert.equal(report.observations[name].width, width)
+ assert.equal(report.observations[name].height, height)
+ assert(report.observations[name].controls.length >= 8, 'Missing layout measurement')
+ }
+ const keys = report.interactions.filter(item => item.code)
+ assert(keys.every(item => item.trusted), 'Input was not trusted browser interaction')
+ const seek = keys.find(item => item.code === 'ArrowRight' && item.target !== 'INPUT')
+ assert(seek?.focused && seek.afterTime === seek.time + 5 && seek.afterHotkeys === seek.hotkeys + 1, 'Missing real keyboard seek')
+ const input = keys.find(item => item.code === 'ArrowRight' && item.target === 'INPUT')
+ assert(input?.focused && input.afterTime === input.time && input.afterHotkeys === input.hotkeys, 'Input consumed a player hotkey')
+ assert(keys.some(item => item.code === 'Escape' && item.focused && item.afterHotkeys === item.hotkeys + 1), 'Missing Escape interaction')
+ assert.equal(keys.filter(item => item.code === 'Tab').length, 2, 'Missing Tab traversal')
+ const focus = report.interactions.filter(item => item.focus).slice(0, 3)
+ assert.deepEqual(focus, [{ focus: 'BUTTON', label: null, id: 'tab-start' }, { focus: 'INPUT', label: 'Typing probe', id: '' }, { focus: 'BUTTON', label: null, id: 'narrow' }], 'Published focus traversal changed; assess accessibility improvements explicitly')
+}
+
+export function domProfile(report) {
+ return {
+ snapshot: report.snapshot,
+ checks: report.checks,
+ selected: report.observations.selected,
+ layouts: Object.fromEntries(['wide', 'narrow'].map(name => {
+ const { width, height, controls } = report.observations[name]
+ return [name, { width, height, controls: controls.map(({ class: className, withinPlayer, display }) => ({ class: className, withinPlayer, display })) }]
+ })),
+ }
+}
+
+export function verifyFrozenDom() {
+ const frozen = JSON.parse(fs.readFileSync(path.join(refactorDir, 'baselines/dom.json'), 'utf8'))
+ assert.equal(frozen.schemaVersion, 1)
+ validateDomReport(frozen.report)
+ assert.equal(hash(JSON.stringify(domProfile(frozen.report))), frozen.verification.profileSha256, 'Frozen DOM profile changed')
+ return frozen
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+ const frozen = verifyFrozenDom()
+ const index = process.argv.indexOf('--compare')
+ if (index !== -1) {
+ assert(process.argv[index + 1], '--compare requires a report path')
+ const captured = JSON.parse(fs.readFileSync(process.argv[index + 1], 'utf8'))
+ validateDomReport(captured)
+ assert.deepEqual(domProfile(captured), domProfile(frozen.report), 'Published DOM profile differs; review the change')
+ console.log('Published DOM capture matches baseline; this comparison is not a candidate accessibility gate')
+ }
+ else {
+ assert(process.argv.slice(2).every(arg => arg === '--check'), 'Use --check or --compare ')
+ console.log(`Frozen DOM verified: ${domChecks.length} checks; this command does not rerun the browser`)
+ }
+}
diff --git a/refactor/scripts/dom.test.mjs b/refactor/scripts/dom.test.mjs
new file mode 100644
index 000000000..bad16de6e
--- /dev/null
+++ b/refactor/scripts/dom.test.mjs
@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { domProfile, validateDomReport, verifyFrozenDom } from './dom.mjs'
+
+test('DOM baseline rejects absent interaction, fake input and wrong media', () => {
+ const frozen = verifyFrozenDom().report
+ for (const mutate of [
+ report => report.checks.pop(),
+ report => report.interactions.find(item => item.code === 'ArrowRight').trusted = false,
+ report => report.interactions.find(item => item.code === 'ArrowRight').afterTime = 0,
+ report => report.interactions.find(item => item.code === 'ArrowRight' && item.target === 'INPUT').afterHotkeys++,
+ report => report.capture.media['video.mp4'] = 'wrong',
+ report => report.unhandled.push('unexpected'),
+ ]) {
+ const changed = structuredClone(frozen)
+ mutate(changed)
+ assert.throws(() => validateDomReport(changed))
+ }
+})
+
+test('DOM comparison detects class, variable and layout changes without freezing subpixel widths', () => {
+ const frozen = verifyFrozenDom().report
+ const expected = domProfile(frozen)
+ const jitter = structuredClone(frozen)
+ jitter.observations.wide.controls[0].width += 0.01
+ assert.deepEqual(domProfile(jitter), expected)
+ for (const mutate of [
+ report => report.snapshot.tree.attributes.class = 'renamed',
+ report => report.snapshot.cssVariables.pop(),
+ report => report.snapshot.controlAttributes[0].role = 'button',
+ report => report.observations.narrow.controls[0].withinPlayer = false,
+ ]) {
+ const changed = structuredClone(frozen)
+ mutate(changed)
+ assert.notDeepEqual(domProfile(changed), expected)
+ }
+})
diff --git a/refactor/tasks.json b/refactor/tasks.json
index 87fb47d3a..8d513a035 100644
--- a/refactor/tasks.json
+++ b/refactor/tasks.json
@@ -325,11 +325,16 @@
"dependsOn": [
"BASE-02"
],
- "status": "todo",
+ "status": "done",
"risk": "M",
"deliverable": "核心模板/类名/变量、键盘/焦点/可访问名称基线及全 demo 路径映射；docs-browser-testing.md 中 HTML/编辑器的脚本来源与存储状态；登记契约/版本/固定测试 ID/命令/报告与负责任务",
"acceptance": "核心/试点用户样式和输入用法已记录，其他 demo 运行状态与未知项明确；使用已发布包和最小可重跑探针启动，不等待后续 ENG 服务",
- "evidence": []
+ "evidence": [
+ "changes/2026-09-10-BASE-04-dom.md",
+ "baselines/dom.json",
+ "baselines/dom-coverage.md",
+ "baselines/demo-inventory.json"
+ ]
},
{
"id": "BASE-05",
@@ -911,7 +916,7 @@
"status": "todo",
"risk": "H",
"deliverable": "Component/control/layer/contextmenu 的资源与 TS 边界",
- "acceptance": "add/update/remove、name、selector、mounted/beforeUnmount 通过",
+ "acceptance": "add/update/remove、name、selector、mounted/beforeUnmount 通过；处理 BASE-DOM-02 窄容器控件裁切，保留 controls.update 的旧 undefined 返回值",
"evidence": []
},
{
@@ -927,7 +932,7 @@
"status": "todo",
"risk": "H",
"deliverable": "setting model/selection/render/layout 的分批实现",
- "acceptance": "不强行统一控件返回值，嵌套选择、默认高亮、更新清理通过",
+ "acceptance": "不强行统一控件返回值，嵌套选择、默认高亮、更新清理通过；结合 BASE-DOM-02 验证窄容器设置定位",
"evidence": []
},
{
@@ -1071,7 +1076,7 @@
"BASE-04"
],
"deliverable": "主要控件/设置/模式退出的键盘与焦点回归、名称和字幕可用性检查及必要兼容修正",
- "acceptance": "保持旧快捷键和 DOM/CSS 钩子；真实浏览器验证，不以静态属性检查代替交互"
+ "acceptance": "保持旧快捷键和 DOM/CSS 钩子；真实浏览器验证，不以静态属性检查代替交互；处理 BASE-DOM-01 的主要控件 Tab 不可达，保留既有名称与快捷键"
},
{
"id": "CORE-22",
@@ -3318,7 +3323,7 @@
"status": "todo",
"risk": "M",
"deliverable": "中英文文档、插件页面、demo URL、编辑器声明与生成目录清单；六类 HTML 入口、prod/libs/code/example 加载行为及移动重定向",
- "acceptance": "所有公开 API/插件有对应页面或明确补充任务",
+ "acceptance": "所有公开 API/插件有对应页面或明确补充任务；核实 BASE-DEMO-01 的历史 thumbnail 插件来源及 29 示例/36 HTML 路径",
"evidence": []
},
{
@@ -3494,7 +3499,7 @@
"status": "todo",
"risk": "H",
"deliverable": "8082 全 demo、HLS/DASH/FLV/MPEGTS/WebTorrent 集成记录",
- "acceptance": "旧 URL/参数/脚本加载保持；网络/SDK 限制明确，不静默跳过；覆盖编辑器重复 Run 和 ESM/i18n/mobile/iframe，记录实际候选脚本及状态隔离证据",
+ "acceptance": "旧 URL/参数/脚本加载保持；网络/SDK 限制明确，不静默跳过；覆盖编辑器重复 Run 和 ESM/i18n/mobile/iframe，记录实际候选脚本及状态隔离证据；依据 BASE-04 路径台账逐项消除 not-run，处理 BASE-DEMO-01",
"evidence": []
},
{