Harden touch and scroll ownership for 0.1.0-alpha.1

Author: Cylop

.github/workflows/release.yml

@@ -19,4 +19,4 @@ jobs:
           registry-url: https://registry.npmjs.org
       - run: npm ci
       - run: npm run check
-      - run: npm publish
+      - run: npm publish --tag alpha --access public

CHANGELOG.md

@@ -4,14 +4,28 @@ All notable changes follow Keep a Changelog.
 
 ## [Unreleased]
 
+## [0.1.0-alpha.1] - 2026-09-06
+
+### Fixed
+
+- Correct directional touch-action to pan-down and preserve pinch zoom.
+- Add session-scoped touch compatibility handling with shared gesture mechanics.
+- Ignore bubbled child capture loss when capture transfers to Root.
+- Remove unintended root overflow and overscroll containment; preserve sticky and Window scrolling.
+- Resolve actual scrollability and nested gesture-origin consumers at gesture start and claim.
+- Keep explicit delayed refs unresolved until available.
+- Validate finite positive thresholds and scale small-threshold hysteresis.
+- Cap refresh hold by threshold and released distance.
+- Settle rejected/thrown application refreshes without logging consumer errors.
+- Protect editing controls; support data-pull-to-refresh-ignore surfaces.
+- Expand browser regressions, touch evidence, fixtures, architecture and physical-device QA documentation.
+
 ### Changed
 
 - Delayed pointer capture until downward intent and the scroll boundary are
   confirmed.
 - Added live pull metrics, lifecycle stress controls, browser guidance, and
   published-package integration proofs to the documentation site.
-- Preserved the upward touch-pan direction at the top boundary so scrollable
-  content can begin scrolling normally from its first row.
 - Documented explicit pointer ownership for Pull to Refresh inside a draggable
   bottom sheet.
 

README.md

@@ -5,6 +5,9 @@ Pull to refresh without owning your feed.
 A small, accessible pull-to-refresh primitive with scroll arbitration,
 resistance, and an async refresh lifecycle.
 
+Mobile pull-to-refresh depends on browser gesture ownership. See
+[Browser Behavior](docs/BROWSER_BEHAVIOR.md).
+
 ```bash
 npm install @nipe-solutions/react-pull-to-refresh
 ```
@@ -73,22 +76,16 @@ Available root variables:
 
 ## Scroll ownership
 
-The root resolves an explicit scroll container or the nearest ancestor with
-scrollable vertical overflow, then falls back to the window. A one-pixel
-tolerance includes fractional and negative WebKit offsets. Movement must clearly
-favor downward intent; horizontal and upward movement are rejected. Pointer
-capture begins only after intent is established and the boundary is rechecked.
-
-For page-level custom pull-to-refresh, browser-native refresh can still win.
-Choose document containment explicitly in your application when appropriate:
-
-```css
-html {
-  overscroll-behavior-y: contain;
-}
-```
+The root resolves an explicit owner or the nearest actually scrollable ancestor,
+then Window. It checks nested scrollers from the gesture origin and rechecks the
+boundary before claim. An explicit null ref stays unresolved until a subsequent
+gesture. Gestures starting below the top stay browser-owned for that stream.
 
-The library never modifies html or body styles.
+Core CSS does not set root overflow or overscroll policy. Apply optional
+`overscroll-behavior-y: contain` to your actual scroller. Chromium page-level
+containment may help suppress native refresh; it is not a universal guarantee.
+Page-level custom Pull to Refresh on iOS Safari is not a guaranteed configuration.
+Safari may retain native browser Pull-to-Refresh ownership.
 
 ## Accessibility
 
@@ -99,11 +96,10 @@ keyboard gesture, or focus movement.
 
 ## Browser notes
 
-- Chromium supports element overscroll containment and Pointer Events.
-- Firefox uses the same mechanics but presents overscroll differently.
-- Safari can report negative offsets while rubber-banding; real-device
-  validation remains required.
-- Desktop primary-button dragging exists for demos and tests.
+Directional-capable browsers use Pointer Events with `pan-x pan-down pinch-zoom`.
+Firefox/Safari use a session-scoped Touch Events compatibility adapter. Automated
+engine tests do not verify physical iOS or Android behavior. Mobile QA remains
+beta-blocking; use an application refresh button as the accessible alternative.
 
 See [browser behavior](docs/BROWSER_BEHAVIOR.md),
 [integrations](docs/INTEGRATIONS.md), and
@@ -125,7 +121,7 @@ npm run test:e2e
 Requires Node 24. React 18.3 and React 19 are peer-supported. Runtime
 dependencies are limited to React peers.
 
