test(refactor): [BASE-HARNESS-01] add isolated published API fixture

refactor/changes/2026-09-10-BASE-HARNESS-01-browser-fixture.md

@@ -0,0 +1,13 @@
+# BASE-HARNESS-01 最小发布包浏览器采集服务
+
+- 日期：2026-09-10；分支：codex/compatible-modernization；起点：1d705b30。
+- 提交主题：`test(refactor): [BASE-HARNESS-01] add isolated published API fixture`。
+- BASE-02 的独立前置子任务；验收范围是夹具与 HTTP 服务，不包括实际浏览器 API 基线。
+
+新增本地服务，从已校验 tarball 提供指定 JS 成员、从 docs 提供本地媒体；固定路由、限定报告写入和大小，缓存不进入仓库。api.html/api.js 准备公开描述符、配置、同步插件及事件调用采集；没有修改生产包或公开接口，没有新增依赖。
+
+`node --test refactor/scripts/browser-server.test.mjs` 1 项通过：精确 tarball 字节、页面路由、媒体 Range、无效 Range、路径越界、未知产物和异源报告拒绝。`node --check refactor/fixtures/api.js` 与计划检查通过。Node 25.2.1，Windows。
+
+Chrome 工具打开页、读取清单、重置后重试均失败，不能取得真实页面报告。用户明确答复先继续其他实施任务；BASE-02 标 blocked 并保留完整范围，后续恢复浏览器连接再捕获。HTTP 测试不能替代浏览器。服务和夹具维护说明见 fixtures/README.md。
+
+本子任务完成后独立提交，下一项 ENG-01。可回退本提交，不影响生产功能；临时测试进程和缓存不代表测试完成。

refactor/fixtures/README.md

@@ -0,0 +1,14 @@
+# 发布基线浏览器夹具
+
+`node refactor/scripts/browser-server.mjs` 在 127.0.0.1:8083 启动独立测试服务；ARTPLAYER_TEST_PORT 可更换端口。它不启动或修改用户的 Chrome，也不占用 docs 的 8082 开发服务。
+
+- `/fixtures/api.html` 加载固定核心/chapter tarball 的真实 JS，准备捕获描述符、默认配置、utils/子系统/插件形状及基础调用。
+- `/releases/<name>/<member>` 只读取 releases.json 明确登记的成员；启动时核对 archive 完整性，不使用未编译源码或 CDN latest。
+- `/assets/sample/` 读取本仓库样本，支持普通 bytes 范围请求。当前服务用于最小基线；不是完整 ENG-05 故障注入或 HTTP Range 兼容实现，不支持后缀/多段 Range。
+- 页面将 `public-api` 报告发送给同源 `/reports/api`，服务器保存 refactor/.cache/reports/api.json。最多 1 MiB；其他 Origin 和未知写入路径失败。临时报告不能自动覆盖冻结快照。
+
+运行 `node --test refactor/scripts/browser-server.test.mjs` 验证真实 HTTP 服务返回原始 JS 字节、样本范围和路由隔离；`node --check refactor/fixtures/api.js` 只检查脚本语法。两者不能证明页面能在浏览器运行。
+
+2026-09-10：Chrome 连接服务连续失败，用户要求先继续其他任务；api.html 尚未实际执行，没有 API 快照或浏览器通过记录。BASE-02 保持 blocked；恢复连接后打开完整 URL，确认页面 PASS、没有错误，再核对报告和来源、生成持久基线。
+
+夹具与报告路径由基线任务维护；ENG-05 可复用并扩充受控等待、媒体错误和正式自动化。api.js 依据已核对源码设计断言，真实发布行为如有不同应调查并记录，不能修改断言来盲目通过。

