@thincoder/core 0.10.4 → 0.10.6

package/browser/input.mjs

@@ -0,0 +1,256 @@
+/**
+ * browser/input.mjs — 输入引擎（纯函数）：键表 ∥ 修饰 / 移位解析 ∥ 序列构造器（键 ∥ 鼠标 ∥ 滚轮 ∥ 拖拽 ∥ 触屏）。
+ * 设计权威 = `docs/core/design/BROWSER-TOOL.md` §2.8（键面）∥ §2.7（坐标语义）∥ §6 KD-14 / KD-16；
+ * 本档零会话依赖（DAG 叶面——动作模块 import 本档，本档不 import 动作 / 会话 / 传输）。
+ *
+ * 序列形沿 CDP `Input` 域实证口径（对照 Puppeteer `cdp/Input.ts`）：
+ *  - 有文本产出的键 ⇒ `keyDown` + `text`；无 ⇒ `rawKeyDown`（协议注记：Control + A 一类不发文本）；
+ *  - 任一非 Shift 修饰在位 ⇒ 不发文本（`modifiers & ~8` 口径）；
+ *  - 修饰键按下 / 抬起逐事件演进 `modifiers` 位（按下先置位、抬起先清位——修饰态可被页面观察）。
+ * 坐标一律视口 CSS 像素（§2.7）。
+ */
+
+/** 修饰位（CDP `modifiers` 位域）。 */
+export const MODIFIER_BITS = { Alt: 1, Control: 2, Meta: 4, Shift: 8 }
+export const MODIFIER_ORDER = ["Alt", "Control", "Meta", "Shift"]
+
+/** 修饰键本体（按下 / 抬起事件面）。 */
+const MODIFIER_SLOTS = {
+  Alt: { key: "Alt", code: "AltLeft", vk: 18, loc: 1 },
+  Control: { key: "Control", code: "ControlLeft", vk: 17, loc: 1 },
+  Meta: { key: "Meta", code: "MetaLeft", vk: 91, loc: 1 },
+  Shift: { key: "Shift", code: "ShiftLeft", vk: 16, loc: 1 },
+}
+
+const FN_KEYS = {}
+for (let i = 1; i <= 12; i++) FN_KEYS[`F${i}`] = { key: `F${i}`, code: `F${i}`, vk: 111 + i }
+
+/** 命名键表（§2.8）：`{ key, code, vk, text?, loc? }`——值 = US 布局传统键码。 */
+export const NAMED_KEYS = {
+  Enter: { key: "Enter", code: "Enter", vk: 13, text: "\r" },
+  Escape: { key: "Escape", code: "Escape", vk: 27 },
+  Tab: { key: "Tab", code: "Tab", vk: 9, text: "\t" },
+  Backspace: { key: "Backspace", code: "Backspace", vk: 8 },
+  Delete: { key: "Delete", code: "Delete", vk: 46 },
+  Space: { key: " ", code: "Space", vk: 32, text: " " },
+  Insert: { key: "Insert", code: "Insert", vk: 45 },
+  Home: { key: "Home", code: "Home", vk: 36 },
+  End: { key: "End", code: "End", vk: 35 },
+  PageUp: { key: "PageUp", code: "PageUp", vk: 33 },
+  PageDown: { key: "PageDown", code: "PageDown", vk: 34 },
+  ArrowUp: { key: "ArrowUp", code: "ArrowUp", vk: 38 },
+  ArrowDown: { key: "ArrowDown", code: "ArrowDown", vk: 40 },
+  ArrowLeft: { key: "ArrowLeft", code: "ArrowLeft", vk: 37 },
+  ArrowRight: { key: "ArrowRight", code: "ArrowRight", vk: 39 },
+  ...FN_KEYS,
+  ...Object.fromEntries(Object.entries(MODIFIER_SLOTS).map(([name, slot]) => [name, { key: slot.key, code: slot.code, vk: slot.vk, loc: slot.loc }])),
+}
+
+/** 单字符行表（US 布局）：`[基键, 移位键, code, vk]`（`1`→`!`、`-`→`_`……）。 */
+const CHAR_ROWS = [
+  ["1", "!", "Digit1", 49], ["2", "@", "Digit2", 50], ["3", "#", "Digit3", 51], ["4", "$", "Digit4", 52],
+  ["5", "%", "Digit5", 53], ["6", "^", "Digit6", 54], ["7", "&", "Digit7", 55], ["8", "*", "Digit8", 56],
+  ["9", "(", "Digit9", 57], ["0", ")", "Digit0", 48],
+  ["-", "_", "Minus", 189], ["=", "+", "Equal", 187],
+  ["[", "{", "BracketLeft", 219], ["]", "}", "BracketRight", 221], ["\\", "|", "Backslash", 220],
+  [";", ":", "Semicolon", 186], ["'", "\"", "Quote", 222], ["`", "~", "Backquote", 192],
+  [",", "<", "Comma", 188], [".", ">", "Period", 190], ["/", "?", "Slash", 191],
+]
+
+/** 单字符 → 键面描述（`shift` = 该字符本身需 Shift；`alt` = 显式 Shift 时的产出形）。 */
+function charSpec(ch) {
+  if (ch === " ") return { key: " ", text: " ", code: "Space", vk: 32, shift: false, alt: null }
+  if (/^[a-z]$/.test(ch)) {
+    const up = ch.toUpperCase()
+    return { key: ch, text: ch, code: `Key${up}`, vk: up.charCodeAt(0), shift: false, alt: { key: up, text: up } }
+  }
+  if (/^[A-Z]$/.test(ch)) return { key: ch, text: ch, code: `Key${ch}`, vk: ch.charCodeAt(0), shift: true, alt: null }
+  for (const [base, shifted, code, vk] of CHAR_ROWS) {
+    if (ch === base) return { key: ch, text: ch, code, vk, shift: false, alt: { key: shifted, text: shifted } }
+    if (ch === shifted) return { key: ch, text: ch, code, vk, shift: true, alt: null }
+  }
+  return null
+}
+
+/** 键解析（§2.8）：命名键 ∥ 单字符（US 布局）；未列 ⇒ 抛 `unknown key "<k>" — keys: …`（不执行）。 */
+export function resolveKey(key) {
+  const raw = String(key ?? "")
+  const named = NAMED_KEYS[raw]
+  if (named) return { ...named, shift: false, alt: null }
+  if (raw.length === 1) {
+    const spec = charSpec(raw)
+    if (spec) return spec
+  }
+  throw new Error(`unknown key "${raw}" — keys: ${Object.keys(NAMED_KEYS).join(", ")} — or a single US-layout character (a-z, 0-9, punctuation)`)
+}
+
+/** 修饰数组归一（大小写不敏感 → 固定序 Alt/Control/Meta/Shift）；未列名 ⇒ 拒（不静默发裸键）。 */
+export function normalizeModifiers(list) {
+  const given = Array.isArray(list) ? list : []
+  const out = []
+  for (const raw of given) {
+    const name = MODIFIER_ORDER.find((m) => m.toLowerCase() === String(raw).toLowerCase())
+    if (!name) throw new Error(`unknown modifier "${raw}" — modifiers: ${MODIFIER_ORDER.join(", ")}`)
+    if (!out.includes(name)) out.push(name)
+  }
+  return MODIFIER_ORDER.filter((m) => out.includes(m))
+}
+
+function keyDownParams(slot, bits, { text = null, autoRepeat = false } = {}) {
+  const params = { type: text ? "keyDown" : "rawKeyDown", modifiers: bits, windowsVirtualKeyCode: slot.vk, code: slot.code, key: slot.key }
+  if (slot.loc) params.location = slot.loc
+  if (text) { params.text = text; params.unmodifiedText = text }
+  if (autoRepeat) params.autoRepeat = true
+  return { method: "Input.dispatchKeyEvent", params }
+}
+
+function keyUpParams(slot, bits) {
+  const params = { type: "keyUp", modifiers: bits, windowsVirtualKeyCode: slot.vk, code: slot.code, key: slot.key }
+  if (slot.loc) params.location = slot.loc
+  return { method: "Input.dispatchKeyEvent", params }
+}
+
+/**
+ * 按键序列（§2.8）：修饰键按下 → 主键（+`autoRepeat`×repeat）→ 主键抬起 → 修饰键抬起。
+ * `phase` = down（只按）∥ up（只抬）∥ press（默认 = 按 + 抬）；`repeat` 0–100（越界夹取）。
+ * @returns {{combo: string, commands: Array<{method: string, params: object}>}}
+ */
+export function pressSequence({ key, modifiers = [], phase = "press", repeat = 0 } = {}) {
+  const spec = resolveKey(key)
+  const mods = normalizeModifiers(modifiers)
+  const wanted = Number(repeat)
+  const repeatCount = Math.max(0, Math.min(Number.isFinite(wanted) ? Math.floor(wanted) : 0, 100))
+  const autoShift = spec.shift && !mods.includes("Shift") // 大写字母 / 移位符号 ⇒ 自动置 Shift 位（§2.8）
+  const shift = spec.shift || mods.includes("Shift")
+  const main = (shift && spec.alt ? spec.alt : { key: spec.key, text: spec.text })
+  const mainSlot = { key: main.key, code: spec.code, vk: spec.vk, loc: spec.loc }
+  const text = mods.some((m) => m !== "Shift") ? null : (main.text ?? null) // 非 Shift 修饰 ⇒ 不发文本
+  const bitsAll = mods.reduce((acc, m) => acc | MODIFIER_BITS[m], 0) | (autoShift ? MODIFIER_BITS.Shift : 0)
+  const commands = []
+  if (phase !== "up") {
+    let bits = 0
+    for (const name of mods) {
+      bits |= MODIFIER_BITS[name]
+      commands.push(keyDownParams(MODIFIER_SLOTS[name], bits))
+    }
+    for (let i = 0; i <= repeatCount; i++) commands.push(keyDownParams(mainSlot, bitsAll, { text, autoRepeat: i > 0 }))
+  }
+  if (phase !== "down") {
+    commands.push(keyUpParams(mainSlot, bitsAll))
+    let bits = bitsAll
+    for (const name of [...mods].reverse()) {
+      bits &= ~MODIFIER_BITS[name]
+      commands.push(keyUpParams(MODIFIER_SLOTS[name], bits))
+    }
+  }
+  return { combo: [...mods, spec.key].join("+"), repeat: repeatCount, commands }
+}
+
+/** 鼠标按钮位（CDP `buttons` 位域）——键序 = 报错枚举序。 */
+export const MOUSE_BUTTONS = { left: 1, middle: 4, right: 2, back: 8, forward: 16 }
+
+function mouseEvent(type, x, y, extra = {}) {
+  return { method: "Input.dispatchMouseEvent", params: { type, x, y, ...extra } }
+}
+
+/** 指针移动序列（hover——仅 `mouseMoved`）。 */
+export function moveSequence({ x, y } = {}) {
+  return [mouseEvent("mouseMoved", x, y, { button: "none", buttons: 0 })]
+}
+
+/** 鼠标序列（§2.2 mouse）：click = 移动 → 按下 → 抬起（double ⇒ clickCount 1、2）；down / up = 单边。 */
+export function mouseSequence({ x, y, button = "left", phase = "click", double = false } = {}) {
+  const flag = MOUSE_BUTTONS[button]
+  if (!flag) throw new Error(`unknown mouse button "${button}" — buttons: ${Object.keys(MOUSE_BUTTONS).join(", ")}`)
+  const shape = phase === "down" || phase === "up" ? phase : "click"
+  const commands = []
+  if (shape !== "up") commands.push(mouseEvent("mouseMoved", x, y, { button: "none", buttons: 0 }))
+  if (shape === "down") {
+    commands.push(mouseEvent("mousePressed", x, y, { button, buttons: flag, clickCount: 1 }))
+  } else if (shape === "up") {
+    commands.push(mouseEvent("mouseReleased", x, y, { button, buttons: 0, clickCount: 1 }))
+  } else {
+    const times = double ? 2 : 1
+    for (let i = 1; i <= times; i++) {
+      commands.push(mouseEvent("mousePressed", x, y, { button, buttons: flag, clickCount: i }))
+      commands.push(mouseEvent("mouseReleased", x, y, { button, buttons: 0, clickCount: i }))
+    }
+  }
+  return commands
+}
+
+/** 滚轮序列（§2.2 wheel）：落点处一发 `mouseWheel`（`deltaX` / `deltaY` 至少一非零——校验在工具面）。 */
+export function wheelSequence({ x, y, deltaX = 0, deltaY = 0 } = {}) {
+  return [mouseEvent("mouseWheel", x, y, { button: "none", buttons: 0, pointerType: "mouse", deltaX, deltaY })]
+}
+
+/** 中间步数夹取（§2.2：默认 10 · 2–50）。 */
+export function clampSteps(value, fallback = 10) {
+  const n = Number(value)
+  const base = Number.isFinite(n) ? Math.floor(n) : fallback
+  return Math.max(2, Math.min(base, 50))
+}
+
+/** 拖拽序列（KD-16 默认形——鼠标序列）：按下 → 移动×steps（末步落于 `to`）→ 抬起（`release:false` ⇒ 只按不放——html5 拦截链用）。 */
+export function dragSequence({ from, to, steps = 10, release = true } = {}) {
+  const n = clampSteps(steps)
+  const commands = [mouseEvent("mouseMoved", from.x, from.y, { button: "none", buttons: 0 })]
+  commands.push(mouseEvent("mousePressed", from.x, from.y, { button: "left", buttons: MOUSE_BUTTONS.left, clickCount: 1 }))
+  for (let i = 1; i <= n; i++) {
+    const x = from.x + (to.x - from.x) * (i / n)
+    const y = from.y + (to.y - from.y) * (i / n)
+    commands.push(mouseEvent("mouseMoved", x, y, { button: "left", buttons: MOUSE_BUTTONS.left }))
+  }
+  if (release) commands.push(mouseEvent("mouseReleased", to.x, to.y, { button: "left", buttons: 0, clickCount: 1 }))
+  return commands
+}
+
+/** 触屏手势面（§2.2 touch gesture——工具面同表校验）。 */
+export const TOUCH_GESTURES = ["tap", "doubleTap", "swipe", "pinch"]
+/** doubleTap 两次序列之间的间隔（同一双击窗内——双击计数仍由浏览器手势引擎管）。 */
+export const TOUCH_TAP_GAP_MS = 60
+
+/** 触屏点形（CDP TouchPoint——坐标取整）。 */
+function touchPoint(px, py) {
+  return { x: Math.round(px), y: Math.round(py), radiusX: 0.5, radiusY: 0.5, force: 0.5, id: 1 }
+}
+
+/** 单次打字序列（tap）：touchStart → touchEnd（同点同 id）——全链 click 实证（KD-14 收正）。 */
+function touchTapCommands(x, y) {
+  return [
+    { method: "Input.dispatchTouchEvent", params: { type: "touchStart", touchPoints: [touchPoint(x, y)] } },
+    { method: "Input.dispatchTouchEvent", params: { type: "touchEnd", touchPoints: [touchPoint(x, y)] } },
+  ]
+}
+
+/**
+ * 触屏序列（KD-14 实证收正）：tap / doubleTap 走 `dispatchTouchEvent` 显式序列（全链 mousedown/mouseup/click
+ * 实证；synthesizeTapGesture 实测不产 click）；pinch 走 `synthesizePinchGesture`（实测有效）；
+ * swipe 走显式路径（手指路径语义——from → to 插值 ×steps）。
+ * doubleTap = 同序列×2 + `TOUCH_TAP_GAP_MS` 间隔（时序在动作层控——双击计数由浏览器管）。
+ */
+export function touchSequence({ gesture = "tap", x, y, from, to, steps = 10, scale } = {}) {
+  if (gesture === "tap" || gesture === "doubleTap") return touchTapCommands(x, y)
+  if (gesture === "pinch") {
+    return [{ method: "Input.synthesizePinchGesture", params: { x, y, scaleFactor: scale } }]
+  }
+  if (!TOUCH_GESTURES.includes(gesture)) throw new Error(`unknown touch gesture "${gesture}" — gestures: ${TOUCH_GESTURES.join(", ")}`)
+  const n = clampSteps(steps)
+  const commands = [{ method: "Input.dispatchTouchEvent", params: { type: "touchStart", touchPoints: [touchPoint(from.x, from.y)] } }]
+  for (let i = 1; i <= n; i++) {
+    const px = from.x + (to.x - from.x) * (i / n)
+    const py = from.y + (to.y - from.y) * (i / n)
+    commands.push({ method: "Input.dispatchTouchEvent", params: { type: "touchMove", touchPoints: [touchPoint(px, py)] } })
+  }
+  commands.push({ method: "Input.dispatchTouchEvent", params: { type: "touchEnd", touchPoints: [touchPoint(to.x, to.y)] } })
+  return commands
+}
+
+/** 目标形解析（§2.2：`e<N>` ∥ `"x,y"`）；不符 ⇒ null（调用面拒——`must be an element ref (e<N>) or "x,y"`）。 */
+export function parseTargetSpec(spec) {
+  const raw = String(spec ?? "").trim()
+  if (/^e\d+$/.test(raw)) return { kind: "ref", ref: raw }
+  const m = /^(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)$/.exec(raw)
+  if (m) return { kind: "point", x: Number(m[1]), y: Number(m[2]) }
+  return null
+}

