dsh-browser-view 0.4.1 → 0.7.0

package/lib/types/browser/primitives/hierarchy.d.ts

@@ -0,0 +1,3 @@
+import type { Locator, Page } from "playwright-core";
+export declare function selectPathHelper(page: Page, trigger: string | Locator, path: string[]): Promise<boolean>;
+//# sourceMappingURL=hierarchy.d.ts.map

package/lib/types/browser/primitives/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./types.js";
+export * from "./dom.js";
+export * from "./dialog.js";
+export * from "./select.js";
+export * from "./virtual.js";
+export * from "./editor.js";
+export * from "./form.js";
+export * from "./transfer.js";
+export * from "./drag.js";
+export * from "./hierarchy.js";
+export * from "./temporal.js";
+//# sourceMappingURL=index.d.ts.map

package/lib/types/browser/primitives/select.d.ts

@@ -0,0 +1,7 @@
+import type { SelectContext, SelectResult } from "./types.js";
+/**
+ * 通用下拉选择原语
+ * 适用于原生 HTML <select> 及各类通过 Portal 挂载在 body 根节点的非标合成下拉组件
+ */
+export declare function executeUniversalSelect(ctx: SelectContext): Promise<SelectResult>;
+//# sourceMappingURL=select.d.ts.map

package/lib/types/browser/primitives/temporal.d.ts

@@ -0,0 +1,3 @@
+import type { Locator, Page } from "playwright-core";
+export declare function fillDateRangeHelper(page: Page, container: string | Locator, dateValue: string | [string, string]): Promise<boolean>;
+//# sourceMappingURL=temporal.d.ts.map

package/lib/types/browser/primitives/transfer.d.ts

@@ -0,0 +1,3 @@
+import type { Page } from "playwright-core";
+export declare function transferItemsHelper(page: Page, selector: string, arg3: string | string[], arg4?: string | string[]): Promise<boolean>;
+//# sourceMappingURL=transfer.d.ts.map

package/lib/types/browser/primitives/types.d.ts

