@onekeyfe/react-native-pager-view 6.7.0-2 → 6.7.0-21

package/docs/SPEC.md

@@ -14,17 +14,32 @@ valid prop values. Both the style and overlay are
 disabled by default. On iOS 26 or newer, a local overlay remains fixed at the
 top of the viewport while the owned vertical `UIScrollView` can draw behind it.
 The component measures the overlay's Fabric layout height and owns the
-corresponding top content inset. It binds UIKit's
+corresponding top content inset.
+For callers with a known initial height, `topOverlayHeightHint` reserves that
+height on the first frame after the overlay is enabled, before Fabric delivers
+`onLayout`. The measured height replaces the hint, and disabling the overlay
+clears the measurement so a later enablement can use a new hint. The hint does
+not enable the effect or reserve an inset without an active local overlay.
+This uses the existing native `topOverlayHeight` prop without changing the
+native interface. For native smooth local Hard mode, a complete Fabric mount
+attaches the overlay slot synchronously before `didMount` returns; incomplete
+slots retain the deferred fallback. It binds UIKit's
 `UIScrollEdgeElementContainerInteraction` to that exact scroll view and selects
 the requested top edge style. Hard has UIKit's dividing line; Soft has its
 gradual blurred transition. A pager owns the effect and inset for its current page;
 its nested NativeList or NativeScroller must not opt into another top overlay.
 Invisible, noninteractive native labels let UIKit recognize the React-drawn
 overlay and sticky header as scroll-edge elements. The pager does not add an
-auxiliary full-area glass or opaque material. It clips scrolling assets above
+auxiliary full-area glass. It clips scrolling assets above
 the fixed overlay boundary; during horizontal transitions it clips its owned
 visible page hosts below the current sticky boundary so text cannot pass in
 front of the fixed controls. Masked assets must not intercept their hit targets.
+On iOS 27 or newer, a local smooth Hard pager with a valid shared-header mask
+fades a bottommost overlay layer using the resolved opaque pager or ancestor
+theme color as the real header collapses, without hard-coded colors or changing
+UIKit's Hard style, owner or interactions. During temporary horizontal owner
+transitions the layer holds its last opacity until geometry is valid again;
+disabling the local overlay, changing style or recycling removes it.
 
 For an iOS 26 pager whose fixed header is rendered by a sibling in the same
 React surface, `externalTopOverlayTag` may identify that header's native view.
@@ -59,8 +74,10 @@ the shared host before their old scroll-edge interaction is released.
 The measured overlay height is excluded from the collapsible header distance:
 `header` remains collapsible and `stickyHeader` pins immediately below the
 overlay. Selection, cancellation, reuse and disposal rebind or release the
-interaction and restore any prior scroll-edge style. Native scroll/refresh
+interaction and restore any prior scroll-edge style. The existing owner-scoped native sticky-height callback also reaches NativeList hosts, so their React container slots clip below the same fixed viewport region and release it when the owner detaches. Native scroll/refresh
 coordination continues on the main thread without per-frame JavaScript work.
+Refresh retains the pager-owned `overlay + header + sticky` top inset but offsets
+the indicator by `header + sticky`, so its spinner begins below the fixed overlay.
 
 On iOS before 26, the external tag is not forwarded to native. On iOS before
 26, Android and Web the new props have no scroll-edge effect.
@@ -73,17 +90,15 @@ Acceptance requires real iOS 26 scrolling, partial collapse, short/empty page,
 refresh, page transition/cancellation, dynamic tabs and light/dark checks;
 source and build checks alone do not establish visual correctness.
 
-Experimental trial: `CollapsiblePagerView` paints a cover at each owned
+`CollapsiblePagerView` paints a cover at each owned
 fixed-overlay or pinned-sticky boundary with one physical pixel of the nearest
 opaque ancestor background color (system background if none is available).
 These native layers do not receive touches, change insets, or clip glass shadows.
 They are removed for Soft, disabled/detached effects, and recycling. This is a
-visual workaround using public layer APIs, not a UIKit separator setting; rendered
-light/dark, scrolling, and transition acceptance is pending. Standalone
+visual workaround using public layer APIs, not a UIKit separator setting. While
+the sticky header is pinned, only the top cover is hidden; it reappears on unpin,
+and the sticky cover and both Hard interactions remain active. Standalone
 NativeScroller and NativeList retain UIKit's unmodified Hard appearance.