refactor/fixtures/api.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+<meta charset="utf-8">
+<title>ArtPlayer published API baseline</title>
+<style>.player { width: 640px; height: 360px; } pre { white-space: pre-wrap; }</style>
+<h1>Published API contract</h1>
+<p id="status">Capturing...</p>
+<div class="player"></div>
+<pre id="result"></pre>
+<script src="/releases/artplayer/dist/artplayer.js"></script>
+<script src="/releases/artplayer-plugin-chapter/dist/artplayer-plugin-chapter.js"></script>
+<script src="/fixtures/api.js"></script>
+</html>

refactor/fixtures/api.js

@@ -0,0 +1,74 @@
+/* global Artplayer, artplayerPluginChapter */
+(async () => {
+  const report = { kind: 'public-api', environment: { userAgent: navigator.userAgent }, checks: [], errors: [] }
+  const check = (name, result) => {
+    report.checks.push({ name, passed: Boolean(result) })
+    if (!result) throw new Error(name)
+  }
+  function descriptors(object) {
+    return Object.fromEntries(Object.getOwnPropertyNames(object).sort().map((name) => {
+      const d = Object.getOwnPropertyDescriptor(object, name)
+      return [name, {
+        enumerable: d.enumerable,
+        configurable: d.configurable,
+        ...(Object.hasOwn(d, 'value') ? { writable: d.writable, type: typeof d.value } : { get: typeof d.get, set: typeof d.set }),
+      }]
+    }))
+  }
+  function valueOf(input) {
+    if (typeof input === 'function') return { $function: true }
+    if (input === undefined) return { $undefined: true }
+    if (typeof input === 'number' && !Number.isFinite(input)) return { $number: String(input) }
+    if (Array.isArray(input)) return input.map(valueOf)
+    if (input && typeof input === 'object') return Object.fromEntries(Object.keys(input).sort().map(key => [key, valueOf(input[key])]))
+    return input
+  }
+  let art
+  try {
+    check('published core version', Artplayer.version === '5.4.0')
+    const defaults = valueOf(Artplayer.option)
+    art = new Artplayer({ container: '.player', url: '/assets/sample/video.mp4', muted: true, plugins: [artplayerPluginChapter()] })
+    check('constructor registers exact instance', Artplayer.instances.includes(art))
+    check('native media element exposed', art.video instanceof HTMLVideoElement)
+    check('chapter registered synchronously', art.plugins.artplayerPluginChapter?.name === 'artplayerPluginChapter')
+    const plugin = { name: 'baselineProbe', ping: () => 'pong' }
+    const added = art.plugins.add(() => plugin)
+    check('plugins.add returns synchronous registry', added === art.plugins)
+    check('plugin result methods callable', art.plugins.baselineProbe.ping() === 'pong')
+    let received = 0
+    const handler = amount => { received += amount }
+    check('on is chainable', art.on('baseline:event', handler) === art)
+    art.emit('baseline:event', 3)
+    art.off('baseline:event', handler)
+    art.emit('baseline:event', 7)
+    check('custom event on/emit/off', received === 3)
+    const integrations = {}
+    for (const name of ['template', 'events', 'controls', 'setting', 'contextmenu', 'layers', 'plugins', 'storage', 'subtitle', 'i18n']) {
+      integrations[name] = { own: descriptors(art[name]), prototype: descriptors(Object.getPrototypeOf(art[name])) }
+    }
+    report.snapshot = {
+      static: descriptors(Artplayer),
+      prototype: descriptors(Artplayer.prototype),
+      emitterPrototype: descriptors(Object.getPrototypeOf(Artplayer.prototype)),
+      defaults,
+      config: valueOf(Artplayer.config),
+      utilityDescriptors: descriptors(Artplayer.utils),
+      instance: descriptors(art),
+      chapterFactory: descriptors(artplayerPluginChapter),
+      chapterResult: descriptors(art.plugins.artplayerPluginChapter),
+      integrations,
+    }
+  }
+  catch (error) {
+    report.errors.push(error.message)
+  }
+  finally {
+    if (art) {
+      art.destroy(true)
+      report.checks.push({ name: 'instance cleanup', passed: !Artplayer.instances.includes(art) })
+    }
+  }
+  const response = await fetch('/reports/api', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(report) })
+  document.getElementById('status').textContent = response.ok && !report.errors.length && report.checks.every(c => c.passed) ? 'PASS: published API captured' : 'FAIL: inspect report'
+  document.getElementById('result').textContent = JSON.stringify({ environment: report.environment, checks: report.checks, errors: report.errors }, null, 2)
+})()

