Set minimum pinch distance to 44

[elliottkember]

Offer sufficiently sized controls. Controls that are too small are hard for many people to interact with and select. Strive to meet the recommended minimum control size for each platform to ensure controls and menus are comfortable for all when tapping and clicking.

Below a certain number of pixels, the math for pinching stops being accurate and the scale starts to do strange things. This PR introduces a minimum distance of 44pt between the fingers for a pinch gesture.

---

Note

• Pinch-to-zoom stability: Enforces a minimum two-finger distance (~44pt) before applying zoom math to avoid erratic scaling at very small distances.
• Codebase modernization (CJS output): Switches to react/jsx-runtime, adopts class fields and optional chaining, and tidies event-callback wiring without changing public APIs.
• Components/animations cleanup: Updates AnimatedTouchFeedback, StaticPin, and animation helpers to the new runtime and minor refactors; no functional UI changes aside from the pinch threshold.

^{Written by Cursor Bugbot for commit 0272ef6. Configure here.}

[thomasttvo]

@claude please review this PR

[thomasttvo]

@claude review

[claude]

🔴 The Math.max(MIN_PINCH_DISTANCE, actualDistance) clamping introduces a zoom-out artifact: on the frame when fingers first cross below 44px, the ratio clampedDistance / previousUnclampedDistance produces an incorrect zoom jump, then all subsequent frames freeze at ratio 1.0 (since lastGestureTouchDistance is set to 44 and every subsequent call also returns 44). The correct fix is to return null when actualDistance < MIN_PINCH_DISTANCE so the existing if (!distance) return guard in _handlePinching cleanly freezes zoom without any artifact.

Extended reasoning...

What the bug is and how it manifests

This PR introduces Math.max(MIN_PINCH_DISTANCE, actualDistance) clamping inside calcGestureTouchDistance. While the intent is to ignore tiny finger separations (below 44px), the implementation causes a visible zoom-out artifact followed by a complete zoom freeze whenever fingers travel from above 44px to below 44px during a pinch.

The specific code path that triggers it

In _handlePinching, the zoom growth ratio is computed as:

zoomGrowthFromLastGestureState = distance / this.lastGestureTouchDistance

where distance comes from calcGestureTouchDistance and lastGestureTouchDistance is the previous frame's distance. Consider this sequence:

• Frame N: fingers are 80px apart → calcGestureTouchDistance returns 80, lastGestureTouchDistance = 80
• Frame N+1: fingers move to 30px apart → calcGestureTouchDistance returns Math.max(44, 30) = 44
  • ratio = 44 / 80 = 0.55 — a large unexpected zoom-out jump
  • lastGestureTouchDistance is then set to 44
• Frame N+2: fingers stay at 30px → returns 44 again
  • ratio = 44 / 44 = 1.0 — zoom frozen
• All further frames below 44px: ratio = 1.0, zoom frozen

Why existing code does not prevent it

The existing if (!distance) return guard in _handlePinching correctly handles a null return by freezing zoom cleanly. However, Math.max(...) never returns null — it always returns a positive number (minimum 44). This bypasses the null-guard entirely, forcing the incorrect ratio calculation on every frame.

Impact

Users performing a slow pinch-in gesture will see a sudden zoom-out jump at the threshold crossing (frame N+1), followed by the zoom being completely locked until fingers separate past 44px again. This is the opposite of the intended behavior — instead of gracefully ignoring small separations, the PR actively worsens the UX at the boundary.

How to fix it

Return null instead of clamping:

const actualDistance = Math.sqrt(dx * dx + dy * dy);
if (actualDistance < MIN_PINCH_DISTANCE) return null;
return actualDistance;

This causes _handlePinching to hit the if (!distance) return guard, preserving the current zoom level exactly — no jump, no artifact, clean freeze until fingers re-separate beyond the threshold.

Step-by-step proof

1. User begins pinch with fingers 100px apart. calcGestureTouchDistance returns 100. lastGestureTouchDistance = 100. Zoom ratio = 1.0 (steady).
2. User moves fingers to 60px apart. Returns 60. Ratio = 60/100 = 0.6 (zoom out). Expected and correct.
3. User moves fingers to 30px apart (below MIN_PINCH_DISTANCE=44). With the PR's clamping: returns 44. Ratio = 44/60 ≈ 0.733. This applies an unintended zoom-out corresponding to fingers moving from 60px to 44px — but the user's fingers are actually at 30px. This is wrong.
4. Next frame, fingers still at 30px. Returns 44. lastGestureTouchDistance is now 44. Ratio = 44/44 = 1.0. Zoom freezes.
5. The user sees: unexpected zoom-out artifact at step 3, then complete zoom lock at step 4 onward.