-On the iOS 26.5 simulator, a runtime probe confirmed Hard and the cover layers,
-including pinned-header ownership. The original hairline was not reliably
-reproduced with the covers hidden, so separator suppression is not yet verified.
 
 Style selection crosses Fabric as the enum `none | hard | soft`, defaulting to
 `none`, rather than a hard-effect boolean. Switching Hard ↔ Soft on an attached
@@ -156,6 +171,24 @@ intent. Real vertical consumption, a newer valid command, or owner detachment
 releases the target. Existing NativeList and NativeScroller public coordinates
 are unchanged. The same page-top/sticky-top destinations are available without smooth-header mode.
 
+## Current-page partial header command
+
+`scrollHeaderBy(delta: number)` moves the current page's shared collapsible
+header from its displayed offset C to `clamp(C + delta, 0, D)`.
+`scrollHeaderToOffset(offset: number)` moves it to `clamp(offset, 0, D)`
+regardless of intervening native keyboard or user scrolling. D is the latest
+measured collapsible height. Inputs use logical points on iOS and Android and
+CSS pixels on Web. Non-finite values are ignored. The header and current body move immediately
+so a focused input becomes visible before the next keyboard frame. A valid command
+clears only the current page's body reading position B; it never changes
+another page's memory or adds permanent content/insets. It requires the same
+stable attached current owner as the page-top commands and is a safe no-op
+during horizontal transitions, before mount, or after disposal. A newer
+command or real user vertical consumption takes ownership from an older one.
+Dynamic header measurements clamp any in-flight target to the latest D.
+This command allows a focused input inside the shared header to move above a
+keyboard without replacing the pager's sole vertical scroll owner.
+
 ## Independent NativeScroller migration
 
 Status: implemented in source. Both native builds pass. Android focused emulator
@@ -318,6 +351,43 @@ warnings were observed. Keyboard, multi-touch, physical-device performance and
 the full lifecycle/interaction matrix remain unverified. These are local source
 builds; the currently installed npm version does not yet contain this migration.
 
+## Android removal-transition geometry retention
+
+Status: implemented locally; unreleased. On the Android UI thread, during a
+screen removal transition,
+NativeList and CollapsiblePager layout entry points respect the RecyclerView
+suppression state established by the screen-transition owner. The owner restores
+the original state when its last transition ownership ends. In addition,
+`CollapsiblePagerHost` disables `DefaultItemAnimator` on its internal
+`ViewPager2` `RecyclerView` (`itemAnimator = null`) and skips pre-draw
+(`layoutPagerIfRequested`) and host-driven `ViewPager2` layout passes when all
+React page children have been removed from the adapter (`adapter.itemCount == 0`)
+while previously rendered page `ViewHolder` views remain attached
+(`attachedPageCount() > 0`), matching `PagerViewViewManagerImpl`'s unmount
+guard. Initial empty measurement before any page is attached
+(`attachedPageCount() == 0`) and subsequent page insertions (`adapter.itemCount > 0`)
+still measure and lay out normally. This prevents unmount-time empty-adapter
+layout passes from clearing visible exit frames or recycling attached
+`ViewHolder` views held in `mDisappearingChildren` by `ViewGroup.startViewTransition`.
+This adds no public API and does not change Web or iOS behavior.
+
+If Fabric removes the current NativeScroller React child while its origin-frame
+transition remains active, Android retains the already displayed native extent
+for drawing. The current child and raw content dimensions still clear normally;
+only native content measurement and layout use the retained effective extent.
+The matching transition end or detach clears the private child and extent state
+idempotently. Adding a new child cancels prior retention, and a late end for the
+old child cannot alter the new content. Ordinary removal, size events and scroll
+commands keep their existing semantics.
+
+Local arm64 DevShell acceptance covered Base, CXO and Overview exit content,
+normal scrolling, RecyclerView ownership and suppression cleanup for the
+observed CXO exit, and NativeScroller raw-zero content dimensions with a
+nonzero displayed origin followed by detach cleanup. Nested-owner and cancel
+paths, Overview rebound/cancel, natural resize and new-child runtime cases,
+and the full performance matrix remain unverified. SDK publication and
+consumer version alignment are separate steps.
+
 ## iOS vertical-scroll press cancellation
 
 Status: implemented in source. A source-identical `node_modules` build was