@@ -0,0 +1,48 @@
+import type { Locator, Page } from "playwright-core";
+/** 下拉选择上下文 */
+export interface SelectContext {
+    page: Page;
+    target: Locator;
+    want: string;
+    label?: string;
+    exact?: boolean;
+    clear?: boolean;
+    timeout?: number;
+}
+/** 下拉选择执行结果 */
+export interface SelectResult {
+    selected: string;
+}
+/** 表单填充条目 */
+export interface FormFieldItem {
+    key: string;
+    value: any;
+}
+/** 表单填充汇总结果 */
+export interface FormFillResult {
+    filled: string[];
+    skipped: string[];
+    errors: Record<string, string>;
+    submitted?: boolean;
+}
+/** 页面稳态等待选项 */
+export interface QuiescenceOptions {
+    /** 连续无 DOM 变更的静默时间(ms)，默认 80ms */
+    quietMs?: number;
+    /** 最大等待超时(ms)，默认 2500ms */
+    maxTimeoutMs?: number;
+    /** 检查的根节点选择器，默认 document.body */
+    scope?: string;
+}
+/** 虚拟长列表与表格抽取选项 */
+export interface VirtualExtractOptions {
+    /** 虚拟滚动的容器 CSS 选择器 */
+    scope?: string;
+    /** 待抽取的字段与对应列选择器字典，如 { id: ".col-id", name: ".col-name" } */
+    fields: Record<string, string>;
+    /** 最大抓取行数，默认 1000 */
+    maxRows?: number;
+    /** 每次滚动步进像素，默认 350 */
+    stepPixels?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/browser/primitives/virtual.d.ts

@@ -0,0 +1,4 @@
+import type { Page } from "playwright-core";
+import type { VirtualExtractOptions } from "./types.js";
+export declare function extractVirtualListHelper(page: Page, options: VirtualExtractOptions): Promise<Record<string, any>[]>;
+//# sourceMappingURL=virtual.d.ts.map

package/lib/types/browser/reports.d.ts

@@ -30,8 +30,6 @@ export interface RunRecord {
     retryOf?: string;
     results: RunStepResult[];
 }
-/** 报告存储目录($DSH_HOME/.dsh-browser/reports)。 */
-export declare function reportsDir(): string;
 /** 生成 runId:YYYYMMDD-HHmmss-随机4位。 */
 export declare function makeRunId(ts: number): string;
 /** 追加一条运行记录;超限时截断旧行(原子替换)。 */

package/lib/types/browser/session/cache.d.ts

@@ -0,0 +1,103 @@
+import type { Page } from "playwright-core";
+import type { MarkEntry, RefEntry } from "../types.js";
+/** 页面当前导航代际(0 = 尚未导航/未标记)。 */
+export declare function pageNavSeq(page: Page): number;
+/** 推进导航代际并返回新值;旧代际的 ref 全部标记为疑似过期。 */
+export declare function bumpPageNav(page: Page): number;
+export declare function noteReanchorAttempt(page: Page): void;
+/** 当前代际是否已尝试过重锚定。 */
+export declare function reanchorAttempted(page: Page): boolean;
+/**
+ * 重锚定纯逻辑:按指纹把旧 ref 表映射到导航后的新扫描结果上。
+ * 匹配规则:role 相等 && 去-空白 name 相等(其次同 role 内 LCS ≥ 0.6 的名称
+ * 漂移);同指纹多命中按组内注册顺序 zip(稳定)。命中的 ref **沿用原编号**,
+ * 更新 selector/rect/scroll/navSeq;未命中的删除。
+ * 导出供测试。
+ */
+export declare function remapRefs(oldRefs: Map<string, RefEntry>, fresh: {
+    role: string;
+    name: string;
+    selector: string;
+    rect?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    scroll?: {
+        x: number;
+        y: number;
+    };
+}[], seq: number): {
+    merged: Map<string, RefEntry>;
+    remapped: number;
+    dropped: number;
+    drifted: number;
+};
+/** 记录一次 aria 快照分配的 ref(整表替换)。 */
+export declare function setPageRefs(page: Page, refs: Map<string, RefEntry>): void;
+/** 查询某个 ref 的定位信息;未注册返回 undefined。 */
+export declare function pageRef(page: Page, ref: string): RefEntry | undefined;
+/** 清空页面的 ref 表(导航/新快照时调用)。 */
+export declare function clearPageRefs(page: Page): void;
+/** 取页面当前完整 ref 表(browser_find 增量续号合并用;无则空 Map)。 */
+export declare function pageRefsOf(page: Page): Map<string, RefEntry>;
+/**
+ * 为命中元素增量分配 ref:沿用既有注册表的编号继续(不与上次快照冲突),
+ * 合并写回;返回带 ref 的命中列表(上限 maxRefs,超出标 truncated)。
+ * 纯逻辑不依赖浏览器;findTool 与语义定位(semantic.ts)共用。
+ */
+export declare function assignRefs(existing: Map<string, RefEntry>, matches: {
+    role: string;
+    name: string;
+    selector: string;
+    ancestors?: string[];
+}[], maxRefs: number, navSeq?: number): {
+    withRefs: {
+        ref: string;
+        role: string;
+        name: string;
+        selector: string;
+        ancestors?: string[];
+    }[];
+    merged: Map<string, RefEntry>;
+    truncated: boolean;
+};
+/** 记录一次 SoM 截图的标徽表(整表替换)。 */
+export declare function setPageMarks(page: Page, marks: Map<number, MarkEntry>): void;
+/** 查询某个标徽的定位信息;未注册返回 undefined。 */
+export declare function pageMark(page: Page, id: number): MarkEntry | undefined;
+/** 清空页面的标徽表(导航时调用)。 */
+export declare function clearPageMarks(page: Page): void;
+/** 一个历史版本的快照内容(text/aria 两种模式共用同一条版本序列)。 */
+export interface SnapshotEntry {
+    version: number;
+    text: string;
+    aria: string;
+}
+/**
+ * F3 增量快照历史:per-page 环形数组保存最近 K 个版本(K = snapshotHistory,
+ * 默认 5,上限 20;text 模式 ≤20KB/版本 → 内存上界 ≈100KB/page)。
+ * 任意 since ∈ [latest-K+1, latest] 都能 diff;更旧版本回落全量标 stale。
+ */
+export interface SnapshotCache {
+    /** 最新版本号(单调递增,不因环形淘汰回退)。 */
+    version: number;
+    /** 最近 K 个版本,按 version 升序;长度 ≤ K。 */
+    history: SnapshotEntry[];
+}
+export declare function snapshotCacheOf(page: Page): SnapshotCache | undefined;
+export declare function setSnapshotCache(page: Page, cache: SnapshotCache): void;
+/** 环形容量钳制(1..20,非法值回落默认 5)。导出供测试。 */
+export declare function snapshotCapacity(k: unknown): number;
+/**
+ * 追加一个新版本并淘汰超限的最旧版本(纯逻辑,导出供测试)。
+ * cache 为 undefined 时从 version 1 开始;返回新缓存(不修改入参)。
+ */
+export declare function pushSnapshotVersion(cache: SnapshotCache | undefined, content: {
+    text: string;
+    aria: string;
+}, capacity: unknown): SnapshotCache;
+/** 按版本号取历史条目;不在环形窗口内(更旧/未知)返回 undefined。 */
+export declare function snapshotVersionEntry(cache: SnapshotCache | undefined, version: number): SnapshotEntry | undefined;
+//# sourceMappingURL=cache.d.ts.map

package/lib/types/browser/session/collaboration.d.ts

@@ -0,0 +1,53 @@
+export declare function setPauseInstruction(instruction: string): void;
+export declare function clearPauseInstruction(): void;
+export declare function currentPause(): {
+    instruction: string;
+    startedAt: number;
+} | null;
+/** 一次待审批的敏感操作(browser_confirm 等待期间供面板展示与提交决策)。 */
+export interface PendingConfirm {
+    id: string;
+    reason: string;
+    tool?: string;
+    args?: Record<string, any>;
+    startedAt: number;
+    decision?: "allowed" | "denied";
+}
+export declare function setPendingConfirm(entry: PendingConfirm): void;
+export declare function getPendingConfirm(): PendingConfirm | null;
+export declare function clearPendingConfirm(): void;
+/** 面板提交审批决策;id 不匹配(已被新审批取代/超时清理)时返回 false。 */
+export declare function resolveConfirm(id: string, decision: "allowed" | "denied"): boolean;
+/** 一次待点选的教学请求(browser_pick_element 等待期间供面板展示与提交)。 */
+export interface PendingPick {
+    id: string;
+    instruction: string;
+    startedAt: number;
+    /** 建立等待时快照的推流帧视口 CSS 尺寸(CDP metadata);坐标换算基准。 */
+    deviceWidth?: number;
+    deviceHeight?: number;
+    /** 面板提交的点选结果(截图位图像素坐标 + 截图尺寸)。 */
+    pick?: {
+        x: number;
+        y: number;
+        imgW: number;
+        imgH: number;
+    };
+}
+export declare function setPendingPick(entry: PendingPick): void;
+export declare function getPendingPick(): PendingPick | null;
+export declare function clearPendingPick(): void;
+/** 面板提交点选坐标;id 不匹配(已被新请求取代/超时清理)时返回 false。 */
+export declare function resolvePick(id: string, pick: {
+    x: number;
+    y: number;
+    imgW: number;
+    imgH: number;
+}): boolean;
+/** live 工具调用开始(register 包装层调用)。 */
+export declare function noteToolStart(): void;
+/** live 工具调用结束(成功/失败都算结束)。 */
+export declare function noteToolEnd(): void;
+/** 当前在途的 live 工具调用数(0 = agent 空闲)。 */
+export declare function activeToolCalls(): number;
+//# sourceMappingURL=collaboration.d.ts.map

package/lib/types/browser/session/recorder.d.ts

@@ -0,0 +1,62 @@
+import type { ReplayStep, SelectorHint } from "../types.js";
+/** 已保存的录制脚本:name → 步骤数组。 */
+export declare const savedRecordings: Map<string, {
+    steps: ReplayStep[];
+    savedAt: number;
+}>;
+/** 一次工具调用的记录(操作轨迹 / 录制 / 回放共用)。 */
+export interface TestCall {
+    tool: string;
+    args: Record<string, any>;
+    ok: boolean;
+    ms: number;
+    ts: number;
+    error?: string;
+    /** 录制时采集的选择器指纹(回放自愈用;register 包装层异步补齐)。 */
+    meta?: {
+        hint?: SelectorHint;
+        source?: "human";
+    };
+    /** source: "human" 表示这条来自用户在浏览器中的手动操作(混合录制)。 */
+    source?: "human";
+}
+export declare function isRecording(): boolean;
+export declare function startRecording(): void;
+export declare function stopRecording(): TestCall[];
+/** 最近一次完整录制(start→stop)的 buffer;从未录制过返回 null。 */
+export declare function lastRecordingOf(): TestCall[] | null;
+/** 操作轨迹追加(同时写入录制 buffer,排除 record/replay 自身)。返回存入的调用对象(供调用方补 meta)。 */
+export declare function recordCall(call: TestCall): TestCall;
+/** 操作轨迹(按时间倒序,最新在前)。 */
+export declare function testLogOf(): TestCall[];
+export declare function clearTestLog(): void;
+/** window 上的回传 binding 名(须为合法 JS 标识符)。 */
+export declare const HUMAN_BINDING = "__dshBrowserHumanEvent";
+/** agent 即将/刚刚执行了 DOM 操作(register 包装层调用);1.5s 内的页内事件视为工具回声。 */
+export declare function noteAgentAction(): void;
+/** 导出供测试:距上次 agent 操作是否在去重窗口内。 */
+export declare function agentActionRecent(now?: number, windowMs?: number): boolean;
+/**
+ * 页内人工操作事件 → 录制步骤(纯函数,导出供测试)。
+ * payload 由 installHumanRecorder 生成:{ kind, selector, value?, testid?, role?, name?, id?, text?, tag? }。
+ * 无法映射(缺 selector / 未知 kind / 空输入)返回 null。
+ */
+export declare function humanEventToStep(payload: unknown): {
+    tool: string;
+    args: Record<string, any>;
+    meta: {
+        hint: SelectorHint;
+        source: "human";
+    };
+} | null;
+/** binding 回调入站口:仅录制中生效;去重窗口内(agent 工具回声)丢弃。 */
+export declare function handleHumanEvent(payload: unknown): void;
+/**
+ * 页内注入的人工操作监听(addInitScript 序列化;每次导航自动重装)。
+ * 监听常驻但 node 侧只在录制中生效,关闭录制等价于"移除"。
+ * 只上报可交互元素上的 click 与表单控件的 change,避免逐键噪音。
+ * F5 收敛:cssPath 等元素描述来自 walker.ts 单一来源(构建期拼装注入),
+ * 不再持有内联副本;payload 字段语义与 v0.3 完全一致。
+ */
+export declare const installHumanRecorder: (payload: unknown) => void;
+//# sourceMappingURL=recorder.d.ts.map

package/lib/types/browser/session/screencast.d.ts

@@ -0,0 +1,37 @@
+import type { Page } from "playwright-core";
+export interface ScreencastFrame {
+    /** 原始 JPEG 图像 Buffer */
+    buffer: Buffer;
+    /** Base64 编码字符串 */
+    base64: string;
+    /** CDP 帧元数据 (如 deviceWidth, deviceHeight, pageScaleFactor 等) */
+    metadata: Record<string, any>;
+    timestamp: number;
+}
+export type FrameListener = (frame: ScreencastFrame) => void;
+declare class ScreencastManager {
+    private cdp;
+    private currentPage;
+    private listeners;
+    private isStarting;
+    private lastFrame;
+    /**
+     * 注册帧监听器。返回注销函数。
+     * 当第一个监听器加入时自动激活 CDP Screencast；
+     * 当所有监听器离开时自动注销并停止 CDP，实现零空载开销。
+     */
+    subscribe(listener: FrameListener): () => void;
+    get subscriberCount(): number;
+    getLastFrame(): ScreencastFrame | null;
+    /**
+     * 启动 CDP Screencast
+     */
+    start(targetPage?: Page | null): Promise<boolean>;
+    /**
+     * 停止 CDP Screencast，静默释放资源
+     */
+    stop(): Promise<void>;
+}
+export declare const screencastManager: ScreencastManager;
+export {};
+//# sourceMappingURL=screencast.d.ts.map

package/lib/types/browser/session/screenshot.d.ts

@@ -0,0 +1,17 @@
+/** 记录最近一次截图目录(截图工具调用时写入)。 */
+export declare function noteScreenshotDir(dir: string): void;
+/** 定时清扫入口:若已知截图目录则按当前配置清理。 */
+export declare function sweepScreenshotDir(opts: {
+    maxAgeDays?: number;
+    maxCount?: number;
+}): number;
+/**
+ * 清理截图目录里的 .png 文件:按修改时间保留最新的 maxCount 个,
+ * 并删除超过 maxAgeDays 天的旧文件。只处理目录直属文件,不递归;
+ * 单个文件删除失败(被占用等)静默跳过。返回删除数量。
+ */
+export declare function cleanupScreenshots(dir: string, opts: {
+    maxAgeDays?: number;
+    maxCount?: number;
+}): number;
+//# sourceMappingURL=screenshot.d.ts.map

package/lib/types/browser/session/semantic.d.ts

@@ -0,0 +1,94 @@
+import type { Page } from "playwright-core";
+import type { TargetResolution } from "../types.js";
+/** 页内扫描命中的元素(带打分与上下文)。 */
+export interface SemanticMatch {
+    role: string;
+    name: string;
+    selector: string;
+    text: string;
+    visible: boolean;
+    inDialog: boolean;
+    /** 命中得分:name 命中权重 3 / testid·id 2 / text·role 1,多 token 求和;传统子串命中加基础分。 */
+    score: number;
+    ancestors: string[];
+}
+/** 语义未命中时返回的最相近候选。 */
+export interface SemanticCandidate {
+    role: string;
+    name: string;
+    selector: string;
+    score: number;
+}
+/** 语义未命中结果(与 TargetResolution 用 "candidates" 字段区分)。 */
+export interface SemanticMiss {
+    what: string;
+    candidates: SemanticCandidate[];
+}
+/**
+ * 页内语义扫描:按 query 打分收集可交互元素(弹窗内优先、可见优先、高分优先)。
+ * 匹配语义与 browser_find 完全一致(去空白归一化支持 antd「确 定」分词);
+ * 多 token(空格/中英混排拆分)按 AND 命中 —— 单 token 行为与旧子串匹配等价。
+ */
+export declare const scanInteractive: (payload: {
+    query: string;
+    exact: boolean;
+    scope: string;
+    limit: number;
+    dialogSelector?: string;
+}) => {
+    matches: SemanticMatch[];
+    candidates: {
+        role: string;
+        name: string;
+        selector: string;
+    }[];
+    scanned: number;
+};
+/**
+ * 语义未命中时候选排序(纯逻辑,导出供测试):按与 query 的最长公共子串
+ * 打分取 top5,阈值与 topSuggestions 一致(短 query ≥1,长 query ≥2)。
+ */
+export declare function semanticMissCandidates(query: string, candidates: {
+    role: string;
+    name: string;
+    selector: string;
+}[], count?: number): SemanticCandidate[];
+/** 语义未命中的错误消息(候选表内嵌,agent 不必再跑一轮 find)。 */
+export declare function semanticMissMessage(miss: SemanticMiss): string;
+/**
+ * 意图语义定位:what → 打分扫描 → 命中注册成正式 ref 并返回标准
+ * TargetResolution(含 matchedCount/visibleCount,与 selector 路径无缝衔接);
+ * 零命中返回 SemanticMiss(候选由调用方决定呈现方式)。
+ */
+export declare function resolveSemanticTarget(page: Page, what: string, opts?: {
+    exact?: boolean;
+    scope?: string;
+    limit?: number;
+    maxRefs?: number;
+}): Promise<TargetResolution | SemanticMiss>;
+/**
+ * 全量可交互元素扫描(SPA ref 重锚定的数据源):返回页面(或 scope 内)全部
+ * 可见可交互元素的 role/name/selector(视口内附 rect/scroll),与 aria 快照
+ * 同一 walker 语义。上限 300 条,超出截断(超大页面重锚定按命中部分处理)。
+ */
+export declare const scanAllInteractive: (payload: {
+    scope?: string;
+}) => {
+    elements: {
+        role: string;
+        name: string;
+        selector: string;
+        rect?: {
+            x: number;
+            y: number;
+            w: number;
+            h: number;
+        };
+        scroll?: {
+            x: number;
+            y: number;
+        };
+    }[];
+    truncated: boolean;
+};
+//# sourceMappingURL=semantic.d.ts.map

package/lib/types/browser/session/target.d.ts

@@ -0,0 +1,16 @@
+import type { Locator, Page } from "playwright-core";
+import type { TargetResolution } from "../types.js";
+/**
+ * 构造对字符间/词间任意空白不敏感的匹配正则。
+ * 处理中英文混排、单字间隔、Tab、换行以及   等特殊空白字符。
+ */
+export declare function buildFlexibleTextPattern(text: string): RegExp;
+/**
+ * 统一解析目标元素：
+ * 自动识别 selector 或 ref；若 ref 标记位于子 Frame，自动绑定到对应子 Frame 上下文。
+ * 具备路径防漂移校验与 getByRole 自愈降级能力。
+ */
+export declare function resolveTargetLocator(page: Page, args: Record<string, any>): Promise<TargetResolution>;
+/** 兼容旧版签名的目标定位快捷方式 */
+export declare function targetLocator(page: Page, args: Record<string, any>): Promise<Locator>;
+//# sourceMappingURL=target.d.ts.map

package/lib/types/browser/session/tracer.d.ts

@@ -0,0 +1,56 @@
+import type { Page } from "playwright-core";
+export interface ConsoleLogEntry {
+    type: string;
+    text: string;
+    timestamp: number;
+    stepId?: string;
+}
+export interface FailedRequestEntry {
+    url: string;
+    method: string;
+    status?: number;
+    error?: string;
+    timestamp: number;
+    stepId?: string;
+}
+export interface StepTraceEntry {
+    stepId: string;
+    stepIndex: number;
+    tool: string;
+    args?: Record<string, any>;
+    url: string;
+    startedAt: number;
+    durationMs: number;
+    success: boolean;
+    error?: string;
+    consoleLogs: ConsoleLogEntry[];
+    failedRequests: FailedRequestEntry[];
+    thumbnail?: string;
+    /** 定位失败遥测(M6):失败阶段 + 页面特征,随 /timeline 透出,为按真实流量优化提供数据。 */
+    locationFailure?: {
+        phase: "zeroMatch" | "ambiguous" | "dialogOverlay" | "staleRef" | "coordinateMiss";
+        candidates: number;
+        dialogActive: boolean;
+        hasShadow: boolean;
+    };
+}
+declare class SessionTracer {
+    private consoleLogsByProfile;
+    private failedRequestsByProfile;
+    private tracesByProfile;
+    private activeStepByProfile;
+    private stepCounter;
+    /** 记录 Console 输出 */
+    recordConsole(profile: string, entry: ConsoleLogEntry): void;
+    /** 记录失败网络请求 (4xx/5xx 或网络断裂) */
+    recordFailedRequest(profile: string, entry: FailedRequestEntry): void;
+    /** 步骤开始 */
+    startStep(profile: string, tool: string, args?: Record<string, any>, page?: Page | null): string;
+    /** 步骤结束并归档 */
+    endStep(profile: string, success: boolean, error?: string, page?: Page | null, locationFailure?: StepTraceEntry["locationFailure"]): Promise<StepTraceEntry | null>;
+    getTraces(profile: string): StepTraceEntry[];
+    clear(profile?: string): void;
+}
+export declare const sessionTracer: SessionTracer;
+export {};
+//# sourceMappingURL=tracer.d.ts.map