package/browser/launch.mjs

@@ -0,0 +1,143 @@
+/**
+ * browser/launch.mjs — 浏览器发现 ∥ profile 锁 ∥ 启动 ∥ 杀树（BROWSER-TOOL.md §4）。
+ *
+ * 候选表与启动参数沿 `scripts/console-walkthrough.mjs:33-44`（Edge 先于 Chrome）∥ `:123`
+ * （`--headless=new` ∥ `--remote-debugging-port=0` ∥ `stdio:"ignore"` ∥ POSIX `detached`）——
+ * 本档不 import 该脚本，只内化其形。
+ * profile = `~/.thincoder/browser/profile`（`configDir` 同源——`config-io.mjs:32`）= **持久**
+ * （F-BT6：有头登录一次 ⇒ 后续含无头复用登录态）。
+ *
+ * 注入缝（N-BT6）：`resolveBrowser({platform, env, pathExists, which})` 与 `acquireProfileLock`
+ * 的 `io`——缺省回落真实现，单元测试零真实文件系统。
+ */
+import { execFileSync, spawn } from "node:child_process"
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { configDir } from "../config-io.mjs"
+
+/** 平台候选表（edge 先于 chrome——walkthrough 实证表）。 */
+export const CANDIDATES = {
+  edge: {
+    win32: ["C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe", "C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe"],
+    darwin: ["/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"],
+    linux: ["microsoft-edge", "microsoft-edge-stable"],
+  },
+  chrome: {
+    win32: ["C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe", "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe"],
+    darwin: ["/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"],
+    linux: ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser"],
+  },
+}
+
+/** 全候选落空（N-BT5）——装配期不剔除工具，首用显式报此句（§2.6）。 */
+export const BROWSER_NOT_FOUND = "no Chromium-based browser found (Edge/Chrome) — install one or set BROWSER_PATH"
+export const START_TIMEOUT_MS = 12_000
+
+const defaultPathExists = (p) => existsSync(p)
+function defaultWhich(name) {
+  try { return execFileSync("which", [name], { stdio: ["ignore", "pipe", "ignore"] }).toString().trim() || null }
+  catch { return null }
+}
+
+/** 浏览器可执行文件解析：`BROWSER_PATH`（exe 路径 ∥ 名字）→ 候选表 edge → chrome；全空 ⇒ 抛钉死句。 */
+export function resolveBrowser({ platform = process.platform, env = process.env, pathExists = defaultPathExists, which = defaultWhich } = {}) {
+  const lookup = (candidate) => (candidate.includes("/") || candidate.includes("\\")
+    ? (pathExists(candidate) ? candidate : null)
+    : which(candidate))
+  const override = String(env?.BROWSER_PATH ?? "").trim()
+  if (override) {
+    const byName = CANDIDATES[override.toLowerCase()]
+    for (const candidate of byName ? byName[platform] ?? [] : [override]) {
+      const found = lookup(candidate)
+      if (found) return found
+    }
+    // 覆盖值不可用 ⇒ 落回候选表（不静默吞：表亦空时抛钉死句——「设置 BROWSER_PATH」指引仍成立）
+  }
+  for (const family of Object.values(CANDIDATES)) {
+    for (const candidate of family[platform] ?? []) {
+      const found = lookup(candidate)
+      if (found) return found
+    }
+  }
+  throw new Error(BROWSER_NOT_FOUND)
+}
+
+/** 本工具的持久化面（profile ∥ 锁 ∥ 截图目录）。 */
+export function browserPaths(base = configDir) {
+  const root = join(base, "browser")
+  return { root, profile: join(root, "profile"), lock: join(root, "session.lock"), shots: join(root, "shots") }
+}
+
+function defaultPidAlive(pid) {
+  try { process.kill(pid, 0); return true }
+  catch (e) { return e?.code === "EPERM" } // 存在但无权限 ⇒ 视为活着（保守）
+}
+
+/**
+ * profile 锁（单会话/进程——KD-5）：他进程持有 ⇒ 抛 `browser profile in use by another
+ * ThinCoder instance (pid <N>)`；陈旧锁（pid 死）⇒ 接管。
+ * `io` = 注入缝（readText ∥ writeText ∥ isAlive ∥ pid）——缺省真文件系统。
+ */
+export function acquireProfileLock(lockPath, io = {}) {
+  const readText = io.readText ?? ((p) => { try { return readFileSync(p, "utf8") } catch { return "" } })
+  const writeText = io.writeText ?? ((p, text) => { mkdirSync(dirname(p), { recursive: true }); writeFileSync(p, text, "utf8") })
+  const isAlive = io.isAlive ?? defaultPidAlive
+  const pid = io.pid ?? process.pid
+  const held = Number(String(readText(lockPath) ?? "").trim())
+  if (Number.isInteger(held) && held > 0 && held !== pid && isAlive(held)) {
+    throw new Error(`browser profile in use by another ThinCoder instance (pid ${held})`)
+  }
+  writeText(lockPath, String(pid))
+  return { pid }
+}
+
+export function releaseProfileLock(lockPath, io = {}) {
+  const removeText = io.removeText ?? ((p) => { try { rmSync(p, { force: true }) } catch { /* 已被接管/清除 */ } })
+  removeText(lockPath)
+}
+
+/**
+ * 启动浏览器（spawn + `DevToolsActivePort` 轮询 ≤12s）。
+ * 持久 profile ⇒ 启动前清陈旧端口文件（否则旧值被当本次读数——发现即失效）。
+ * @returns {Promise<{child: import("node:child_process").ChildProcess, port: number, profile: string}>}
+ */
+export async function launchBrowser({ exe, headless = true, profile, timeoutMs = START_TIMEOUT_MS, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+  const args = [
+    ...(headless ? ["--headless=new"] : []),
+    "--disable-gpu", "--no-first-run", "--hide-scrollbars",
+    `--user-data-dir=${profile}`, "--remote-debugging-port=0",
+    "--window-size=1440,900", "about:blank",
+  ]
+  mkdirSync(profile, { recursive: true })
+  const portFile = join(profile, "DevToolsActivePort")
+  rmSync(portFile, { force: true })
+  const child = spawn(exe, args, { stdio: "ignore", detached: process.platform !== "win32" })
+  let spawnError = null
+  child.on("error", (e) => { spawnError = e }) // 捕获（否则 unhandled 'error' 事件崩进程）；下面显式上报
+  const deadline = Date.now() + timeoutMs
+  while (!existsSync(portFile)) {
+    if (spawnError) { killBrowser(child); throw new Error(`browser failed to start: ${spawnError.message} (${exe})`) }
+    if (child.exitCode !== null || Date.now() >= deadline) {
+      killBrowser(child)
+      throw new Error(`browser failed to start: DevToolsActivePort not written within ${Math.round(timeoutMs / 1000)}s (${exe})`)
+    }
+    await sleep(50)
+  }
+  const port = Number(String(readFileSync(portFile, "utf8")).split("\n")[0])
+  if (!Number.isInteger(port) || port <= 0) {
+    killBrowser(child)
+    throw new Error(`browser failed to start: DevToolsActivePort is malformed (${exe})`)
+  }
+  return { child, port, profile }
+}
+
+/** 杀整棵进程树（win32 `taskkill /T /F`；POSIX 组杀 + 单杀兜底——walkthrough `:192-193` 同式）。 */
+export function killBrowser(child, { platform = process.platform, exec = execFileSync } = {}) {
+  if (!child || typeof child.pid !== "number") return
+  if (platform === "win32") {
+    try { exec("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore" }) } catch { /* 已退出 */ }
+    return
+  }
+  try { process.kill(-child.pid, "SIGKILL") }
+  catch { try { child.kill("SIGKILL") } catch { /* 已退出 */ } }
+}

