From ee4e06f948f091312db11ae4063a0bd8824f7bc2 Mon Sep 17 00:00:00 2001
From: Jonathan Kingston <jonathankingston@test-mac-box.localdomain>
Date: Sun, 29 Mar 2026 19:52:44 +0100
Subject: [PATCH] fix: improve mobile review card scrolling and swipe gestures

Keep the review page locked to the viewport, move long-form content scrolling into the card body, and make mobile swipe gestures hold onto horizontal intent even when a thumb path drifts vertically.

Made-with: Cursor
---
 team-ui/src/components/Layout.tsx     |  17 +-
 team-ui/src/components/ReviewCard.tsx |  33 +--
 team-ui/src/hooks/useCardDrag.ts      | 278 +++++++++++++++++++++++---
 team-ui/src/pages/ReviewPage.tsx      |  24 ++-
 4 files changed, 294 insertions(+), 58 deletions(-)

diff --git a/team-ui/src/components/Layout.tsx b/team-ui/src/components/Layout.tsx
index 9fa076a..e952a66 100644
--- a/team-ui/src/components/Layout.tsx
+++ b/team-ui/src/components/Layout.tsx
@@ -8,6 +8,7 @@ export function Layout() {
   const location = useLocation();
   const [pendingCount, setPendingCount] = useState(0);
   const onDashboard = location.pathname === "/dashboard";
+  const onReview = location.pathname === "/review";
 
   useEffect(() => {
     if (onDashboard) return;
@@ -41,8 +42,12 @@ export function Layout() {
   }
 
   return (
-    <div className="min-h-screen bg-gray-50 overflow-x-hidden">
-      <nav className="bg-white border-b border-gray-200">
+    <div
+      className={`bg-gray-50 overflow-x-hidden ${
+        onReview ? "flex h-dvh flex-col overflow-y-hidden" : "min-h-dvh"
+      }`}
+    >
+      <nav className="shrink-0 bg-white border-b border-gray-200">
         <div className="max-w-2xl mx-auto px-4 py-3 flex items-center justify-between">
           <div className="flex items-center gap-3 md:gap-6">
             <span className="text-lg font-bold text-indigo-600">cq</span>
@@ -60,7 +65,13 @@ export function Layout() {
           </div>
         </div>
       </nav>
-      <main className="max-w-2xl mx-auto py-8 px-4">
+      <main
+        className={`max-w-2xl mx-auto w-full px-4 ${
+          onReview
+            ? "flex flex-1 min-h-0 flex-col overflow-hidden py-4 md:py-8"
+            : "py-8"
+        }`}
+      >
         <Outlet context={{ setPendingCount }} />
       </main>
     </div>
diff --git a/team-ui/src/components/ReviewCard.tsx b/team-ui/src/components/ReviewCard.tsx
index e1e14b4..c274728 100644
--- a/team-ui/src/components/ReviewCard.tsx
+++ b/team-ui/src/components/ReviewCard.tsx
@@ -2,14 +2,14 @@ import { forwardRef } from "react";
 import type { KnowledgeUnit, Selection } from "../types";
 import { DomainTags } from "./DomainTags";
 import { timeAgo } from "../utils";
-import type { DragState, PointerHandlers } from "../hooks/useCardDrag";
+import type { DragState, GestureHandlers } from "../hooks/useCardDrag";
 import { FLY_OFF_MS, MAX_ROTATION_DEG, SNAP_BACK_MS } from "../hooks/useCardDrag";
 
 interface Props {
   unit: KnowledgeUnit;
   selection: Selection;
   drag: DragState;
-  pointerHandlers: PointerHandlers;
+  pointerHandlers: GestureHandlers;
 }
 
 const CARD_STYLES: Record<string, string> = {
@@ -54,33 +54,38 @@ export const ReviewCard = forwardRef<HTMLDivElement, Props>(
     return (
       <div
         ref={ref}
-        className={`relative z-0 border-2 rounded-lg p-6 max-w-xl mx-auto select-none touch-none ${cardStyle}`}
+        className={`relative z-0 mx-auto flex h-full max-h-full w-full max-w-xl select-none flex-col overflow-hidden rounded-lg border-2 p-4 touch-pan-y sm:p-6 ${cardStyle}`}
         style={{ transform, transition, boxShadow: shadow }}
         {...pointerHandlers}
       >
-        <div className="flex items-center justify-between mb-3">
+        <div className="mb-3 flex items-center justify-between">
           <DomainTags domains={unit.domain} variant={activeState} />
           <span className="text-xs text-gray-400">
             {timeAgo(unit.evidence.first_observed)}
           </span>
         </div>
 
-        <h2 className="text-lg font-semibold text-gray-900 mb-2">
+        <h2 className="mb-3 text-lg font-semibold text-gray-900">
           {unit.insight.summary}
         </h2>
 
-        <p className="text-gray-600 mb-3 leading-relaxed">
-          {unit.insight.detail}
-        </p>
+        <div
+          className="min-h-0 flex-1 overflow-y-auto overscroll-contain pr-1"
+          data-scroll-region="true"
+        >
+          <p className="mb-3 leading-relaxed text-gray-600">
+            {unit.insight.detail}
+          </p>
 
-        <div className={`border-l-3 rounded-r-lg px-4 py-3 mb-6 ${actionBoxStyle}`}>
-          <span className="text-xs font-semibold uppercase tracking-wide">
-            Action
-          </span>
-          <p className="text-gray-800 text-sm mt-1">{unit.insight.action}</p>
+          <div className={`mb-6 rounded-r-lg border-l-3 px-4 py-3 ${actionBoxStyle}`}>
+            <span className="text-xs font-semibold uppercase tracking-wide">
+              Action
+            </span>
+            <p className="mt-1 text-sm text-gray-800">{unit.insight.action}</p>
+          </div>
         </div>
 
-        <div className="flex gap-4 text-sm text-gray-500">
+        <div className="flex gap-4 pt-3 text-sm text-gray-500">
           <span>
             Confidence: <strong className={confidenceColor(unit.evidence.confidence)}>{unit.evidence.confidence.toFixed(2)}</strong>
           </span>
diff --git a/team-ui/src/hooks/useCardDrag.ts b/team-ui/src/hooks/useCardDrag.ts
index 727952d..687af13 100644
--- a/team-ui/src/hooks/useCardDrag.ts
+++ b/team-ui/src/hooks/useCardDrag.ts
@@ -8,6 +8,8 @@ export const BADGE_APPEAR_RATIO = 0.3;
 export const MAX_ROTATION_DEG = 3;
 export const SNAP_BACK_MS = 200;
 export const FLY_OFF_MS = 300;
+export const GESTURE_SLOP_PX = 10;
+export const AXIS_DOMINANCE_RATIO = 1.5;
 
 export interface DragOffset {
   x: number;
@@ -29,27 +31,69 @@ export interface PointerHandlers {
   onPointerCancel: (e: React.PointerEvent) => void;
 }
 
+export interface TouchHandlers {
+  onTouchStartCapture: (e: React.TouchEvent) => void;
+  onTouchMoveCapture: (e: React.TouchEvent) => void;
+  onTouchEndCapture: (e: React.TouchEvent) => void;
+  onTouchCancelCapture: (e: React.TouchEvent) => void;
+}
+
+export type GestureHandlers = PointerHandlers & TouchHandlers;
+
 export interface UseCardDragResult {
   drag: DragState;
-  handlers: PointerHandlers;
+  handlers: GestureHandlers;
   flyOff: (action: Exclude<Selection, null>) => Promise<void>;
   snapBack: () => void;
 }
 
+function startedInScrollRegion(target: EventTarget | null): boolean {
+  return target instanceof HTMLElement
+    ? target.closest("[data-scroll-region='true']") !== null
+    : false;
+}
+
 function inferAction(offset: DragOffset): Selection {
   const absX = Math.abs(offset.x);
   const absY = Math.abs(offset.y);
-  if (absX < 10 && absY < 10) return null;
+  if (absX < GESTURE_SLOP_PX && absY < GESTURE_SLOP_PX) return null;
   // Require clear dominant axis to avoid flicker on diagonal drags.
-  if (absX >= absY * 1.5) {
+  if (absX >= absY * AXIS_DOMINANCE_RATIO) {
     return offset.x > 0 ? "approve" : "reject";
   }
-  if (absY >= absX * 1.5) {
+  if (absY >= absX * AXIS_DOMINANCE_RATIO) {
     return "skip";
   }
   return null;
 }
 
+function constrainOffset(
+  offset: DragOffset,
+  action: Exclude<Selection, null>,
+): DragOffset {
+  return action === "skip"
+    ? { x: 0, y: offset.y }
+    : { x: offset.x, y: 0 };
+}
+
+function resetDragState(
+  setOffset: (offset: DragOffset) => void,
+  setDragProgress: (progress: number) => void,
+  setIsDragging: (dragging: boolean) => void,
+  startPos: React.RefObject<{ x: number; y: number } | null>,
+  pointerId: React.RefObject<number | null>,
+  dragStartTarget: React.RefObject<EventTarget | null>,
+  lockedAction: React.RefObject<Exclude<Selection, null> | null>,
+) {
+  startPos.current = null;
+  pointerId.current = null;
+  dragStartTarget.current = null;
+  lockedAction.current = null;
+  setIsDragging(false);
+  setOffset({ x: 0, y: 0 });
+  setDragProgress(0);
+}
+
 export function useCardDrag(
   cardRef: React.RefObject<HTMLDivElement | null>,
   onCommit: (action: Exclude<Selection, null>) => void,
@@ -65,6 +109,8 @@ export function useCardDrag(
 
   const startPos = useRef<{ x: number; y: number } | null>(null);
   const pointerId = useRef<number | null>(null);
+  const dragStartTarget = useRef<EventTarget | null>(null);
+  const lockedAction = useRef<Exclude<Selection, null> | null>(null);
 
   const getThresholds = useCallback(() => {
     const el = cardRef.current;
@@ -90,41 +136,91 @@ export function useCardDrag(
 
   const onPointerDown = useCallback((e: React.PointerEvent) => {
     if (flyingOffRef.current || disabled) return;
+    if (e.pointerType === "touch") return;
     pointerId.current = e.pointerId;
     startPos.current = { x: e.clientX, y: e.clientY };
-    setIsDragging(true);
-    (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
+    dragStartTarget.current = e.target;
+    lockedAction.current = null;
   }, [disabled]);
 
   const onPointerMove = useCallback(
     (e: React.PointerEvent) => {
+      if (e.pointerType === "touch") return;
       if (!startPos.current || e.pointerId !== pointerId.current) return;
       const dx = e.clientX - startPos.current.x;
       const dy = e.clientY - startPos.current.y;
       const off = { x: dx, y: dy };
-      setOffset(off);
-      setDragProgress(computeProgress(off));
+      const action = inferAction(off);
+
+      if (!isDragging) {
+        if (Math.abs(dx) < GESTURE_SLOP_PX && Math.abs(dy) < GESTURE_SLOP_PX) {
+          return;
+        }
+
+        // When a gesture starts inside the scrollable body, keep vertical motion
+        // reserved for native scrolling and only lock into card drag on a clear
+        // horizontal swipe.
+        if (startedInScrollRegion(dragStartTarget.current) && action === "skip") {
+          resetDragState(
+            setOffset,
+            setDragProgress,
+            setIsDragging,
+            startPos,
+            pointerId,
+            dragStartTarget,
+            lockedAction,
+          );
+          return;
+        }
+
+        if (!action) {
+          return;
+        }
+
+        lockedAction.current = action;
+        setIsDragging(true);
+        (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
+      }
+
+      const activeAction = lockedAction.current;
+      if (!activeAction) {
+        return;
+      }
+
+      const constrainedOffset = constrainOffset(off, activeAction);
+      setOffset(constrainedOffset);
+      setDragProgress(computeProgress(constrainedOffset));
     },
-    [computeProgress],
+    [computeProgress, isDragging],
   );
 
   const onPointerUp = useCallback(
     (e: React.PointerEvent) => {
+      if (e.pointerType === "touch") return;
       if (e.pointerId !== pointerId.current) return;
       if (!startPos.current) return;
-      const currentOffset = { x: e.clientX - startPos.current.x, y: e.clientY - startPos.current.y };
-      const action = inferAction(currentOffset);
-      const progress = computeProgress(currentOffset);
-
-      startPos.current = null;
-      pointerId.current = null;
-      setIsDragging(false);
+      const rawOffset = { x: e.clientX - startPos.current.x, y: e.clientY - startPos.current.y };
+      const action = lockedAction.current;
+      const currentOffset = action ? constrainOffset(rawOffset, action) : rawOffset;
+      const progress = action ? computeProgress(currentOffset) : 0;
 
       if (action && progress >= 1) {
+        startPos.current = null;
+        pointerId.current = null;
+        dragStartTarget.current = null;
+        lockedAction.current = null;
+        setIsDragging(false);
         onCommit(action);
       } else {
-        setOffset({ x: 0, y: 0 });
-        setDragProgress(0);
+        resetDragState(
+          setOffset,
+          setDragProgress,
+          setIsDragging,
+          startPos,
+          pointerId,
+          dragStartTarget,
+          lockedAction,
+        );
       }
     },
     [computeProgress, onCommit],
@@ -132,16 +228,125 @@ export function useCardDrag(
 
   const onPointerCancel = useCallback(
     (e: React.PointerEvent) => {
+      if (e.pointerType === "touch") return;
       if (e.pointerId !== pointerId.current) return;
-      startPos.current = null;
-      pointerId.current = null;
-      setIsDragging(false);
-      setOffset({ x: 0, y: 0 });
-      setDragProgress(0);
+      resetDragState(
+        setOffset,
+        setDragProgress,
+        setIsDragging,
+        startPos,
+        pointerId,
+        dragStartTarget,
+        lockedAction,
+      );
     },
     [],
   );
 
+  const onTouchStartCapture = useCallback((e: React.TouchEvent) => {
+    if (flyingOffRef.current || disabled) return;
+    const touch = e.touches[0];
+    if (!touch) return;
+    startPos.current = { x: touch.clientX, y: touch.clientY };
+    dragStartTarget.current = e.target;
+    lockedAction.current = null;
+  }, [disabled]);
+
+  const onTouchMoveCapture = useCallback(
+    (e: React.TouchEvent) => {
+      if (!startPos.current) return;
+      const touch = e.touches[0];
+      if (!touch) return;
+      const dx = touch.clientX - startPos.current.x;
+      const dy = touch.clientY - startPos.current.y;
+      const off = { x: dx, y: dy };
+      const action = inferAction(off);
+
+      if (!isDragging) {
+        if (Math.abs(dx) < GESTURE_SLOP_PX && Math.abs(dy) < GESTURE_SLOP_PX) {
+          return;
+        }
+
+        if (startedInScrollRegion(dragStartTarget.current) && action === "skip") {
+          startPos.current = null;
+          dragStartTarget.current = null;
+          lockedAction.current = null;
+          return;
+        }
+
+        if (!action) {
+          return;
+        }
+
+        lockedAction.current = action;
+        setIsDragging(true);
+      }
+
+      const activeAction = lockedAction.current;
+      if (!activeAction) {
+        return;
+      }
+
+      e.preventDefault();
+      const constrainedOffset = constrainOffset(off, activeAction);
+      setOffset(constrainedOffset);
+      setDragProgress(computeProgress(constrainedOffset));
+    },
+    [computeProgress, isDragging],
+  );
+
+  const onTouchEndCapture = useCallback(
+    (e: React.TouchEvent) => {
+      if (!startPos.current) {
+        dragStartTarget.current = null;
+        lockedAction.current = null;
+        return;
+      }
+
+      const touch = e.changedTouches[0];
+      const action = lockedAction.current;
+      const rawOffset = touch
+        ? {
+            x: touch.clientX - startPos.current.x,
+            y: touch.clientY - startPos.current.y,
+          }
+        : offset;
+      const currentOffset = action ? constrainOffset(rawOffset, action) : rawOffset;
+      const progress = action ? computeProgress(currentOffset) : 0;
+
+      if (action && progress >= 1) {
+        startPos.current = null;
+        dragStartTarget.current = null;
+        lockedAction.current = null;
+        setIsDragging(false);
+        onCommit(action);
+      } else {
+        resetDragState(
+          setOffset,
+          setDragProgress,
+          setIsDragging,
+          startPos,
+          pointerId,
+          dragStartTarget,
+          lockedAction,
+        );
+      }
+    },
+    [computeProgress, offset, onCommit],
+  );
+
+  const onTouchCancelCapture = useCallback(() => {
+    resetDragState(
+      setOffset,
+      setDragProgress,
+      setIsDragging,
+      startPos,
+      pointerId,
+      dragStartTarget,
+      lockedAction,
+    );
+  }, []);
+
   const flyOff = useCallback(
     async (action: Exclude<Selection, null>) => {
       flyingOffRef.current = true;
@@ -164,18 +369,31 @@ export function useCardDrag(
     if (pointerId.current !== null) {
       cardRef.current?.releasePointerCapture(pointerId.current);
     }
-    setOffset({ x: 0, y: 0 });
-    setDragProgress(0);
-    setIsDragging(false);
-    startPos.current = null;
-    pointerId.current = null;
+    resetDragState(
+      setOffset,
+      setDragProgress,
+      setIsDragging,
+      startPos,
+      pointerId,
+      dragStartTarget,
+      lockedAction,
+    );
   }, [cardRef]);
 
-  const dragAction = inferAction(offset);
+  const dragAction = lockedAction.current ?? inferAction(offset);
 
   return {
     drag: { offset, isDragging, isFlyingOff, dragAction, dragProgress },
-    handlers: { onPointerDown, onPointerMove, onPointerUp, onPointerCancel },
+    handlers: {
+      onPointerDown,
+      onPointerMove,
+      onPointerUp,
+      onPointerCancel,
+      onTouchStartCapture,
+      onTouchMoveCapture,
+      onTouchEndCapture,
+      onTouchCancelCapture,
+    },
     flyOff,
     snapBack,
   };
diff --git a/team-ui/src/pages/ReviewPage.tsx b/team-ui/src/pages/ReviewPage.tsx
index 0d517b7..b5d7656 100644
--- a/team-ui/src/pages/ReviewPage.tsx
+++ b/team-ui/src/pages/ReviewPage.tsx
@@ -137,7 +137,7 @@ export function ReviewPage() {
 
   if (loading) {
     return (
-      <div className="flex justify-center mt-16">
+      <div className="flex flex-1 items-center justify-center">
         <div className="h-8 w-8 animate-spin rounded-full border-4 border-indigo-500 border-t-transparent" />
       </div>
     );
@@ -183,22 +183,24 @@ export function ReviewPage() {
   }
 
   return (
-    <div>
+    <div className="flex h-full flex-col overflow-hidden">
       {conflictMessage && (
-        <p className="text-center text-amber-600 text-sm font-medium mb-3">
+        <p className="mb-3 text-center text-sm font-medium text-amber-600">
           {conflictMessage}
         </p>
       )}
 
       <DragIndicators drag={drag.drag} />
 
-      <ReviewCard
-        ref={cardRef}
-        unit={current.knowledge_unit}
-        selection={selection}
-        drag={drag.drag}
-        pointerHandlers={drag.handlers}
-      />
+      <div className="flex-1 min-h-0">
+        <ReviewCard
+          ref={cardRef}
+          unit={current.knowledge_unit}
+          selection={selection}
+          drag={drag.drag}
+          pointerHandlers={drag.handlers}
+        />
+      </div>
 
       <ReviewActions
         selection={selection}
@@ -208,7 +210,7 @@ export function ReviewPage() {
       />
 
       {error && (
-        <p className="text-center text-red-600 text-sm mt-3">{error}</p>
+        <p className="mt-3 text-center text-sm text-red-600">{error}</p>
       )}
     </div>
   );