// `tools/cdp.mjs` 的类型声明。
//
// 它是纯 JS，以前没有任何声明——于是每个 import 它的验收脚本都退化成 `any`，
// 连带 `withPage(..., ({ send, evaluate }) => ...)` 的解构参数全部是隐式 any。
// 一个 20 行的声明就能把那一整类错误消掉（实测 180 处里占 41 处）。
//
// 这里刻意用 `any` 而不是 `unknown` 作为 evaluate/send 的返回值：它们直通 CDP，
// 返回什么完全取决于传进去的表达式字符串，静态上无从约束——写成 `unknown` 只会逼每个
// 调用点加断言，反而把噪音搬了个地方。

export interface PageOptions {
  width?: number;
  height?: number;
  /** Edge 的 user-data-dir；给不同脚本各用一个，免得并发时互相踢掉。 */
  profile?: string;
  extraArgs?: string[];
}

/** 一个已连上的页面。 */
export interface Page {
  /** 发一条 CDP 命令。 */
  send(method: string, params?: Record<string, unknown>): Promise<any>;
  /** 在页面里求值并取回值。表达式里的异常会抛出来。 */
  evaluate(expression: string): Promise<any>;
  /** 页面控制台输出（含 Log.entryAdded 的 error）。 */
  consoleLines: string[];
  /** 未捕获异常。 */
  exceptions: string[];
  /** Edge 的 stderr，排查启动失败时用。 */
  stderr(): string;
}

/**
 * 起一个无头 Edge、连上它、执行 `fn`，结束后收掉浏览器。
 * `fn` 的返回值原样返回。
 */
export function withPage<T>(opts: PageOptions, fn: (page: Page) => Promise<T>): Promise<T>;

export function sleep(ms: number): Promise<void>;