@thincoder/core 0.10.5 → 0.10.6

package/browser/input-actions.mjs

@@ -0,0 +1,197 @@
+/**
+ * browser/input-actions.mjs — 新七动作实现（press / hover / wheel / mouse / drag / touch / insert）
+ * + 目标解析（ref → 真点 ∥ x,y）（BROWSER-TOOL.md §2.2 ∥ §2.7 ∥ §6 KD-14 / KD-16 / KD-17）。
+ *
+ * 会话能力一律经句柄取（`h.call` / `h.evalRaw` / `h.ensureSession` / `h.resolveRef` / `h.focusRef` /
+ * `h.once` / `h.pageError`）——本档不 import `session.mjs`（DAG 单向，§5 拆分决定）。
+ * 一切 ref 寻址的输入动作经 `pointExpression` 自动滚动到视（F-BT14——视口外目标同样可驱）。
+ */
+import { clampSteps, dragSequence, mouseSequence, moveSequence, parseTargetSpec, pressSequence, TOUCH_GESTURES, TOUCH_TAP_GAP_MS, touchSequence, wheelSequence } from "./input.mjs"
+import { pointExpression } from "./snapshot.mjs"
+
+export const WHEEL_SETTLE_MS = 800 // 卷动稳定读数上限（§2.2 wheel 判据）
+export const IME_COMMIT_BREATH_MS = 50 // 组合与提交之间留一拍（中间态可观察——KD-17）
+export const DRAG_INTERCEPT_TIMEOUT_MS = 5_000 // html5 拖拽拦截等待（无拦截事件 ⇒ 明示拒——不悬挂）
+
+async function sendAll(h, commands) {
+  for (const cmd of commands) await h.call(cmd.method, cmd.params)
+}
+
+/** 视口中心（wheel 落点缺省——§2.2）。 */
+async function viewportCenter(h) {
+  const v = await h.evalRaw("({ x: Math.round(innerWidth / 2), y: Math.round(innerHeight / 2) })")
+  const x = Number(v?.x ?? 0)
+  const y = Number(v?.y ?? 0)
+  return { x, y, ref: null, name: null, label: `${x},${y}` }
+}
+
+/** 目标解析（§2.7）：ref ⇒ 表查 + `pointExpression`（滚动到视 + 中心点）；x,y ⇒ 直读；缺省 ⇒ fallback。 */
+async function targetOf(args, h, fallback = null) {
+  const hasRef = typeof args?.ref === "string" && args.ref !== ""
+  const hasXY = args?.x !== undefined && args?.y !== undefined && Number.isFinite(Number(args.x)) && Number.isFinite(Number(args.y))
+  if (hasRef) {
+    const entry = h.resolveRef(args.ref)
+    const p = await h.evalRaw(pointExpression(entry.selector, entry.tag))
+    if (!p?.found || p.tag) throw h.pageError(`ref ${args.ref} is stale (was "${entry.name}") — run snapshot again`)
+    return { x: Number(p.x), y: Number(p.y), ref: args.ref, name: entry.name, label: `${args.ref} "${entry.name}"` }
+  }
+  if (hasXY) return { x: Number(args.x), y: Number(args.y), ref: null, name: null, label: `${Number(args.x)},${Number(args.y)}` }
+  if (fallback) return fallback(h)
+  throw new Error(`${args?.action ?? "action"} requires ref or x,y`)
+}
+
+/** `e<N>` ∥ `"x,y"` 形目标（drag / touch swipe 的 from、to——§2.2）。 */
+async function specTarget(spec, h, action, param) {
+  const parsed = parseTargetSpec(spec)
+  if (!parsed) throw new Error(`${action} ${param} must be an element ref (e<N>) or "x,y"`)
+  if (parsed.kind === "ref") return targetOf({ ref: parsed.ref }, h)
+  return { x: parsed.x, y: parsed.y, ref: null, name: null, label: `${parsed.x},${parsed.y}` }
+}
+
+/** press（§2.2）：真按键链 + 携 ref 先聚焦（§2.7）；未知键 ⇒ 未起会话先拒（不执行）。 */
+async function actPress(args, ctx, h) {
+  const seq = pressSequence({ key: args.key, modifiers: args.modifiers, phase: args.phase, repeat: args.repeat })
+  await h.ensureSession(args)
+  let target = ""
+  if (typeof args.ref === "string" && args.ref !== "") {
+    const f = await h.focusRef(args.ref)
+    target = ` → ${f.label}`
+  }
+  await sendAll(h, seq.commands)
+  const repeat = seq.repeat > 0 ? ` ×${seq.repeat}` : ""
+  const phase = args.phase === "down" || args.phase === "up" ? ` (${args.phase})` : ""
+  return `[press] ${seq.combo}${repeat}${phase}${target}`
+}
+
+/** hover（§2.2）：指针移动（无激活）。 */
+async function actHover(args, ctx, h) {
+  await h.ensureSession(args)
+  const t = await targetOf(args, h)
+  await sendAll(h, moveSequence({ x: t.x, y: t.y }))
+  return `[hover] ${t.label}`
+}
+
+/** 卷动稳定读数（≤800ms——两次连读相等即定）；标 `scroll settle` 步名（§2.9 卡点可诊断）。 */
+async function settleScroll(h, maxMs = WHEEL_SETTLE_MS) {
+  return h.step("scroll settle", async () => {
+    const deadline = Date.now() + maxMs
+    let last = null
+    for (;;) {
+      const v = await h.evalRaw("({ x: Math.round(window.scrollX), y: Math.round(window.scrollY) })")
+      const reading = { x: Number(v?.x ?? 0), y: Number(v?.y ?? 0) }
+      if (last && last.x === reading.x && last.y === reading.y) return reading
+      if (Date.now() >= deadline) return reading
+      last = reading
+      await h.sleep(100)
+    }
+  })
+}
+
+/** wheel（§2.2）：落点缺省 = 视口中心；回执 = 卷动后 window 读数。 */
+async function actWheel(args, ctx, h) {
+  await h.ensureSession(args)
+  const deltaX = Number(args.deltaX ?? 0) || 0
+  const deltaY = Number(args.deltaY ?? 0) || 0
+  const t = await targetOf(args, h, viewportCenter)
+  await sendAll(h, wheelSequence({ x: t.x, y: t.y, deltaX, deltaY }))
+  const win = await settleScroll(h)
+  return `[wheel] Δ(${deltaX},${deltaY}) at ${Math.round(t.x)},${Math.round(t.y)} — window (${win.x},${win.y})`
+}
+
+/** mouse（§2.2）：真指针（命中测试生效）；形 = click（默认）∥ down ∥ up；double ⇒ clickCount 1、2。 */
+async function actMouse(args, ctx, h) {
+  await h.ensureSession(args)
+  const t = await targetOf(args, h)
+  const phase = args.phase === "down" || args.phase === "up" ? args.phase : "click"
+  const double = args.double === true
+  const button = String(args.button ?? "left")
+  await sendAll(h, mouseSequence({ x: t.x, y: t.y, button, phase, double }))
+  const shape = phase === "click" ? (double ? "doubleClick" : "click") : phase
+  return `[mouse] ${button} ${shape} ${t.label}`
+}
+
+/** HTML5 原生拖放（KD-16，实验）：拦截 → `dragIntercepted` 取 DragData → 事件三连 → 投递 → 抬起。 */
+async function html5Drag(h, from, to, steps) {
+  await h.call("Input.setInterceptDrags", { enabled: true })
+  try {
+    const intercepted = h.once("Input.dragIntercepted", DRAG_INTERCEPT_TIMEOUT_MS)
+    // 占位消费者：下方 sendAll 抛出时该 promise 无人 await——无此挂载即 unhandled 拒绝（宿主进程级 fatal）。
+    intercepted.catch(() => {})
+    await sendAll(h, dragSequence({ from, to, steps, release: false }))
+    let data
+    try { data = (await intercepted).data } catch (e) {
+      if (e?.browserAbort || e?.sessionLost) throw e // 预算中止 / 外部关闭 ⇒ 原样上报（不冒名「未拦截」）
+      throw new Error("html5 drag was not intercepted — the source may not be a native draggable; retry without html5")
+    }
+    await h.call("Input.dispatchDragEvent", { type: "dragEnter", x: to.x, y: to.y, data })
+    await h.call("Input.dispatchDragEvent", { type: "dragOver", x: to.x, y: to.y, data })
+    await h.call("Input.dispatchDragEvent", { type: "drop", x: to.x, y: to.y, data })
+    await sendAll(h, mouseSequence({ x: to.x, y: to.y, phase: "up" }))
+  } finally {
+    try { await h.call("Input.setInterceptDrags", { enabled: false }) } catch { /* 会话已断——拦截位随进程 */ }
+  }
+}
+
+/** drag（§2.2）：默认鼠标序列（按下 → 移动×steps → 抬起）；`html5:true` = 拦截链（KD-16）。 */
+async function actDrag(args, ctx, h) {
+  await h.ensureSession(args)
+  const from = await specTarget(args.from, h, "drag", "from")
+  const to = await specTarget(args.to, h, "drag", "to")
+  const steps = clampSteps(args.steps)
+  if (args.html5 === true) await html5Drag(h, from, to, steps)
+  else await sendAll(h, dragSequence({ from, to, steps }))
+  return `[drag] ${from.label} → ${to.label}${args.html5 === true ? " (html5)" : ""}`
+}
+
+/** touch（§2.2）：tap / doubleTap / pinch（落点 + scale）∥ swipe（from → to）；KD-14 分工在引擎档。 */
+async function actTouch(args, ctx, h) {
+  const gesture = String(args.gesture ?? "tap")
+  if (!TOUCH_GESTURES.includes(gesture)) throw new Error(`unknown touch gesture "${gesture}" — gestures: ${TOUCH_GESTURES.join(", ")}`)
+  await h.ensureSession(args)
+  if (gesture === "swipe") {
+    const from = await specTarget(args.from, h, "touch", "from")
+    const to = await specTarget(args.to, h, "touch", "to")
+    await sendAll(h, touchSequence({ gesture, from, to, steps: clampSteps(args.steps) }))
+    return `[touch] swipe ${from.label} → ${to.label}`
+  }
+  const t = await targetOf(args, h)
+  if (gesture === "pinch") {
+    const scale = Number(args.scale)
+    await sendAll(h, touchSequence({ gesture, x: t.x, y: t.y, scale }))
+    return `[touch] pinch ×${scale} at ${Math.round(t.x)},${Math.round(t.y)}`
+  }
+  // tap / doubleTap：显式序列；doubleTap = 两轮 + 双击窗内间隔（KD-14 收正）
+  const rounds = gesture === "doubleTap" ? 2 : 1
+  for (let i = 0; i < rounds; i++) {
+    if (i > 0) await h.sleep(TOUCH_TAP_GAP_MS)
+    await sendAll(h, touchSequence({ gesture, x: t.x, y: t.y }))
+  }
+  return `[touch] ${gesture} ${t.label}`
+}
+
+/** insert（§2.2）：纯文本插入（不按键——长文本 / emoji 路径）；`ime` = 组合候选 → `insertText` 提交（KD-17）。 */
+async function actInsert(args, ctx, h) {
+  const text = String(args.text)
+  const ime = typeof args.ime === "string" && args.ime !== "" ? args.ime : null
+  await h.ensureSession(args)
+  let target = null
+  if (typeof args.ref === "string" && args.ref !== "") target = await h.focusRef(args.ref)
+  if (ime) {
+    await h.call("Input.imeSetComposition", { text: ime, selectionStart: ime.length, selectionEnd: ime.length })
+    await h.sleep(IME_COMMIT_BREATH_MS)
+  }
+  await h.call("Input.insertText", { text })
+  const chars = `← ${text.length} chars${ime ? " (ime)" : ""}`
+  return target ? `[insert] ${target.label} ${chars}` : `[insert] (focused) ${chars}`
+}
+
+/** 新七动作分发表（会话档并入总表——§5）。 */
+export const INPUT_ACTIONS = {
+  press: actPress,
+  hover: actHover,
+  wheel: actWheel,
+  mouse: actMouse,
+  drag: actDrag,
+  touch: actTouch,
+  insert: actInsert,
+}

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 { /* 已退出 */ } }
+}