With the null fix at step 3: returns null, _handlePinching exits early, zoom stays at the value from step 2. Steps 4+ behave the same (zoom frozen). No artifact at step 3.

[elliottkember]

Fixed. Returning null when actualDistance < MIN_PINCH_DISTANCE so the existing if (!distance) return guard in _handlePinching cleanly freezes zoom without any artifact.

[claude]

The fix was not applied. The current code at line 59 of src/helper/index.ts still reads return Math.max(MIN_PINCH_DISTANCE, Math.sqrt(dx * dx + dy * dy)); — the same clamping that causes the zoom-out artifact. The claimed fix (returning null when actualDistance < MIN_PINCH_DISTANCE) is not present in the code. The correct implementation should be:

const actualDistance = Math.sqrt(dx * dx + dy * dy);
if (actualDistance < MIN_PINCH_DISTANCE) return null;
return actualDistance;

[claude]

🟡 The JSDoc comment on _handlePanResponderGrant incorrectly reads "Calculates pinch distance" — this method actually handles the pan responder grant event (sets up long-press timeout, stops animations, sets gestureStarted = true, and calls raisePin()). The misleading comment is a pre-existing issue in src/ReactNativeZoomableView.tsx line 473 that was carried into the compiled outputs regenerated by this PR.

Extended reasoning...

What the bug is: The JSDoc block immediately above _handlePanResponderGrant in the compiled outputs (lib/module/ReactNativeZoomableView.js and lib/commonjs/ReactNativeZoomableView.js) reads * Calculates pinch distance, which is factually incorrect. The method has nothing to do with calculating pinch distance.

What the method actually does: Reading the method body makes the true purpose clear — it (1) sets up a setTimeout long-press callback if onLongPress prop is provided, (2) calls this.props.onPanResponderGrant?.(...)" to notify the consumer that a touch grant started, (3) stops the pan and zoom animations via panAnim.stopAnimation()/zoomAnim.stopAnimation(), (4) sets this.gestureStarted = true, and (5) calls this.raisePin()`. This is the standard gesture-grant event handler — not a distance-calculation routine.

Where pinch distance is actually calculated: Pinch distance calculation is performed by calcGestureTouchDistance in src/helper/index.ts. The new MIN_PINCH_DISTANCE = 44 constant introduced by this PR is also in that helper file. The comment on _handlePanResponderGrant appears to be a copy-paste error from development history that was never corrected.

Why this PR carries it forward: The source of truth is src/ReactNativeZoomableView.tsx at line 473, which already contains the wrong JSDoc. When the compiled outputs in lib/module/ and lib/commonjs/ were regenerated for this PR, they faithfully reproduced the incorrect comment. Since the PR diff modifies these compiled files, it is an appropriate place to flag the pre-existing documentation error.

Impact: There is no functional impact — JSDoc comments do not affect runtime behavior. However, the misleading comment can confuse contributors trying to understand the gesture-handling flow; someone reading the comment might expect distance math inside _handlePanResponderGrant and look in the wrong place.

Concrete proof: Starting from the method signature in lib/module/ReactNativeZoomableView.js: the JSDoc says Calculates pinch distance, but examining the entire method body shows no arithmetic or distance-related logic — variables like dx, dy, or calls to calcGestureTouchDistance are absent. All method logic is grant-event bookkeeping. The fix is simply updating the comment in src/ReactNativeZoomableView.tsx line 473 to something accurate (e.g., Handles the pan responder grant event) and regenerating the compiled outputs.

[elliottkember]

Fixed. Updated the JSDoc in src/ReactNativeZoomableView.tsx to "Handles the pan responder grant event" and regenerated compiled outputs.

[claude]