refactor/plan.md

@@ -2,9 +2,9 @@
 
 > 由 tasks.json 生成。请修改数据后运行 `node refactor/scripts/plan.mjs --write`，不要手改本表。
 
-基线：`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 211 项，范围 22 个包及工作区/示例。
+基线：`40fcda6a37d0049d42e49c1e64e70d4fd9ba5f7f`。总任务 212 项，范围 22 个包及工作区/示例。
 
-状态：todo 198 / doing 0 / blocked 0 / done 13 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
+状态：todo 197 / doing 0 / blocked 1 / done 14 / deferred 0。风险 L/M/H 表示兼容风险，不表示工期。
 
 前置依赖是启动条件；验收是完成条件。任务可以继续拆分，但不能复用或悄悄删除旧 ID。
 
@@ -59,7 +59,8 @@
 | ID | 范围 / 步骤 | 前置依赖 | 交付物 | 验收条件 | 风险 | 状态 |
 | --- | --- | --- | --- | --- | --- | --- |
 | BASE-01 | workspace<br>固定核心与试点的最小发布基线 | DOC-07 | 核心及 chapter 的 npm tarball/integrity、源码 SHA、已知支持窗口；其他包标待核对 | 核心/试点来源可重跑；不虚构全生态已验证，各包 01 步负责补齐自身历史发布基线 | H | done |
-| BASE-02 | workspace<br>捕获公共 API 和属性描述符 | BASE-01 | 核心与试点的构造/默认值/静态和实例 API 快照，其余包由 01/02 步补齐；登记契约/版本/固定测试 ID/命令/报告与负责任务 | 真实发布包反射与旧用户调用可重跑，未验证项明确 | H | todo |
+| BASE-HARNESS-01 | workspace<br>建立最小发布包浏览器采集夹具与服务 | BASE-01 | 固定 tarball 静态服务、本地媒体 Range、公开 API 采集页面及受控报告路径 | HTTP 精确内容/范围和路由隔离测试、夹具语法通过；浏览器采集仍由 BASE-02 负责 | M | done |
+| BASE-02 | workspace<br>捕获公共 API 和属性描述符 | BASE-01, BASE-HARNESS-01 | 核心与试点的构造/默认值/静态和实例 API 快照，其余包由 01/02 步补齐；登记契约/版本/固定测试 ID/命令/报告与负责任务 | 真实发布包反射与旧用户调用可重跑，未验证项明确 | H | blocked |
 | BASE-03 | workspace<br>捕获事件、异步和生命周期 | BASE-02 | ready/restart/destroy、Promise、切源/插件事件 trace；登记契约/版本/固定测试 ID/命令/报告与负责任务 | 成功、失败、重入和多实例有断言，历史缺陷有标记；使用已发布包和最小可重跑探针启动，不等待后续 ENG 服务 | H | todo |
 | BASE-04 | workspace<br>捕获 DOM、CSS 和官方 demo | BASE-02 | 核心模板/类名/变量、键盘/焦点/可访问名称基线及全 demo 路径映射；docs-browser-testing.md 中 HTML/编辑器的脚本来源与存储状态；登记契约/版本/固定测试 ID/命令/报告与负责任务 | 核心/试点用户样式和输入用法已记录，其他 demo 运行状态与未知项明确；使用已发布包和最小可重跑探针启动，不等待后续 ENG 服务 | M | todo |
 | BASE-05 | workspace<br>捕获包入口、资源和类型消费 | BASE-01 | 全包 manifest/资源路径清单；核心/试点的 UMD/AMD/ESM/CJS/legacy/i18n 和类型消费者基线；登记契约/版本/固定测试 ID/命令/报告与负责任务；区分库/npm 与站点实际分发类别，SSR import/模板/非浏览器构造错误分别捕获 | 核心/试点隔离消费可运行，其他包由各自契约任务验证，thumbnail tool 差异已登记 | H | todo |
@@ -413,3 +414,5 @@
 - DOC-11: [记录](changes/2026-09-10-DOC-11-major-version-policy.md)
 - DOC-12: [记录](changes/2026-09-10-DOC-12-execution-readiness-review.md)
 - BASE-01: [记录](changes/2026-09-10-BASE-01-published-baseline.md) [记录](baselines/releases.json)
+- BASE-HARNESS-01: [记录](changes/2026-09-10-BASE-HARNESS-01-browser-fixture.md)
+- BASE-02:  Chrome 工具连接连续失败，重置后仍不可用；用户要求先继续其他任务。恢复连接后执行 api.html 并核对报告，HTTP 服务通过不代表浏览器通过。

refactor/progress.md

@@ -1,6 +1,12 @@
 # 进度与证据
 
-## 当前实施：BASE-01 已发布基线
+## 当前实施：浏览器夹具已保存，继续 ENG-01
+
+BASE-01 已提交 `1d705b30`。BASE-HARNESS-01 完成发布包采集页面/本地 HTTP 服务及 1 项真实 HTTP 测试，详见 [交付记录](changes/2026-09-10-BASE-HARNESS-01-browser-fixture.md)。BASE-02 因 Chrome 连接失败保持 blocked；用户要求先继续其他实施任务，没有伪造浏览器基线。
+
+完成 12 项规划、2 项实施基础任务；BASE-02 阻塞，其余 197 项待办。没有生产 TS 迁移。下一项 ENG-01 固定依赖和运行环境，浏览器恢复后继续 BASE-02。
+
+## 2026-09-10：BASE-01 已发布基线
 
 2026-09-10，goal 开始执行。固定核心 5.4.0/chapter 1.1.0 的真实 tarball、47 个成员哈希和支持范围未知项。核心工作区 5.4.1 未发布，两包 registry gitHead 版本过旧，均已如实记录。详见 [BASE-01 交付](changes/2026-09-10-BASE-01-published-baseline.md)。
 

refactor/scripts/browser-server.mjs

@@ -0,0 +1,83 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import http from 'node:http'
+import path from 'node:path'
+import { ensureArchive, readMember, refactorDir } from './releases.mjs'
+
+const root = path.resolve(refactorDir, '..')
+const baseline = JSON.parse(fs.readFileSync(path.join(refactorDir, 'baselines/releases.json'), 'utf8'))
+const archives = new Map()
+for (const release of baseline.releases) archives.set(release.name, await ensureArchive(release))
+const mime = { '.html': 'text/html', '.js': 'text/javascript', '.mjs': 'text/javascript', '.json': 'application/json', '.mp4': 'video/mp4', '.webm': 'video/webm', '.vtt': 'text/vtt', '.png': 'image/png' }
+let port = Number(process.env.ARTPLAYER_TEST_PORT || 8083)
+assert(Number.isInteger(port) && port >= 0 && port < 65536, 'Invalid test port')
+
+function sendBytes(req, res, bytes, filename) {
+  res.setHeader('Content-Type', mime[path.extname(filename)] || 'application/octet-stream')
+  res.setHeader('Cache-Control', 'no-store')
+  res.setHeader('Accept-Ranges', 'bytes')
+  const range = req.headers.range
+  if (range) {
+    const match = /^bytes=(\d+)-(\d*)$/.exec(range)
+    const start = match ? Number(match[1]) : -1
+    const end = match?.[2] ? Math.min(Number(match[2]), bytes.length - 1) : bytes.length - 1
+    if (start < 0 || start >= bytes.length || end < start) {
+      res.writeHead(416, { 'Content-Range': `bytes */${bytes.length}` })
+      res.end()
+      return
+    }
+    res.statusCode = 206
+    res.setHeader('Content-Range', `bytes ${start}-${end}/${bytes.length}`)
+    bytes = bytes.subarray(start, end + 1)
+  }
+  res.setHeader('Content-Length', bytes.length)
+  res.end(req.method === 'HEAD' ? undefined : bytes)
+}
+
+const server = http.createServer(async (req, res) => {
+  try {
+    const url = new URL(req.url, `http://127.0.0.1:${port}`)
+    if (req.method === 'POST' && url.pathname === '/reports/api') {
+      assert.equal(req.headers.origin, `http://127.0.0.1:${port}`, 'Unexpected report origin')
+      const chunks = []
+      let size = 0
+      for await (const chunk of req) {
+        size += chunk.length
+        assert(size <= 1024 * 1024, 'Report too large')
+        chunks.push(chunk)
+      }
+      const report = JSON.parse(Buffer.concat(chunks).toString('utf8'))
+      assert.equal(report.kind, 'public-api')
+      const output = path.join(refactorDir, '.cache/reports')
+      fs.mkdirSync(output, { recursive: true })
+      fs.writeFileSync(path.join(output, 'api.json'), `${JSON.stringify(report, null, 2)}\n`)
+      res.writeHead(204).end()
+      return
+    }
+    assert(['GET', 'HEAD'].includes(req.method), 'Unsupported method')
+    if (url.pathname.startsWith('/releases/')) {
+      const [, , name, ...parts] = url.pathname.split('/')
+      const release = baseline.releases.find(item => item.name === name)
+      const member = `package/${parts.join('/')}`
+      assert(release && Object.hasOwn(release.files, member), 'Unknown release member')
+      sendBytes(req, res, readMember(archives.get(name), member), member)
+      return
+    }
+    const prefix = url.pathname.startsWith('/assets/sample/') ? '/assets/sample/' : '/fixtures/'
+    assert(url.pathname.startsWith(prefix), 'Unknown test route')
+    const dir = prefix === '/fixtures/' ? path.join(refactorDir, 'fixtures') : path.join(root, 'docs/assets/sample')
+    const filename = path.resolve(dir, decodeURIComponent(url.pathname.slice(prefix.length)))
+    const relative = path.relative(dir, filename)
+    assert(relative && !relative.startsWith('..') && !path.isAbsolute(relative), 'Invalid fixture path')
+    sendBytes(req, res, fs.readFileSync(filename), filename)
+  }
+  catch (error) {
+    if (!res.headersSent) res.writeHead(400, { 'Content-Type': 'text/plain' })
+    res.end(error.message)
+  }
+})
+server.listen(port, '127.0.0.1', () => {
+  port = server.address().port
+  console.log(`Baseline browser server: http://127.0.0.1:${port}/fixtures/api.html`)
+})
+for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => server.close())