-Current status: 0.1.0-alpha.0. Automated checks do not replace the manual device
+Current status: 0.1.0-alpha.1. Automated checks do not replace the manual device
 matrix.
 
 Part of [NIPE Open Source](https://opensource.nipesolutions.com).

docs/API.md

@@ -14,13 +14,31 @@ if disabled changes while its promise is pending.
 
 onRefresh is invoked synchronously and exactly once on an armed release. A
 returned promise holds refreshing; void settles on the next microtask.
-Resolution and rejection both enter settling. Rejections are reported to the
-console so they are not silent; application error UI, retry, and cancellation
-remain outside the library.
+Resolution, rejection and synchronous throw all enter settling. The library
+does not log consumer errors, show error UI, retry, or cancel the application
+promise. Handle application errors in your refresh function. Unmount removes
+listeners and prevents UI updates from later promise completion.
 
 ## Motion
 
 Finger travel is direct until the threshold. Overshoot follows a sublinear
 power curve, remaining continuous and monotonic while adding resistance.
-Refreshing holds at 52 pixels. Settling uses a 220 ms ease-out and becomes
+Refreshing holds at the minimum of 52 pixels, the gesture threshold and the
+released distance; release never adds extra pull. The internal 52px hold is a
+presentation convention, so size indicator content accordingly. Settling uses a 220 ms ease-out and becomes
 effectively immediate under reduced motion.
+
+## Threshold and scroll container
+
+Threshold must be finite and greater than zero. Intent still requires six pixels
+of movement; armed hysteresis is min(6px, threshold × 0.25). Threshold is snapped
+at gesture start, so rerenders cannot change an active gesture.
+
+scrollContainer accepts an HTMLElement, Window, or element ref. A null explicit
+ref leaves the owner unresolved and PTR ineligible until a later gesture resolves
+it. Automatic detection requires actual vertical overflow and runs at gesture
+start. Nested scroll descendants participate in ownership even with an explicit
+outer owner. See [Browser Behavior](BROWSER_BEHAVIOR.md).
+
+Editing controls and contenteditable origins are ignored. Mark custom gesture
+surfaces with `data-pull-to-refresh-ignore` to opt out of initiation.

docs/ARCHITECTURE.md

@@ -0,0 +1,71 @@
+# Architecture and test boundaries
+
+```text
+Pointer adapter (directional touch, mouse, pen)
+Touch adapter (directional values unsupported)
+                    ↓
+start snapshot: origin, owner, adapter, coordinates, threshold
+                    ↓
+shared intent: 6px slop → axis/direction arbitration
+                    ↓
+recheck same owner + entire relevant top boundary chain
+                    ↓
+claim → shared resistance → pulling ⇄ armed
+                    ↓
+release once → application onRefresh → refreshing
+                    ↓
+resolve / reject / synchronous throw → settling → idle or disabled
+```
+
+Scroll ownership lives in `src/scroll-ownership.ts`. Root does not acquire
+scroll ownership by adding mechanical overflow. The root/ancestor owner is
+resolved at start; origin descendants are checked for competing scroll
+consumers. Invalid explicit refs remain unresolved. Browser-owned gestures are
+never resumed mid-stream.
+
+`src/mechanics.ts` owns intent, resistance, progress and hysteresis. Visual travel
+remains direct through the threshold and sublinear above it. Hysteresis is
+`min(6, threshold * 0.25)`; every finite positive threshold is valid. The 6px
+intent slop still applies even for threshold 4. Armed release holds at
+`min(52, session threshold, released distance)`. The internal 52px resting height
+is an indicator presentation convention, not a measured height or public prop.
+Applications should size their indicator for this hold; small thresholds imply
+smaller available space. Progress remains 1 during refreshing and returns to 0
+when settling begins, independent of promise success/failure.
+
+Session listeners are removed before release/abandonment; cleanup releases root
+capture only after clearing session state so capture-loss events cannot commit
+again. Touch fallback uses one non-passive root touchmove listener during a
+candidate only. Session-scoped window end/blur/additional-pointer detection handles
+abandonment outside the root. No idle RAF, document touchmove listener, generic
+gesture dependency, observer of content mutations, or application promise
+cancellation is introduced. React supplies its normal delegated start handlers.
+
+A disabled change cancels an uncommitted session. Committed work finishes, then
+settles to disabled. Unmount removes listeners; promise completion is ignored
+for UI updates. Application errors are consumed for lifecycle cleanup without
+console logging, retries, or a second error callback. Applications retain error
+UI and telemetry ownership.
+
+## Verification layers
+
+- Pure mechanics tests: intent, resistance, progress, threshold hysteresis.
+- React tests: adapter invariants, null refs, nesting, lifecycle, StrictMode,
+  cancellation, editing exclusions, ref/threshold rerenders and listener cleanup.
+- Browser tests: computed touch-action, actual overflow geometry, sticky headers,
+  Window/element scroll surfaces, dynamic auto ancestors, nesting, large lists,
+  console hygiene, and trusted Chromium CDP touch traces.
+- Synthetic DOM touch tests: exercise adapter integration in each engine. They
+  cannot prove native touch delivery or arbitration.
+- Physical-device QA: native overscroll/refresh, selection handles, zoom,
+  Safari/Firefox mobile fallback and actual browser chrome interactions.
+
+Directly invoking React handlers or `page.mouse` cannot establish mobile touch
+support. Beta requires meaningful physical iOS and Android evidence.
+
+Native listeners route through handlers published at React commit, so owner and
+refresh callback changes are observed without resubscribing active sessions.
+The threshold remains a gesture-start snapshot. The JS gzip budget is 3,200 B
+(previously 3,000 B), allowing the focused compatibility adapter and ownership
+checks; the measured baseline before hardening was 2,194 B. Runtime dependencies
+remain zero beyond React peers.