@@ -363,7 +433,11 @@ content, the shared header, and touches beginning on an inner horizontal banner.
 Normal taps MUST remain functional. Press-retention behavior in application
 controls belongs to the consuming responder implementation; the Pager package
 does not contain or publish Tamagui helpers. The native application tab bar has
-a separate contract in react-native-tab-view/docs/SPEC.md.
+a separate contract in react-native-bottom-tabs/docs/SPEC.md.
+
+On Android, smooth-touch coordination and nested interception share the same
+native-gesture state. Once either path starts the gesture, later MOVE events
+MUST NOT start it again before its end or cancellation clears that state.
 
 The current native implementation confirms horizontal intent after at least
 32 points on iOS or 32 dp on Android, with horizontal displacement exceeding
@@ -437,6 +511,40 @@ The attached UIKit regression intentionally constrains the real pager pan to two
 required touches to prove the no-pan path; it is distinct from natural Home OS
 input, coalesced-event delivery, and physical-device acceptance.
 
+## Native segmented tab bar
+
+Status: implemented locally. Focused production-class iOS XCTest and Android
+instrumentation checks pass; consuming App interaction acceptance is separate.
+`nativeTabBar.style.variant` accepts `"underline"` (the default) or
+`"segmented"` on iOS and Android. The optional
+`nativeTabBar.style.contentPaddingVertical` is a nonnegative logical inset,
+defaulting to zero. Omitting both fields preserves the existing content-width,
+horizontally scrollable underline bar. Web ignores `nativeTabBar` and retains
+its caller-rendered sticky header.
+
+In segmented mode, the existing `height` is the entire tab slot. The track
+fills the space inside `contentPaddingHorizontal` and
+`contentPaddingVertical`, uses `backgroundColor`, and has a fully rounded
+outline. Its visible items divide the track into equal-width segments in their
+current order, including after item insertion, removal, relabeling, or resize.
+The thumb uses `indicatorColor`, is inset two logical points from its segment,
+and is fully rounded. Segment titles use the existing font and active/inactive
+text colors, remain single-line with truncation, and retain their existing
+accessibility labels, test IDs, and native press event keys. The segmented bar
+does not scroll horizontally; `itemSpacing`, `indicatorHeight`, and
+`indicatorBottom` apply only to underline mode. The pager's native fractional
+page progress moves the thumb continuously between equal-width segments and
+interpolates text emphasis without per-frame JavaScript updates. It settles at
+the actual selected page after a completed or cancelled gesture. RTL reverses
+physical segment order without changing logical page keys or indices.
+
+Switching variants or removing the native tab bar clears the previous visual
+state. The existing native press command, page callbacks, retention, vertical
+header geometry, and Web behavior remain unchanged. Acceptance requires
+focused native geometry/progress/press checks on iOS and Android, including
+two or three segments, dynamic labels/items, RTL, narrow widths, and variant
+switching. Type forwarding alone does not prove rendered behavior.
+
 ## Native tab-press animation default
 
 Behavior change: previously an omitted `nativeTabPressAnimationEnabled` animated
@@ -457,6 +565,28 @@ Status: implemented; focused native-wrapper tests cover both directions,
 explicit overrides and in-flight/superseded command targets. Home applies this policy to its JS tab bar, with iOS and
 Android simulator recordings verifying distant jumps and adjacent transitions.
 
+## Native tab trailing control reservation
+
+Status: implemented locally, unreleased. The focused Android host test passed
+(1/1); iOS hit tests had 8 passes and 1 existing skip. iOS companion-app UI
+acceptance remains unverified.
+`nativeTabBar.style.trailingReservedWidth` is an optional logical trailing
+reservation for a sibling React control in the full-width sticky header. It
+defaults to zero. JavaScript normalizes non-finite or negative input to zero;
+native also clamps the reservation to the actual tab viewport width. On Android
+and iOS, only the native tab viewport shrinks from `W` to `W - R`: its frame
+begins at zero in LTR and at `R` in RTL. The sticky React header, its height,
+and page content keep their original full-width geometry. Touches in the
+reserved region reach the sibling control, while native tab hit testing and
+last-tab visibility use the reduced viewport. Changing the reservation updates
+that viewport; removing it or recycling the pager restores the default zero.
+Web does not render the native tab and ignores this style field. For a positive
+reservation, the box-none sticky React control draws above the native tab so
+its inward fade and toolbar hit area remain visible; zero preserves the old
+native-tab foreground order. Acceptance requires focused native layout and hit
+testing for zero, nonzero, reset, and RTL reservations; type forwarding alone
+is insufficient.
+
 ## Android refresh foreground coordination
 
 Status: implemented; Android Home simulator placement verified on 2026-09-28.
