dsh-browser-view 0.1.2 → 0.3.0

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

@@ -0,0 +1,13 @@
+export declare function toCsv(rows: Record<string, unknown>[]): string;
+export declare function toJsonl(rows: Record<string, unknown>[]): string;
+export declare function toMarkdownTable(rows: Record<string, unknown>[]): string;
+/** 按格式序列化抽取结果(json 为 pretty JSON 字符串)。 */
+export declare function serializeRows(rows: Record<string, unknown>[], format: string): string;
+/** 由文件扩展名推断序列化格式(显式 format 优先)。 */
+export declare function formatFromFile(file: string): string | null;
+/**
+ * 解析 CSV 文本为行对象数组(首行为表头;支持引号包裹、双引号转义、
+ * 逗号/换行内嵌)。供 browser_replay 的 dataFile 使用。
+ */
+export declare function parseCsv(text: string): Record<string, string>[];
+//# sourceMappingURL=extract.d.ts.map

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

@@ -1,14 +1,12 @@
+import type { ReplayStep } from "./types.js";
 /** 录制存储目录($DSH_HOME/.dsh-browser/recordings)。 */
 export declare function recordingsDir(): string;
 /** 名字安全化:只保留字母数字 . _ -,连续点压成下划线防路径穿越。 */
 export declare function safeName(name: string): string;
 /** 加载目录下所有 .json 录制进内存表;返回加载数量。坏文件静默跳过。 */
 export declare function loadRecordings(): number;
-/** 写一个录制到磁盘(原子替换);返回文件路径。 */
-export declare function saveRecordingFile(name: string, steps: {
-    tool: string;
-    args: any;
-}[]): string;
+/** 写一个录制到磁盘(原子替换);返回文件路径。formatVersion 2 起步骤可带 meta(选择器指纹)与 {{var}} 占位符。 */
+export declare function saveRecordingFile(name: string, steps: ReplayStep[]): string;
 /** 删除磁盘上的录制文件;返回是否存在并删除。 */
 export declare function deleteRecordingFile(name: string): boolean;
 /** 录制列表(面板 / browser_record list 共用)。 */
@@ -21,10 +19,7 @@ export declare function listRecordings(): Array<{
 /** 录制详情(面板展开查看步骤)。 */
 export declare function recordingDetail(name: string): {
     name: string;
-    steps: {
-        tool: string;
-        args: any;
-    }[];
+    steps: ReplayStep[];
 } | undefined;
 /** 删除录制(内存 + 磁盘同步);返回是否存在并删除。 */
 export declare function deleteRecording(name: string): boolean;

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

@@ -0,0 +1,42 @@
+/** 一步的执行结果(与 runReplay results 条目同形,外加自愈标记)。 */
+export interface RunStepResult {
+    index: number;
+    tool: string;
+    ok: boolean;
+    error?: string;
+    healed?: boolean;
+    via?: string;
+    resolved?: string;
+}
+/** 一次 replay/batch 的运行记录。 */
+export interface RunRecord {
+    runId: string;
+    ts: number;
+    kind: "replay" | "batch";
+    source: string;
+    total: number;
+    passed: number;
+    failed: number;
+    healedCount: number;
+    durationMs: number;
+    /** data 数据集模式时的行号(单次运行为 undefined)。 */
+    row?: number;
+    results: RunStepResult[];
+}
+/** 报告存储目录($DSH_HOME/.dsh-browser/reports)。 */
+export declare function reportsDir(): string;
+/** 生成 runId:YYYYMMDD-HHmmss-随机4位。 */
+export declare function makeRunId(ts: number): string;
+/** 追加一条运行记录;超限时截断旧行(原子替换)。 */
+export declare function appendRun(record: RunRecord): void;
+/** 读取全部运行记录(按时间倒序);坏行静默跳过。 */
+export declare function listRuns(limit?: number): RunRecord[];
+/** 最近一次运行(无记录返回 null)。 */
+export declare function latestRun(): RunRecord | null;
+/** 按 runId 取单条记录。 */
+export declare function getRun(runId: string): RunRecord | null;
+/** 生成 Markdown 回归报告。 */
+export declare function renderMarkdownReport(runs: RunRecord[], source?: string): string;
+/** 生成自包含 HTML 回归报告(内联样式,无外部资源)。 */
+export declare function renderHtmlReport(runs: RunRecord[], source?: string): string;
+//# sourceMappingURL=reports.d.ts.map

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

@@ -1,5 +1,5 @@
-import type { Page } from "playwright-core";
-import type { BrowserConfig, ProfileState, DownloadEntry, FormField, NavEntry } from "./types.js";
+import type { BrowserContext, Page } from "playwright-core";
+import type { BrowserConfig, ProfileState, DownloadEntry, FormField, NavEntry, RefEntry, ReplayStep, SelectorHint } from "./types.js";
 /** 当前活动 profile 名(默认 "default")。 */
 export declare let currentProfile: string;
 /** 多配置文件浏览器会话:name → 会话状态。 */
@@ -8,12 +8,24 @@ export declare const profileStates: Map<string, ProfileState>;
 export declare const savedForms: Map<string, FormField[]>;
 /** 最近一次 browser_form 填充的字段(供 browser_form_save 无参保存)。 */
 export declare let lastFormFields: FormField[];
+/** 记录一次 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>;
+export interface SnapshotCache {
+    version: number;
+    text: string;
+    aria: string;
+}
+export declare function snapshotCacheOf(page: Page): SnapshotCache | undefined;
+export declare function setSnapshotCache(page: Page, cache: SnapshotCache): void;
 /** 已保存的录制脚本:name → 步骤数组。 */
 export declare const savedRecordings: Map<string, {
-    steps: {
-        tool: string;
-        args: any;
-    }[];
+    steps: ReplayStep[];
     savedAt: number;
 }>;
 /** 一次工具调用的记录(操作轨迹 / 录制 / 回放共用)。 */
@@ -24,15 +36,69 @@ export interface TestCall {
     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[];
-/** 操作轨迹追加(同时写入录制 buffer,排除 record/replay 自身)。 */
-export declare function recordCall(call: TestCall): void;
+/** 最近一次完整录制(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 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;
 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;
+/**
+ * 页内注入的人工操作监听(addInitScript 序列化;每次导航自动重装)。
+ * 监听常驻但 node 侧只在录制中生效,关闭录制等价于"移除"。
+ * 只上报可交互元素上的 click 与表单控件的 change,避免逐键噪音。
+ */
+export declare function installHumanRecorder(): void;
 /** 网络请求/响应记录。 */
 export interface NetworkEntry {
     url: string;
@@ -62,6 +128,14 @@ export declare function loadPlaywright(): Promise<typeof import("playwright-core
 export declare function launchProfile(name: string, config: BrowserConfig): Promise<void>;
 /** 当前 profile 状态(未启动时创建空状态)。 */
 export declare function stateOf(): ProfileState;
+export interface NamedContext {
+    context: BrowserContext;
+    pageIds: Set<number>;
+    createdAt: number;
+}
+export declare function namedContextsOf(): Map<string, NamedContext>;
+/** 把一个已 attach 的页面注册进 profile 标签表并激活,返回分配的 tab id。 */
+export declare function registerTabPage(state: ProfileState, page: Page): number;
 /** 新建一个页面(当前 profile 会话未启动时先启动)。 */
 export declare function newPage(config: BrowserConfig): Promise<Page>;
 /** 返回当前活动页面(没有则新建),并保证浏览器已启动。 */