@thincoder/core 0.10.4 → 0.10.6

package/browser/cdp.mjs

@@ -0,0 +1,161 @@
+/**
+ * browser/cdp.mjs — CDP 传输客户端（零第三方——N-BT1：Node ≥ 24 原生 WebSocket）。
+ *
+ * 形沿 `scripts/console-walkthrough.mjs:133-141` 的实证客户端（id 派发 ∥ 事件派发）——本文档把它
+ * 拆成类以承载多动作会话（connect / call / on / close），并加 HTTP 面 `/json/new` 取标签页。
+ * `WebSocketImpl` = 注入缝（缺省 `globalThis.WebSocket`；单元测试注假传输——缺省回落真实现，`??`）。
+ *
+ * 错误语义：CDP 回 `{ error: { message } }` ⇒ 拒以 `Error(message)`（BROWSER-TOOL.md §5）。
+ * 帽（§2.9 三层帽——层二 / 层三）：`call` 缺省帽 15s（任何未显式配帽的调用也不悬挂）；`connectCdp` open 帽
+ * 10s；`/json/new` fetch 帽 5s——动作内调用另随动作控制器（session 侧接线，预算先行）。
+ * 断连面：WS `onclose` / `onerror` ⇒ 拒在飞命令**并通知订阅者**（session 据此复位会话态——§2.10 源②）。
+ */
+
+/** `call` 缺省兜底帽（§2.9 层三——未显式配帽的调用同样有界）。 */
+export const DEFAULT_CALL_TIMEOUT_MS = 15_000
+/** `connectCdp` open 帽（§2.9 层二）。 */
+export const CONNECT_TIMEOUT_MS = 10_000
+/** `/json/new` fetch 帽（§2.9 层二）。 */
+export const NEWTAB_TIMEOUT_MS = 5_000
+
+/** 与浏览器标签页的一条 CDP 连接。 */
+export class CdpClient {
+  constructor(ws) {
+    this._ws = ws
+    this._nextId = 0
+    this._pending = new Map()
+    this._listeners = new Map()
+    this._disconnects = []
+    this.closed = false
+    ws.onmessage = (ev) => this._onMessage(ev)
+    ws.onclose = () => this._die(new Error("CDP connection closed"))
+    ws.onerror = () => this._die(new Error("CDP connection error"))
+  }
+
+  _onMessage(ev) {
+    let msg
+    try { msg = JSON.parse(ev.data) } catch { return } // 非 JSON 帧（调试器噪声）忽略
+    if (msg.id !== undefined && this._pending.has(msg.id)) {
+      const p = this._pending.get(msg.id)
+      this._pending.delete(msg.id)
+      if (msg.error) p.reject(new Error(msg.error.message ?? JSON.stringify(msg.error)))
+      else p.resolve(msg.result ?? {})
+      return
+    }
+    const handlers = msg.method ? this._listeners.get(msg.method) : null
+    if (!handlers) return
+    for (const handler of handlers) {
+      try { handler(msg.params ?? {}, msg.method) } catch { /* 订阅者自担——一条订阅抛错不打断派发 */ }
+    }
+  }
+
+  /** 连接断（WS close/error）单点：通知订阅者（先）⇒ 拒在飞命令（同一因由实例——§2.10）。 */
+  _die(error) {
+    if (this.closed) return
+    this.closed = true
+    for (const handler of this._disconnects) {
+      try { handler(error) } catch { /* 订阅者自担 */ }
+    }
+    this._abortAll(error)
+  }
+
+  _abortAll(error) {
+    for (const pending of this._pending.values()) pending.reject(error)
+    this._pending.clear()
+  }
+
+  /** 订阅断连（会话健康接线——§2.10 源②）；返回退订函数。 */
+  onDisconnect(handler) {
+    this._disconnects.push(handler)
+    return () => { this._disconnects = this._disconnects.filter((h) => h !== handler) }
+  }
+
+  /** 发一条 CDP 命令，解析其 result（失败拒以 `Error`）；缺省帽 15s（§2.9 层三）。 */
+  call(method, params = {}, { timeoutMs = DEFAULT_CALL_TIMEOUT_MS } = {}) {
+    if (this.closed) return Promise.reject(new Error("CDP client is closed"))
+    const id = ++this._nextId
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._pending.delete(id)
+        const error = new Error(`${method} did not respond within ${timeoutMs}ms`)
+        error.cdpTimeout = true
+        reject(error)
+      }, timeoutMs)
+      timer.unref?.() // 挂死型调用不吊住宿主进程（命令真返回时在 settle 里清钟）
+      const settle = (fn, value) => { clearTimeout(timer); this._pending.delete(id); fn(value) }
+      this._pending.set(id, { resolve: (v) => settle(resolve, v), reject: (e) => settle(reject, e) })
+      try { this._ws.send(JSON.stringify({ id, method, params })) }
+      catch (e) { settle(reject, e) }
+    })
+  }
+
+  /** 订阅 CDP 事件（无 id 帧）；返回退订函数。 */
+  on(method, handler) {
+    const list = this._listeners.get(method) ?? []
+    list.push(handler)
+    this._listeners.set(method, list)
+    return () => this._listeners.set(method, (this._listeners.get(method) ?? []).filter((h) => h !== handler))
+  }
+
+  close() {
+    if (this.closed) return
+    this.closed = true
+    this._abortAll(new Error("CDP client closed"))
+    try { this._ws.close() } catch { /* 已断开 */ }
+  }
+}
+
+/**
+ * 连标签页调试地址（open 帽 10s——§2.9 层二）。
+ * @param {string} wsUrl `webSocketDebuggerUrl`
+ * @param {{WebSocketImpl?: Function, openTimeoutMs?: number}} [opts] 注入缝 ∥ open 帽
+ */
+export async function connectCdp(wsUrl, { WebSocketImpl, openTimeoutMs = CONNECT_TIMEOUT_MS } = {}) {
+  const Impl = WebSocketImpl ?? globalThis.WebSocket
+  if (typeof Impl !== "function") {
+    throw new Error("no WebSocket implementation available — Node >= 24 required (CDP transport is stdlib-only)")
+  }
+  const ws = new Impl(wsUrl)
+  await new Promise((resolve, reject) => {
+    let settled = false
+    const finish = (fn, value) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      fn(value)
+    }
+    const timer = setTimeout(
+      () => finish(reject, new Error(`failed to connect to CDP at ${wsUrl} (no response within ${openTimeoutMs}ms)`)),
+      openTimeoutMs,
+    )
+    timer.unref?.()
+    ws.onopen = () => finish(resolve)
+    ws.onerror = () => finish(reject, new Error(`failed to connect to CDP at ${wsUrl}`))
+  })
+  return new CdpClient(ws)
+}
+
+/** 开一张标签页并取其调试地址（`PUT /json/new`，GET 兜底——walkthrough `:131-132` 同式；fetch 帽 5s）。 */
+export async function newTabWebSocketUrl(port, { host = "127.0.0.1", fetchImpl = globalThis.fetch, timeoutMs = NEWTAB_TIMEOUT_MS } = {}) {
+  const url = `http://${host}:${port}/json/new?about:blank`
+  let timer = null
+  const deadline = new Promise((_, reject) => {
+    timer = setTimeout(
+      () => reject(new Error(`browser did not answer /json/new within ${timeoutMs}ms (port ${port})`)),
+      timeoutMs,
+    )
+    timer.unref?.()
+  })
+  const fetchTab = async (init) => (await fetchImpl(url, init)).json()
+  try {
+    let tab
+    try { tab = await Promise.race([fetchTab({ method: "PUT" }), deadline]) }
+    catch { tab = await Promise.race([fetchTab(), deadline]) } // GET 兜底（同帽——到点即拒，不悬挂）
+    if (!tab?.webSocketDebuggerUrl) {
+      throw new Error(`browser did not return a debuggable tab from /json/new (port ${port})`)
+    }
+    return tab.webSocketDebuggerUrl
+  } finally {
+    if (timer) clearTimeout(timer)
+  }
+}

