ci: [CI-BROWSER-01] separate source and installed browser scopes

scripts/browser-check.mjs

@@ -0,0 +1,30 @@
+import { spawn } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+import { browserInvocation, installedPackages } from './browser-validation/scope.ts'
+import { verifyInstalledArtifacts } from './installed-artifacts.mjs'
+
+const invocation = browserInvocation(process.argv[2], process.argv.slice(3), process.env)
+const artifacts = invocation.scope === 'installed'
+  ? verifyInstalledArtifacts(process.cwd(), invocation.env.ARTPLAYER_BROWSER_ARTIFACTS, installedPackages)
+  : null
+fs.mkdirSync(invocation.directory, { recursive: true })
+fs.writeFileSync(path.join(invocation.directory, 'invocation.json'), `${JSON.stringify({ scope: invocation.scope, args: invocation.args, node: process.versions.node, artifactMap: invocation.env.ARTPLAYER_BROWSER_ARTIFACTS || null, inputs: artifacts?.inputs || [] }, null, 2)}\n`)
+const child = spawn(process.execPath, ['node_modules/@playwright/test/cli.js', ...invocation.args], { env: invocation.env, stdio: 'inherit', windowsHide: true })
+let spawnError
+let interrupted
+child.on('error', (error) => {
+  spawnError = error.message
+  console.error(error)
+})
+child.on('close', (code, signal) => {
+  fs.writeFileSync(path.join(invocation.directory, 'result.json'), `${JSON.stringify({ scope: invocation.scope, exitCode: code, signal, interrupted, spawnError, args: invocation.args }, null, 2)}\n`)
+  process.exitCode = interrupted || spawnError ? 1 : code ?? 1
+})
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.on(signal, () => {
+    interrupted = signal
+    child.kill(signal)
+  })
+}

scripts/browser-validation/README.md

@@ -0,0 +1,36 @@
+# Browser validation scopes
+
+`yarn test:browser:source` runs every `test/browser/**/*.spec.js` under the normal
+three-engine configuration. The launcher clears only ARTPLAYER_BROWSER_ARTIFACTS
+from the child environment, so an installed-core map inherited from CI cannot
+mislabel source/explicit-vendor SDK tests. The caller's environment is untouched.
+Other deliberate fixture switches retain their existing meaning.
+
+`yarn test:browser:installed` requires ARTPLAYER_BROWSER_ARTIFACTS from
+`yarn test:package --include=artplayer-plugin-ambilight,artplayer-proxy-canvas`.
+Both launcher and config validate the selected four packages' installed hashes
+and source/build freshness. `scope.ts` lists the currently supported installed
+test files. This is a growing installed subset, not full ecosystem acceptance.
+Source checks remain complete when the installed list grows.
+
+`scope.ts` owns the typed scope, package/test roster, argument policy and report
+paths. The two thin Playwright configs preserve the base engine, retry, timeout
+and server settings. `../browser-check.mjs` owns preflight, child environment,
+process exit/signal forwarding and invocation/result metadata. The existing
+`yarn test:browser` entry remains available for established ad hoc commands.
+
+Reports use `refactor/.cache/browser-source/` and `browser-installed/`; one scope
+cannot overwrite the other's JSON, HTML, traces or screenshots. Archive existing
+local reports before rerunning the same scope. Invocation JSON records arguments
+and artifact identity; result JSON records the child's actual exit. Preflight
+errors occur before starting Playwright and remain in the terminal/CI tee log.
+Listing tests with `--list` is collection evidence only, not playback validation.
+Local `--grep`, file names, workers and project options are supported for diagnosis;
+config/output/report overrides and passing with zero tests are rejected.
+
+CI executes both scopes with `if: !cancelled()` and no continue-on-error. An
+ordinary source failure still permits installed evidence, while the failed step
+keeps the job failed. Both report directories upload with always(). Node/runtime
+and framework consumers keep their earlier fixed two-package scope. Full matrix
+timing, remote cancellation behavior and runner execution remain CI-01/CI-04
+acceptance items; local configuration checks do not establish those results.

scripts/browser-validation/scope.ts

@@ -0,0 +1,39 @@
+import type { PlaywrightTestConfig } from '@playwright/test'
+import assert from 'node:assert/strict'
+
+export type BrowserScope = 'source' | 'installed'
+export const installedPackages = ['artplayer', 'artplayer-plugin-chapter', 'artplayer-plugin-ambilight', 'artplayer-proxy-canvas']
+export const installedTests = [
+  'playback.spec.js',
+  'lifecycle.spec.js',
+  'initialization.spec.js',
+  'chapter.spec.js',
+  'chapter-combinations.spec.js',
+  'ambilight-lifecycle.spec.js',
+  'ambilight-proxy.spec.js',
+  'canvas-lifecycle.spec.js',
+]
+
+export function browserInvocation(scope: string, args: string[], environment: NodeJS.ProcessEnv) {
+  assert(scope === 'source' || scope === 'installed', 'Choose source or installed browser scope')
+  assert(!args.some(arg => /^(?:--(?:config|reporter|output|pass-with-no-tests)(?:=|$)|-c)/.test(arg)), 'Do not override browser scope configuration or evidence output')
+  const env: NodeJS.ProcessEnv = { ...environment, ARTPLAYER_BROWSER_SCOPE: scope }
+  if (scope === 'source')
+    delete env.ARTPLAYER_BROWSER_ARTIFACTS
+  else
+    assert(env.ARTPLAYER_BROWSER_ARTIFACTS, 'Installed browser checks require ARTPLAYER_BROWSER_ARTIFACTS')
+  return { scope, env, args: ['test', `--config=playwright.${scope}.config.js`, ...args], directory: `refactor/.cache/browser-${scope}` }
+}
+
+export function browserScopeConfig(scope: BrowserScope): PlaywrightTestConfig {
+  const directory = `refactor/.cache/browser-${scope}`
+  return {
+    testMatch: scope === 'source' ? ['**/*.spec.js'] : installedTests.map(file => `**/${file}`),
+    outputDir: `${directory}/results`,
+    reporter: [
+      ['list'],
+      ['html', { outputFolder: `${directory}/html`, open: 'never' }],
+      ['json', { outputFile: `${directory}/report.json` }],
+    ],
+  }
+}

scripts/tsconfig.docs.json

@@ -29,6 +29,7 @@
     "build-i18n.js",
     "build-docs.js",
     "../packages/artplayer-vitepress/build/**/*.ts",
-    "build-vconsole.mjs"
+    "build-vconsole.mjs",
+    "browser-validation/**/*.ts"
   ]
 }