screenshot-vision-algorithm 0.3.0__py3-none-any.whl

screenshot_vision_algorithm/android/wechat/algorithms/card_bbox.py

@@ -0,0 +1,1000 @@
+"""Resume-thumbnail card geometry from ``favorite_label`` template hits.
+
+Given the (variable) set of ``favorite_label.png`` hits found across one chat
+screenshot, derive:
+    - the bounding box (top/bottom/left/right) of each resume-thumbnail card
+    - the recommended click center for ``tap_thumbnail``
+    - the ``click_side`` half (``left`` / ``right``) relative to the
+      screen midline — stored in ``click_context.click_side`` for gate-1e/4
+      group-A discipline
+
+Two-stage strategy (DD section 2.4.x A + section 3.3 1):
+
+    Stage 1: ``favorite_label.png`` template match (done upstream by
+             ``collector.template_matcher``) returns a list of (x, y, score)
+             hits, one per card (the label is the strongest on-card anchor
+             and appears exactly once per card).
+
+    Stage 2: For each hit:
+        - card.top    = prev_hit.y2 + FAVORITE_TAIL_OFFSET + 1
+                        (for i=0, fall back to ``y1 - FAVORITE_TO_CARD_TOP_OFFSET``)
+        - card.bottom = hit.y2 + FAVORITE_TAIL_OFFSET (anchor sits near bottom)
+        - card.left   = 0, card.right = screen_w
+          (the label only gives us y; the card always spans full text column
+           width, and tapping anywhere horizontally inside it opens the note)
+
+    The click target is the **center of the ``favorite_label`` template
+    hit** (the ``收藏`` crop — ``chat_profiles/.../favorite_label.png``,
+    **70×60 @ 1080 baseline**, scaled by ``scale_w`` at match time). This
+    keeps taps on the label foot instead of the card mid-column (avoids
+    right-side image thumbnails and lands on the note entry chrome).
+
+    Constants are anchored to the 1080x2248 baseline; runtime ``scale_w`` is
+    applied when loading templates.
+
+Aligned with:
+    DD section 2.4.x A (two-stage thumbnail detection)
+    DD section 3.3 step 1 (tap_thumbnail)
+    chat_profiles/README.md v0.2.2 UI constants
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Optional, Sequence
+
+import cv2
+import numpy as np
+
+#: Distance from the top of the ``favorite_label.png`` hit to the top of the
+#: enclosing note card, measured at 1080x2248 baseline. Used as an
+#: **upper-bound heuristic** for the first hit only (subsequent hits derive
+#: their top from the previous hit's bottom + ``FAVORITE_TAIL_OFFSET``).
+FAVORITE_TO_CARD_TOP_OFFSET_BASELINE = 421
+
+#: Gap from the bottom of the ``favorite_label.png`` hit to the card's
+#: actual bottom edge, at 1080x2248 baseline. Used to extend the card bbox
+#: past the label.
+FAVORITE_TAIL_OFFSET_BASELINE = 60
+
+#: ``favorite_label.png`` raster size @ 1080-wide baseline (`chat_profiles/README.md`).
+FAVORITE_LABEL_TEMPLATE_W_BASELINE = 70
+FAVORITE_LABEL_TEMPLATE_H_BASELINE = 60
+
+#: **edb1a89f 1080×2248** empirical row step (px @ baseline width):
+#:
+#: - ``session_20260506193232`` ``scr_004`` ``chat_resume_rescan``: real card tops
+#:   424→966 → **Δtop = 542** (minimal full-notebook row step that frame).
+#: - Same session ``scr_009``: first row ``top`` clamps to **0**, next real row top
+#:   **396** → **Δtop = 396** (pseudo strip from «421px 顶上启发» eating grey/chrome).
+#:
+#: When ``card.top == 0`` and another card sits below: if
+#: ``Δtop < round(REFERENCE_RESUME_CARD_TOP_GAP_BASELINE * scale_w)
+#:        - round(FAVORITE_LABEL_TEMPLATE_H_BASELINE * scale_w)``
+#: (same as ``Δtop - H_fixed <`` 收藏小矩形高度 in px), drop the clamped strip as
+#: a false clickable card. Single top-clamped hits (no sibling) stay — no pitch to
+#: compare (caller may rely on OCR / downstream).
+REFERENCE_RESUME_CARD_TOP_GAP_BASELINE: int = 542
+
+#: Session de-dup: ``chat_resume_rescan`` / 连续帧上同一张卡，只比较 **纵轴**：两卡行区间
+#: ``[top,bottom]``（端点像素含于区间内）相交长度除以 ``min(h_a,h_b)``
+#: ≥ 本阈值 → 视为已从会话内路径处理过。**不**用 2D 面积交叉（Notebook 推导卡本就
+#: 横跨整列宽，横轴对辨重贡献小；且略省乘加）。仍为 O(K) 逐项比、\(K\le\) 屏幕上收藏命中数，
+#: **相对 screencap + OpenCV**，性能可忽略。
+PROCESSED_CARD_MATCH_MIN_OVERLAP_RATIO: float = 0.70
+
+#: Anti-detection horizontal jitter (px @ 1080 baseline) applied by
+#: ``enter_note`` on every tap attempt: ``tap_x = click_x ± random(0..15)``.
+#: Y is never jittered (speaker attribution depends on exact Y).
+TAP_ANTI_DETECT_X_JITTER_PX: int = 15
+
+#: 3b gap 合并/延长判别距离（px @ 1080 baseline，运行时 ×scale_w）：
+#: 收藏锚点落在同一竖线相邻两 zone 的间隙时，取锚点下方第一条横线，
+#: 横线与下方 zone 起点距离 ≤ 本值 → 两 zone 同卡（被收藏标签行打断），合并；
+#: > 本值 → 异卡，上方 zone 向下延长至该横线作为卡片下界。
+GAP_HLINE_TO_NEXT_ZONE_MAX_BASELINE: int = 30
+
+#: 3a 标签相交横线排除的纵向扩展（px @ 1080 baseline，运行时 ×scale_w）：
+#: 横线 y 落在收藏标签纵向范围上下各扩本值内、且横向与标签有交集 → 排除
+#: （收藏标签行自身的中方差纹理会产生伪横线，不能作为卡片边界）。
+FAV_LABEL_HLINE_EXCLUDE_PAD_BASELINE: int = 5
+
+#: zone 端点 snap 容差（px，图像空间，**不**随 scale_w 缩放）：中方差掩码经
+#: 7×7 盒滤波产生 ±3px 边缘扩散，zone 端点可越过其真实边界横线 1~3px；
+#: snap 时允许横线落在 zone 端点向内本值范围内，避免跳过紧贴的真边界。
+ZONE_SNAP_BLUR_TOL_PX: int = 4
+
+
+@dataclass(frozen=True)
+class FavoriteLabelHit:
+    """One match of ``favorite_label.png`` on the chat screenshot.
+
+    ``x, y`` are the top-left corner (OpenCV convention — same as what
+    ``collector.template_matcher.Hit`` carries). ``w, h`` are the
+    (possibly scale_w-adjusted) template dimensions so callers can compute
+    ``y2 = y + h`` without re-loading the template image.
+    """
+
+    x: int
+    y: int
+    w: int
+    h: int
+    score: float
+
+    @property
+    def y1(self) -> int:
+        return self.y
+
+    @property
+    def y2(self) -> int:
+        return self.y + self.h
+
+
+@dataclass(frozen=True)
+class ThumbnailCard:
+    """Derived rectangle for one resume-note thumbnail.
+
+    Coordinates are in raw-image pixel space (same as the source screenshot).
+    ``click_x`` / ``click_y`` is what the driver passes to ``adb shell
+    input tap``. ``click_side`` is the DD §2.4.x A ``click_context.click_side``
+    signal (which half of the screen the card lives on — historically useful
+    because WeChat sometimes shows the reply preview on the opposite side).
+    """
+
+    index: int  # 0-based; matches the favorite_label hit ordering (top→bottom)
+    top: int
+    bottom: int
+    left: int
+    right: int
+    click_x: int
+    click_y: int
+    click_side: str  # "left" or "right"
+    favorite_hit: FavoriteLabelHit
+
+
+@dataclass(frozen=True)
+class BubbleBbox:
+    """Derived rectangle for one text-chat bubble.
+
+    Coordinates are in raw-image pixel space. Generated from remaining
+    mid-variance zones after card zones are excluded (Step 4).
+    """
+
+    top: int
+    bottom: int
+    left: int
+    right: int
+
+
+def _compute_exact_card_and_bubble_bboxes(
+    ordered_hits: list[FavoriteLabelHit],
+    bgr_img: np.ndarray,
+    screen_w: int,
+    screen_h: int,
+) -> tuple[list[ThumbnailCard], list[BubbleBbox]]:
+    """PRD S6: vline-segment + hline-boundary card + bubble bbox detection.
+
+    Steps:
+        1. Convert to grayscale, compute local variance via box filter,
+           derive mid-variance mask (gray 190-248, std 6-25).
+        2. Find right-side vline candidates via vertical projection;
+           score them (total + longest run) as the per-card try order.
+        3. Segment every candidate vline into continuous runs (zones);
+           clamp to [TOP, BOT].
+        4. Find card-boundary hlines (span > 50% card_w); per vline keep
+           hlines whose endpoint is within 100px of the vline; exclude
+           hlines intersecting any 收藏 label (3a — the label row's own
+           texture creates spurious hlines).
+        5. Per fav anchor, walk candidate vlines: zone containment →
+           normal hline snap; anchor in a zone gap → 3b merge/extend via
+           the first hline below the anchor; enforce fav_cy ∈ bbox.
+        6. Remaining zones not vertically intersecting any card bbox are
+           emitted as text-bubble bboxes.
+    """
+    gray = cv2.cvtColor(bgr_img, cv2.COLOR_BGR2GRAY).astype(np.float32)
+
+    H, _W = gray.shape
+    TOP = int(H * 0.10)
+    BOT = int(H * 0.93)
+    AR = int(108 * screen_w / 1080)
+    card_w = screen_w - AR
+    sw = screen_w / 1080.0  # 1080-baseline scale for px constants
+
+    # Step 1 — fast local variance via box filter (O(N) via integral images)
+    win = 7
+    mean = cv2.boxFilter(gray, -1, (win, win), normalize=True)
+    sq_mean = cv2.boxFilter(gray * gray, -1, (win, win), normalize=True)
+    var_map = np.maximum(sq_mean - mean * mean, 0.0)
+    std_map = np.sqrt(var_map)
+
+    # Mid-variance mask: gray 190-248, std 6-25
+    mid = (
+        (gray >= 190.0) & (gray <= 248.0) &
+        (std_map >= 6.0) & (std_map <= 25.0)
+    )
+
+    # Step 2 — right-side vline candidates
+    # PRD: per-column max *continuous-segment* length > 15% of zone height
+    # (not total pixel sum across the column).
+    vh = BOT - TOP
+    min_seg = vh * 0.15
+
+    cand_cols = []
+    for x in range(screen_w):
+        col = mid[TOP:BOT, int(x)]
+        max_seg = 0
+        cur = 0
+        for v in col:
+            if v:
+                cur += 1
+            else:
+                if cur > max_seg:
+                    max_seg = cur
+                cur = 0
+        if cur > max_seg:
+            max_seg = cur
+        if max_seg > min_seg:
+            cand_cols.append(x)
+
+    # PRD: group qualifying columns by >30px gap, take cluster mean
+    vd_lines = []
+    if cand_cols:
+        cluster = [cand_cols[0]]
+        for i in range(1, len(cand_cols)):
+            if cand_cols[i] - cand_cols[i - 1] > 30:
+                vd_lines.append(int(round(sum(cluster) / len(cluster))))
+                cluster = [cand_cols[i]]
+            else:
+                cluster.append(cand_cols[i])
+        vd_lines.append(int(round(sum(cluster) / len(cluster))))
+
+    # PRD §B.2 Step 2: 竖线离发言人头像的X距离应该 >= 260 px (1080基准)
+    min_card_x_gap = int(260 * screen_w / 1080)
+    vd_lines = [vx for vx in vd_lines if vx - AR >= min_card_x_gap]
+
+    if not vd_lines:
+        return [], []
+
+    # Pick best vline: max total mid pixels + longest continuous segment
+    vline_scores: dict[int, float] = {}
+    best_vx, best_score = None, 0.0
+    for vx in vd_lines:
+        col = mid[:, vx]
+        segs = []
+        k = 0
+        while k < H:
+            if col[k]:
+                s = k
+                while k < H and col[k]:
+                    k += 1
+                segs.append(k - s)
+            else:
+                k += 1
+        total = float(sum(segs))
+        longest = float(max(segs) if segs else 0)
+        score = total + longest
+        vline_scores[vx] = score
+        if score > best_score:
+            best_score = score
+            best_vx = vx
+
+    if best_vx is None:
+        return [], []
+
+    # Step 3 — vline segments, computed per candidate vline. A fav-anchored
+    # card may sit on a different right-edge vline than the frame-global best
+    # one when plain text bubbles and note cards mix in one frame (the bubble
+    # edge can out-score the card edge — 20260611 session_185429 C1 case).
+    def _zones_for(vx: int) -> list[tuple[int, int]]:
+        colv = mid[:, int(vx)]
+        segs: list[tuple[int, int]] = []
+        yy = 0
+        while yy < H:
+            if colv[yy]:
+                s = yy
+                while yy < H and colv[yy]:
+                    yy += 1
+                segs.append((s, yy - 1))
+            else:
+                yy += 1
+        # Clamp to [TOP, BOT], drop tiny
+        return [
+            (max(TOP, s), min(BOT, e))
+            for s, e in segs
+            if min(BOT, e) - max(TOP, s) > 10
+        ]
+
+    vline_order: list[int] = [int(best_vx)] + sorted(
+        (int(vx) for vx in vd_lines if vx != best_vx),
+        key=lambda vx: vline_scores[vx],
+        reverse=True,
+    )
+    zones_by_vx = {vx: _zones_for(vx) for vx in vline_order}
+    if not any(zones_by_vx.values()):
+        return [], []
+
+    # Step 4 — card boundary hlines (span > 50% card_w, X-near vline,
+    # max gray gradient >= 30 = white→gray boundary)
+    hproj = np.sum(mid[:, AR:], axis=1).astype(float)
+    above = hproj > card_w * 0.25
+    XLIMIT = int(100 * screen_w / 1080)
+    all_hd: list[tuple[int, int, int, int, int]] = []  # (hy,span,left_x,right_x,white_pct_diff)
+    i = 0
+    while i < H:
+        if above[i]:
+            j = i + 1
+            while j < H and above[j]:
+                j += 1
+            hy = (i + j - 1) // 2
+            hrow = int(hy)
+            row = mid[hrow, :]
+            seg_info: list[tuple[int, int, int]] = []  # (len, start_x, end_x)
+            k = 0
+            while k < screen_w:
+                if row[k]:
+                    s = k
+                    while k < screen_w and row[k]:
+                        k += 1
+                    seg_info.append((k - s, s, k - 1))
+                else:
+                    k += 1
+            if seg_info:
+                span, left_x, right_x = max(seg_info, key=lambda t: t[0])
+            else:
+                span, left_x, right_x = 0, 0, 0
+            # Vertical white-pct change across this hline: real white→gray
+            # boundaries show a large drop in white-pixel ratio above vs
+            # below; uniform UI separators (e.g. y=206) show near-zero.
+            col = gray[:, AR:int(best_vx)]
+            H_img = col.shape[0]
+            r1 = max(0, hrow - 2)
+            r2 = min(H_img, hrow + 2)
+            above_zone = col[r1:hrow, :]
+            below_zone = col[hrow:r2, :]
+            above_white = int((above_zone > 244).sum())
+            below_white = int((below_zone > 244).sum())
+            above_pct = above_white / above_zone.size if above_zone.size else 0.0
+            below_pct = below_white / below_zone.size if below_zone.size else 0.0
+            white_pct_diff = int(abs(above_pct - below_pct) * 100)
+            all_hd.append((hy, span, left_x, right_x, white_pct_diff))
+            i = j
+        else:
+            i += 1
+
+    # 3a — exclude label-row artifact hlines: the 收藏 label row's own
+    # mid-variance texture creates spurious hlines that must never act as
+    # card boundaries. Horizontal-locality guard: only lines confined to
+    # the label's neighborhood (±1 label width) are artifacts — the card's
+    # TRUE bottom boundary also intersects the label's vertical range
+    # (the label sits at the card bottom) but spans the full card width
+    # and must stay eligible (20260611 18-session benchmark: vertical-only
+    # exclusion extended every card bottom to the next card's top).
+    fav_pad = int(round(FAV_LABEL_HLINE_EXCLUDE_PAD_BASELINE * sw))
+
+    def _hline_intersects_fav_label(
+        hy: int, left_x: int, right_x: int,
+    ) -> bool:
+        for h_ in ordered_hits:
+            if (h_.y - fav_pad) <= hy <= (h_.y2 + fav_pad):
+                if (
+                    left_x >= h_.x - h_.w
+                    and right_x <= h_.x + 2 * h_.w
+                ):
+                    return True
+        return False
+
+    def _hline_endpoint_near_vline(
+        left_x: int, right_x: int, vx: int, x_limit: int,
+    ) -> bool:
+        # 横线段覆盖竖线 x（±x_limit）即可：真实卡片边界横线常与全宽
+        # 分隔行（时间戳行等）融合，端点远在竖线 100px 之外但线体确实
+        # 经过竖线（20260611 191430 scr_002 基准回归）；纯"端点判距"
+        # 会把这类真边界排除。远离竖线的短横线仍被本判据拒绝。
+        return (left_x - x_limit) <= int(vx) <= (right_x + x_limit)
+
+    hlines_by_vx: dict[int, list[tuple[int, int, int, int, int]]] = {
+        vx: sorted(
+            (hy, span, left_x, right_x, white_pct_diff)
+            for hy, span, left_x, right_x, white_pct_diff in all_hd
+            if TOP <= hy <= BOT and span > card_w * 0.5
+            and _hline_endpoint_near_vline(left_x, right_x, vx, XLIMIT)
+            and not _hline_intersects_fav_label(hy, left_x, right_x)
+        )
+        for vx in vline_order
+    }
+
+    # Step 5 — match vline zones to fav hits, snap to hlines. Per hit, walk
+    # candidate vlines (best-scored first) and accept the first bbox that
+    # actually contains the fav anchor: the 收藏 label lives INSIDE its card,
+    # so a bbox excluding it is a mis-matched zone, not this card.
+    gap_tol = max(1, int(round(GAP_HLINE_TO_NEXT_ZONE_MAX_BASELINE * sw)))
+    cards: list[ThumbnailCard] = []
+    prev_bottom: int | None = None  # anti-overlap: enforce card boundaries non-overlapping
+    for idx, hit in enumerate(ordered_hits):
+        fav_cy = hit.y + hit.h // 2
+
+        chosen: tuple[int, int, int] | None = None  # (vx, exact_y1, exact_y2)
+        for vx in vline_order:
+            zones = zones_by_vx[vx]
+            if not zones:
+                continue
+            card_hlines = hlines_by_vx[vx]
+
+            def _snap(y1_: int, y2_: int) -> tuple[int, int]:
+                # 盒滤波边缘扩散：zone 端点可越过真实边界横线 1~3px，
+                # 允许横线落在端点向内 ZONE_SNAP_BLUR_TOL_PX 内。
+                # Upper: "向上最近的白底-灰底的中方差横线（要求另一端在发言人
+                #         头像100 px附近）或者 TOP_BAR_BOT"
+                upper = [h for h in card_hlines
+                         if TOP <= h[0] < y1_ + ZONE_SNAP_BLUR_TOL_PX
+                         and h[2] < AR + XLIMIT]
+                ey1 = max(upper, key=lambda h: h[0])[0] if upper else TOP
+                # Lower: "向下最近的白底-灰底的中方差横线 或者 BOT_BAR_TOP"
+                lower = [h for h in card_hlines
+                         if y2_ - ZONE_SNAP_BLUR_TOL_PX < h[0] <= BOT]
+                ey2 = min(lower, key=lambda h: h[0])[0] if lower else BOT
+                return ey1, ey2
+
+            # 锚点直接落在某个 zone 内 → 正常 snap
+            fav_zone_idx = None
+            for zi, (z1, z2) in enumerate(zones):
+                if z1 <= fav_cy <= z2:
+                    fav_zone_idx = zi
+                    break
+
+            if fav_zone_idx is not None:
+                exact_y1, exact_y2 = _snap(
+                    zones[fav_zone_idx][0], zones[fav_zone_idx][1],
+                )
+            else:
+                # 锚点落在相邻两 zone 的间隙（收藏标签行可能打断竖线）→ 3b
+                gap_idx = None
+                for zi in range(len(zones) - 1):
+                    if zones[zi][1] < fav_cy < zones[zi + 1][0]:
+                        gap_idx = zi
+                        break
+                if gap_idx is None:
+                    # 锚点在所有 zone 上方或下方 → 该竖线与这张卡无关
+                    continue
+
+                upper_zone = zones[gap_idx]
+                next_zone = zones[gap_idx + 1]
+                # 3b 仅处理"收藏标签行打断竖线"的窄缝（标签高 + 2×判别
+                # 容差）。宽缝意味着该竖线在锚点处根本没有边缘纹理（多为
+                # 其它气泡的右缘竖线），借横线构造的 bbox 会假性包含锚点
+                # （20260611 185429 scr_003/008/013 基准回归），跳过该竖线。
+                if (next_zone[0] - upper_zone[1]) > hit.h + 2 * gap_tol:
+                    continue
+                # 3b 第一步：从锚点中心向下找第一条（已 3a 过滤的）横线。
+                # 含等于（>=）：锚点恰好压在本卡底边界横线上时，该边界
+                # 必须参与判别，否则会越过它误触发情况 A 跨卡合并。
+                below = [h for h in card_hlines if h[0] >= fav_cy]
+                first_hline_y = min(below, key=lambda h: h[0])[0] if below else None
+
+                if first_hline_y is None:
+                    # 缺省策略：沿用旧规则只取上方 zone，正常 snap
+                    exact_y1, exact_y2 = _snap(upper_zone[0], upper_zone[1])
+                elif abs(first_hline_y - next_zone[0]) <= gap_tol:
+                    # 情况 A：横线靠近下方 zone 起点 → 同一张卡被收藏标签行
+                    # 打断，合并两 zone 后重新 snap
+                    exact_y1, exact_y2 = _snap(upper_zone[0], next_zone[1])
+                else:
+                    # 情况 B：横线远离下方 zone 起点 → 异卡；上方 zone 向下
+                    # 延长，以该横线作为卡片下界（上界仍正常 snap）
+                    ey1, _ = _snap(upper_zone[0], upper_zone[1])
+                    exact_y1, exact_y2 = ey1, int(first_hline_y)
+
+            if exact_y2 <= exact_y1 or exact_y2 - exact_y1 < 80:
+                continue
+            if not (exact_y1 <= fav_cy <= exact_y2):
+                continue
+            chosen = (vx, exact_y1, exact_y2)
+            break
+
+        if chosen is None:
+            continue
+        card_vx, exact_y1, exact_y2 = chosen
+
+        # Anti-overlap: ensure sequence of cards is strictly non-overlapping
+        # (essential when gap-matching + hline snapping pushes boundaries inward)
+        if prev_bottom is not None and exact_y1 <= prev_bottom:
+            exact_y1 = prev_bottom + 1
+            if exact_y2 <= exact_y1 or exact_y2 - exact_y1 < 80:
+                continue
+
+        click_x = min(screen_w - 1, max(0, hit.x + hit.w // 2))
+        click_y = min(screen_h - 1, max(0, hit.y + hit.h // 2))
+        midline = screen_w / 2.0
+        click_side = "left" if click_x < midline else "right"
+
+        cards.append(ThumbnailCard(
+            index=idx,
+            top=exact_y1,
+            bottom=exact_y2,
+            left=AR,
+            right=card_vx,
+            click_x=click_x,
+            click_y=click_y,
+            click_side=click_side,
+            favorite_hit=hit,
+        ))
+        prev_bottom = exact_y2
+
+    # Step 6 — remaining zones → text-bubble bboxes. 对每条竖线的每个 zone：
+    # 若与任何卡片包围盒纵向相交则放弃该 zone；否则该 zone 属于文本聊天气泡。
+    card_intervals = [(c.top, c.bottom) for c in cards]
+
+    def _intersects_any_card(z1: int, z2: int) -> bool:
+        return any(z2 >= ct and z1 <= cb for ct, cb in card_intervals)
+
+    bubbles: list[BubbleBbox] = []
+    for vx in sorted(zones_by_vx):
+        zones = zones_by_vx[vx]
+        if not zones:
+            continue
+        bubble_hlines = hlines_by_vx[vx]
+        last_zi = len(zones) - 1
+        for zi, (z1, z2) in enumerate(zones):
+            if _intersects_any_card(z1, z2):
+                continue
+            # 上端向上找最近横线（要求另一端在头像附近 100px 内）；
+            # 仅第一个 zone 允许回退到 TOP_BAR_BOT，中间 zone 匹配不到
+            # 横线时保留原始 zone 边界
+            upper = [h for h in bubble_hlines
+                     if TOP <= h[0] < z1 + ZONE_SNAP_BLUR_TOL_PX
+                     and h[2] < AR + XLIMIT]
+            if upper:
+                by1 = max(upper, key=lambda h: h[0])[0]
+            else:
+                by1 = TOP if zi == 0 else z1
+            # 下端向下找最近横线；仅最后一个 zone 允许回退到 BOT_BAR_TOP
+            lower = [h for h in bubble_hlines
+                     if z2 - ZONE_SNAP_BLUR_TOL_PX < h[0] <= BOT]
+            if lower:
+                by2 = min(lower, key=lambda h: h[0])[0]
+            else:
+                by2 = BOT if zi == last_zi else z2
+            if by2 - by1 < 80:
+                continue
+            bubbles.append(BubbleBbox(top=by1, bottom=by2, left=AR, right=int(vx)))
+
+    return cards, bubbles
+
+
+def _compute_exact_card_bboxes(
+    ordered_hits: list[FavoriteLabelHit],
+    bgr_img: np.ndarray,
+    screen_w: int,
+    screen_h: int,
+) -> list[ThumbnailCard]:
+    """Backward-compat wrapper — cards only (see
+    :func:`_compute_exact_card_and_bubble_bboxes`)."""
+    cards, _bubbles = _compute_exact_card_and_bubble_bboxes(
+        ordered_hits, bgr_img, screen_w, screen_h,
+    )
+    return cards
+
+
+def derive_cards_and_bubbles(
+    hits: Sequence[FavoriteLabelHit],
+    *,
+    screen_w: int,
+    screen_h: int,
+    scale_w: float = 1.0,
+    chat_img: np.ndarray,
+) -> tuple[list[ThumbnailCard], list[BubbleBbox]]:
+    """Like :func:`derive_cards` but also returns text-bubble bboxes
+    (PRD §9(1) Step 4 — remaining vline zones not occupied by cards).
+
+    ``chat_img`` is mandatory: bubble derivation requires the
+    variance-texture pipeline (no legacy fixed-offset fallback).
+    Bubbles can exist on frames with zero 收藏 hits as well, but this
+    function mirrors :func:`derive_cards` and returns ``([], [])`` for an
+    empty ``hits`` sequence (callers without hits don't run the pipeline).
+    """
+    if not hits:
+        return [], []
+    ordered = sorted(hits, key=lambda h: h.y)
+    try:
+        cards, bubbles = _compute_exact_card_and_bubble_bboxes(
+            ordered, chat_img, screen_w, screen_h,
+        )
+    except Exception:
+        return [], []
+    return (
+        drop_top_clamped_false_positive_cards(cards, scale_w=scale_w),
+        bubbles,
+    )
+
+
+def bubble_to_metadata_list(bubble: BubbleBbox) -> list[int]:
+    """Convert a :class:`BubbleBbox` to schema shape ``[x1, y1, x2, y2]``."""
+    return [bubble.left, bubble.top, bubble.right, bubble.bottom]
+
+
+def derive_cards(
+    hits: Sequence[FavoriteLabelHit],
+    *,
+    screen_w: int,
+    screen_h: int,
+    scale_w: float = 1.0,
+    chat_img: Optional[np.ndarray] = None,
+) -> list[ThumbnailCard]:
+    """Translate favorite_label hits into click-ready :class:`ThumbnailCard`.
+
+    Args:
+        hits: favorite_label.png hits on the chat screenshot, in any order
+              (we sort by y ourselves).
+        screen_w / screen_h: the source screenshot's raw-image dimensions
+                             (usually equal to ``device_info.screen_resolution``).
+        scale_w: ``screen_w / baseline_w`` (baseline = 1080). Used to scale
+                 ``FAVORITE_TO_CARD_TOP_OFFSET`` + ``FAVORITE_TAIL_OFFSET``
+                 so the logic survives across the 720 / 1080 / 1220 device
+                 whitelist.
+        chat_img: optional BGR image (as returned by ``cv2.imdecode``).
+                  When provided, uses the vline-segment + hline-boundary
+                  variance-based algorithm (PRD S6) for precise card bbox
+                  derivation. Falls back to legacy fixed-offset logic
+                  when ``chat_img`` is None.
+
+    Returns:
+        One :class:`ThumbnailCard` per hit, sorted top -> bottom. Empty list
+        if ``hits`` is empty (caller should then decide whether to scroll
+        further or end the session).
+    """
+    if not hits:
+        return []
+
+    ordered = sorted(hits, key=lambda h: h.y)
+
+    # New algorithm: vline-segment + hline-boundary (PRD S6). When the
+    # pipeline ran successfully its verdict is final — an anchor it dropped
+    # (no containing zone → "点对卡、记错框" guard) must NOT be resurrected
+    # by the legacy fixed-offset fallback. Legacy only serves chat_img=None
+    # callers and pipeline exceptions.
+    if chat_img is not None and len(ordered) > 0:
+        try:
+            exact_cards = _compute_exact_card_bboxes(
+                ordered, chat_img, screen_w, screen_h,
+            )
+        except Exception:
+            pass
+        else:
+            return drop_top_clamped_false_positive_cards(
+                exact_cards, scale_w=scale_w,
+            )
+
+    # Legacy: fixed-offset algorithm
+    top_offset = int(round(FAVORITE_TO_CARD_TOP_OFFSET_BASELINE * scale_w))
+    tail_offset = int(round(FAVORITE_TAIL_OFFSET_BASELINE * scale_w))
+
+    cards: list[ThumbnailCard] = []
+    for idx, hit in enumerate(ordered):
+        if idx == 0:
+            card_top = max(0, hit.y1 - top_offset)
+        else:
+            prev_bottom = ordered[idx - 1].y2 + tail_offset
+            card_top = max(prev_bottom + 1, 0)
+
+        card_bottom = min(screen_h - 1, hit.y2 + tail_offset)
+
+        if card_bottom <= card_top:
+            continue
+
+        click_x = min(screen_w - 1, max(0, hit.x + hit.w // 2))
+        click_y = min(screen_h - 1, max(0, hit.y + hit.h // 2))
+        midline = screen_w / 2
+        click_side = "left" if click_x < midline else "right"
+
+        cards.append(ThumbnailCard(
+            index=idx,
+            top=card_top,
+            bottom=card_bottom,
+            left=0,
+            right=screen_w - 1,
+            click_x=click_x,
+            click_y=click_y,
+            click_side=click_side,
+            favorite_hit=hit,
+        ))
+
+    return drop_top_clamped_false_positive_cards(cards, scale_w=scale_w)
+
+
+def drop_top_clamped_false_positive_cards(
+    cards: list[ThumbnailCard],
+    *,
+    scale_w: float,
+) -> list[ThumbnailCard]:
+    """Drop notebook strips whose ``top`` clamped to 0 when the gap to the
+    next derived card top matches the empirical **pseudo-row** signature on
+    edb1a89f — see :data:`REFERENCE_RESUME_CARD_TOP_GAP_BASELINE`.
+
+    Condition (scaled): let ``Δ = cards[k+1].top - cards[k].top``.
+    Discard ``cards[k]`` when ``cards[k].top == 0`` and
+    ``Δ < round(base_gap * scale_w) - round(label_h * scale_w)`` — i.e.
+    ``Δ - H_fixed < H_收藏`` in device px.
+    """
+    if len(cards) <= 1:
+        return cards
+
+    ref_gap = max(1, int(round(REFERENCE_RESUME_CARD_TOP_GAP_BASELINE * scale_w)))
+    label_scaled = max(1, int(round(FAVORITE_LABEL_TEMPLATE_H_BASELINE * scale_w)))
+    min_step = ref_gap - label_scaled
+
+    kept: list[ThumbnailCard] = []
+    i = 0
+    while i < len(cards):
+        card = cards[i]
+        gap_to_next_card_top = (
+            cards[i + 1].top - card.top if i + 1 < len(cards) else None
+        )
+        reject = False
+        if card.top == 0 and gap_to_next_card_top is not None:
+            dy = gap_to_next_card_top
+            if dy < min_step:
+                reject = True
+
+        if not reject:
+            kept.append(card)
+
+        i += 1
+
+    return [
+        ThumbnailCard(
+            index=j,
+            top=c.top,
+            bottom=c.bottom,
+            left=c.left,
+            right=c.right,
+            click_x=c.click_x,
+            click_y=c.click_y,
+            click_side=c.click_side,
+            favorite_hit=c.favorite_hit,
+        )
+        for j, c in enumerate(kept)
+    ]
+
+
+def bbox_to_metadata_list(card: ThumbnailCard) -> list[int]:
+    """Convert a :class:`ThumbnailCard` bbox to the schema's
+    ``resume_thumb_bboxes`` element shape ``[x1, y1, x2, y2]``.
+
+    The schema declares ``resume_thumb_bboxes: Optional[list[list[int]]]``
+    per screenshot — one list-of-4 entry per thumbnail the collector
+    identified on that screen.
+    """
+    return [card.left, card.top, card.right, card.bottom]
+
+
+def click_context_for_tap_thumbnail(card: ThumbnailCard) -> dict:
+    """Build the ``click_context`` dict for a group-A ``tap_thumbnail`` frame.
+
+    Schema requirement (gate 1e/4):
+        group A action → ``click_coords`` + ``click_side`` MUST be populated
+        AND ``click_position`` + ``divider_verified`` MUST be null.
+    """
+    return {
+        "click_coords": [card.click_x, card.click_y],
+        "click_side": card.click_side,
+    }
+
+
+def card_bounding_tuple(card: ThumbnailCard) -> tuple[int, int, int, int]:
+    """Inclusive pixel bbox ``(left, top, right, bottom)`` aligned with
+    ``bbox_to_metadata_list`` / gate-1d thumbnail rectangles."""
+    return (card.left, card.top, card.right, card.bottom)
+
+
+def y_interval_overlap_ratio(
+    top_a: int,
+    bottom_a: int,
+    top_b: int,
+    bottom_b: int,
+) -> float:
+    """1D overlap of inclusive row intervals `[top_* , bottom_*]`.
+
+    Returns ``intersection_px / min(h_a, h_b)`` with
+    ``h = bottom - top + 1``, or ``0.0`` if disjoint."""
+    iy1 = max(top_a, top_b)
+    iy2 = min(bottom_a, bottom_b)
+    if iy2 < iy1:
+        return 0.0
+    inter = iy2 - iy1 + 1
+    ha = bottom_a - top_a + 1
+    hb = bottom_b - top_b + 1
+    denom = min(ha, hb)
+    return inter / denom if denom > 0 else 0.0
+
+
+def card_overlaps_processed(
+    card: ThumbnailCard,
+    processed_bboxes: Iterable[tuple[int, int, int, int]],
+    *,
+    min_overlap_ratio: float = PROCESSED_CARD_MATCH_MIN_OVERLAP_RATIO,
+) -> bool:
+    """True if ``card``'s **vertical span** overlaps any processed card enough.
+
+    Compared per pair: ``intersection_rows / min(height_new, height_old)
+    >= min_overlap_ratio`` where heights use inclusive ``card.top /
+    card.bottom``. ``processed_bboxes`` tuples are ``(left,top,right,bottom)``
+    from :func:`card_bounding_tuple` — only ``top,bottom`` are read.
+    """
+    for prev in processed_bboxes:
+        _l, pt, _r, pb = prev
+        r = y_interval_overlap_ratio(card.top, card.bottom, pt, pb)
+        if r >= min_overlap_ratio:
+            return True
+    return False
+
+
+def pick_first_unprocessed_card(
+    cards: Iterable[ThumbnailCard],
+    processed_card_bboxes: Sequence[tuple[int, int, int, int]] | None = None,
+) -> ThumbnailCard | None:
+    """Return the first card that does **not** sufficiently overlap any
+    already-processed card in the current session (**Y-span only**, see below).
+
+    Overlap rule: for inclusive row intervals ``[top,bottom]`` vs each stored
+    processed bbox, compute
+    ``intersection_px / min(h_new,h_old)``; if ``>=``
+    :data:`PROCESSED_CARD_MATCH_MIN_OVERLAP_RATIO` (default **0.70**) → same
+    logical card → skip. Stored tuples remain ``(left,top,right,bottom)``
+    from :func:`card_bounding_tuple`; only ``top``/``bottom`` participate.
+
+    Used between ``chat_content_scroll_down`` / ``chat_resume_rescan`` frames so a
+    notebook card that reappears with a **slightly shifted** ``favorite_label``
+    match (integer ``(x,y)`` off by a few pixels) is still treated as the same
+    card and not double-tapped.
+
+    ``processed_card_bboxes`` is the list accumulated from prior
+    :func:`card_bounding_tuple` values for cards that entered ``tap_thumbnail``
+    (see ``run_collector_minimal``).
+
+    NOTE: does not model new messages inserted above the card; P0 accepts
+    that rare edge.
+    """
+    seen: list[tuple[int, int, int, int]] = (
+        list(processed_card_bboxes) if processed_card_bboxes else []
+    )
+    for card in cards:
+        if not card_overlaps_processed(card, seen):
+            return card
+    return None
+
+
+@dataclass
+class TrackedCard:
+    """One tracked card in the height-sequence dedup state (array A)."""
+
+    height: int  # bbox height (bottom - top + 1)
+    clicked: bool  # whether this card has been entered
+
+
+def _card_height(card: ThumbnailCard) -> int:
+    """Pixel-height of a card bbox (inclusive row count)."""
+    return card.bottom - card.top + 1
+
+
+def _longest_subsequence_match(
+    a_heights: list[int],
+    b_heights: list[int],
+) -> tuple[int, int, int] | None:
+    """Find the longest contiguous substring of a_heights that appears in b_heights.
+
+    Returns ``(a_start, b_start, length)`` or ``None``.
+    If multiple matches share the same maximum length, picks the one with
+    the smallest ``b_start`` (earliest in B).
+    """
+    if not a_heights or not b_heights:
+        return None
+
+    best: tuple[int, int, int] | None = None  # (a_start, b_start, length)
+
+    for a_start in range(len(a_heights)):
+        max_len = len(a_heights) - a_start
+        for length in range(max_len, 0, -1):
+            if best is not None and length < best[2]:
+                break
+            sub = a_heights[a_start:a_start + length]
+            for b_start in range(len(b_heights) - length + 1):
+                if b_heights[b_start:b_start + length] == sub:
+                    if (
+                        best is None
+                        or length > best[2]
+                        or (length == best[2] and b_start < best[1])
+                    ):
+                        best = (a_start, b_start, length)
+
+    return best
+
+
+def pick_next_unclicked_card(
+    cards: list[ThumbnailCard],
+    tracked_cards: list[TrackedCard],
+) -> ThumbnailCard | None:
+    """Return the next card to enter based on height-sequence dedup.
+
+    Algorithm (PRD S6):
+      1. If ``tracked_cards`` (A) is empty -> build A from current ``cards`` (B),
+         return ``cards[0]``.
+      2. Find the longest contiguous substring of A-heights in B-heights.
+         If multiple, pick the one with smallest B start index.
+      3. Rebuild A: keep matched cards (inheriting ``clicked``), add new
+         B cards before/after the match segment (unclicked), drop unmatched A.
+      4. Collect candidates (B indices where ``tracked_cards[i].clicked`` is
+         ``False``), return ``cards[min(candidates)]`` or ``None``.
+
+    ``tracked_cards`` is mutated in-place on every call - the caller must
+    clear it on ``chat_content_scroll_up`` / ``chat_content_scroll_down``
+    to reset the tracking window.
+    """
+    cur_heights = [_card_height(c) for c in cards]
+
+    if not tracked_cards:
+        tracked_cards[:] = [TrackedCard(height=h, clicked=False) for h in cur_heights]
+        return cards[0]
+
+    a_heights = [tc.height for tc in tracked_cards]
+    match = _longest_subsequence_match(a_heights, cur_heights)
+
+    if match is None:
+        tracked_cards[:] = [TrackedCard(height=h, clicked=False) for h in cur_heights]
+        candidates = [i for i, tc in enumerate(tracked_cards) if not tc.clicked]
+        if not candidates:
+            return None
+        return cards[min(candidates)]
+
+    a_start, b_start, length = match
+
+    new_tracked: list[TrackedCard] = []
+
+    for i in range(b_start):
+        new_tracked.append(TrackedCard(height=cur_heights[i], clicked=False))
+
+    for j in range(length):
+        a_idx = a_start + j
+        new_tracked.append(TrackedCard(
+            height=tracked_cards[a_idx].height,
+            clicked=tracked_cards[a_idx].clicked,
+        ))
+
+    for i in range(b_start + length, len(cards)):
+        new_tracked.append(TrackedCard(height=cur_heights[i], clicked=False))
+
+    tracked_cards[:] = new_tracked
+
+    candidates = [i for i, tc in enumerate(tracked_cards) if not tc.clicked]
+    if not candidates:
+        return None
+    return cards[min(candidates)]
+
+
+__all__ = [
+    "FAVORITE_LABEL_TEMPLATE_W_BASELINE",
+    "FAVORITE_LABEL_TEMPLATE_H_BASELINE",
+    "FAVORITE_TO_CARD_TOP_OFFSET_BASELINE",
+    "FAVORITE_TAIL_OFFSET_BASELINE",
+    "FAV_LABEL_HLINE_EXCLUDE_PAD_BASELINE",
+    "GAP_HLINE_TO_NEXT_ZONE_MAX_BASELINE",
+    "PROCESSED_CARD_MATCH_MIN_OVERLAP_RATIO",
+    "REFERENCE_RESUME_CARD_TOP_GAP_BASELINE",
+    "TAP_ANTI_DETECT_X_JITTER_PX",
+    "FavoriteLabelHit",
+    "ThumbnailCard",
+    "TrackedCard",
+    "BubbleBbox",
+    "derive_cards",
+    "derive_cards_and_bubbles",
+    "drop_top_clamped_false_positive_cards",
+    "bbox_to_metadata_list",
+    "bubble_to_metadata_list",
+    "card_bounding_tuple",
+    "card_overlaps_processed",
+    "click_context_for_tap_thumbnail",
+    "pick_first_unprocessed_card",
+    "pick_next_unclicked_card",
+    "y_interval_overlap_ratio",
+    "_compute_exact_card_bboxes",
+    "_compute_exact_card_and_bubble_bboxes",
+]