package/browser/queue.mjs

@@ -0,0 +1,171 @@
+/**
+ * browser/queue.mjs — 调度策略：串行队列 ∥ 动作预算表 ∥ 动作控制器（超时 / 取消单点）∥ 步名跟踪
+ * （设计权威 = `docs/core/design/BROWSER-TOOL.md` §2.9——单时钟动作预算 + 三层帽；KD-18 ∥ KD-19）。
+ *
+ * 单时钟：预算 deadline 自**入队**起算（队列等待计入预算——有意）；到点 ⇒ 控制器 `abort`（超时因由）。
+ * 排队期到点 ⇒ 动作从未起执行（回执步名 `queue wait`）；动作内到点 ⇒ 步名 = 在飞阶段 / CDP 方法名。
+ * 控制器（超时 ∥ 取消共用——KD-19）：abort 后在飞操作以同一因由拒绝，其后一切调用**快速失败**
+ * （清理路径不得再起命令——防僵尸命令与下一动作交错）。
+ * 步名：`ctl.run(name, fn)` 压帧（栈顶 = `stuck in <步名>` 的读数源）；`h.call` 帧 = CDP 方法名（session 侧接线）。
+ */
+import { WAIT_TIMEOUT_DEFAULT, WAIT_TIMEOUT_MAX } from "./actions.mjs"
+
+/** 动作预算表（§2.9——机检）：动作 ⇒ 预算 ms。wait 无固定值（谓词帽 + 余量——`budgetFor` 解算）。 */
+export const ACTION_BUDGETS = {
+  navigate: 45_000, // 含会话自启（12s 启动帽内）+ 导航 + 就绪轮询 + 快照
+  click: 30_000,
+  evaluate: 30_000,
+  screenshot: 30_000,
+  close: 30_000,
+  press: 30_000,
+  hover: 30_000,
+  wheel: 30_000,
+  mouse: 30_000,
+  drag: 30_000,
+  touch: 30_000,
+  insert: 30_000,
+  clipboard: 30_000,
+  type: 15_000, // 单页内快动作
+  snapshot: 15_000,
+  wait: 45_000, // = 谓词帽缺省 30s + 15s 余量（timeoutMs 给出时按帽 + 余量重解——§2.9 表）
+}
+export const BUDGET_FALLBACK_MS = 30_000 // 未在册动作的兜底预算（防御——全部在册动作已列）
+export const BUDGET_MAX_MS = 120_000 // `timeoutMs` override 硬上限（§2.9）
+export const WAIT_MARGIN_MS = 15_000 // wait 预算余量（谓词帽之上——§2.9 表）
+export const QUEUE_WAIT_STEP = "queue wait"
+
+/** 预算解算（§2.9）：`timeoutMs` = 动作预算 override（硬上限 120s）；wait = 谓词帽 + 15s 余量（语义零变）。 */
+export function budgetFor(action, args = {}) {
+  const wanted = Number(args?.timeoutMs)
+  const given = Number.isFinite(wanted) && wanted > 0
+  if (action === "wait") {
+    return (given ? Math.min(wanted, WAIT_TIMEOUT_MAX) : WAIT_TIMEOUT_DEFAULT) + WAIT_MARGIN_MS
+  }
+  if (given) return Math.min(wanted, BUDGET_MAX_MS)
+  return ACTION_BUDGETS[action] ?? BUDGET_FALLBACK_MS
+}
+
+/** 单动作控制器：超时 / 取消 / 会话丢失共用一个中止点（一个机制多个因由——KD-19）。 */
+export class ActionController {
+  constructor({ action, budgetMs }) {
+    this.action = action
+    this.budgetMs = budgetMs
+    this.aborted = false
+    this.reason = null
+    this.error = null
+    this._deadline = Date.now() + budgetMs
+    this._steps = []
+    this._abortHooks = []
+    this._abortP = new Promise((resolve) => { this._resolveAbort = resolve })
+    this._timer = setTimeout(() => this.abort("timeout"), budgetMs)
+  }
+
+  /** 剩余预算（ms）——动作内调用帽的下界参照（§2.9 层一：动作内调用随控制器）。 */
+  remaining() {
+    return Math.max(1, this._deadline - Date.now())
+  }
+
+  /** 快速失败（§2.9）：abort 之后一切后续调用即刻拒绝（清理路径不得再起命令）。 */
+  failIfAborted() {
+    if (this.aborted) throw this.error
+  }
+
+  /** 步名帧 + 中止守卫：帧存活期栈顶 = `stuck in <name>` 读数源；work 随中止以同一因由拒绝。 */
+  run(name, work) {
+    this.failIfAborted()
+    this._steps.push(name)
+    let out
+    try { out = work() } catch (e) { this._pop(name); throw e }
+    return this.guard(Promise.resolve(out)).finally(() => this._pop(name))
+  }
+
+  /** 中止守卫：在飞工作与中止竞速（未中止 ⇒ 原样返回）。 */
+  guard(work) {
+    if (this.aborted) return Promise.reject(this.error)
+    return Promise.race([work, this._abortP.then(() => Promise.reject(this.error))])
+  }
+
+  /** 受控等待（§2.9 层一：轮询 sleep 同受控）。 */
+  async sleep(ms) {
+    let timer = null
+    try {
+      await this.guard(new Promise((resolve) => { timer = setTimeout(resolve, ms) }))
+    } finally {
+      if (timer) clearTimeout(timer)
+    }
+  }
+
+  /** 订阅一次中止（发出即退订）；返回退订函数。 */
+  onAbort(fn) {
+    if (this.aborted) { fn(); return () => {} }
+    this._abortHooks.push(fn)
+    return () => { this._abortHooks = this._abortHooks.filter((hook) => hook !== fn) }
+  }
+
+  /** 中止单点：因由 = timeout ∥ cancelled ∥ session-lost（错误句分形——§2.9 / §2.10）。 */
+  abort(reason, error = null) {
+    if (this.aborted) return this.error
+    this.aborted = true
+    this.reason = reason
+    this.error = error ?? this._makeError(reason)
+    if (this._timer) { clearTimeout(this._timer); this._timer = null }
+    this._resolveAbort()
+    for (const hook of this._abortHooks.splice(0)) { try { hook() } catch { /* 订阅者自担 */ } }
+    return this.error
+  }
+
+  /** 取消（§2.11 kill 单点——与超时共用控制器）。 */
+  cancel() {
+    return this.abort("cancelled")
+  }
+
+  /** 动作结束（清钟——不中止）。 */
+  finish() {
+    if (this._timer) { clearTimeout(this._timer); this._timer = null }
+  }
+
+  _pop(name) {
+    const at = this._steps.lastIndexOf(name)
+    if (at >= 0) this._steps.splice(at, 1)
+  }
+
+  _makeError(reason) {
+    const step = this._steps.at(-1) ?? QUEUE_WAIT_STEP
+    const message = reason === "cancelled"
+      ? `${this.action} cancelled (stuck in ${step})`
+      : `${this.action} timed out after ${this.budgetMs}ms (stuck in ${step}) — retry the action, or run \`close\` to reset the session`
+    const error = new Error(message)
+    error.browserAbort = true
+    error.abortReason = reason
+    return error
+  }
+}
+
+/** 串行队列（§2.4：批并行调用按调用序排队——单页不引入并发）。 */
+export function createActionQueue() {
+  let tail = Promise.resolve()
+  const chain = (task) => {
+    const next = tail.then(task)
+    tail = next.then(() => { /* 保持链活 */ }, () => { /* 失败不断链 */ })
+    return next
+  }
+  return {
+    /** 入队动作：`run(ctl)` 起执行；返回终态（回执 ∥ 拒绝）。排队中到点 ⇒ 即时以同失败形拒绝
+     *  （`queue wait`——动作从未起执行）；起执行后由任务自身守卫裁决 —— 回执/拒绝晚于动作收尾
+     *  （调用方拿到终态时会话侧清理已完成，不留残余控制器）。
+     *  signal（批 browser-async-fix 最小增补——可选取消柄）：abort ⇒ `cancel()`（queued 丢队 ∥ running 展开）；缺省 null 旧调用零变。 */
+    enqueue(action, args, run, signal = null) {
+      const ctl = new ActionController({ action, budgetMs: budgetFor(action, args) })
+      if (signal?.aborted) ctl.cancel()
+      else signal?.addEventListener("abort", () => ctl.cancel(), { once: true })
+      let started = false
+      const task = chain(() => { started = true; return run(ctl) }).finally(() => ctl.finish())
+      return new Promise((resolve, reject) => {
+        task.then(resolve, reject)
+        ctl.onAbort(() => { if (!started) reject(ctl.error) })
+      })
+    },
+    /** 队列直通（无预算语义——空闲关等动作外路径）。 */
+    chain,
+  }
+}