#Page Context 字段与生命周期

Page Context 是 Test Kit 在浏览器渲染完成后生成的有界事实记录。它补充组件归属、源码提示、稳定定位器、多坐标空间几何和 UI 理解证据，并与浏览器可访问快照绑定成同一次观察。

Test Kit 是增强项。没有它，A3S Test 仍能依据浏览器可访问语义执行 Web 动作、断言和证据采集。需要组件、坐标、布局图、渲染态样式或人工点选时，再接入 Page Context。

#为什么需要 Page Context

浏览器中的任何单一表示，都不能回答编码 Agent 需要知道的全部问题。

Page Context 是填补这些缺口的最小共享记录。它不替代浏览器，也不依赖框架私有状态，而是在渲染后提取事实、限制范围和大小、绑定单调修订，并把源码信息明确标为证据而不是修改权限。

#三类浏览器事实如何配合

浏览器完成样式计算与布局
        |
        +--> 可访问快照     角色、名称、原生状态
        |
        +--> Page Context   组件、定位器、几何、受控 facts
        |
        +--> UI 理解        样式、布局、重复结构、状态、动效
                         |
                         v
             同一观察编号与页面修订

UI 理解是 Page Context 中可选的嵌套记录。它不生成另一棵可访问树，也不会根据类名猜组件类型。

#Bridge 能做什么

页面通过非枚举的 Symbol 暴露 a3s.test.page-context/1 bridge。业务代码通常只需挂载 provider，A3S Test 的浏览器驱动会完成探测和快照读取。需要在开发工具或自有集成中检查时，可以使用框架无关入口。

import { getPageContextBridge } from '@a3s-lab/testkit';

const bridge = getPageContextBridge();
if (!bridge) throw new Error('Test Kit is not enabled');

const summary = bridge.snapshot({
  detail: 'summary',
  scope: { kind: 'page' },
  limits: { nodes: 300, uiNodes: 120 },
});

const diff = await bridge.waitForDiff({
  sinceRevision: summary.revision,
  timeoutMs: 5_000,
  ui: false,
});

Bridge 不提供 eval、Cookie、浏览器存储、任意网络请求、文件系统或 Shell。

#按任务选择快照

#明细级别

#范围

范围只能引用当前修订上的私有身份。A3S Test 对外投影为观察绑定的 @cN，调用方不应持久化 nodeId。

#快照字段

每次响应都包含 protocol、sdkVersion、revision、page、components、nodes、facts、可选 ui、可选 delta、removedNodeIds、truncated 和 nextCursor。

#页面字段

#组件字段

A3STestBoundary 可以为页面增加以下信息。

边界是可选的。没有 A3STestBoundary 时，自动 DOM、开放 Shadow DOM、语义、定位器与几何采集仍会运行。

#节点字段

定位器候选优先顺序为角色与名称、label、test ID、placeholder、文本和 CSS。几何用于证据与最后退化，不能因为坐标存在就跳过语义定位。

#渲染节点源码映射

sourceMapping 使用 a3s.test.source-mapping/1 协议，最多返回八个去重后按置信度降序排列的候选。

框架适配器通过 registerSource 声明归属，需要时再调用 registerSourceMap。A3STestBoundary 可以提供更粗粒度的 source 或 generated 提示。用户明确发送 finding 后，点选节点会把同一份映射带入 repair context，从而减少一次浏览器探索。

Test Kit 不检查 React Fiber、Vue 实例或其它框架私有状态，也不会自行发现或下载 Source Map。它只接受显式注册的扁平编码 Source Map v3，并在进入运行时存储前丢弃 sourcesContent。Web 驱动会再次拒绝不支持的协议、非法跨度或置信度、未排序或重复候选，以及不一致的截断信息。

#几何和缩放

每个有渲染盒子的节点最多包含三套矩形。

normalized 值可以小于 0 或大于 1，这表示盒子位于当前可见缩放区域之外。page.viewport.width 和 height 始终表示布局视口 CSS 像素。DPR 与可选 visual viewport 的偏移、尺寸和 scale 单独记录，不会把 CSS 像素乘成设备像素。

几何还包含 visibleRatio、occluded、position、transformed 和最近的 scrollContainerNodeId。固定与 sticky 元素不会被误写成普通文档位置，多根组件使用 boxes 保留真实边界。

#UI 理解记录

a3s.test.ui-understanding/1 记录浏览器已经计算出的视觉事实。

布局节点会分别保留物理 margin、border width、padding、boxSizing、writingMode 和 direction。这些字段说明浏览器结果，不推测逻辑布局意图。

