ArtPlayer/refactor/changes/2026-09-11-CORE-20-entry.md

# CORE-20 核心入口与依赖收敛

## 范围与状态

从 ccf77c4e 开始，CORE-20 源码及任务验收完成；下文保留阶段实施过程。上一任务已独立提交并验证，工作区开始时干净。覆盖剩余 13 个自有 JS：公共入口、Player 安装与 option 初始化、config/storage、DOM/环境工具和六个属性 mixin。screenfull 为登记的第三方文件，遵循来源与许可规则。完整迁移、严格类型、旧接口/描述符/静态/事件差分、构建和安装产物验证完成前不标 done，也不提前提交任务完成 commit。

API-01/02/03/04/05/07/08/09/10/11/12 均相关。保留构造顺序、属性安装顺序、静态字段可写性与求值时机、实例收集、就绪回调 this、导入样式/global/日志副作用。公共类型精确视图由 CORE-21 收敛，不能用全局 any 索引绕过入口检查。

## 实施顺序与边界

先迁移叶层属性、storage 和环境判断；按职责拆分 DOM 查询/树操作、样式、事件路径与布局测量，utils 保留兼容导出。然后类型化 config 与 optionInit，明确初始化依赖及失效边界；最后将 Player 和 Artplayer 门面接入已迁移子系统，复核断言是否确实只存在于动态属性安装和旧媒体扩展边界。

Storage 必须先保留 artplayer_settings 信封、name/settings 可观察字段、同步返回及错误 fallback。attr 的动态属性访问、cssVar 的 truthy 判定和 poster 解析也属于历史事实，不能在补类型时顺手规范化。发现缺陷先复现登记，再记录兼容修正。

## 验收与交接

复用既有 Node/类型/浏览器/真实 tarball 入口，新增测试只覆盖未覆盖的行为、失效与重入。普通显示与媒体流程继续使用真实浏览器，AirPlay 等实体设备能力不能以受控对象证明。各阶段结果如实记录，不将上个候选的完整矩阵当作当前代码证据。

本任务可使用已有工具链；新增依赖或脚本时记录用途和固定版本。完成后独立本地提交 CORE-20，不推送或发布。回退只撤销本任务并重建对应产物，保留 CORE-19 已交付功能。

## 叶层与 DOM 阶段

已迁移 storage、compatibility 及 attr/cssVar/type/theme/poster 五个 mixin；保留动态属性访问、undefined getter、truthy CSS 写入、原媒体/样式目标捕获、poster 引号解析和同步描述符。Storage 使用 unknown 表示未校验的历史 JSON 读取；没有把既有错误 fallback 改成无记录的新持久化策略。

环境测试从发布包复现自定义 iPhone/Macintosh UA 的 SSR ReferenceError。候选增加缺失全局保护，同时保留自定义 UA 的优先级与 navigator 惰性访问。该异常修复的完整候选入口/安装产物验证仍待完成，BASE-ENV-02 保持 open。

utils/dom 迁移并拆为 tree/styles/event-path/measure/presentation，公开 utils 仍是原导出集合。初次严格检查暴露 23 个隐含节点类型假设；设置内已知 DOM 复用 appendElement，Map.has 后的缓存和已挂载模板节点使用局部断言，没有把所有返回扩大为 any 或强行宣称 public append 永不为空。

事件路径无 window 时的 ReferenceError 已由发布包复现。安全区测量失败后泄漏探测节点则来自 CORE-19 工作区；最初误以 npm 基线也有该 helper，Node 检查指出 getSafeAreaInsets 不存在，已更正来源。test/helpers/legacy-safe-area.js 是从 ccf77c4e 原函数逐字提取的自有代码夹具，注明函数 SHA-256；浏览器服务也登记其来源与哈希。不依赖浅 clone 中的 Git 历史来运行回归，不将该夹具当作生产实现。

