dsh-agent-team-ui-testing 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,193 @@
-# Temporary Holding Version
+# dsh-agent-team-ui-testing
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="banner.png" alt="dsh-agent-team-ui-testing — multi-platform GUI automation testing for DeepSeekHarness" width="100%">
+
+**AI-native frontend GUI testing for DeepSeekHarness.**
+
+Let AI agents operate, inspect, test and verify real user interfaces — with evidence humans can review.
+
+**English** | [简体中文](README_zh.md)
+
+> **Status: pre-release.** The Web/Chromium channel is implemented across all four tiers: 36 agent tools plus a debug panel for programmatic inspection, structured GUI actions, static visual analysis, dynamic frame/timing analysis, network capture, multi-tab page groups, shared viewport control, a hybrid canvas, an element picker and client-side annotations. Other environments are planned and stay disabled in the runtime picker. **Install:** `dsh plugin --profile web add dsh-agent-team-ui-testing`. Capabilities, limits and verification are documented in [docs/capability-tiers.md](docs/capability-tiers.md) and [docs/verification.md](docs/verification.md).
+
+## What is this?
+
+**dsh-agent-team-ui-testing** is a UI testing infrastructure plugin for [DeepSeekHarness (DSH)](https://github.com/deepseek-ai/deepseek-harness). It lets an AI agent — or a coordinated Agent Team — drive a real application, inspect what the application exposes, verify expected behavior, collect reviewable evidence and report actionable failures.
+
+The runtime is built around a shared Chromium instance with one isolated page per DSH workspace, a typed tool surface, and a human-facing debug panel. The same session can be inspected programmatically, operated through structured DOM/accessibility data, captured as screenshots, or analyzed visually.
+
+The project grows out of the earlier `dsh-agent-team-browser` idea. The shared browser workspace remains the first adapter of a broader, capability-aware UI testing runtime.
+
+## Why build it?
+
+Coding agents can produce UI code without being able to answer: **“Does the finished application actually work and look right?”** A 200 response, a running process or a single screenshot is not proof of a working user journey.
+
+This project focuses on:
+
+- **Real UI feedback** — exercise user journeys on rendered interfaces, not only source code.
+- **Structured-first automation** — prefer APIs, DOM and accessibility data; use vision when structure is insufficient.
+- **Evidence-based results** — record what ran, what was observed, what passed, what failed and what remains unverified.
+- **Human control** — authorized access, scoped sessions and a panel humans can watch or take over.
+- **Low disruption** — prefer background browser operations over hijacking the desktop foreground.
+
+## What works today
+
+- **Shared browser runtime** — one Chromium per host (the system Chrome/Chromium binary; the plugin does not bundle or install a browser), headless by default with an optional headed mode in the Web view (off-screen hidden window + persistent profile); each DSH workspace gets its own page, URL, viewport, history, network buffer and lease. Cookies and storage are shared by the active Chromium profile.
+- **36 agent tools** across programmatic, structured GUI, static vision, dynamic behavior, network debugging and per-workspace tab management.
+- **Multi-tab page group (P0-E)** — each workspace keeps a primary page plus up to three child tabs, with per-tab leases, per-agent tab selection and popup adoption kept under the same isolation rules.
+- **Dynamic behavior (T4)** — real CDP screencast plus a screenshot-loop path, a bounded frame store with integrity counters, seven deterministic motion analyses, WAAPI motion control with restore, region-only frame delivery, and six-direction frame↔network event correlation.
+- **Debug panel** — live preview, responsive size controls, shared viewport state, a hybrid canvas, and a client-side annotation layer that agents can read back.
+- **Element picker** — select an element in the panel preview to append its node description to the chat as an `@` reference chip; the model receives the full text block and the page is not modified.
+- **Evidence and safety** — typed errors, structured action evidence, validated PNG capture, managed visual baselines, network evidence and optimistic concurrency for shared state.
+
+### Agent tools
+
+| Group | Tools | What it covers |
+| --- | --- | --- |
+| **Programmatic** (10) | `browser_navigate` `browser_eval` `browser_screenshot` `browser_input` `browser_network` `browser_computed_style` `browser_http_request` `browser_viewport` `browser_state` `browser_capabilities` | Navigation, JavaScript, console/network inspection, independent HTTP requests, computed styles, screenshots, raw mouse/wheel/keyboard input, shared viewport state and capability reporting |
+| **Page group** (1) | `browser_tabs` | Primary + up to three child tabs per workspace, per-tab leases, agent tab selection and tab lifecycle (list/current/select/open/close/wait) |
+| **Structured GUI** (7) | `browser_snapshot` `browser_click` `browser_type` `browser_scroll` `browser_fill_form` `browser_node_state` `browser_wait_for` | Snapshot → ref targeting, trusted input, forms, node state and waits, with structured evidence and typed errors |
+| **Static vision** (6) | `browser_vision_image` `browser_vision_find` `browser_vision_compare` `browser_vision_act` `browser_vision_baseline` `browser_vision_check` | Crop/zoom/preprocess/annotate PNGs, deterministic colour/component/edge/template finders, YIQ diff, coordinate input, managed baselines and visual assertions |
+| **Dynamic** (5) | `browser_dynamic_session` `browser_motion_observe` `browser_motion_analyze` `browser_motion_control` `browser_dynamic_correlate` | Bounded frame capture with integrity counters, region-only frame delivery, seven motion/transition analyses, WAAPI pause/seek/rate/restore, and six-direction frame↔network correlation |
+| **Network** (7) | `browser_network_session` `browser_network_events` `browser_network_detail` `browser_network_trace` `browser_network_control` `browser_network_evidence` `browser_network_subscribe` | Capture, timeline, analysis, business-step traces, interception/throttling/replay/mock, JSONL/HAR evidence and per-agent subscriptions |
+
+### Debug panel
+
+The panel is the human window into the same runtime the agent uses.
+
+- **Live preview** of the workspace page, driven by a screencast with a polling fallback.
+- **Size bar** — 宽屏 / 横屏 / 平板 / 手机 presets as a segmented control, X/Y canvas position, width × height, display scale, and a `拖拽 | 适应窗口 | 默认` mode selector. Preset clicks reset X/Y and keep the chosen display mode; the selected preset shows a green dot and is mutually exclusive with drag mode.
+- **Hybrid canvas** — the viewport can be positioned like a canvas: a signed origin, negative coordinates and blank areas, a dark checkerboard in the panel (pure white in screenshots), drag-to-pan and screen-anchored wheel zoom.
+- **Annotation mode** — circle, rectangle, line, arrow, brush, text and eraser, plus fill/outline, colour, width and clear-canvas. Drawings are anchored in canvas coordinates, the page receives no input while annotating, and the document is published so agents can read it through `browser_state.annotations`.
+- **Shared state** — agent and panel read the same viewport; updates use `expectedRevision`, and conflicts are reported instead of silently overwriting.
+
+### Evidence and safety
+
+- Every structured action can return evidence: target identity, before/after state, dispatch facts, network deltas and typed errors.
+- Screenshots are validated PNGs with explicit scale and canvas-space regions; capture can be staged or persisted under a controlled root.
+- Visual baselines are immutable revisions with compare-and-swap HEAD updates and tombstones.
+- Network evidence supports JSONL (lossless) and HAR 1.2 export with default redaction and explicit truncation counters.
+- Frame evidence keeps the original `sourceTimestamp`, separate encoded and RGBA hashes, and dropped/evicted/gap counters; motion analyses are deterministic and report budget exhaustion or timeout as `BLOCKED` instead of pretending to pass.
+- Runtime access is scoped to a DSH workspace; mutating page work is serialized through a lease and a serial queue.
+- Navigation is restricted to approved targets (loopback by default; private ranges blocked unless explicitly enabled), with DNS, redirect and popup checks.
+
+## How it works
+
+```text
+DSH Agent / Agent Team
+        │
+        ▼
+UI testing plugin runtime
+  ├─ shared Chromium (headless by default; headed available in Web view)
+  ├─ one page per DSH workspace (URL, viewport, history, network, lease)
+  ├─ agent tool surface (36 tools)
+  └─ debug panel (preview, size bar, canvas, annotations)
+        │
+        ▼
+Observations, evidence and verdicts
+```
+
+Only the Web/Chromium adapter is implemented. Desktop, Android, TUI, HarmonyOS, game and 3D adapters are planned; each must report its real capabilities instead of pretending to support the same operations.
+
+## Capability tiers
+
+The tool surface is organized as **selection and fallback levels**, not a mandatory pipeline. Pick the lowest-cost reliable path; escalate when it cannot produce the required evidence.
+
+| Level | Focus | Typical use |
+| --- | --- | --- |
+| **T1** Programmatic | CDP, HTTP, JavaScript, network, console | API checks, network faults, page state, performance data |
+| **T2** Structured GUI | DOM, accessibility tree, snapshot/ref, trusted input | Buttons, forms, navigation, interaction tests |
+| **T3** Static vision | Screenshots, deterministic pixel analysis, coordinate actions | Layout, colour, occlusion, canvas, chart and style defects |
+| **T4** Dynamic vision | Frame sequences, timing, motion reasoning | Animation, transitions, dragging and time-dependent behavior — escalates from T3 when a single image cannot prove motion |
+
+A successful T1 call is never treated as a visual pass. UI-specific acceptance criteria still require UI-level observations.
+
+## Getting started
+
+**Requirements:** a DSH installation and a local Chrome/Chromium binary. The plugin does not bundle or install a browser; it launches the system binary it resolves (see [docs/getting-started.md](docs/getting-started.md)). A headed Web view additionally needs `DISPLAY` or `WAYLAND_DISPLAY` on POSIX hosts; Windows hosts always provide a window system, so headed mode needs no such variable there. The plugin requires Node.js 22+ (native `WebSocket`); the current DSH release itself requires Node.js 24.9+, so a real DSH host follows the stricter version.
+
+The plugin ships as a DSH plugin bundle and is published on npm as `dsh-agent-team-ui-testing`. There is no compatibility matrix beyond the Node.js and DSH requirements above.
+
+```sh
+# npm form (recommended): follows semver, so dsh-market can prompt for updates
+dsh plugin --profile web add dsh-agent-team-ui-testing
+
+# floating GitHub form: also receives updates, but only when package.json version is bumped
+dsh plugin --profile web add github:bloodarea/dsh-agent-team-ui-testing
+
+# pinned tag: reproduces exactly one release and never receives update prompts
+dsh plugin --profile web add github:bloodarea/dsh-agent-team-ui-testing#vX.Y.Z
+```
+
+1. Install the package into the DSH profile being used.
+2. Restart DSH after the first install so the plugin bundle is registered.
+3. Open the debug view from **更多 → 调试视图**, or from the plugin card in the right sidebar.
+4. Changes to `client.js` only need a panel refresh; changes to `index.js`, the tool surface or bundled skills need a DSH restart.
+
+For plugin development, link or copy this repository into the profile instead of installing the npm package.
+
+Requirements, install steps and panel usage are in [docs/getting-started.md](docs/getting-started.md).
+
+A typical agent flow is: navigate to the target, inspect state with `browser_state`/`browser_eval`, perform structured actions with the T2 tools, capture screenshots or run T3 checks, inspect network traffic with the network tools, escalate to the dynamic tools (`browser_dynamic_session` → `browser_motion_observe` → `browser_motion_analyze`/`browser_dynamic_correlate`) when the question is about motion, timing or a frame sequence, and use the shared viewport/canvas/annotation state when the task involves layout, framing or visual feedback.
+
+## Current limits
+
+- **Web target only.** Web/Chromium is the only implemented target environment and runs on Linux, macOS and Windows hosts. Desktop applications, Android, TUI, HarmonyOS, games and 3D are planned targets and stay disabled in the runtime picker.
+- **Vision is deterministic, not semantic.** T3 judges single PNGs and T4 judges frame sequences with deterministic algorithms: no VLM/OCR, no semantic naming, so "what does this text mean" and "looks right to a human" stay out of scope.
+- **T4 verification is partial.** Of the 44 dynamic-behavior criteria, 12 pass, 20 are partial, 0 fail and 12 were not run — the suite exits non-zero only because required checks were not run, not because they failed. Close/dispose restore, WebGPU rendering, media seeking/stalling, header-verified identity, 16 ms flicker coverage and long-lived connections remain unverified.
+- **Shared browser profile.** Cookies and storage are shared by the Chromium profile; only page, URL, viewport, history, network buffer and leases are isolated per workspace.
+- **Screenshots are not redacted.** Review their content before sharing.
+- **Attachments are not provider visibility.** A returned image attachment does not prove the model received it at full resolution.
+- **Network capture is partial at the edges.** Same-page iframe and dedicated workers are covered; OOPIF is partial; shared and service workers are not collected; HAR is a 1.2 subset; body/header redaction is not a general secret detector.
+- **Viewport display is a 1× screencast.** A display scale above 100% magnifies the bitmap rather than adding pixel density; request an explicit screenshot scale when resolution matters. Resize input barriers are best-effort, while canvas offsets use a fail-closed barrier.
+- **Shared state is optimistic.** `browser_viewport get` is a cache diagnostic; `stale` means “not recently observed”, and a lost `expectedRevision` race returns `VIEWPORT_CONFLICT` instead of replaying the patch.
+
+## Roadmap
+
+- Harden the Web channel and close the remaining dynamic-behavior criteria (12 not run, 20 partial).
+- Add the cross-environment test core: typed sessions, observations, assertions and reports.
+- Validate desktop (Windows/Linux/macOS), Android, TUI, HarmonyOS, game and 3D adapters by demand and platform feasibility.
+- Add multi-agent scheduling, human takeover and release hardening.
+
+## Documentation
+
+| File | Contents |
+| --- | --- |
+| [docs/index.md](docs/index.md) | Documentation index |
+| [docs/getting-started.md](docs/getting-started.md) | Requirements, install, debug panel and first calls |
+| [docs/tools.md](docs/tools.md) | All 36 tools, parameters and error classes |
+| [docs/capability-tiers.md](docs/capability-tiers.md) | T1–T4 selection model, P0 infrastructure and known limits |
+| [docs/viewport-control.md](docs/viewport-control.md) | Shared viewport, hybrid canvas and annotations |
+| [docs/capture-p0.md](docs/capture-p0.md) | Screenshots, image delivery and file lifecycle |
+| [docs/multi-tab.md](docs/multi-tab.md) | Per-workspace tab group, per-tab leases and agent tab selection |
+| [docs/element-picker.md](docs/element-picker.md) | Panel element picking and `@` element reference chips |
+| [docs/network-p0.md](docs/network-p0.md) | Network capture, tracing, control and evidence |
+| [docs/t2-structured-gui.md](docs/t2-structured-gui.md) | Snapshot/ref, trusted input and form filling |
+| [docs/t3-vision.md](docs/t3-vision.md) | Static vision algorithms, baselines and verdicts |
+| [docs/t4-dynamic-behavior.md](docs/t4-dynamic-behavior.md) | Frame capture, motion analysis, control and correlation |
+| [docs/architecture.md](docs/architecture.md) | Runtime, module responsibilities and extension points |
+| [docs/verification.md](docs/verification.md) | Reproducible tests, result interpretation and contributing |
+
+
+## Relationship to other projects
+
+| Project | Role |
+| --- | --- |
+| [`dsh-agent-team-presets`](https://github.com/bloodarea/dsh-agent-team-presets) | Reusable team and role configurations, model routes and tool policies |
+| **`dsh-agent-team-ui-testing`** | UI testing targets, sessions, automation, evidence and governed human/agent control |
+
+They are complementary but do not require each other; the runtime supports a single DSH agent without the presets plugin.
+
+## Contributing
+
+Reproducible DSH integration findings, platform feasibility tests, accessibility/DOM fallback cases, security threat models and concrete UI acceptance scenarios are the most useful contributions.
+
+When filing an issue, include the DSH version/commit, platform and runtime versions, reproduction steps, expected and observed results, and sanitized evidence. Never upload credentials, personal device data or unredacted authenticated traffic.
+
+## License
+
+The repository does not currently declare a license. Add an explicit license before redistribution or reuse; third-party code incorporated later must retain its applicable notices.
+
+---
+
+**Repository:** [bloodarea/dsh-agent-team-ui-testing](https://github.com/bloodarea/dsh-agent-team-ui-testing) · **Maintainer:** [bloodarea](https://github.com/bloodarea) · **Status:** pre-release

package/browser-safety.js

@@ -0,0 +1,249 @@
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+
+const TAXONOMY = {
+  NAV_FAILED: ['navigation', true], CDP_TIMEOUT: ['timeout', true],
+  CDP_DISCONNECTED: ['disconnected', true], TARGET_NOT_FOUND: ['action', false],
+  EVAL_ERROR: ['app', false], INVALID_ARGUMENT: ['input', false], BUSY: ['concurrency', true],
+  UNSUPPORTED: ['capability', false], INTERNAL: ['internal', false], ABORTED: ['cancelled', true],
+  // Headed mode without a window system is a capability refusal; it must never degrade to INTERNAL.
+  DISPLAY_UNAVAILABLE: ['capability', false],
+  // Independent HTTP client (docs/tools.md): HTTP timeouts are not CDP timeouts
+  // (they must never trigger the page "close the browser before releasing the queue" path).
+  HTTP_TIMEOUT: ['timeout', true], HTTP_FAILED: ['network', true], HTTP_REDIRECT_LIMIT: ['network', false],
+  // Workspace isolation (docs/architecture.md): these must never fall back to INTERNAL.
+  SCOPE_INVALID: ['input', false], SCOPE_NOT_FOUND: ['scope', false],
+  SCOPE_UNAVAILABLE: ['scope', true], SCOPE_FORBIDDEN: ['authorization', false],
+  RUNTIME_LIMIT: ['resource', true],
+  // Web T2 (structured GUI, docs/t2-structured-gui.md): a ref that no longer points at the node it
+  // was minted for, a selector that is not unique, a target that cannot be acted on, and a bounded
+  // wait that ran out. RETRYABLE only tells the caller a retry *may* help — a stale ref needs a new
+  // snapshot, not a replay.
+  REF_STALE: ['action', false], TARGET_NOT_UNIQUE: ['action', false],
+  NOT_INTERACTABLE: ['action', false], WAIT_TIMEOUT: ['timeout', true],
+  // Shared viewport (docs/viewport-control.md, Lead freeze 2026-11-01): an optimistic
+  // concurrency failure, not a bad argument and not a page failure. `state` + retryable=true means
+  // "read the current view and decide again"; the patch was NOT applied and page lastError is kept.
+  VIEWPORT_CONFLICT: ['state', true],
+  // P0 capture infrastructure (docs/capture-p0.md): the capture pipeline has its own taxonomy so a
+  // bad screenshot never masquerades as INTERNAL. Size/format refusals are not retryable (the same
+  // page would produce the same bytes); a failed CDP capture and a failed output write are.
+  // ABORTED/CDP_TIMEOUT/CDP_DISCONNECTED keep their existing codes for capture too.
+  CAPTURE_FAILED: ['capture', true], INVALID_PNG: ['capture', false],
+  CAPTURE_SIZE_MISMATCH: ['capture', false], CAPTURE_UPSCALED: ['capture', false],
+  CAPTURE_TOO_LARGE: ['resource', false], OUTPUT_PATH_INVALID: ['input', false],
+  OUTPUT_EXISTS: ['output', false], OUTPUT_WRITE_FAILED: ['output', true],
+  // Web T3 (static vision, docs/t3-vision.md). Every code below is fixed by the contract:
+  // a vision refusal must never degrade into INTERNAL, and a product/baseline that cannot be
+  // read must never be reported as a visual FAIL. `vision` marks "the image/source side said no",
+  // `action` marks "the live page no longer matches the screenshot", `output` marks the managed
+  // baseline root on disk, `concurrency` marks the HEAD CAS loser.
+  VISION_SOURCE_NOT_FOUND: ['vision', false], VISION_FORMAT_UNSUPPORTED: ['vision', false],
+  VISION_LIMIT_EXCEEDED: ['resource', false], VISION_TIMEOUT: ['timeout', true],
+  VISION_SIZE_MISMATCH: ['vision', false], VISION_EMPTY_COMPARISON: ['vision', false],
+  VISION_STALE_IMAGE: ['action', false], VISION_HIT_MISMATCH: ['action', false],
+  VISION_BASELINE_ROOT_UNAVAILABLE: ['output', false], VISION_BASELINE_NAME_INVALID: ['input', false],
+  VISION_BASELINE_NOT_FOUND: ['vision', false], VISION_BASELINE_EXISTS: ['output', false],
+  VISION_BASELINE_CONFLICT: ['concurrency', false],
+  VISION_BASELINE_READ_FAILED: ['output', true], VISION_BASELINE_WRITE_FAILED: ['output', true],
+  // Web P0 network collection (docs/network-p0.md). Codes, categories and retryability are
+  // fixed by the contract table: `scope` = the session/store is not there, `action` = the cited
+  // event is gone, `resource` = a declared budget, `concurrency` = the page/session is owned
+  // elsewhere or an id/step name collides, `capability` = no CDP/page or an unsupported CDP call,
+  // `output`/`input` = the evidence file side, `authorization` = cross-agent/cross-scope access.
+  NET_SESSION_NOT_FOUND: ['scope', false], NET_SESSION_ACTIVE: ['concurrency', false],
+  NET_SESSION_NOT_ACTIVE: ['scope', true], NET_CONFIG_INVALID: ['input', false],
+  NET_EVENT_NOT_FOUND: ['action', false], NET_BODY_UNAVAILABLE: ['network', true],
+  NET_QUOTA_EXCEEDED: ['resource', false], NET_RULE_INVALID: ['input', false],
+  NET_RULE_CONFLICT: ['concurrency', false], NET_RULE_NOT_FOUND: ['input', false],
+  NET_CONTROL_UNAVAILABLE: ['capability', false], NET_CONTROL_TIMEOUT: ['timeout', true],
+  NET_EXPORT_FAILED: ['output', true], NET_IMPORT_FAILED: ['input', false],
+  NET_HAR_INVALID: ['input', false], NET_SUBSCRIPTION_NOT_FOUND: ['scope', false],
+  NET_SUBSCRIPTION_FORBIDDEN: ['authorization', false], NET_INTEGRITY_FAILED: ['integrity', false],
+  NET_SCOPE_FORBIDDEN: ['authorization', false],
+  // R1-5（docs/network-p0.md）：新 7 工具的参数/路径/根/写盘错误一律 NET_*，
+  // 只有 BUSY/ABORTED/CDP_*/RUNTIME_LIMIT 这些平台码可以透传。
+  NET_INVALID_ARGUMENT: ['input', false], NET_OUTPUT_ROOT_UNKNOWN: ['output', false],
+  NET_OUTPUT_PATH_INVALID: ['input', false], NET_OUTPUT_WRITE_FAILED: ['output', true],
+  // Web T4 (docs/t4-dynamic-behavior.md): the DYNAMIC_* surface is its own taxonomy — a
+  // dynamic refusal must never degrade into INTERNAL, and missing frame/clock evidence is an
+  // evidence problem, not a page failure. `scope` = the session/event is gone or belongs to
+  // another scope, `input` = pure pre-check (zero start/control), `capability` = the requested
+  // frame source/encoding/adapter is unavailable (never silently substituted), `evidence` =
+  // clock/mapping limits make an exact claim impossible (keep the events, degrade the verdict),
+  // `state` = page-generation/control conflict, `resource` = a declared budget.
+  DYNAMIC_INVALID_ARGUMENT: ['input', false], DYNAMIC_SESSION_NOT_FOUND: ['scope', false],
+  DYNAMIC_EVENT_NOT_FOUND: ['scope', false], DYNAMIC_SESSION_ACTIVE: ['concurrency', false],
+  DYNAMIC_SOURCE_UNAVAILABLE: ['capability', false], DYNAMIC_CLOCK_UNCERTAIN: ['evidence', false],
+  DYNAMIC_LIMIT_EXCEEDED: ['resource', false], DYNAMIC_TIMEOUT: ['timeout', true],
+  DYNAMIC_CONTROL_CONFLICT: ['state', false], DYNAMIC_RESTORE_FAILED: ['state', false],
+  DYNAMIC_MAPPING_INCOMPATIBLE: ['evidence', false],
+  // P0-E page group (docs/multi-tab.md): a tab that is gone (`scope`), a tab owned by another
+  // workspace (`authorization`), the per-workspace/global page capacity (`resource`) and a popup
+  // whose first document cannot be hosted (`capability`). None of them may read as INTERNAL.
+  TAB_NOT_FOUND: ['scope', false], TAB_FORBIDDEN: ['authorization', false],
+  TAB_LIMIT: ['resource', false], POPUP_UNSUPPORTED: ['capability', false],
+  // T4 extend on a stopped/retained session: the session is gone but starting a new one may
+  // recover, hence scope + retryable (docs/t4-dynamic-behavior.md §extend).
+  DYNAMIC_SESSION_NOT_ACTIVE: ['scope', true],
+};
+
+/** Frozen copy of the error taxonomy: every thrown code must have an entry (tests enforce it). */
+export const ERROR_TAXONOMY = Object.freeze({ ...TAXONOMY });
+export class BrowserError extends Error {
+  constructor(code, message, details = {}) {
+    super(`[${code}] ${redactText(message)}`);
+    this.name = 'BrowserError';
+    this.code = code;
+    [this.category, this.retryable] = TAXONOMY[code] || TAXONOMY.INTERNAL;
+    this.details = details;
+  }
+  payload() {
+    return { code: this.code, category: this.category, retryable: this.retryable,
+      message: this.message, details: this.details };
+  }
+}
+export function asBrowserError(error) {
+  return error instanceof BrowserError ? error : new BrowserError('INTERNAL', String(error?.message || error));
+}
+export function checkAbort(signal) {
+  if (signal?.aborted) throw new BrowserError('ABORTED', '操作已取消');
+}
+export function abortable(promise, signal) {
+  checkAbort(signal);
+  if (!signal) return promise;
+  return new Promise((resolve, reject) => {
+    const abort = () => { cleanup(); reject(new BrowserError('ABORTED', '操作已取消')); };
+    const cleanup = () => signal.removeEventListener('abort', abort);
+    signal.addEventListener('abort', abort, { once: true });
+    Promise.resolve(promise).then((value) => { cleanup(); resolve(value); }, (error) => { cleanup(); reject(error); });
+  });
+}
+const sensitive = /token|key|secret|password|auth|code|session/i;
+export function redactUrl(raw) {
+  try {
+    const url = new URL(raw);
+    if (url.username) url.username = '***';
+    if (url.password) url.password = '***';
+    for (const key of [...url.searchParams.keys()]) if (sensitive.test(key)) url.searchParams.set(key, '***');
+    if (url.hash) url.hash = '***';
+    return url.toString();
+  } catch { return String(raw).replace(/\b(token|key|secret|password|auth|code|session)=[^&\s]*/gi, '$1=***'); }
+}
+export function redactText(value) {
+  return String(value).replace(/https?:\/\/[^\s<>"']+/gi, (url) => redactUrl(url));
+}
+function blockedAddress(address, allowPrivate) {
+  let value = address.toLowerCase().replace(/^\[|\]$/g, '');
+  if (value.startsWith('::ffff:')) {
+    const tail = value.slice(7);
+    if (isIP(tail) === 4) value = tail;
+    else {
+      const parts = tail.split(':');
+      if (parts.length === 2) {
+        const n = parseInt(parts[0], 16) * 65536 + parseInt(parts[1], 16);
+        value = [n >>> 24, (n >>> 16) & 255, (n >>> 8) & 255, n & 255].join('.');
+      }
+    }
+  }
+  if (isIP(value) === 4) {
+    const [a, b] = value.split('.').map(Number);
+    if (a === 0 || (a === 169 && b === 254) || a >= 224) return true;
+    return !allowPrivate && (a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168));
+  }
+  if (isIP(value) === 6) {
+    if (value === '::' || /^ff/i.test(value) || /^fe[89ab]/i.test(value)) return true;
+    return !allowPrivate && /^f[cd]/i.test(value);
+  }
+  return true;
+}
+export async function validateTarget(raw, { origins = [], allowPrivate = process.env.DSH_UI_TESTING_ALLOW_PRIVATE === '1', signal, resolve = lookup } = {}) {
+  checkAbort(signal);
+  let url;
+  try { url = new URL(raw); } catch { throw new BrowserError('INVALID_ARGUMENT', '地址不是合法 URL'); }
+  if (!['http:', 'https:'].includes(url.protocol)) throw new BrowserError('INVALID_ARGUMENT', '只支持 http/https 地址');
+  if (url.username || url.password) throw new BrowserError('INVALID_ARGUMENT', '导航地址不能包含凭据');
+  const blockedOrigins = [...origins, process.env.DSH_WEB_URL].filter(Boolean).map((origin) => {
+    try { return new URL(origin).origin; } catch { return null; }
+  });
+  if (blockedOrigins.includes(url.origin)) throw new BrowserError('INVALID_ARGUMENT', '不能导航到 DSH 自身 origin');
+  const hostname = url.hostname.replace(/^\[|\]$/g, '');
+  let addresses;
+  try {
+    // `resolve` is an injection point for probes (mixed public/private DNS, zero-dispatch
+    // scenarios). Production always uses the real `dns/promises` lookup imported above.
+    addresses = isIP(hostname) ? [{ address: hostname }] : await abortable(resolve(hostname, { all: true }), signal);
+  } catch (error) {
+    if (error instanceof BrowserError) throw error;
+    throw new BrowserError('NAV_FAILED', '导航域名解析失败', { url: redactUrl(raw) });
+  }
+  if (!addresses.length || addresses.some(({ address }) => blockedAddress(address, allowPrivate))) {
+    throw new BrowserError('INVALID_ARGUMENT', '导航目标地址不在允许范围', { url: redactUrl(raw) });
+  }
+  return url.href;
+}
+
+/** Minimal cancellable CDP transport. Each settlement removes its timer and abort listener. */
+export class Cdp {
+  constructor(url) {
+    this.url = url; this.nextId = 1; this.pending = new Map(); this.listeners = new Set(); this.closed = false;
+  }
+  connect({ signal, timeoutMs = 30000 } = {}) {
+    checkAbort(signal);
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(this.url);
+      this.ws = ws;
+      let settled = false;
+      const finish = (error) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer); signal?.removeEventListener('abort', abort);
+        if (error) { this.close(); reject(error); } else resolve(this);
+      };
+      const abort = () => finish(new BrowserError('ABORTED', 'CDP 连接已取消'));
+      const timer = setTimeout(() => finish(new BrowserError('CDP_TIMEOUT', 'CDP 连接超时')), timeoutMs);
+      signal?.addEventListener('abort', abort, { once: true });
+      ws.onopen = () => finish();
+      ws.onerror = () => finish(new BrowserError('CDP_DISCONNECTED', 'CDP 连接失败'));
+      ws.onclose = () => {
+        this.closed = true;
+        finish(new BrowserError('CDP_DISCONNECTED', 'CDP 连接已关闭'));
+        this.rejectPending();
+      };
+      ws.onmessage = (event) => {
+        let message;
+        try { message = JSON.parse(event.data); } catch { return; }
+        if (message.id !== undefined) {
+          const entry = this.pending.get(message.id);
+          if (entry) entry.finish(message.error ? new BrowserError('INTERNAL', message.error.message || 'CDP error') : null, message.result);
+        } else for (const listener of this.listeners) listener(message);
+      };
+    });
+  }
+  send(method, params = {}, { signal, timeoutMs = 30000, sessionId } = {}) {
+    if (this.closed) return Promise.reject(new BrowserError('CDP_DISCONNECTED', 'CDP 连接已关闭', { method }));
+    if (signal?.aborted) return Promise.reject(new BrowserError('ABORTED', '操作已取消'));
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const abort = () => finish(new BrowserError('ABORTED', '操作已取消', { method }));
+      const finish = (error, value) => {
+        if (!this.pending.delete(id)) return;
+        clearTimeout(timer); signal?.removeEventListener('abort', abort);
+        if (error) reject(error); else resolve(value);
+      };
+      const timer = setTimeout(() => finish(new BrowserError('CDP_TIMEOUT', 'CDP 超时: ' + method)), timeoutMs);
+      this.pending.set(id, { finish, timer, method });
+      signal?.addEventListener('abort', abort, { once: true });
+      try { this.ws.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) })); }
+      catch {
+        finish(new BrowserError('CDP_DISCONNECTED', 'CDP 发送失败'));
+        this.close();
+      }
+    });
+  }
+  rejectPending() {
+    for (const entry of [...this.pending.values()]) entry.finish(new BrowserError('CDP_DISCONNECTED', 'CDP 连接已关闭', { method: entry.method }));
+  }
+  on(listener) { this.listeners.add(listener); return () => this.listeners.delete(listener); }
+  close() { this.closed = true; this.rejectPending(); try { this.ws?.close(); } catch { /* already closed */ } }
+}