UI 记录有独立 observationId。焦点、悬停或运行中的动画可能改变计算样式，但不一定改变页面语义修订。它的 pageRevision、viewport 和 scope 仍必须与外层 Page Context 完全一致。

重复结构不会把类名当作组件真相。状态采集不会主动移动焦点或派发事件。跨域样式表不会绕过浏览器限制，只会增加 inaccessibleStyleSheets 计数。

#修订、精确差异与公开引用

MutationObserver、ResizeObserver、路由、视口、滚动和相关表单变化会推进单调修订号。页面不变时不会轮询。A3S Test 会把浏览器可访问快照与 Test Kit 修订原子绑定，组装观察期间页面再次变化时会直接拒绝竞态。

从第一性原理看，规则不应该是“每次编辑后丢掉整页”，而应该是“只丢掉已经无法证明仍然有效的证据”。Test Kit 0.6.0 通过 a3s.test.page-context-diff/1 实现这条规则。

{
  "delta": {
    "protocol": "a3s.test.page-context-diff/1",
    "fromRevision": 42,
    "toRevision": 43,
    "status": "complete",
    "invalidated": {
      "all": false,
      "page": false,
      "facts": false,
      "ui": true,
      "nodeIds": ["n12"],
      "componentIds": ["checkout-form"]
    }
  }
}

• complete 只返回变化节点和组件，列出每个变化或消失的私有节点 ID，并分别标记 page 与 facts。修订一旦推进，UI 证据一定失效，因为几何、样式、状态和动效都绑定原修订。
• 同修订的 complete 是没有任何变化的空差异。
• reset_required 表示精确 baseline 已不在历史中，或完整失效元数据无法装入字节预算。它会声明全部失效，不返回容易误解的部分 ID，并要求调用方重新获取非 diff baseline。

运行时最多保留八种标准化 projection，每种保留十二个修订。projection 由 semantic 或 forensic 明细、标准化 scope 和字符串预算共同决定。diff 分页始终使用同一个 baseline。opaque cursor 还会绑定 detail、scope、baseline、UI 选择、全部标准化 limit 和当前修订；任何错配或过期都会明确拒绝，不会偷偷回到第一页。waitForDiff 的 timeoutMs 必须是 0 到 300,000 的整数，非法值和未来修订会直接拒绝，不会 clamp。

Web adapter 会在 Rust 中再次校验协议、修订顺序、UTF-8 ID 顺序、唯一性、大小、changed/removed 互斥和失效集合完整性。因此 Core 只能保留未受影响 @cN 背后的稳定定位器，任何不确定目标都会关闭失败。

A3S Test 仍会拒绝来自更早 A3S 观察的引用。在最新观察内部，只要 delta 缺失、返回 reset_required、绑定来自旧版协议、目标变化或消失、修订倒退，相关 @cN 就会在输入前被清除或拒绝。这个例外只用于稳定定位，不允许复用截图、坐标或 UI 证据。

#预算、截断与分页

安装级配置确定上限，每次 snapshot() 请求只能继续降低，不能提高。

返回 truncated: true 时，检查 nextCursor 并使用完全相同的请求与修订继续读取。页面变化，或 detail、scope、baseline、UI 选择、limit 任一变化后都不能复用 cursor。

UI 记录还有自己的 budget.used、truncated 和原因列表。如果 UI 投影无法同时满足图完整性和编码预算，A3S Test 会省略这块可选记录，保留外层语义观察。它不会为了塞进预算而返回断边、循环关系或私有身份。

单次不需要 UI 证据时使用 snapshot({ ui: false })。整个安装都不需要时设置 uiUnderstanding={false}。

#隐私和宿主边界

运行时不会序列化以下内容。

• password 和 hidden input 的值。
• Cookie、localStorage、sessionStorage、请求头和 token。
• React、Vue 或 Svelte 的任意 props、state、fiber、闭包和内部对象。
• redact 选择器覆盖的文本。
• 跨域 iframe 内容和跨域样式规则。
• summary 模式下的完整 computed style。

私有节点 ID 存在 WeakMap 侧表中。Test Kit 不会把 ID、坐标、组件归属或源码路径写进业务 DOM 属性。facts 只接受项目主动返回的 JSON 值，并经过相同的深度、键、字符串和编码限制。

#常见问题定位

继续阅读接入 Web Test Kit完成安装，或查看人工评审与修复了解 Page Context 如何随明确发送的问题进入修复验证。