新增 Node 边界检查覆盖 Storage 信封/JSON/异常、属性转发、环境 flags/SSR、DOM 字符串与节点、原始样式值、事件路径和安全区 finally 清理。浏览器专项复验原生树/样式/事件与探测节点清理，同时复用设置、模板和方向场景。此阶段不生成或验收正式 tarball，最终仍需完成剩余初始化与入口源码。

叶层/DOM 历史阶段已完成 CI 436 项（407 单元 + 4 工程 + 25 基线）、220 个生产 TS 检查与 180 项源码 UMD 三浏览器专项，见 baselines/entry-leaf-dom-partial.json。该证据固定当时源码；后续初始化改动不能沿用它作为全量候选验收。

## 初始化与配置阶段

媒体 config 迁移 TS，公共数组仍可修改，保持顺序。optionInit 保持属性、静音、配置音量、持久音量、poster、autoplay、inline、theme/CSS、url 的顺序；在 getter、原生 setter、storage 和样式回调后检查销毁，阻止后续写入。原函数与 AirPlay 函数从 ccf77c4e 冻结成自有测试夹具，仅调整 utils 相对导入，注明原文件 SHA。

六项 Node 测试比较原初始化顺序和八个销毁重入边界，并验证属性 getter、AirPlay 可用性/接收者/事件/错误和销毁后的 picker/notice。候选均通过；AirPlay 的真实连接设备仍需环境矩阵验证。新增内部类型夹具明确 raw storage unknown、append 可空以及 mutable config；公开声明未改。BASE-LIFE-46/47 保持 open，等待两个入口及完整出口验证。

初始化阶段 `yarn ci:check` 已通过：442 项（413 单元、4 工程、25 基线），223 个生产 TS 文件严格检查（核心 218 + chapter 5）。日志为 `refactor/.cache/core20-initialization-ci.log`。本任务已迁移 11 个原有 JS，自有 JS 尚余 Artplayer 与 Player 两个入口；当前改动尚未作为完成任务提交，后续仍需最终构建、安装产物与全量浏览器验收。

## Player 安装与构造取消阶段

player/index.ts 将原 35 个步骤保留在一个有类型的安装表中，Player 实例仍无自有字段、构造参数个数为 1。PlayerHost 从各拥有模块的参数推导安装依赖，包含安装期间提供、稍后回调才读取的能力；不将其当成所有构造阶段已初始化的证明。Artplayer 入口暂仍为 JS，现已在子系统之间检查关闭状态；公共字段仍在各自构造返回后赋值，未提前填充 undefined 字段。Storage 原本不接收参数，入口移除未使用实参。

内部接线修正 PiP 读取类型为真实 element/null/boolean、写入仍为 boolean；初始 native/proxy autoplay 和 URL 视图保留可选能力及 nullable URL。续播记录在读取处明确历史 JSON 形状假设，不再要求所有 Storage.get 返回已校验对象。公开 types 目录未改。

新增浏览器对照确认正常实例属性描述符顺序、原型/静态形状和构造 arity 保持；发布核心在初始 volume setter 销毁后仍安装插件并登记实例，候选现在停止。能力 getter 销毁也会停止后续 Player 安装。最初夹具使用 layers 工厂被既有 schema 拒绝，已改成合法对象，不能把该夹具错误当生产回归。扩大用例后发现 AirPlay 检测内部仍会继续读取/定义，进一步在能力 getter、picker getter 和监听注册返回后检查关闭；新 Node 用例与冻结函数对照。

proxy 在 art.template 赋值前同步销毁的检查，首先在当前候选 Chromium 复现：removeHtml=true 仍残留 DOM；false 未标记 art-destroy；返回的 proxy 仍被挂载和改类名。失败报告 core20-mounting-before.json 固定当时 bundle 指纹。现在 lifecycle 仅在模板构造期间保留私有清理引用，destroy 事件前执行对应 DOM 清理，finally 清除引用；proxy 回调结束发现关闭即停止，不再处理其返回节点。没有提前暴露 art.template，也不替调用方释放其新建 proxy。正常挂载、初始化失败回滚和后续容器复用一并复验。