package/browser/clipboard.mjs

@@ -0,0 +1,142 @@
+/**
+ * browser/clipboard.mjs — 剪贴板动作（read / write / copy / paste）∥ Browser 域授权 ∥ 页侧表达式
+ * （BROWSER-TOOL.md §3.5 ∥ §2.2 clipboard ∥ N-BT9）。
+ *
+ * 路径（KD-13）：CDP 无剪贴板直控方法 ⇒ 页面 API（`navigator.clipboard`）+ Browser 域按 origin 惰性授予；
+ * `write` 页面拒 / 非安全上下文 ⇒ 回落 `document.execCommand('copy')` 隐藏 textarea 面（再败才报错）。
+ * copy / paste = 真加速键（平台分支：darwin ⇒ Meta+C/V；win32 / linux ⇒ Ctrl+C/V——受信按键直驱浏览器复制 / 粘贴）。
+ * 隐私（N-BT9）：read 回执上限 8000 字符 + 截断标记；write 回执不回显文本；剪贴板内容不落盘、不写日志（本档零 fs 面）。
+ */
+import { pressSequence } from "./input.mjs"
+import { truncateText } from "./snapshot.mjs"
+
+export const CLIPBOARD_MAX_CHARS = 8_000
+export const CLIPBOARD_OPS = ["read", "write", "copy", "paste"]
+/** `Browser.setPermission` 取的描述符名（实测在册可用——PermissionDescriptor ≠ PermissionType）。 */
+export const CLIPBOARD_PERMISSION_DESCRIPTORS = ["clipboard-read", "clipboard-write"]
+/** `Browser.grantPermissions` 取的权限枚举（PermissionType——回落面，两法同名不同名面，实测在案）。 */
+export const CLIPBOARD_PERMISSIONS = ["clipboardReadWrite", "clipboardSanitizedWrite"]
+
+const mark = (kind) => `/*thincoder-browser:${kind}*/`
+
+/** 授权缓存（§3.5：会话内按 origin 缓存——close / 换 origin 重授；键 = 连接身份）。 */
+let grantCache = { client: null, origins: new Set() }
+/** 无头焦点模拟缓存（§3.5：会话内一次性——仅剪贴板动作触发，不进其他动作路径）。 */
+let focusCache = { client: null, done: false }
+
+/** 无头焦点适配：`document.hasFocus()` 为假 ⇒ `Emulation.setFocusEmulationEnabled`（一次/会话）。 */
+async function ensureFocusEmulation(h) {
+  const client = h.connection()
+  if (client && focusCache.client === client && focusCache.done) return
+  let hasFocus = true
+  try { hasFocus = (await h.evalRaw("document.hasFocus()")) === true } catch { hasFocus = true } // 页不可读 ⇒ 不模拟
+  if (!hasFocus) await h.call("Emulation.setFocusEmulationEnabled", { enabled: true })
+  focusCache = { client, done: true }
+}
+
+/**
+ * 按当前页 origin 惰性授予（§3.5）：`setPermission` 两权（描述符名）→ 方法缺 / 拒 ⇒ `grantPermissions`
+ * 回落（PermissionType 枚举）→ 再败明示错。实测（本机 Edge）：`setPermission` 只认描述符名
+ * （`clipboard-read` / `clipboard-write`）；PermissionType 名在该方法上被拒（版本 / 名面漂移——回落层兜住）。
+ */
+async function ensureClipboardPermission(h, origin) {
+  const client = h.connection()
+  if (grantCache.client !== client) grantCache = { client, origins: new Set() }
+  if (grantCache.origins.has(origin)) return
+  try {
+    for (const name of CLIPBOARD_PERMISSION_DESCRIPTORS) {
+      await h.call("Browser.setPermission", { permission: { name }, setting: "granted", origin })
+    }
+  } catch (e) {
+    try {
+      await h.call("Browser.grantPermissions", { permissions: CLIPBOARD_PERMISSIONS, origin })
+    } catch (e2) {
+      throw h.pageError(`clipboard permission failed — setPermission: ${e?.message ?? e}; grantPermissions fallback: ${e2?.message ?? e2}`)
+    }
+  }
+  grantCache.origins.add(origin)
+}
+
+/** 当前页 origin（授权键）；无真实页 origin（about:blank 等）⇒ 明示拒（不静默降级）。 */
+async function pageOrigin(h) {
+  const info = await h.pageInfo()
+  let origin = null
+  try { origin = new URL(info.url).origin } catch { origin = null }
+  if (!origin || origin === "null") throw h.pageError(`clipboard requires an http/https page origin — current page is "${info.url}"`)
+  return origin
+}
+
+/** 页侧写表达式：`navigator.clipboard.writeText` → 失败回落 `document.execCommand('copy')` 隐藏 textarea。 */
+function clipboardWriteExpression(text) {
+  return `${mark("clipboard-write")}(async function () {
+  var text = ${JSON.stringify(text)}
+  try {
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      await navigator.clipboard.writeText(text)
+      return { ok: true, via: 'navigator.clipboard' }
+    }
+  } catch (e) { /* 页面拒 / 非安全上下文 ⇒ 走 execCommand 回落 */ }
+  try {
+    var ta = document.createElement('textarea')
+    ta.value = text
+    ta.setAttribute('readonly', '')
+    ta.style.position = 'fixed'
+    ta.style.opacity = '0'
+    document.body.appendChild(ta)
+    ta.select()
+    var ok = false
+    try { ok = document.execCommand('copy') } finally { document.body.removeChild(ta) }
+    return ok ? { ok: true, via: 'execCommand' } : { ok: false, message: 'document.execCommand("copy") returned false' }
+  } catch (e2) { return { ok: false, message: String((e2 && e2.message) || e2) } }
+})()`
+}
+
+/** 页侧读表达式：`navigator.clipboard.readText()`（安全上下文限定——非安全上下文给引导句）。 */
+function clipboardReadExpression() {
+  return `${mark("clipboard-read")}(async function () {
+  try {
+    if (!navigator.clipboard || !navigator.clipboard.readText) {
+      return { ok: false, message: 'navigator.clipboard.readText is unavailable — a secure context (https or localhost) is required' }
+    }
+    var text = await navigator.clipboard.readText()
+    return { ok: true, text: String(text == null ? '' : text) }
+  } catch (e) { return { ok: false, message: String((e && e.message) || e) } }
+})()`
+}
+
+/** 加速键序列（§3.5 平台分支）：darwin ⇒ Meta+C/V；win32 / linux ⇒ Ctrl+C/V。 */
+export function acceleratorSequence(op, platform = process.platform) {
+  const modifier = platform === "darwin" ? "Meta" : "Control"
+  const key = op === "copy" ? "c" : "v"
+  return pressSequence({ key, modifiers: [modifier] }).commands
+}
+
+/** clipboard（§2.2）：op ∈ read / write / copy / paste；write 必填 text；copy / paste 可携 ref 聚焦。 */
+async function actClipboard(args, ctx, h) {
+  const op = String(args.op ?? "")
+  if (!CLIPBOARD_OPS.includes(op)) throw new Error(`unknown clipboard op "${op}" — ops: ${CLIPBOARD_OPS.join(", ")}`)
+  await h.ensureSession(args)
+  await ensureFocusEmulation(h)
+  const origin = await pageOrigin(h)
+  await ensureClipboardPermission(h, origin)
+  if (op === "write") {
+    const text = String(args.text)
+    const res = await h.evalRaw(clipboardWriteExpression(text))
+    if (!res?.ok) throw h.pageError(`clipboard write failed: ${res?.message ?? "the page rejected the write"}`)
+    return `[clipboard] write ← ${text.length} chars` // 不回显文本（N-BT9）
+  }
+  if (op === "read") {
+    const res = await h.evalRaw(clipboardReadExpression())
+    if (!res?.ok) throw h.pageError(`clipboard read failed: ${res?.message ?? "the page rejected the read"}`)
+    const text = String(res.text ?? "")
+    const body = text ? `\n${truncateText(text, CLIPBOARD_MAX_CHARS, `clipboard reads are capped at ${CLIPBOARD_MAX_CHARS} chars`)}` : ""
+    return `[clipboard] read (${text.length} chars)${body}`
+  }
+  let target = null
+  if (typeof args.ref === "string" && args.ref !== "") target = await h.focusRef(args.ref)
+  for (const cmd of acceleratorSequence(op)) await h.call(cmd.method, cmd.params)
+  return `[clipboard] ${op}${target ? ` → ${target.label}` : ""}`
+}
+
+/** 剪贴板分发表（会话档并入总表——§5）。 */
+export const CLIPBOARD_ACTIONS = { clipboard: actClipboard }

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,
+}