@@ -802,6 +932,64 @@ fallback debounce, including replacement-state restoration. Other collection
 fallbacks keep that safety delay. Caller insets and retained logical offsets
 remain governed by the existing restoration policy.
 
+A verified, mounted NativeList with usable vertical bounds is a scroll-owner
+boundary. Its React container slots may contain independent Fabric scroll views,
+NativeScroller views or nested pagers; those descendants MUST NOT replace that
+NativeList as the enclosing page's owner or receive its shared header. Candidate
+priority between sibling page owners remains unchanged, including an explicit
+NativeScroller sibling. Pages without an enclosing NativeList retain nested-pager
+active-owner delegation. This boundary does not change scroll offsets, insets,
+shared-header collapse or per-page body memory.
+
+Status: implemented and verified by production-native UIKit regressions on
+iOS 27.1 for footer insertion, explicit-sibling priority and nested-pager
+delegation. Full App and physical-device visual acceptance are reported separately.
+
+When the active scroll owner is removed before its replacement becomes usable,
+the pager MUST retain bounded recovery (at most 12 retries per recovery round,
+spaced 100 ms apart). Clearing the completed mount's reattachment flag MUST NOT
+cancel that recovery. A replacement that becomes usable during that round,
+without another Fabric insertion, MUST receive the observer, shared headers,
+insets and retained collapse state. Page selection changes and recycling
+invalidate stale retry callbacks. Repeated mount attempts MUST NOT reset the
+retry budget. Once all 12 retries have been scheduled, an Insert whose parent is
+in the current page subtree MUST reopen recovery if that page retains a released
+scroll owner, including when the final retry callback is still pending. Reopening
+invalidates the old callback before clearing its scheduled state. The Insert
+MUST be recorded during a horizontal drag or transition, while observer and shared
+header attachment remain deferred until selection settles. Cancelling the drag
+on the same page MUST retain the reopened recovery round. Empty transactions,
+removals and inserts outside the current page MUST NOT reopen the budget. Owned
+`NativeScroller` and `NativeList` hosts additionally emit push readiness
+notifications when their scroll views attach and obtain positive bounds so late
+replacements recover immediately even without another Fabric insertion or after
+the retry budget expires; static pages with neither an unready scroll host nor a
+released scroll owner do not schedule retry timers.
+
+Status of transition-time and pending-final-retry recovery: implemented and
+UIKit regression verified on iOS 26.5 (2026-10-27). Both new regressions fail
+before the fix and pass afterward. Cancellation settles on the source page
+before the replacement becomes usable; the pending-final-retry case makes the
+replacement usable after the old timer's deadline. Observer and shared header
+ownership stay detached during the drag, then recover with the retained collapse.
+The full Pager suite executes 85 tests, with one iOS-27-only skip and no failures.
+
+Status of exhausted-budget recovery: implemented and UIKit regression verified
+on iOS 26.5 (2026-10-27). The regression exhausts the initial round, checks that
+empty transactions, removals and offscreen inserts do not reopen it, then inserts
+a current-page replacement whose scroller appears after did-mount. It fails
+before the fix and passes afterward, including preservation of an active round
+and restoration of the observer, shared headers and retained collapse. The full
+Pager suite executes 83 tests, with one iOS-27-only skip and no failures.
+
+Status of replacement recovery: implemented and runtime verified on iOS 26.5
+(2026-10-23). The late-replacement UIKit regression fails before the fix and
+passes afterward; the full Pager suite executes 82 tests, with one iOS-27-only
+skip and no failures. In the consuming app based on x at b0789571d8 with SDK
+6.7.0-9 and this local native change, two empty Favorites-to-Wallet-add-to-Market
+cycles and a Trending/Favorites round trip keep the first row aligned with the
+sticky header. The previously observed 212-point gap is absent.
+
 This is a UI-thread, main-runtime native coordination change with no new props,
 events, background-runtime work, persistence or retained strong view cache.
 Android already prepares discovered scroll children before draw and is unchanged;