refactor/scripts/browser-server.test.mjs

@@ -0,0 +1,50 @@
+import assert from 'node:assert/strict'
+import { spawn } from 'node:child_process'
+import { once } from 'node:events'
+import fs from 'node:fs'
+import path from 'node:path'
+import { test } from 'node:test'
+import { hash, refactorDir } from './releases.mjs'
+
+test('baseline host serves exact release bytes, media ranges and isolated routes', { timeout: 15000 }, async () => {
+  const child = spawn(process.execPath, [path.join(refactorDir, 'scripts/browser-server.mjs')], {
+    env: { ...process.env, ARTPLAYER_TEST_PORT: '0' }, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true,
+  })
+  let timer
+  try {
+    const origin = await new Promise((resolve, reject) => {
+      let output = ''
+      timer = setTimeout(() => reject(new Error('Host did not start')), 10000)
+      child.once('error', reject)
+      child.once('exit', code => reject(new Error(`Host exited: ${code}`)))
+      child.stdout.on('data', (chunk) => {
+        output += chunk
+        const match = output.match(/http:\/\/127\.0\.0\.1:\d+/)
+        if (match) { clearTimeout(timer); resolve(match[0]) }
+      })
+    })
+    const baseline = JSON.parse(fs.readFileSync(path.join(refactorDir, 'baselines/releases.json'), 'utf8'))
+    const response = await fetch(`${origin}/releases/artplayer/dist/artplayer.js`)
+    assert.equal(response.status, 200)
+    assert.equal(hash(Buffer.from(await response.arrayBuffer())), baseline.releases[0].files['package/dist/artplayer.js'])
+    const html = await fetch(`${origin}/fixtures/api.html`)
+    assert.equal(html.status, 200)
+    assert((await html.text()).includes('/releases/artplayer-plugin-chapter/'))
+    const media = fs.readFileSync(path.resolve(refactorDir, '../docs/assets/sample/video.mp4'))
+    const range = await fetch(`${origin}/assets/sample/video.mp4`, { headers: { Range: 'bytes=0-31' } })
+    assert.equal(range.status, 206)
+    assert.equal(range.headers.get('content-range'), `bytes 0-31/${media.length}`)
+    assert.deepEqual(Buffer.from(await range.arrayBuffer()), media.subarray(0, 32))
+    const invalid = await fetch(`${origin}/assets/sample/video.mp4`, { headers: { Range: `bytes=${media.length}-` } })
+    assert.equal(invalid.status, 416)
+    assert.equal((await fetch(`${origin}/fixtures/%2e%2e%2fbaselines/releases.json`)).status, 400)
+    assert.equal((await fetch(`${origin}/releases/artplayer/no-such-member.js`)).status, 400)
+    assert.equal((await fetch(`${origin}/reports/api`, { method: 'POST', headers: { Origin: 'https://example.com' }, body: '{}' })).status, 400)
+  }
+  finally {
+    clearTimeout(timer)
+    const exited = once(child, 'exit')
+    child.kill()
+    await exited
+  }
+})