此阶段 CI 445 项通过（416 单元、4 工程、25 基线），224 个生产 TS 严格检查（核心 219 + chapter 5）；核心剩余一个自有 JS 总入口。同一源码 UMD 三浏览器 105 项初始化/生命周期/配置/模板回归，加上新增销毁回调内重建实例的 3 项检查，共 108 个唯一用例（其中初始化专项 24 项）；无重试、跳过、意外 pageerror。见 [阶段指纹与报告](../baselines/entry-player-partial.json)。两份成功报告均记录相同候选 bundle 哈希，不是安装包验收。BASE-LIFE-48/49 登记模板挂载和跨阶段取消差异，全部七项 CORE-20 风险保持 open，等待最终出口。

接续重点：src/index.js 迁移必须给真实子系统组合提供类型证明，不能将 PlayerHost 的安装依赖交叉类型当成完整实例实现。Template 保留缺失 SSR 节点可空的实际语义；Canvas proxy 与 native video 能力不同。外部旧回调类型、内部 UI callback this、Emitter 的开放事件和模块 Host 的窄事件需要在组合处协调。不要通过全局 any 或整个实例的旧声明断言跳过这些边界。完成后再处理最终构建、安装包、自定义 UA SSR、全量浏览器与本任务独立 commit。

## 完整入口与类型接线

src/index.ts 已迁移，player/properties.ts 单独描述实际安装的读写属性和方法，不再把模块输入交叉类型当作实例实现。URL 先按实际泛型 Host 安装，再运行原顺序中的其余 34 步。Artplayer 与 Icons 的 declaration-only interface 合并明确登记为动态描述符边界，避免 class fields 提前创建或遮蔽属性；每个子系统均用实际 Artplayer 类型检查。公开 class/prototype/静态值仍按原顺序创建，bootstrap/browser.ts 负责全局发布、样式注入与 100ms 版本日志。

组合检查修正了旧模块视图中的实际不一致：只写 seek/quality/forward/backward 读取为 undefined；metadata 之前 fullscreen 可缺失；PiP 读取为 element/null/boolean；notice 显示 getter 为 boolean，写入使用 NoticeSink；字幕图标可缺失，quality html 支持 HTMLElement。事件使用开放的 CoreEvents 和按名称约束的 CoreEmission，保留原 Emitter 实现；窄接口中的媒体事件补上真实 Event payload。五个内置插件去除整段 unknown factory casts，直接检查实际 host。Storage 的原始读取和续播局部历史记录假设维持分离。

保留两处有名称、可审查的输入兼容边界：option/runtime.ts 将旧声明中的回调视图接到实际模块，不包装函数或改变 this/对象身份；PlayerTemplate 只对核心消费者所需的 SSR 节点和 media-like proxy 标明既有预期，断言局限在模板赋值处。未使用的可省略 SSR 节点继续可空；不添加提前拒绝或合成节点。它们不是对所有任意 JS 输入的运行时证明，公开消费者声明仍留 CORE-21 独立收敛。

test/types/entry-source.ts 检查真实入口满足 Player/Builtin host、参数和读写语义的正反例。根 tsconfig 纳入已有资源声明，使类型夹具能导入带 SVG/LESS 的完整源入口，没有启用 ambient Node 或 skipLibCheck。test/entry.test.js 使用仓库构建配置生成完整 UMD，在隔离服务端环境验证自定义 UA、惰性 navigator、无定时器/DOM 副作用和构造错误；build helper 提取编译入口并保留原 ES loader。类型和 SDK 台账中的当前路径同步至 index.ts/option/resolve.ts，历史快照不改写。

最新 CI 447 项、229 个生产 TS 严格检查、五组原声明消费者通过；完整入口源码 UMD 36 项三浏览器专项通过，覆盖正常描述符/静态、子类、回调身份、可省略 SSR 节点和构造销毁。旧阶段报告不沿用为当前候选证据。