@@ -841,3 +1029,62 @@ The native Home Spotlight adapter consumes this snapshot in the main UI runtime
 Removing a page or clearing the page collection MUST cancel the active horizontal transition and its temporary display snapshots before notifying the adapter. Cancellation MUST NOT rewrite the shared Header collapse or surviving pages' saved body reading memory. The previous observed owner MUST be detached without committing an offset under a shifted page key.
 
 An empty adapter MUST reject transition starts and transition completion without coercing an index into an empty range. The selected index uses zero as an empty-state sentinel; nonempty mutations clamp it to the remaining valid range. Readding pages MUST allow a fresh selection and MUST NOT resume a removed transition source. Conformance requires actual Android active-transition → zero-pages → readd/selection regression and remaining-page mutation checks; structural checks and compilation alone do not establish runtime behavior.
+
+
+## Web parent-scroll owner identity
+
+Web Header and sticky overlays use the named scroll timeline only when the
+browser supports every CSS property needed for that linkage. Otherwise, the
+active scroll owner's offset drives the same clamped Header collapse in JS:
+`C = min(max(scrollTop, 0), max(headerHeight, 0))`. The fallback keeps the
+existing page owner, insets, body offset memory, and sticky anchor. It updates
+when scrolling, selecting or restoring a page, replacing an owner, or changing
+Header height, and releases its listener when that owner detaches. An inactive
+page cannot move the visible Header. This is a Web-only compatibility path; no
+native behavior or public prop changes.
+When an overlay forwards a vertical wheel or touch scroll to the active owner,
+the owner receives the same internal user-input notification used by route
+restoration to cancel an obsolete pending offset.
+
+On Web, an explicitly marked NativeScroller is selected before an implicit NativeList viewport. There is one vertical owner per page; callers using parent-owned NativeList pass that same scroll element as webScrollHost.
+
+The existing NativeScroller pagerScrollKey identifies a Web page scroll owner. Changing the key invalidates that page body offset without remounting its React business content. The active owner also resets the shared header collapse and cancels queued old restore/top commands. Inactive owners invalidate their saved body offset without imperative scrolling; selection checks the current identity before restoring. A→B→A identity changes never revive a prior owner offset. Stable keys preserve ordinary page C+B restoration. Current-page top commands continue to affect only the selected page.
+
+Identity notifications and DOM owner listeners are internal implementation details, removed when the pager root or owner is replaced/unmounted. No native behavior or public configuration is added.
+
+### Web overlay input and keyed-page updates
+
+- Header and sticky slots remain overlays: overflow outside the sticky slot may remain visible without adding its portal height to page insets twice.
+- Vertical wheel or touch input over those overlays transfers only to the active page scroll owner when no nested scrollable consumes it. Horizontal controls, editable inputs, and ordinary button/tap behavior retain their own events. Input originating inside the page owner follows native scrolling once.
+- Reordering or removing keyed pages must save the previously configured key and owner, rather than resolving the old selected index against new children. Caller index synchronization preserves keyed body offsets and shared header collapse.
+- For an explicit NativeScroller, Pager chrome insets apply to the existing ScrollView content element, not its viewport. Insets taller than the available window cannot enlarge the scroll viewport. Existing owner/content padding is preserved and restored separately from Pager insets; direct NativeList/page-host fallback retains its prior layout path.
+- The Pager root clips without becoming a programmatically scrollable overflow box. Browser focus and descendant scrollIntoView cannot add a second horizontal page offset outside the selected-page transform.
+
+## Web page geometry and route restoration
+
+Status: Implemented in Web source and focused tests; browser and native runtime acceptance remain separate.
+
+`WebCollapsiblePagerView` is the existing Web `CollapsiblePagerView` class under an explicit root export. Its `isActive` prop defaults to true and represents route visibility, independently of the selected page. The Web-only `useWebCollapsiblePagerPage()` hook returns null outside a Web pager and otherwise exposes `isFocused`, `isRouteActive`, `owner`, `content`, optional `contentHeight`, `width`, `height`, content-relative `scrollTop`, `registerContent`, and read-only `pendingRouteScrollTop`. Native `CollapsiblePagerView`, its bridge, and its props are unchanged. The Web component rejects mounting without a DOM; importing the root or Web module alone must not access DOM globals.
+
+Web callers may supply finite nonnegative `headerHeight` and `stickyHeaderHeight`. When omitted or invalid (negative, NaN, or infinite), the SDK measures the natural inner Header and sticky content with `ResizeObserver`; explicit valid values take precedence, including zero. An initial unmeasured zero is not ready for route restoration; a measured empty chrome element may legitimately have zero height. Measurement must not use the constrained slot height as its own input. Height changes update the owned insets before route restoration. Existing explicit-height callers retain their layout path.
+
+Each page has one SDK-discovered vertical owner: explicit `NativeScroller`, then implicit NativeList viewport, then page host. Registration accepts a connected content element and optional finite nonnegative explicit height; invalid height metadata is ignored. It does not change DOM layout or make a pending target reachable. A later registration of the same element supersedes an earlier one, and stale cleanup cannot remove it. An explicit-height change schedules geometry measurement even if the element border box is unchanged. Metrics use owner client width; `pinnedBottom = ownerRect.top + max(0, headerHeight - owner.scrollTop) + stickyHeaderHeight`; `visibleTop = max(ownerRect.top, pinnedBottom, contentRect.top if present)`; visible height is `max(0, ownerRect.bottom - visibleTop)` and content-relative scroll top is `max(0, pinnedBottom - contentRect.top)`. Unregistered content falls back to the first owner child. Detached content and callbacks from old owners are ignored. One animation-frame measurement per page coalesces scroll, resize, registration, owner configuration, and active-page changes. Disposal releases observers, listeners, frames, and subscriptions.
+
+On active-to-inactive transition, the Web pager freezes the selected logical React page key, `pagerScrollKey` identity, actual owner generation, and last valid raw DOM top. Inactive scroll/geometry changes cannot replace the snapshot. A second blur of the same pending identity preserves the original target. On focus, owner, content, chrome, or inset changes, the pager retries without a timer only when the route is active, that exact key/identity/owner remains selected and connected, the viewport has positive height, the pager has configured the expected insets, and real `scrollHeight - clientHeight` reaches the target. Short content keeps the target pending. Restoration clears pending before one instant scroll and synchronizes the existing shared Header C and per-page body B memory. An idempotent Web `restoreScrollPosition()` returns false while inactive or not ready and true when no target remains or it applies; normal callers need no polling.
+
+Valid vertical wheel, scroll keys, scrollbar drag, overlay-forwarded input, accepted NativeList commands, and explicit page-top/sticky-top commands cancel pending route intent through the existing SDK takeover path. As in the prior Web app adapter, any owner `pointerdown` or `touchstart`, including a child target, cancels only route pending; this does not newly commit or clear SDK C+B memory. Geometry-only scroll/resize/scrollend cannot cancel intent. Valid same-offset commands cancel it; invalid or stale commands do not. A matching route target takes priority over automatic tab C+B restoration. Selection of a different key, owner identity reset (including A→B→A), genuine DOM owner replacement, or removal cancels pending; a same-key index reorder preserves it. A same-commit blur and Activity/Offscreen effect disconnect captures the current route target before releasing the owner; repeated disconnects preserve an existing pending target. A temporary React ref null or Activity/Offscreen effect disconnect followed by the identical connected owner preserves the logical route target and owner generation while releasing all observers, listeners, frames, and DOM configuration during disconnect. Restoration is unavailable while disconnected; reconnect remeasures automatic chrome before applying pending. A truly removed pager instance cannot transfer its pending target to a new instance. Older queued tab/top callbacks must validate generation before writing after route restoration or cancellation. The app owns navigation focus and business tab names; the SDK never infers them from escaped React child keys.
+
+Platform matrix: Web owns this DOM geometry, registration, route pending, and explicit Web export. iOS and Android keep native scrolling, restoration, and page coordination documented above, with no new prop, native bridge call, JS heap sharing, or process resource. The UI main runtime owns Web state; background runtimes do not deserialize it. Source/type tests establish only Web contract implementation, not browser rendering or native device behavior. Acceptance requires real Web/Desktop route blur, short content then growth, user takeover, dynamic chrome, key reset, and Home/Market scroll regressions.
+
+## Native package entry isolation
+
+The Native package entry exports the existing Native PagerView,
+CollapsiblePagerView, NativeScroller, usePagerView and ScrollEdgeEffect APIs.
+Native package resolution MUST NOT evaluate the Web pager or Web page-context
+modules. The react-native field and conditional export resolve to a real Native
+entry; the browser entry retains the Web runtime APIs. The generic declaration
+entry preserves the existing shared Web value/type API for TypeScript callers.
+This separates package initialization in the Native UI main runtime; it does not
+add a bridge, share JS heaps with background, or change Native scroll commands.
+Acceptance includes the actual Native dependency graph and unchanged startup
+budgets, Web runtime/type exports, and package source/module/declaration entries.