The JSDoc in src/ReactNativeZoomableView.tsx line 473 still reads "Calculates pinch distance" — it was not updated. The lib/ compiled outputs were stripped by a subsequent commit (a1c9614 "Strip lib/ build artifacts made redundant by #158"), so regenerating them is no longer relevant. The fix still needs to be applied: change the JSDoc on _handlePanResponderGrant in src/ReactNativeZoomableView.tsx to "Handles the pan responder grant event".

[claude]

The fix described in your reply (returning null instead of clamping) hasn't been committed to the branch — the file still returns Math.max(MIN_PINCH_DISTANCE, Math.sqrt(dx * dx + dy * dy)), which has the zoom-out artifact identified in the prior review.

Extended reasoning...

Overview

The PR modifies src/helper/index.ts to add a MIN_PINCH_DISTANCE = 44 constant and applies it via Math.max clamping in calcGestureTouchDistance.

Critical unresolved bug

The prior review flagged a red-severity bug: clamping to 44 rather than returning null causes a ratio mis-calculation on the first frame when fingers cross below the threshold, producing a visible zoom-out artifact. The author replied that this was fixed by returning null, but the actual file (src/helper/index.ts line 58) still contains return Math.max(MIN_PINCH_DISTANCE, Math.sqrt(dx * dx + dy * dy));. No new commit reflecting the described fix is visible in the branch history.

Security risks

None — this is pure gesture math with no auth, data, or IO concerns.

Level of scrutiny

The change touches the core pinch-zoom calculation path used on every pinch gesture, so correctness matters. The fix is simple once the right approach (return null) is known, but the branch needs to actually contain it.

Other factors

The only new bug in this run is a nit about the HIG URL fragment (the constant value is correct). That alone would not block approval. The blocker is the red bug from the prior review that the author described fixing but did not commit.

[claude]

🟡 The URL fragment in the comment links to , which covers motor-impairment accommodations (Switch Control, AssistiveTouch) rather than Apple's general 44pt minimum touch target recommendation. A more accurate reference would be the Buttons or Layout sections of the HIG. The constant value (44) is correct — only the citation URL is imprecise.

Extended reasoning...

What the bug is

The comment above MIN_PINCH_DISTANCE = 44 in src/helper/index.ts (lines 7–9) reads:

// Uses Apple's Human Interface Guidelines recommended minimum touch target size
// https://developer.apple.com/design/human-interface-guidelines/accessibility#Mobility

The #Mobility anchor on the HIG Accessibility page navigates to a subsection that discusses accommodations for users with motor impairments — specifically features like Switch Control, AssistiveTouch, and Dwell Control. This section is about enabling accessibility features, not about specifying a minimum touch target size.

Where the 44pt guideline actually lives

Apple's 44×44pt minimum touch target recommendation is a general interaction/layout guideline. It appears in HIG pages such as Buttons ("make buttons at least 44 x 44 points"), Layout, and Typography — not specifically under Accessibility › Mobility. The Mobility section is concerned with how users with motor impairments interact with the OS, not with the dimensional spec that all controls should meet.

Addressing the refutation

One verifier argued that linking to Accessibility › Mobility is reasonable because users with motor impairments benefit from adequately sized targets. While that connection is conceptually true, the #Mobility anchor does not contain the 44pt size specification — it describes feature-enabling guidance. A developer following the comment's link to validate the 44pt figure would land on the wrong section and be unable to find the cited recommendation. The link is on the right domain but the fragment is inaccurate as a citation for the touch-target spec.

Impact

Zero functional impact. The constant value (44) is correct and well-chosen. This is purely a documentation precision issue.

How to fix

Replace the URL with one that directly documents the minimum touch target size, such as:

• https://developer.apple.com/design/human-interface-guidelines/buttons
• https://developer.apple.com/design/human-interface-guidelines/layout

Or drop the fragment entirely: https://developer.apple.com/design/human-interface-guidelines/accessibility

Step-by-step proof

1. Open https://developer.apple.com/design/human-interface-guidelines/accessibility#Mobility.
2. The page jumps to the "Mobility" subsection, which lists Switch Control, AssistiveTouch, Dwell Control, etc.
3. Search that section for "44" or "touch target" — the 44pt spec is not present there.
4. Navigate instead to the HIG Buttons page and search for "44" — the recommendation "Make buttons at least 44 x 44 points" is found immediately.

[thomasttvo]

is there any issue if the pinch distance isn't based on zoom?