dsh-agent-team-ui-testing 0.1.1 → 0.1.3

package/targets/web/provider.js

@@ -0,0 +1,415 @@
+/**
+ * Web P0Provider: platform side of the neutral P0 families A-E.
+ *
+ * The provider owns no protocol. It validates arguments, calls the injected `p0Dispatch`, and
+ * normalizes whatever the platform returns through the neutral factories in `core/p0.js`. That
+ * keeps CDP/DOM/screencast details out of `core/` while giving T1-T4 one stable data model.
+ *
+ * `p0Dispatch` may be:
+ * - a function: `p0Dispatch(family, method, { args, session, snapshot, signal })` (canonical), or
+ * - a per-family map `{ A: { screenshot }, B: { events } }` / `{ A: fn }` (test seam).
+ * A family the dispatch cannot serve is reported `unsupported`; it is never faked.
+ */
+
+import {
+  AdapterError,
+  CONTRACT_VERSION,
+  ERROR_CODES,
+  createEvidenceEnvelope,
+} from '../../core/index.js';
+import {
+  P0_AVAILABILITY,
+  P0_EVIDENCE_FIELDS,
+  P0_FAMILIES,
+  P0_SUPPORT,
+  createAnnotationDoc,
+  createDisplaySpace,
+  createFrame,
+  createLease,
+  createNetworkEvent,
+  createTargetIdentity,
+} from '../../core/p0.js';
+
+/** Method inventory per P0 family; mirrors M0 §3 and the shipped provider surface. */
+export const WEB_P0_METHODS = Object.freeze({
+  // `capture`/`product` are the page-capture entry points the tool layer uses (scale/region and
+  // the composited PNG product); they stay platform-shaped and skip neutral normalization.
+  A: Object.freeze(['screenshot', 'capture', 'product', 'validateImage', 'readFrame']),
+  B: Object.freeze(['start', 'stop', 'status', 'reset', 'events', 'detail', 'control', 'trace', 'evidence', 'subscribe']),
+  C: Object.freeze(['read', 'transform', 'set']),
+  D: Object.freeze(['annotationRead', 'annotationWrite']),
+  // P0-E owns target model projection and leases only; bind/close belong to the TargetAdapter.
+  E: Object.freeze(['list', 'leaseAcquire', 'leaseRelease', 'leaseStatus']),
+});
+
+/** Family -> gating capability id (web catalog). */
+const FAMILY_CAPABILITY = Object.freeze({
+  A: 'web.p0.capture',
+  B: 'web.p0.network',
+  C: 'web.p0.display',
+  D: 'web.p0.canvas',
+  E: 'web.p0.targets',
+});
+
+/** Capability ids owned by this provider; the adapter catalog is the authority. */
+export const WEB_P0_CAPABILITIES = Object.freeze(Object.values(FAMILY_CAPABILITY));
+
+const KNOWN_ERROR_CODES = new Set(Object.values(ERROR_CODES));
+
+const FAMILY_KEYS = Object.freeze(Object.values(P0_FAMILIES));
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function nullableString(value) {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function capabilityListOf(snapshot) {
+  const list = snapshot?.capabilities;
+  return Array.isArray(list) ? list.filter((id) => typeof id === 'string') : null;
+}
+
+function configRevisionOf(snapshot) {
+  const revision = snapshot?.revision ?? snapshot?.configRevision;
+  return Number.isInteger(revision) ? revision : null;
+}
+
+function toAdapterError(error, { operation }) {
+  if (error instanceof AdapterError) return error;
+  const code = typeof error?.code === 'string' && KNOWN_ERROR_CODES.has(error.code)
+    ? error.code
+    : ERROR_CODES.INTERNAL;
+  const message = error instanceof Error && error.message
+    ? error.message
+    : typeof error === 'string' && error.length > 0
+      ? error
+      : 'web p0 provider operation failed';
+  const details = { operation };
+  if (isPlainObject(error?.details)) Object.assign(details, error.details);
+  if (error instanceof Error) details.causeName = error.name;
+  return new AdapterError(code, message, {
+    details,
+    cause: error instanceof Error ? error : undefined,
+  });
+}
+
+function requireStringArg(args, field, operation) {
+  if (typeof args[field] !== 'string' || args[field].length === 0) {
+    throw new AdapterError(ERROR_CODES.INVALID_ARGUMENT, `${operation} requires '${field}'`, {
+      details: { operation, field },
+    });
+  }
+}
+
+/**
+ * Argument checks stay deliberately shallow: the provider guarantees the neutral shape, not the
+ * platform payload. Anything the platform needs to reject must surface as a platform error.
+ */
+function validateArgs(family, method, args) {
+  const operation = `${family}.${method}`;
+  if (!isPlainObject(args)) {
+    throw new AdapterError(ERROR_CODES.INVALID_ARGUMENT, `${operation} args must be a plain object`, {
+      details: { operation, field: 'args', type: Array.isArray(args) ? 'array' : typeof args },
+    });
+  }
+  if (operation === 'B.detail' && args.requestId === undefined && args.seq === undefined) {
+    throw new AdapterError(ERROR_CODES.INVALID_ARGUMENT, 'B.detail requires requestId or seq', {
+      details: { operation, fields: ['requestId', 'seq'] },
+    });
+  }
+  if (operation === 'E.leaseAcquire') {
+    requireStringArg(args, 'targetId', operation);
+  }
+  if (operation === 'E.leaseRelease' || operation === 'E.leaseStatus') {
+    requireStringArg(args, 'leaseId', operation);
+  }
+}
+
+function listFrom(raw, key) {
+  if (Array.isArray(raw)) return raw;
+  if (isPlainObject(raw) && Array.isArray(raw[key])) return raw[key];
+  return [];
+}
+
+/** Normalize a platform result through the neutral factories; never invent missing values. */
+function normalizeP0Value(family, method, raw) {
+  const operation = `${family}.${method}`;
+  switch (operation) {
+    case 'A.screenshot':
+    case 'A.readFrame':
+      return createFrame(isPlainObject(raw) ? raw : {});
+    case 'A.capture':
+    case 'A.product':
+      // Platform-shaped payloads: the tool contract owns their fields, so the provider must not
+      // re-shape them into a neutral frame.
+      return raw ?? null;
+    case 'A.validateImage':
+      if (isPlainObject(raw)) return raw;
+      throw new AdapterError(ERROR_CODES.INTERNAL, 'A.validateImage returned a non-object result', {
+        details: { operation },
+      });
+    case 'B.events': {
+      const events = listFrom(raw, 'events').map((event) => createNetworkEvent(isPlainObject(event) ? event : {}));
+      return isPlainObject(raw) && Array.isArray(raw.events) ? { ...raw, events } : events;
+    }
+    case 'B.detail':
+      return createNetworkEvent(isPlainObject(raw) ? raw : {});
+    case 'B.start':
+    case 'B.stop':
+    case 'B.status':
+    case 'B.reset':
+    case 'B.control':
+    case 'B.trace':
+    case 'B.evidence':
+    case 'B.subscribe':
+    case 'C.set':
+      return raw ?? null;
+    case 'C.read':
+    case 'C.transform':
+      return createDisplaySpace(isPlainObject(raw) ? raw : {});
+    case 'D.annotationRead':
+    case 'D.annotationWrite':
+      return createAnnotationDoc(isPlainObject(raw) ? raw : {});
+    case 'E.list': {
+      const targets = listFrom(raw, 'targets').map((target) => createTargetIdentity(isPlainObject(target) ? target : {}));
+      return isPlainObject(raw) && Array.isArray(raw.targets) ? { ...raw, targets } : targets;
+    }
+    case 'E.leaseAcquire':
+      return createLease(isPlainObject(raw) ? raw : {});
+    case 'E.leaseRelease':
+      return raw ?? null;
+    case 'E.leaseStatus': {
+      if (!isPlainObject(raw)) return raw ?? null;
+      return typeof raw.leaseId === 'string' || typeof raw.targetId === 'string'
+        ? createLease(raw)
+        : raw;
+    }
+    default:
+      return raw ?? null;
+  }
+}
+
+/**
+ * Create the web P0Provider.
+ *
+ * @param {object} [options]
+ * @param {Function|object} [options.p0Dispatch] Injected platform dispatch. Missing -> all five
+ *   families report `support: 'unsupported'`.
+ * @param {object} [options.log]
+ * @param {() => number} [options.now]
+ */
+export function createWebP0Provider({ p0Dispatch, log, now = Date.now } = {}) {
+  const manifest = {
+    contractVersion: CONTRACT_VERSION,
+    id: 'web.p0',
+    class: 'p0',
+    environment: 'web',
+    families: [...FAMILY_KEYS],
+    capabilities: [...WEB_P0_CAPABILITIES],
+  };
+
+  let disposed = false;
+
+  function assertNotDisposed() {
+    if (disposed) {
+      throw new AdapterError(ERROR_CODES.ADAPTER_DISABLED, 'web p0 provider is disposed', {
+        details: { providerId: manifest.id },
+      });
+    }
+  }
+
+  function familySupport(family) {
+    if (typeof p0Dispatch === 'function') {
+      const declared = Array.isArray(p0Dispatch.families) ? p0Dispatch.families : null;
+      return declared === null || declared.includes(family)
+        ? P0_SUPPORT.SUPPORTED
+        : P0_SUPPORT.UNSUPPORTED;
+    }
+    if (isPlainObject(p0Dispatch)) {
+      const handler = p0Dispatch[family];
+      if (typeof handler === 'function') return P0_SUPPORT.SUPPORTED;
+      if (isPlainObject(handler) && WEB_P0_METHODS[family].some((method) => typeof handler[method] === 'function')) {
+        return P0_SUPPORT.SUPPORTED;
+      }
+    }
+    return P0_SUPPORT.UNSUPPORTED;
+  }
+
+  function methodSupported(family, method) {
+    if (typeof p0Dispatch === 'function') return familySupport(family) === P0_SUPPORT.SUPPORTED;
+    const handler = p0Dispatch?.[family];
+    if (typeof handler === 'function') return true;
+    return isPlainObject(handler) && typeof handler[method] === 'function';
+  }
+
+  function callP0(family, method, payload) {
+    if (typeof p0Dispatch === 'function') return p0Dispatch(family, method, payload);
+    const handler = p0Dispatch[family];
+    if (typeof handler === 'function') return handler(method, payload);
+    return handler[method](payload);
+  }
+
+  async function invokeFamilyMethod(family, method, { args = {}, session, snapshot, signal, context = null, raw = false } = {}) {
+    assertNotDisposed();
+    const operation = `${family}.${method}`;
+    if (familySupport(family) === P0_SUPPORT.UNSUPPORTED || !methodSupported(family, method)) {
+      throw new AdapterError(
+        ERROR_CODES.CAPABILITY_UNSUPPORTED,
+        `web p0 family ${family} does not provide '${method}'`,
+        { details: { operation, family, method } },
+      );
+    }
+    validateArgs(family, method, args);
+    if (!isPlainObject(session)) {
+      throw new AdapterError(ERROR_CODES.TARGET_NOT_BOUND, `${operation} requires a target session`, {
+        details: { operation },
+      });
+    }
+    if (session.closed === true) {
+      throw new AdapterError(ERROR_CODES.TARGET_GONE, `web session ${String(session.sessionId)} is closed`, {
+        details: { operation, sessionId: session.sessionId ?? null },
+      });
+    }
+    const capabilities = capabilityListOf(snapshot);
+    if (capabilities !== null && !capabilities.includes(FAMILY_CAPABILITY[family])) {
+      throw new AdapterError(
+        ERROR_CODES.ADAPTER_DISABLED,
+        `capability '${FAMILY_CAPABILITY[family]}' is not enabled for '${operation}'`,
+        { details: { operation, capability: FAMILY_CAPABILITY[family] } },
+      );
+    }
+
+    let platformResult;
+    try {
+      // `context` carries the invocation-scoped handles the platform dispatch needs (the page
+      // runtime, the calling exec, the action meta). Dropping it made the production dispatch
+      // unusable: it could only ever answer PROVIDER_UNAVAILABLE (A01).
+      platformResult = await callP0(family, method, {
+        args,
+        session,
+        snapshot,
+        signal,
+        context,
+        // Routing facts for the composition root (§4.2): the P0 call must run on the selected
+        // provider's runtime. `null` for a snapshot that predates the provider field.
+        provider: typeof snapshot?.provider === 'string' ? snapshot.provider : null,
+        executionAdapterId: typeof snapshot?.executionAdapterId === 'string'
+          ? snapshot.executionAdapterId
+          : null,
+      });
+    } catch (error) {
+      throw toAdapterError(error, { operation });
+    }
+
+    // `raw: true` keeps the platform payload (used by the tool layer, whose public result shape
+    // is its own contract); the neutral model is the default for the neutral surface.
+    const value = raw === true ? (platformResult ?? null) : normalizeP0Value(family, method, platformResult);
+    const evidence = createEvidenceEnvelope({
+      scope: session.scopeId ?? null,
+      session: session.sessionId ?? null,
+      target: session.target?.targetId ?? null,
+      generation: Number.isInteger(session.generation) ? session.generation : null,
+      configRevision: configRevisionOf(snapshot) ?? (Number.isInteger(session.configRevision) ? session.configRevision : null),
+      operation,
+      source: 'web.p0',
+      capturedAt: typeof now === 'function' ? now() : Date.now(),
+    });
+    if (typeof evidence === 'object' && evidence !== null) {
+      for (const field of P0_EVIDENCE_FIELDS) {
+        if (!Object.hasOwn(evidence, field)) {
+          throw new AdapterError(ERROR_CODES.EVIDENCE_INCOMPLETE, `evidence is missing '${field}'`, {
+            details: { operation, missing: field },
+          });
+        }
+      }
+    }
+
+    log?.debug?.('web.p0.invoke', { operation });
+    return { value, evidence };
+  }
+
+  function buildFamilySurface(family) {
+    const surface = {};
+    for (const method of WEB_P0_METHODS[family]) {
+      surface[method] = (input = {}) => invokeFamilyMethod(family, method, input);
+    }
+    return Object.freeze(surface);
+  }
+
+  return {
+    manifest,
+
+    familyStatus({ session, snapshot } = {}) {
+      const capabilities = capabilityListOf(snapshot);
+      const out = {};
+      for (const family of FAMILY_KEYS) {
+        const support = familySupport(family);
+        if (support === P0_SUPPORT.UNSUPPORTED) {
+          out[family] = {
+            support,
+            availability: P0_AVAILABILITY.UNAVAILABLE,
+            reason: 'provider-missing',
+            capability: FAMILY_CAPABILITY[family],
+          };
+          continue;
+        }
+        if (!isPlainObject(session)) {
+          out[family] = {
+            support,
+            availability: P0_AVAILABILITY.NOT_PROBED,
+            reason: 'no-session',
+            capability: FAMILY_CAPABILITY[family],
+          };
+          continue;
+        }
+        if (session.closed === true) {
+          out[family] = {
+            support,
+            availability: P0_AVAILABILITY.UNAVAILABLE,
+            reason: 'target-gone',
+            capability: FAMILY_CAPABILITY[family],
+          };
+          continue;
+        }
+        if (capabilities === null) {
+          out[family] = {
+            support,
+            availability: P0_AVAILABILITY.NOT_PROBED,
+            reason: 'capability-unknown',
+            capability: FAMILY_CAPABILITY[family],
+          };
+          continue;
+        }
+        if (!capabilities.includes(FAMILY_CAPABILITY[family])) {
+          out[family] = {
+            support,
+            availability: P0_AVAILABILITY.UNAVAILABLE,
+            reason: 'capability-disabled',
+            capability: FAMILY_CAPABILITY[family],
+          };
+          continue;
+        }
+        out[family] = {
+          support,
+          availability: P0_AVAILABILITY.AVAILABLE,
+          reason: null,
+          capability: FAMILY_CAPABILITY[family],
+        };
+      }
+      return out;
+    },
+
+    capture: buildFamilySurface('A'),
+    network: buildFamilySurface('B'),
+    display: buildFamilySurface('C'),
+    canvas: buildFamilySurface('D'),
+    targets: buildFamilySurface('E'),
+
+    async dispose() {
+      if (disposed) return;
+      disposed = true;
+    },
+  };
+}

package/skills/ui-testing/references/scenarios/annotations.md

@@ -1,87 +0,0 @@
-# 读取面板标注（P0-D annotations）
-
-用户说「看我标的」「我圈的是哪里」「这个箭头指的是什么」时用本页。标注是**用户在调试面板里画的问题线索**，Agent 通过结构化文档读取，不通过截图。
-
-## 1. 唯一读取入口
-
-- `browser_state()` 返回顶层 `annotations`（每个**工作区**一份，与已认证 `/state` 的 `ui.annotations` 同源；旧 Host 无此字段 → 按 `unsupported` 处理，不要假装读到）。
-- `browser_capabilities()` 的 `annotations` 段声明读取方式、`space`（恒为 `canvas-css-px`）与 `limits`；**工具面仍是 30**，没有"标注工具"可调。
-- **标注不进截图、也不进 T3**：`browser_screenshot` 的 `capture.composite:true` 只表示"页面帧合成到白画布"，与标注无关。若在截图里找不到用户画的线，这是设计如此，不是 bug。
-
-## 2. 文档形状
-
-```
-annotations = {
-  version: 1, space: 'canvas-css-px', revision, updatedAt,
-  source:  { kind:'human-panel', panelId, surface:'main'|'sidebar', clientRevision, trusted:false },
-  context: { runtimeId, pageGeneration, documentEpoch, documentKey, addressDigest },
-  view:    { canvasX, canvasY, x, y, width, height, scale, contentWidth, contentHeight, viewRevision, frameEpoch },
-  shapes:  [...], truncated, truncation:{droppedShapes,droppedPoints,shortenedTextCodeUnits},
-  stale, staleReason
-}
-```
-
-- `source.trusted` **恒为 false**：标注是线索，不是页面事实。
-- `view` 是**发布那一刻**的客户端视图快照；`context.documentKey` 是文档身份，导航/刷新会轮换并清空（v3 起跨页签/跨会话保留，见下）。
-
-## 3. 图形与字段
-
-| `type` | 字段 | 备注 |
-| --- | --- | --- |
-| `rect` | `x,y,width,height` | 左上角 + 尺寸 |
-| `circle` | `cx,cy,rx,ry` | PS 默认语义：按下点与落点为**包围盒两角**的内接椭圆，不是"中心+半径" |
-| `line` | `x1,y1,x2,y2` | |
-| `arrow` | `x1,y1,x2,y2,head:{length,width}` | **尖端 = `(x2,y2)`**；`head` 由 Host 按 `min(3t,L)/min(2t,L)` 重算，不可信客户端 |
-| `brush` | `points:[[x,y],...]` | 只有点集 |
-| `text` | `x,y,fontSize,text` | 唯一带**原文**的类型（≤200 UTF-16 code units） |
-
-形状还带 `id`（`a1`、`a2`…）、`color`、`strokeWidth`、`fill`、`stroke`。
-
-## 4. 坐标换算（最容易错的一步）
-
-- shapes 存的是**画布 CSS px `d`**；页面坐标 `p = d − S`，`S` 是**当前** `view.x/y`。
-- 面板侧另有 `q = d − C`（`C = canvasX/canvasY`）；两者关系 `p = q + O`、`O = C − S`。
-- **必须用当前 `view` 换算**，不要用 `annotations.view`（那是发布时快照，`C`/`scale` 可能已经变了）；`scale`（显示比例）与 DPR **不参与**坐标变换。
-- 空白区（`O≠0` 时视口露出的部分）同样可画、可读；`d` 允许负值。
-
-## 5. 能读到什么、读不到什么
-
-- **只有 `text` 有原文**。用户用**画笔手写**的字只有 `brush.points`，没有语义——不要"读"出手写内容，也不要把点集当文本转述。
-- 需要 Auxiliary 视觉时，可以按 `points` 自己渲染成图辅助人工核对，但必须声明"这是按点集重建的几何，不是面板渲染结果"。
-
-
-## 6. 落点解析：「这个箭头指的是什么」
-
-1. 取端点 → `p = d − S` 得到页面点。
-2. `browser_eval` 命中：`document.elementFromPoint(p.x, p.y)`；再枚举同区域可见元素，按**点到矩形边距**排序，得到候选表。
-3. 手绘尖端常偏 10–20 px：**给候选 + 距离**（例如"搜索框容器 2 px、标签栏 3 px、logo 22 px"），不要单点断言"就是它"。
-4. 需要更多证据时：`browser_snapshot` + `browser_node_state` 取 AX 语义/状态；`browser_vision_image` 放大该区域**看页面像素**（仍不含标注）做人工复核；需要记账时把结论写成 `browser_vision_check` 的 `facts`，别用像素推断冒充 DOM 事实。
-
-## 7. 生命周期与隔离（v3）
-
-- 文档按 `documentKey` 绑定：**导航/刷新/换文档会清空**；同一工作区内切页签、重挂面板、换会话**保留**（客户端按文档身份水合）。
-- **按工作区隔离**：不同工作区各有一份，互不串；读取时用当前会话的 `browser_state` 即可，不要跨工作区拼装。
-- `stale:true`（`panel-unseen`）表示来源面板心跳过期，**不代表标注不存在或已删除**：形状照常可读，如实说明"可能不是最新"即可；不得伪造心跳或 revision。
-- 显式「清除画布」会让 `shapes` 变空（`revision` 递增），不要把它当成"读取失败"。
-
-## 8. 红线
-
-- 标注是 `trusted:false` 的**问题线索**：不构成缺陷证明，也**不授权**按它自动点击/提交（要动页面仍需用户明确许可）。
-- 不要用标注内容替代交叉验证：结论至少要落到 DOM 读回、截图或网络证据之一。
-- 不要为了"看起来有标注"而伪造 `annotations` 字段、revision 或截图。
-
-## 9. 常见坑
-
-| 坑 | 正确做法 |
-| --- | --- |
-| 把 `brush.points` 当文字转述 | 只有 `text` 有原文；手写只说"笔画"，必要时提议用户改用文字工具 |
-| 用 `annotations.view` 换算坐标 | 用当前 `view.x/y`（`p = d − S`） |
-| 以为截图/T3 里有标注 | 没有；走 `browser_state.annotations` |
-| 按 `scale` 缩放坐标 | `scale` 只影响显示与截图密度 |
-| 把箭头 `(x1,y1)` 当尖 | 尖端是 `(x2,y2)` |
-| 把 `stale` 当"数据没了" | 只是心跳过期，形状仍可读 |
-
-## 10. 参考
-
-- 权威契约：`docs/viewport-control.md`（共享视口、画布与标注）
-- 验收入口：`tests/acceptance/viewport.mjs`、`tests/acceptance/viewport-gui.mjs`