wechat-screenshot-vision-algorithm 0.1.0__py3-none-any.whl

wechat_screenshot_vision_algorithm/algorithms/card_bbox.py

@@ -0,0 +1,814 @@
+"""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
+
+
+@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_bboxes(
+    ordered_hits: list[FavoriteLabelHit],
+    bgr_img: np.ndarray,
+    screen_w: int,
+    screen_h: int,
+) -> list[ThumbnailCard]:
+    """PRD S6: vline-segment + hline-boundary card 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.
+           Pick the one with most mid-variance pixels as card right edge.
+        3. Segment the vline into continuous runs; clamp to [TOP, BOT].
+        4. Find card-boundary hlines (span > 50% card_w).
+        5. Match vline segment ends to nearest hlines (+/-80px).
+        6. Assign each hit to its zone by fav-center y; classified zones
+           become resume cards.
+    """
+    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
+
+    # 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
+
+    def _hline_near_vline(y: int, vx: int, mid_mask: np.ndarray, x_limit: int) -> bool:
+        x1 = max(0, int(vx) - x_limit)
+        x2 = min(mid_mask.shape[1] - 1, int(vx) + x_limit)
+        return bool(mid_mask[y, x1:x2 + 1].any())
+
+    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_near_vline(hy, vx, mid, XLIMIT)
+        )
+        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.
+    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
+
+            # Try exact zone containment first; if in a gap, pair with the
+            # zone immediately *above* within the SAME vline (收藏 row may
+            # interrupt the vline run).
+            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 None and len(zones) >= 2:
+                # Hit in gap — find the zone just above it
+                for zi in range(len(zones) - 1):
+                    if zones[zi][1] < fav_cy < zones[zi + 1][0]:
+                        fav_zone_idx = zi
+                        break
+
+            if fav_zone_idx is None:
+                continue
+
+            y1 = zones[fav_zone_idx][0]
+            y2 = zones[fav_zone_idx][1]
+            card_hlines = hlines_by_vx[vx]
+
+            # Snap to nearest card hline per PRD Step 3.
+            # Upper: "向上最近的白底-灰底的中方差横线（要求另一端在发言人头像100 px附近）
+            #         或者 TOP_BAR_BOT"
+            upper = [h for h in card_hlines
+                     if TOP <= h[0] < y1 and h[2] < AR + XLIMIT]
+            exact_y1 = 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 < h[0] <= BOT]
+            exact_y2 = min(lower, key=lambda h: h[0])[0] if lower else BOT
+
+            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
+
+    return cards
+
+
+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)
+    if chat_img is not None and len(ordered) > 0:
+        try:
+            exact_cards = _compute_exact_card_bboxes(
+                ordered, chat_img, screen_w, screen_h,
+            )
+            if exact_cards:
+                return drop_top_clamped_false_positive_cards(
+                    exact_cards, scale_w=scale_w,
+                )
+        except Exception:
+            pass
+
+    # 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",
+    "PROCESSED_CARD_MATCH_MIN_OVERLAP_RATIO",
+    "REFERENCE_RESUME_CARD_TOP_GAP_BASELINE",
+    "FavoriteLabelHit",
+    "ThumbnailCard",
+    "TrackedCard",
+    "BubbleBbox",
+    "derive_cards",
+    "drop_top_clamped_false_positive_cards",
+    "bbox_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",
+]