@huseynsnmz/pi-board 0.15.3 → 0.17.0

package/docs/superpowers/specs/2026-10-14-issue-185-attach-wheel-alt-screen-design.md

@@ -1,126 +0,0 @@
-# Issue #185 — attach wheel cannot scroll a fullscreen child session (alternate buffer)
-
-- Issue: https://github.com/zhuxixi/pi-agent-board/issues/185
-- Kind: bug — root-cause report + fix design (delta on top of the merged #183)
-- Repo: `zhuxixi/pi-agent-board` · baseline: `main` @ `f81949d5` (#183) · worktree `issue-185-attach-wheel-alt-screen`
-- Drafted: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-14T00:06:01Z
-- Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-14T00:23:30Z — after round-1 review (mode: degraded same-model, user-confirmed; findings R1-D1..R1-D5 in `research/spec-review-round-1.md`)
-- Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-14T00:52:00Z — after local code-review (workflow `code-review`, run `code-review-mv7dz229-mrt1ay`): the disconnected alternate-buffer wheel now falls through instead of consuming a drop-bound forward (consume-only-on-effect invariant restored); §3.1/§8 updated
-
-## 1. Problem
-
-`#183` fixed the fullscreen wheel by consuming it in `handleMouse` and scrolling the attach's own xterm
-viewport, falling through when that viewport cannot move. For a child that holds the alternate screen —
-i.e. **every session this board launches by default** — the attach-local scrollback collapses to about
-two lines, so the wheel travels those two lines and then falls through to a transcript scroll hidden
-behind the overlay. To the user the wheel still looks dead while `PageUp`/`PageDown` keep working.
-
-Out of scope here: the normal-buffer case, which #183 already fixed and pins with tests.
-
-## 2. Root cause
-
-**2.1 Alternate buffers have no scrollback.** Measured with the extension's own `@xterm/headless` and the live 36×120 geometry (`scrollback: 2000`, `bodyHeight = rows - 2 = 34`):
-
-| buffer | `baseY` | `length` | `min(length, baseY + rows) - bodyHeight` |
-| --- | --- | --- | --- |
-| normal | 65 | 101 | 67 |
-| alternate (`\x1b[?1049h` + 200 lines) | 0 | 36 | **2** |
-
-`bottomViewportTop()` (`src/ui/pty-attach.ts:1340-1344`) and the projection (`:854`, `:1121`, `:1142`, `:1237`) all read `this.term.buffer.active`, so an alternate-screen child is exactly the state where the attach's local scrolling is inert.
-
-**2.2 The hosted child is in that state.** Board host-configs carry no `--tui-mode` and `env: {}`, so the child inherits `tuiMode: "fullscreen"`. A probe pi spawned under the same env/settings in a 36×120 PTY emitted `\x1b[?1049h`, `\x1b[?1000h`, `\x1b[?1006h`, `\x1b[?2004h` at startup.
-
-**2.3 #183's fall-through ends in an invisible scroll.** `src/ui/pty-attach.ts:386-395`: `wheelScrollLinesUp(event)` → `if (this.mouseScrollEnabled() && this.tryScrollBy(wheelLinesUp)) return {handled:true, render:false}` → `return undefined`. Returning `undefined` hands the event to pi's `routeWheel`, which scrolls the transcript underneath the full-screen overlay — no visible effect. The behaviour is pinned as intentional (`test/pty-attach-wheel.test.mjs:29`, `test-support/pty-attach-wheel-scenario.ts:16,92`), so this issue must not regress it for the normal-buffer case.
-
-**2.4 The keyboard path already forwards, the wheel does not.** `handleInput`'s `PageUp`/`PageDown` branches (`src/ui/pty-attach.ts:300`, `:307`) call `tryScrollBy` and, when it returns false, `this.send({ type: "input", data })` — the child scrolls its own viewport and its redraw flows back through the attach. The raw-SGR wheel path does the same (`:967`). The fullscreen wheel branch is the only scroll path without that fallback.
-
-## 3. Fix design
-
-### 3.1 Behaviour contract — `PtyAttachComponent.handleMouse`, wheel branch (`src/ui/pty-attach.ts:386-395`)
-
-| Condition | Behaviour |
-| --- | --- |
-| `wheelLinesUp === 0` (not a wheel, or unusable delta) | unchanged: `undefined` (falls through) |
-| `mouseScrollEnabled() === false` (`AGENT_BOARD_ATTACH_MOUSE=0` / `AGENT_BOARD_ENABLE_MOUSE_SCROLL=0`) | unchanged: `undefined`, no forwarding |
-| active buffer is `alternate` | **new**: skip the local viewport entirely; forward one synthesized SGR wheel report to the child; `return { handled: true, render: false }` |
-| active buffer is `normal`, `tryScrollBy(linesUp)` moved | unchanged #183: `{ handled: true, render: false }` |
-| active buffer is `normal`, viewport cannot move | unchanged #183: `undefined` |
-
-The alternate case deliberately skips `tryScrollBy`: letting the local viewport travel its two lines would pin the attach's projection while the child repaints its own scrolled frame, producing a two-line-jump artefact rather than a scroll.
-
-Two edge notes on the alternate branch:
-
-- While the attach is disconnected, the branch falls through (`undefined`) instead of forwarding — `send()` would silently drop the report (`src/ui/pty-attach.ts`), and the pre-#185 branch likewise consumed the wheel only when it had an effect. The event goes back to pi, whose own handling is equally inert behind the overlay; acceptable, since the attach shows a reconnect surface.
-- `README.md:201`'s sentence ("While attached, `PageUp`, `PageDown`, `Home`, `End`, and the mouse wheel scroll local scrollback") must be updated in the same PR: in the alternate case the wheel scrolls the child's own viewport, same as `PageUp`/`PageDown`.
-
-### 3.2 Wire format and coordinates
-
-- Report shape: `\x1b[<64;{col};{row}M` (up) / `\x1b[<65;{col};{row}M` (down) — the plain SGR wheel report a terminal sends; the child's own TuiAltScreen (or any mouse-aware alt-screen program) parses it exactly as it parses the real terminal's.
-- One report per received event, not one per line, so the child applies its own acceleration (`WheelScrollAccelerator`); `#183`'s `wheelScrollLinesUp()` decides direction and validity, and `AGENT_BOARD_WHEEL_LINES` stays a regular-mode-only knob as #183 documented.
-- Coordinates are the **child screen** frame, not the attach buffer's absolute row: `handleMouse` events are zero-based local (pi-tui `TuiMouseEvent`), the attach body starts at local row 1 (header row 0, footer last row), and the child's screen is the body 1:1. So `col = clampInt(event.x + 1, 1, this.cols)` and `row = clampInt(event.y, 1, Math.max(1, this.bodyHeight()))` (SGR is one-based). This mirrors what the raw path assumes when it maps a 1-based SGR column to `col - 1` (`:1090`).
-
-### 3.3 Testability split (implementation constraint)
-
-| Unit | Kind | Contract |
-| --- | --- | --- |
-| `resolveAttachWheelRoute({ bufferType, wheelLinesUp, mouseEnabled })` (**new**, `src/core/pty-scroll.mjs`) | pure | `"none"` when the switch is off or `wheelLinesUp === 0`; `"child"` when `bufferType === "alternate"`; else `"local"`. The `"local"`→`"none"` downgrade when `tryScrollBy` cannot move stays in the shell (it needs the live viewport). |
-| `encodeWheelReport(direction, { col, row })` (**new**, same module) | pure | `"up" \| "down"` → the SGR string above, coordinates clamped to ≥ 1. |
-| `handleMouse` wheel branch | shell | `resolveAttachWheelRoute` → `"child"`: `send({type:"input", data: encodeWheelReport(...)})`; `"local"`: `tryScrollBy(...) ? handled : undefined`; `"none"`: `undefined`. |
-
-Both helpers are pure and belong next to `wheelScrollLinesUp()` (`src/core/pty-scroll.mjs:175`), which stays as the delta gate.
-
-Seams for the component-level tests: `test-support/pty-attach-mouse-scenario.ts` already provides a real runner plus a `Socket.prototype.write` interception that observes component→runner `{type:"input"}` messages, plus `as any` private access — the same harness that asserts the middle-click paste payload reaches the runner. The alternate-screen branch needs one new additive fixture mode in `test-support/fake-pty-pi.mjs` (`FAKE_PTY_STREAM_MODE=alt`, writing `\x1b[?1049h` before its lines — same additive shape as the existing `steady`/`firehose`/`malformed` modes) — a test-support change, no runtime impact. The new scenario's fake TUI declares `mode: "fullscreen"` (same as `test-support/pty-attach-wheel-scenario.ts`), so the component is exercised in production's dispatch shape.
-
-## 4. Rejected alternatives
-
-| Alternative | Evidence against |
-| --- | --- |
-| Keep the local scroll first and forward only after the two lines | The attach projection would pin at `viewportTop = 0` while the child scrolls its own frame — a two-line artefact plus divergent frames; also invisible in practice. |
-| Forward at the normal-buffer boundary too (full parity with the raw path) | Changes a contract #183 pinned (`test/pty-attach-wheel.test.mjs:29`) for a case where local scrolling does work; keep it as a separate decision, not part of this fix. |
-| Mirror the child's transcript into attach-local history for alternate-screen children | Large redesign of the projection model; unnecessary once forwarding matches the keyboard path. |
-| Ask the user to run sessions with `--tui-mode regular` | Workaround; leaves the default topology broken. |
-| Re-assert the outer mouse mode / bypass `handleMouse` | #169/#173 already settled that `TuiAltScreen` owns the mode in fullscreen. |
-
-## 5. Acceptance matrix
-
-| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
-| --- | --- | --- | --- | --- |
-| A1 | 路由决策与报文编码（纯函数） | 自动化验证（unit） | `node --test test/pty-scroll.test.mjs` | `resolveAttachWheelRoute`：`mouseEnabled:false` → `"none"`；`wheelLinesUp:0` → `"none"`；`alternate` → `"child"`；`normal` → `"local"`。`encodeWheelReport`：up → `"\x1b[<64;5;3M"`、down → `"\x1b[<65;5;3M"`，`col/row < 1` 夹到 1 |
-| A2 | alternate 子进程：转发报文而非本地滚动 | 自动化验证（integration） | 新场景 `test-support/pty-attach-alt-wheel-scenario.ts` + `test/pty-attach-alt-wheel.test.mjs`（真实 runner + `Socket.prototype.write` 拦截 + 新 `FAKE_PTY_STREAM_MODE=alt`） | 子进程收到 `{"type":"input","data":"\x1b[<64;…M"}`（下滑为 65，坐标为 1-based 且落在 `[1, cols] × [1, bodyHeight]`）；`handleMouse` 返回 `{handled:true, render:false}`；`viewportTop` 保持 `null` |
-| A3 | normal 子进程：不回归 #183 | 自动化验证（integration） | `npm test`（`test/pty-attach-wheel.test.mjs` 原样） | 既有多条断言全绿，含 `atBottomFallsThrough === true` |
-| A4 | 关闭开关与不可用 delta 不转发 | 自动化验证（integration） | A2 场景内设 `AGENT_BOARD_ATTACH_MOUSE=0` / `AGENT_BOARD_ENABLE_MOUSE_SCROLL=0` / 无 delta 的 wheel | 三者都返回 `undefined` 且 socket 上无新的 `{type:"input"}` |
-| A5 | 既有鼠标行为不回归 | 自动化验证（integration） | `npm test`（`pty-attach-mouse`、`pty-attach-mouse-mode`、`pty-attach-selection-mirror`） | 全绿：中键粘贴、fullscreen 零 mouse-mode 写入、selection mirror |
-| A6 | 类型、构建与全量门禁 | 自动化验证（static + suite） | `npm run verify` | typecheck / perf gate / `npm test` / coverage 阈值（lines 85 / funcs 80 / branches 70）/ `pack:dry` 全过 |
-| A7 | 文档同步（README 的滚轮声明） | 自动化验证（static） | `rg -n "mouse wheel" README.md` | `README.md:201` 的句子不再只承诺 "scroll local scrollback"——必须说明滚轮与 PageUp/PageDown 一致：本地有 scrollback 滚本地，否则转发给子进程滚它自己的视口 |
-| U1 | 真实 fullscreen attach 里滚轮与键盘一致 | 用户实测 | 合并并入 git checkout 后重启 pi：attach 一个长输出会话，先 `PageUp`/`PageDown` 再滚轮上下 | 滚轮能连续回看历史并回到跟随底部，与 `PageUp`/`PageDown` 一致；无两行跳变或闪烁；时机：PR 合并 → `git pull` → 重启 pi 后任意时刻 |
-| U2 | 中键粘贴与拖拽选择无回归 | 用户实测 | 同一会话中键粘贴 + 左键拖选 | 与改动前一致（X11 PRIMARY 粘贴内容正确、选中高亮） |
-| U3 | regular 模式冒烟（本次改动未触碰的路径） | 用户实测 | 全局 `tuiMode: regular` 重启外层 pi 后 attach 一个长会话并滚轮 | 滚轮走原始路径（本地 scrollback + 边界转发）不变；时机同 U1 |
-
-## 6. Verification path (deployment truth)
-
-- The outer pi loads the extension from `~/.pi/agent/settings.json` → `git:github.com/zhuxixi/pi-agent-board` → `~/.pi/agent/git/github.com/zhuxixi/pi-agent-board`. U-items need that checkout at the merge commit **and** a pi restart (the module is loaded at startup); no build step (`main: ./index.ts`).
-- Implementation baseline: the dev checkout `/home/elling/git-repo/github/pi-agent-board` is at `acc40fd`, i.e. **behind #183**; the worktree must be created from a refreshed `main` (fetch first) so the change builds on `f81949d5` rather than reintroducing the previous wheel branch.
-- A2's `FAKE_PTY_STREAM_MODE=alt` is new fixture surface (`test-support/fake-pty-pi.mjs`, alongside `steady`/`firehose`/`malformed`); keep it additive so existing fixture consumers are unaffected.
-
-## 7. Non-goals
-
-- Changing the normal-buffer boundary behaviour #183 pinned (fall-through) or `AGENT_BOARD_WHEEL_LINES` semantics.
-- Mirroring child history into attach-local scrollback; horizontal wheel; touch/kinetic input.
-- Any pi-tui change (the child parses standard SGR reports; nothing new is required upstream).
-
-## 8. Guarantee boundaries
-
-- The forwarded report is synthesized, not a byte replay: coordinates are best-effort (the child uses them for scroll-view hit testing and falls back to its primary scroll view) and modifier bits are not carried; the child applies its own acceleration.
-- In the alternate case there is deliberately no local fallback: if the child ignores mouse reports, the wheel does nothing in that session (the same class of limitation `PageUp` has today if the child ignores paging keys).
-- The attach cannot observe whether the child actually scrolled; parity with `PageUp` is the contract, not a guarantee about the child's own limits.
-- In the disconnected state the alternate branch falls through rather than consuming the wheel (see §3.1): a forward that `send()` would silently drop is not an effect, so the event is handed back — restoring the pre-#185 consume-only-on-effect invariant.
-
-## 9. Risks
-
-- Sending an escape sequence into a child that does not parse mouse reports (non-pi alt-screen programs with mouse mode off) — accepted, scoped to the alternate buffer, and identical in kind to what the raw path already forwards for wheel/keys in regular mode.
-- A quickly spinning wheel now produces one forwarded report per event, which the child's accelerator may amplify up to ~6 lines (×5 with Alt) per event — same as a real terminal, and #183's README note already explains the fullscreen line count is the TUI's decision.
-- Momentum bursts arriving while the child repaints can interleave; the attach's projection re-renders from the buffer, so no state is lost.
-
-## 10. Next step after approval
-
-Step 5 of `github-issue-driven`: create worktree `issue-185-attach-wheel-alt-screen` from refreshed `main`, land this spec as the first commit at `docs/superpowers/specs/2026-10-14-issue-185-attach-wheel-alt-screen-design.md`, then plan (`writing-plans`) → implement (`subagent-driven-development`) → local CR → PR with Zima single-bot CR.

package/docs/superpowers/specs/2026-10-14-issue-187-motionless-drag-design.md

@@ -1,269 +0,0 @@
-Drafted: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-14T12:29:14Z
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-14T12:48:00Z (round-1 review: R1-G1 accepted — classify the gesture in SCREEN coordinates; R1-D1 accepted — double-click path gets its own case; R1-D2 accepted — A2 gains the content-wait precondition and contains-semantics wording)
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-14T13:05:00Z (round-2 review: R2-G1 accepted — U3 stops demanding double-click-under-drift and the boundary is documented; R2-D1 accepted — A4/A5 gain the press-created-selection precondition; R2-D2 accepted — A6 asserts an observable signal)
-Revised: deepseek/deepseek-flash (selected) · deepseek/deepseek-flash (physical) @ 2026-10-14T13:22:00Z (round-3 review: converged with R3-D1 as the only detail — the raw/unclamped screen-cell semantics now have an explicit A1 case and an implementation note; the round-3 hash is the converged version plus this detail fix)
-
-# Spec: #187 — attach(legacy): a motion-less drag must be classified by geometry, not by the move flag
-
-Status: DRAFT (awaiting spec-cross-review, then user approval — github-issue-driven step 4 gate)
-Issue: https://github.com/zhuxixi/pi-agent-board/issues/187
-Repo state baseline: main @ `f81949d`
-Scope: **#187 only.** #188 (X10 release parsed as press) and #189 (mixed input chunks) stay open and
-untouched; the fix must not assume they are fixed.
-
-## Problem (root cause, verified in code + reproduced at runtime)
-
-`src/ui/pty-attach.ts` → `handleLocalMouseEvent` (legacy/regular-mode mouse path; the fullscreen path
-is `handleMouse` and never reaches this handler):
-
-```ts
-// press  (:1035)  — 1-cell selection, and the drag flag is cleared
-this.selection = { anchor: point, focus: point };
-this.selectionDragging = false;
-// move   (:1045)  — the ONLY place the drag flag is ever set
-this.selectionDragging = true;
-// release(:1054)  — drag inferred from the flag
-const shouldCopy = this.selectionDragging;
-```
-
-The flag answers "did a motion event arrive since the press", not "did the gesture move". Warp
-delivers fast drags as **press + release with zero motion events** (byte capture in the issue), so
-`shouldCopy` is `false` and the release takes the plain-click path (`:1079`
-`schedulePendingClick(point)`): `copySelectionToClipboard()` never runs, and the 1-cell selection is
-wiped by the pending-click timer 260 ms later. That timer is the reported symptom — *"drag-select
-doesn't select at all; the moment I release, the selection is gone"*.
-
-Runtime reproduction (throwaway harness modeled on `test-support/pty-attach-mouse-scenario.ts`: real
-`PtyAttachComponent` + real runner socket + fake PTY, fake TUI capturing `terminal.write`):
-
-| Gesture (row 2 = first body row) | OSC 52 payload | `selection` after 400 ms |
-|---|---|---|
-| press (col 1) → release (col 16), **zero motion** | none | `null` (pending-click timer) |
-| press (col 1) → move (col 8) → release (col 16) | `["fake pi ready"]` | retained |
-| press (col 1) → release (col 1) (same point) | none | `null` (expected click behavior) |
-
-### Why the decision must be taken in SCREEN coordinates, not buffer coordinates
-
-`mousePointForEvent` (`:1088-1089`) maps a screen cell to a buffer line through the *current*
-viewport base: `start = this.viewportTop ?? this.bottomViewportTop(height)`. While following the
-bottom (`viewportTop === null`, the normal case) `bottomViewportTop` (`:1340-1343`) is
-`max(0, min(buf.length, baseY + rows) - height)`, which **grows as the session streams new lines**
-and `clampViewportTop` (`:1346-1348`) deliberately does not pin it.
-
-So `anchor` and `focus` are buffer coordinates captured at two different times against two different
-bases: on a streaming session (the primary attach use case — watching a running agent) a stationary
-click maps to `focus.line > anchor.line` purely because output arrived in between. A buffer-space
-comparison would therefore classify every stationary click on a live session as a drag: the single
-click would stop opening links, the double-click would stop selecting words, and each click would
-write the clipboard. The gesture must be classified from the pointer's **screen cells**
-(`mouse.row` / `mouse.col` of the parsed report, 1-based), which is exactly the data the terminal
-sent and is immune to viewport drift.
-
-## Goal / non-goals
-
-**Goal**: in the legacy path, a release is treated as a drag when the gesture actually moved —
-either a motion event was seen (`selectionDragging`) **or** the release's screen cell differs from
-the press's screen cell. The motion-less gesture then lands on the same branch as the canonical
-drag: copy + highlight retained until the next click. Stationary clicks keep the click path
-regardless of how much output arrived between press and release.
-
-**Non-goals**:
-
-- #172 (clear the highlight after copy) — the drag-copy branch deliberately keeps the highlight;
-  #187 must reproduce that contract, not change it.
-- #186 UX umbrella items (selection background color, no 1-cell press selection, clipboard
-  fallback/`pbcopy`, Shift+drag docs).
-- #188 (X10 `Cb=3` release parsed as press) and #189 (all-or-nothing chunk parsing): separate
-  issues, separate acceptance. The fix works with both still broken.
-- Fullscreen mode / `handleMouse` / pi-tui behavior (upstream concern).
-- Press/move branches, selection autoscroll, middle-click paste, PRIMARY mirroring, wheel handling.
-- No change to how the selection range itself is stored (still buffer coordinates) — only the
-  drag/click classification moves to screen space.
-- No new env knob, no new dependency, no new I/O surface.
-
-## Design
-
-### 1. Pure helpers (`src/core/pty-scroll.mjs`)
-
-```js
-/** Issue #187: two mouse points are "the same" within the terminals' 1-cell coordinate slack.
- * Moved here from pty-attach.ts (it was already pure) so double-click detection and the
- * screen-space gesture comparison share one definition each. Buffer-space comparison. Pure. */
-export function sameMousePoint(a, b) {
-	return a.line === b.line && Math.abs(a.col - b.col) <= 1;
-}
-
-/** Issue #187: two SCREEN cells are "the same" within the same 1-cell slack — the terminal
- * reports cells, and a genuine click must survive a ±1 sub-cell report. Screen-space
- * comparison; see the spec for why the gesture is classified here and not in buffer space. Pure. */
-export function sameScreenCell(a, b) {
-	return a.row === b.row && Math.abs(a.col - b.col) <= 1;
-}
-
-/** Issue #187: whether a mouse release ends a real selection drag. Terminals such as Warp
- * deliver a fast drag as press + release with zero motion events, so the move flag alone is not
- * sufficient — the gesture geometry decides. Points are SCREEN cells, so a viewport that drifts
- * between press and release (streaming session, follow-bottom) cannot turn a click into a drag.
- * Missing geometry (no screen anchor recorded) degrades to the pre-fix answer: not a drag. Pure. */
-export function selectionReleaseIsDrag({ dragging, pressScreen, releaseScreen }) {
-	if (dragging) return true;
-	if (!pressScreen || !releaseScreen) return false;
-	return !sameScreenCell(pressScreen, releaseScreen);
-}
-```
-
-Decision table for `selectionReleaseIsDrag`:
-
-| dragging | pressScreen / releaseScreen (screen cells) | result |
-|---|---|---|
-| `true` | any (incl. missing) | `true` |
-| `false` | same row, `\|Δcol\| <= 1` | `false` (click) |
-| `false` | same row, `\|Δcol\| >= 2` | `true` (motion-less drag) |
-| `false` | different row | `true` (motion-less drag) |
-| `false` | either missing | `false` (degrade to pre-fix behavior) |
-
-Buffer-space points (`anchor`/`focus`) are deliberately **not** inputs: they are only meaningful
-against the viewport base that produced them.
-
-### 2. Component wiring (`src/ui/pty-attach.ts`)
-
-- The selection object carries the gesture anchor in screen space, so its lifetime is bound to the
-  selection and no extra reset site is introduced:
-
-```ts
-// press (:1035): record the raw screen cell alongside the buffer-space anchor
-this.selection = { anchor: point, focus: point, screenAnchor: { row: mouse.row, col: mouse.col } };
-```
-
-  `screenAnchor` is optional: `selectWordAtPoint` (double-click) creates a selection without one,
-  and a missing anchor degrades to "not a drag".
-
-  **Both sides of the comparison must be the raw reported cells** (`mouse.row` / `mouse.col` as
-  parsed from the terminal report) — never the clamped buffer point `mousePointForEvent` returns, and
-  never `this.selection.focus`. A release outside the body is still classified by where the pointer
-  actually went; only the *selection focus* is clamped (unchanged). A1 carries an out-of-body case
-  for exactly this reason.
-
-- Release branch — the decision, and nothing else, changes:
-
-```ts
-if (mouse.action === "release") {
-	this.clearSelectionAutoScroll();
-	const point = this.mousePointForEvent(mouse.row, mouse.col, true);   // unchanged
-	if (point) this.selection.focus = point;                             // unchanged
-	const shouldCopy = selectionReleaseIsDrag({                          // was: this.selectionDragging
-		dragging: this.selectionDragging,
-		pressScreen: this.selection.screenAnchor,
-		releaseScreen: { row: mouse.row, col: mouse.col },
-	});
-	this.selectionDragging = false;                                      // unchanged
-	// ...copy branch / click branch unchanged
-}
-```
-
-Plus: `sameMousePoint` is deleted from `pty-attach.ts` (`:1658`) and imported from
-`../core/pty-scroll.mjs` together with `selectionReleaseIsDrag` (one import line, `:20`).
-`isDoubleClickCandidate` (`:1096`) keeps calling `sameMousePoint` on buffer points, unchanged.
-
-### Resulting behavior matrix
-
-| Gesture | Before | After |
-|---|---|---|
-| press + release, same screen cell | click path: pending link-open, clear after 260 ms | unchanged |
-| press + release, `\|Δcol\| <= 1` on the same screen row | click path | unchanged (documented boundary) |
-| press + release, same screen cell, **session streamed output in between** | click path | **unchanged** (this is the R1-G1 regression the screen-space decision prevents) |
-| press + move + release | copy + highlight retained | unchanged |
-| press + release, `\|Δcol\| >= 2` or different screen row (motion-less drag) | **click path: no copy, selection wiped after 260 ms** | **copy + highlight retained (same branch as the canonical drag)** |
-| drag released outside the body | clamped selection focus, drag if the flag was set | clamped selection focus, drag by screen geometry too |
-| middle press / non-primary press / wheel | unchanged | unchanged |
-| fullscreen TUI | different handler (`handleMouse`) | unchanged |
-
-Side effect of the fix worth stating: a motion-less drag now cancels a pending click from an
-earlier press, exactly as the canonical drag path already does (`clearPendingClick()` in the copy
-branch). That is intended — a drag is not a click.
-
-## Acceptance matrix
-
-| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
-|----|--------|----------|----------|----------|
-| A1 | 纯决策 `selectionReleaseIsDrag` 决策表（屏幕坐标）+ `sameScreenCell` / `sameMousePoint` 边界 | 自动化验证（unit） | `node --test test/pty-scroll.test.mjs`（新增用例：dragging=true；同屏幕单元 → false；`\|Δcol\| = 1` → false；`\|Δcol\| = 2` → true；不同屏幕行 → true；pressScreen/releaseScreen 缺省 → false；**body 外的原始屏幕单元**（`pressScreen={row:2,col:1}`、`releaseScreen={row:30,col:16}`）→ true（按**原始**屏幕值判定，不复用 `mousePointForEvent` 的 clamp 结果）；sameMousePoint 的行相等与 1 格容差；sameScreenCell 的行相等与 1 格容差） | 新增用例全绿，既有用例不回归 |
-| A2 | 组件接线：零 motion 的 press→release 走复制分支（本 issue 的确切复现） | 自动化验证（integration，组件级场景：真 runner socket + 默认模式 fake PTY + fake TUI 捕获 `terminal.write`） | 新增 `test-support/pty-attach-legacy-drag-scenario.ts` + `test/pty-attach-legacy-drag.test.mjs`；case 1：先照 `test-support/pty-attach-mouse-scenario.ts` 的 `sawContent` 轮询等到 `fake pi ready` 渲染完成（**前置条件，防空缓冲竞态**），再注入 `\x1b[<0;1;2M` + `\x1b[<0;16;2m`（零 move） | ① `terminal.write` 收到的序列中包含 `\x1b]52;c;<base64("fake pi ready")>\x07`（**包含语义**：同一通道还有鼠标模式控制序列，不得用等值断言）；② 400 ms 后组件 selection 非 null（未被待点击定时器清除）；③ 无 `{type:"input"}` 转发到 socket |
-| A3 | 等价性：零 motion 拖拽与常规拖拽复制同一份文本 | 自动化验证（integration，同场景） | 同场景 case 2：`press(col1,row2)` + `move(col8,row2)` + `release(col16,row2)`；与 case 1 的 OSC 52 payload 比对 | 两个 case 提取出的 base64 payload 逐字节相同 |
-| A4 | 负向：同屏幕单元的 press+release 仍走点击路径（不复制、260 ms 后清选中） | 自动化验证（integration，同场景） | 同场景 case 3：`press(col1,row2)` + `release(col1,row2)`，等 400 ms | ① press 注入后组件 selection **非 null**（证明 press 路径确实建立了选区，否则本用例空转过绿、无判别力）；② 无 OSC 52 写出；③ 400 ms 后组件 selection 为 null |
-| A5 | 漂移负向控制（R1-G1）：流式输出导致的视口漂移不得把定身点击变成拖拽 | 自动化验证（integration，组件级场景：`FAKE_PTY_STREAM_MODE=steady` 的 fake PTY，缓冲区在 press→release 之间确实增长） | 新增 `test-support/pty-attach-legacy-drag-drift-scenario.ts` + `test/pty-attach-legacy-drag-drift.test.mjs`：等到内容渲染后，在同一屏幕单元 `press(col1,row2)`，等 ≥150 ms（期间 steady 流持续写入），再 `release(col1,row2)` | ① 断言期间缓冲区行数确实增长（否则该用例无判别力，视为失败）；② press 注入后组件 selection 非 null（同 A4 判据①）；③ 无 OSC 52 写出；④ 400 ms 后组件 selection 为 null（点击路径未被改判） |
-| A6 | 点击路径未被改判：双击选词仍复制（该路径修复前无任何既有测试覆盖） | 自动化验证（integration，A2 场景） | 同场景 case 4：同屏幕单元两次快速 `press`+`release`（间隔 < 260 ms，第二次 release 触发 `isDoubleClickCandidate`）。默认模式 PTY 在此期间无新输出，故缓冲坐标不漂移——与 U3 的真实流式环境形成对照 | ① `terminal.write` 中包含以该单元格所在词为内容的 OSC 52 payload（fixture 下预期 `fake`）；② 400 ms 后组件 selection 仍为该词的选区（未被 pending-click 定时器清空） |
-| A7 | 类型 / 构建 / 打包 | 自动化验证（static + build） | `npm run typecheck`；`npm run verify` | 全部通过（含 perf gate、coverage 阈值 lines 85 / funcs 80 / branches 70、`pack:dry`） |
-| A8 | 既有行为不回归（#167 鼠标分发、#171 中键粘贴、#174 选中镜像、滚轮） | 自动化验证（unit + integration，既有套件） | `npm run test:coverage`（含 `test/pty-scroll.test.mjs`、`test/pty-attach-mouse.test.mjs`、`test/pty-attach-selection-mirror.test.mjs`、`test/pty-attach-wheel.test.mjs`） | 既有测试全绿，覆盖率不低于阈值。注：双击/待点击路径**此前无既有覆盖**（`grep -rn 'isDoubleClickCandidate\|selectWordAtPoint\|schedulePendingClick' test/ test-support/` 空），其不回归由 A6 承担 |
-| U1 | 真机（终端原生，回归）：常规模式 attach 内拖选照旧复制 | 用户实测 | ① 把本机加载的扩展更新到合并后的 main：`git -C ~/.pi/agent/git/github.com/zhuxixi/pi-agent-board pull`（该 checkout 当前 HEAD=f81949d、有 `package-lock.json` 本地改动，先确认或 stash；扩展经 `~/.pi/agent/settings.json` 的 `git:github.com/zhuxixi/pi-agent-board` 注册，入口 `./index.ts` 免构建）；② 重启 `pi --tui-mode regular`（legacy 路径只在常规模式生效）→ `/agent-board` → attach 到任一 session；③ 左键拖选一段文字后松开；④ 中键粘贴 | ④ 中键粘贴内容与 ③ 选中的文字一致；高亮状态与 #172 现状一致（保留到下一次点击） |
-| U2 | 真机（精确字节流）：注入 Warp 的 press+release 字节，复现本 issue 的确切输入 | 用户实测（tmux 3.4 已在本机；不可用时标 pending） | ① tmux 内跑 `pi --tui-mode regular` → `/agent-board` → attach；② 注入原始字节：`tmux send-keys -H 1b 5b 3c 30 3b 31 3b 32 4d`（press col1,row2）然后 `tmux send-keys -H 1b 5b 3c 30 3b 31 36 3b 32 6d`（release col16,row2）；③ 观察 attach 视图高亮与该行文本的剪贴板/PRIMARY 内容 | 注入后该行文本进入剪贴板（OSC 52 或 xclip PRIMARY），高亮保留到下一次点击；若常规模式下的真实 TUI 不把该字节流交给 attach 组件（与组件级 A2 环境不同），如实记录观察结果并标 pending，不改 A2 结论 |
-| U3 | 真机（流式会话，R1-G1 回归）：输出持续滚动时单击**不得**被改判为拖拽 | 用户实测 | ① 承接 U1 的环境；② 让被 attach 的 session 持续输出（例如 `while :; do date; sleep 0.2; done`）；③ 输出滚动期间单击一段**无链接**文本数次；④ 停掉持续输出、让 session 空闲后，双击某词作对照 | ③ 单击期间剪贴板内容不变（无 OSC 52 写入迹象）、不误开链接——这是本次修复的核心回归项；④ 输出停止后的双击仍能选中该词并复制。**输出正好滚动时双击失配属既有行为（见保证边界），不计入本项判定** |
-
-## Testability split design (hard constraint for implementation)
-
-- **Pure core** (`src/core/pty-scroll.mjs`): `sameMousePoint(a, b)` (buffer space, shared with
-  double-click detection), `sameScreenCell(a, b)` (screen cells) and
-  `selectionReleaseIsDrag({dragging, pressScreen, releaseScreen})` — plain functions, no env reads,
-  no I/O, no imports from the component. Unit decision tables (A1) call them directly.
-- **I/O shell** (`PtyAttachComponent.handleLocalMouseEvent`): the only caller of the decision. It
-  keeps owning selection state (buffer space), the screen anchor recording, the pending-click timer,
-  the clamp, and `copySelectionToClipboard()`. No new private method is introduced and no new
-  side-effect surface is added — the copy branch already exists and is reused verbatim.
-- **Screen anchor ownership**: the anchor is recorded in the press branch as a field of
-  `this.selection`, so it shares the selection's lifetime — there is no second piece of state to
-  invalidate in `clearSelection()`, the pending-click timer, or `selectWordAtPoint()`.
-- **Test seam** (component-level, A2–A6): the public `handleInput` legacy seam + a fake
-  `tui.terminal.write` capture + a real runner socket with the fake PTY, i.e. exactly the seams
-  `test/pty-attach-mouse.test.mjs` and `test/pty-attach-selection-mirror.test.mjs` already use.
-  No test-only export, no new env knob, no injection hook.
-- **Fixtures**: default-mode `test-support/fake-pty-pi.mjs` prints exactly one stable line
-  (`fake pi ready`), so the expected OSC 52 payload is deterministic; `steady` mode is the drift
-  source for A5. A PATH-stub `xclip` (logs args, swallows stdin) keeps scenarios off the host
-  clipboard.
-- **Boundaries to preserve**: each comparison keeps exactly one definition (`sameMousePoint` for
-  buffer points, `sameScreenCell` for screen cells, both in `pty-scroll.mjs`, both unit-tested);
-  the component must not re-inline either comparison, and the drag decision must not be split
-  between the helper and the component.
-
-## Risks / guarantee boundaries
-
-- **Coordinates are cell-quantized.** A gesture that starts and ends within the same screen cell (or
-  one column apart) is still a click; the fix cannot see sub-cell intent. Both comparison helpers
-  apply the same 1-cell slack used today for double-click detection, so classification stays
-  consistent.
-- **Release outside the body** is clamped into the body before the selection focus is updated
-  (existing behavior, unchanged); the drag decision itself uses the raw screen cells, so an
-  out-of-body release is still classified as a drag when the pointer really moved.
-- **Screen coordinates are only used for classification.** The selection range stays in buffer
-  coordinates; if output scrolls the buffer mid-gesture, the copied text is whatever the current
-  viewport mapping yields — unchanged behavior, not addressed here.
-- **Double-click matching still uses buffer coordinates.** `isDoubleClickCandidate` (`:1096`)
-  compares `lastClickPoint` (captured at the first release) against the second release point, both
-  in buffer space, so output arriving between the two clicks makes a double-click miss — a
-  pre-existing behaviour that #187 deliberately does not change (same drift mechanism as above,
-  different call site). Fixing it means moving that comparison to screen cells too; that is a
-  separate change with its own acceptance and deserves its own issue.
-- **#188 / #189 are not fixed here.** X10-only terminals still misparse the release as a press, and
-  mixed input chunks still bypass the mouse path; in those scenarios the selection is still lost.
-  This is explicitly out of scope for #187.
-- **No claim about terminal clipboard support.** The fix guarantees the copy is *attempted* on this
-  path (OSC 52 write + PRIMARY mirror); whether the outer terminal honors OSC 52 is
-  terminal-dependent (the reporter verified Warp does).
-- **No claim about fullscreen mode.** pi ≥1.0 fullscreen selection/copy is pi-tui's; this handler
-  does not run there.
-
-## Deliverables
-
-- `src/core/pty-scroll.mjs`: + `sameMousePoint` (moved), + `sameScreenCell`, + `selectionReleaseIsDrag`
-- `src/ui/pty-attach.ts`: import both comparators + the decision; delete the local `sameMousePoint`;
-  record `screenAnchor` in the press branch; release-branch decision
-- `test/pty-scroll.test.mjs`: decision-table cases (A1)
-- `test-support/pty-attach-legacy-drag-scenario.ts` + `test/pty-attach-legacy-drag.test.mjs` (A2–A4, A6)
-- `test-support/pty-attach-legacy-drag-drift-scenario.ts` + `test/pty-attach-legacy-drag-drift.test.mjs` (A5)
-- `docs/superpowers/specs/2026-10-14-issue-187-motionless-drag-design.md`: this spec, first commit in the worktree (step 5)
-- CHANGELOG entry via the release tooling at release time (not in this PR)
-
-## Open question for the design gate
-
-U2 depends on tmux + regular TUI mode being available in the operator's environment (tmux 3.4 is
-present on this machine, verified). If the operator confirms it is not available, U2 is recorded as
-`pending` (per the acceptance-reporting rule) and A2 stays the evidence for the fix.