refactor/tasks.json

@@ -238,6 +238,24 @@
         "baselines/releases.json"
       ]
     },
+    {
+      "id": "BASE-HARNESS-01",
+      "phase": "1 基线",
+      "title": "建立最小发布包浏览器采集夹具与服务",
+      "scope": [
+        "workspace"
+      ],
+      "dependsOn": [
+        "BASE-01"
+      ],
+      "status": "done",
+      "risk": "M",
+      "deliverable": "固定 tarball 静态服务、本地媒体 Range、公开 API 采集页面及受控报告路径",
+      "acceptance": "HTTP 精确内容/范围和路由隔离测试、夹具语法通过；浏览器采集仍由 BASE-02 负责",
+      "evidence": [
+        "changes/2026-09-10-BASE-HARNESS-01-browser-fixture.md"
+      ]
+    },
     {
       "id": "BASE-02",
       "phase": "1 基线",
@@ -246,13 +264,15 @@
         "workspace"
       ],
       "dependsOn": [
-        "BASE-01"
+        "BASE-01",
+        "BASE-HARNESS-01"
       ],
-      "status": "todo",
+      "status": "blocked",
       "risk": "H",
       "deliverable": "核心与试点的构造/默认值/静态和实例 API 快照，其余包由 01/02 步补齐；登记契约/版本/固定测试 ID/命令/报告与负责任务",
       "acceptance": "真实发布包反射与旧用户调用可重跑，未验证项明确",
-      "evidence": []
+      "evidence": [],
+      "reason": "Chrome 工具连接连续失败，重置后仍不可用；用户要求先继续其他任务。恢复连接后执行 api.html 并核对报告，HTTP 服务通过不代表浏览器通过。"
     },
     {
       "id": "BASE-03",