## 安装包验收进行中

生产构建及语言生成通过。run-v40AgV 实际 tarball 已通过 29 项运行时、五组类型。新增安装 UMD/legacy 与直接 ESM 自定义 UA SSR；baseline 模式显式断言旧 ReferenceError，候选必须成功，负例证明旧包不能冒充候选通过。初次 ESM 夹具误认为 Node 24 没有 navigator，Macintosh 预期拒绝未发生；现在明确暂时移除并 finally 恢复 navigator，保证这个 profile 测试的是无 browser/navigator 环境，不把环境差异当包回归。具体诊断与修正日志分别为 core20-package-gates.log / core20-package-gates-fixed.log。

安装包全量 UMD/legacy 浏览器矩阵尚未完成，全部七项 CORE-20 风险仍保持 open。无依赖/锁文件/公开声明/版本变更，未推送或发布；待最终出口完成后独立提交本任务。

## 最终验收与交接

本任务源码和完整验收已完成；上面的 doing、待迁移和待验收描述保留分阶段历史。

固定 Node 24.21.0 / Yarn 1.22.22。核心全部 224 个自有 TS 文件和 chapter 5 个生产文件严格检查；只保留已登记第三方 libs/screenfull.js。CI 447 项通过（418 单元、4 工程、25 基线），另显式检查新增浏览器、内部类型、冻结夹具及安装包脚本的 lint。公开 types 和 yarn.lock 未改。

run-v40AgV 实际 tarball 的 29 项运行时、五组消费者类型检查通过；安装 UMD/legacy 分别在 Chromium 153.0.8010.12、Firefox 155.0、WebKit 26.6 完整通过 1503 项，各含 45 项 DOM/初始化专项。无重试、跳过或意外页面错误；已知旧续播/截图拒绝精确登记。完整入口、子类、实例描述符/静态形状、正常事件和生命周期均复验。

[最终证据](../baselines/entry-validation.json) 将全部当前核心源码对照隔离构建快照，再核对包内全部文件、UMD/legacy/ESM、docs 副本、22 个语言文件和第三方许可。每个浏览器用例均校验实际加载的核心与 chapter 安装文件 SHA；源码专项和两个中间阶段快照不能代替该最终产物证据。

关闭 BASE-ENV-02/03 和 BASE-LIFE-45 至 49，共七项。BASE-ENV-01 的 Windows WebKit Blob 解码、真实 Safari/Apple/AirPlay 设备与其他外部集成仍交对应发布任务。CORE-21 继续负责准确公开视图和历史声明的协调，不用虚假的交叉返回或改变运行时掩盖冲突。

结构、类型、兼容、测试、文档和交接证据已齐；本任务以独立本地 commit 交付。当前 214 项：56 完成、158 待办。下一任务 CORE-21 生成既有入口声明并校验包内容；从 src/index.ts、src/option/runtime.ts、src/player/properties.ts、types/ 及 test/types/declaration-legacy.ts 开始，逐项处理 BASE-TYPE-04/05/07/08/09/10，并复核运行时可变的 option 和媒体能力视图。两个局部输入断言的边界已记在包内 ARCHITECTURE.md，不能将其误当任意 JS 输入的验证。

最终另轮审查对照了生成 ESM 的实际差异：DOM/helper 移动和已登记修正、AirPlay 接收者与异常、35 个 Player 步骤顺序、原样回调传递、声明字段不生成实例属性、模板私有挂载清理以及 browser bootstrap 的原样式参数和延时日志。已知运行时差异均有记录及测试。提交主题：refactor(core): [CORE-20] type entry and converge initialization。

没有新增依赖、锁文件或版本变化，没有推送或发布。回退只撤销本任务源码、测试、文档/状态及构建生成产物，保留 CORE-19 及之前交付；下一任务开始前先核实本任务提交。