react-native-reserved-regions 0.1.0-alpha.0 → 0.1.0-alpha.3

package/README.md

@@ -5,15 +5,18 @@ Provider-scoped display divisions and occlusions for React Native's New Architec
 ## Requirements
 
 - React Native New Architecture (Fabric)
-- iOS 27.1 for UIKit reserved regions; earlier iOS versions report an empty list
+- iOS 27.1 SDK and runtime for UIKit reserved regions; older SDKs compile out observation and older runtimes report an empty list
 - Android 7.0 (API 24) or newer; folding features require a device supported by Jetpack WindowManager
 
 The example app uses React Native 0.88.0-rc.1.
+Its iOS target adopts `UISceneDelegate` because the RC template currently crashes on iOS 27 without it ([React Native issue #58606](https://github.com/react/react-native/issues/58606)).
 
 ## Installation
 
+`0.1.0-alpha.3` is an alpha release; its API may still change.
+
 ```sh
-npm install react-native-reserved-regions
+npm install react-native-reserved-regions@0.1.0-alpha.3
 ```
 
 On iOS, install pods in your app's `ios` directory. Android links automatically through React Native autolinking.
@@ -21,13 +24,12 @@ On iOS, install pods in your app's `ios` directory. Android links automatically
 ## Usage
 
 ```tsx
-import {
-  ReservedRegionsProvider,
-  useReservedRegions,
-} from 'react-native-reserved-regions';
+import { ReservedRegionsProvider, useReservedRegions, useReservedRegionsReady } from 'react-native-reserved-regions';
 
 function Screen() {
   const regions = useReservedRegions();
+  const isReady = useReservedRegionsReady();
+  if (!isReady) return null;
   return regions.map((region, index) => {
     if (region.kind === 'division') {
       console.log(region.frame, region.occludesContent);
@@ -47,7 +49,7 @@ export default function App() {
 }
 ```
 
-`useReservedRegions()` returns an empty array until the native view reports its first layout and when no active regions overlap the provider. It must be called beneath a `ReservedRegionsProvider`. Each region's `frame` uses logical points relative to that provider's top-left corner. A nested provider establishes its own coordinate space. The provider accepts standard React Native `View` props and should cover the content whose reserved regions you want to inspect.
+`useReservedRegions()` always returns an array, initially `[]`. `useReservedRegionsReady()` is initially `false` and becomes `true` with the first measurement, including an empty result. It stays true for that provider’s lifetime. Unsupported platforms report a known empty result; readiness does not indicate hardware support or guarantee first-frame timing. Both hooks must be called beneath a `ReservedRegionsProvider`. Each region's `frame` uses logical points relative to that provider's top-left corner. A nested provider establishes its own coordinate space. The provider accepts standard React Native `View` props and should cover the content whose reserved regions you want to inspect.
 
 The public type is a tagged union:
 
@@ -66,24 +68,69 @@ type ReservedRegion =
 
 A division splits the available display. `occludesContent` tells you whether content under that division is hidden. An occlusion is an area where content is hidden. On iOS, division regions currently report `occludesContent: false`. The TypeScript declarations in `src/index.tsx` document every field.
 
+## Why a provider and a hook?
+
+A reserved region needs a coordinate space: the same fold has different local
+coordinates in a full-screen view and an inset panel. `ReservedRegionsProvider`
+renders the native view that defines those bounds and shares its measurements
+with descendants. `useReservedRegions()` reads the nearest provider, so several
+consumers can use the same measurements without each adding a native view. Place
+a provider around each area that needs its own coordinate space; it can replace
+an existing container `View`.
+
+[react-native-hinges](https://appandflow.github.io/react-native-hinges/docs/usage)
+exposes a hook without a provider because posture and angle do not depend on a
+child view's position or size. It observes the existing React root's hierarchy/window.
+Use both libraries when layout and animation need those separate inputs.
+
 ## Native sources
 
-- iOS queries UIKit's active `UIView` reserved division and occlusion regions on the provider view. The selectors are resolved at runtime so the library can compile with an SDK older than iOS 27.1. [Apple's reserved regions overview](https://developer.apple.com/videos/play/tech-talks/111463/)
+- iOS queries UIKit's active `UIView` reserved division and occlusion regions on the provider view. Typed UIKit calls are guarded by the SDK version and runtime availability. Building with an SDK older than iOS 27.1 compiles out this feature. [Apple's reserved regions overview](https://developer.apple.com/videos/play/tech-talks/111463/)
 - Android observes Jetpack WindowManager `FoldingFeature` values and Android display cutout rectangles. A separating or fully occluding fold becomes a division; `OcclusionType.FULL` sets `occludesContent` to `true`. Display cutouts become occlusions. [FoldingFeature reference](https://developer.android.com/reference/androidx/window/layout/FoldingFeature), [WindowInsets reference](https://developer.android.com/reference/android/view/WindowInsets)
 
 The library reports geometry and does not reposition content. Normal safe area insets, system bars, and keyboard insets remain separate concerns.
 
+## Measurement timing
+
+Native events request synchronous delivery. Android measures after Fabric mounting
+and also observes pre-draw changes. The iOS example tests same-frame delivery with
+an [upstream React Native event-beat patch](docs/workflow.md#react-native-event-beat-test-patch).
+That example patch is not installed into consuming apps. Readiness indicates a
+completed measurement, not a universal first-frame guarantee.
+
+### Readiness-gated animated content
+
+On the tested RN `0.88.0-rc.1` Android stack, conditionally mounting Reanimated
+`4.7.0` content when `useReservedRegionsReady()` becomes true can throw
+`__requestMapperRunFinalizer` is undefined: Worklets `0.13.0` can run synchronous
+UI work ahead of queued mapper initialization. The combined hinges example uses
+an [example-only Worklets FIFO patch](https://github.com/appandflow/react-native-hinges/blob/main/patches/react-native-worklets%400.13.0.patch).
+Installing either library does not patch a consuming app's Worklets dependency.
+Keeping the animated subtree mounted avoided this failure in the tested case;
+apps that gate its mount need to apply the patch, rebuild the native app, and
+validate it themselves.
+
+The [performance guide](https://appandflow.github.io/react-native-reserved-regions/docs/performance)
+explains provider placement and optional readiness gating. `ReservedRegionsGate`
+is included starting with `0.1.0-alpha.3`.
+
 ## Development
 
 ```sh
-yarn install
-yarn typecheck
-yarn lint
-yarn test --watch=false
-yarn prepare
+pnpm install --frozen-lockfile
+pnpm run format:check
+pnpm run lint
+pnpm run typecheck
+pnpm test
+pnpm run build
+pnpm run docs:build
 ```
 
-To run the example, use `yarn example start`, then `yarn example ios` or `yarn example android`.
+The example includes full-screen, inset and content-box providers with
+`react-native-safe-area-context` values and overlays for comparison.
+See [the development workflow](docs/workflow.md) for native runs,
+[the docs website](website/README.md) for local previews, and
+[the release process](RELEASE.md) for publishing.
 
 ## License
 

package/android/build.gradle

@@ -36,7 +36,7 @@ if (project.extensions.findByName("kotlin") == null) {
 apply plugin: "com.facebook.react"
 
 android {
-  namespace "com.reservedregions"
+  namespace "com.appandflow.reservedregions"
 
   compileSdkVersion getExtOrDefault("compileSdkVersion")
 

package/android/src/main/java/com/{reservedregions → appandflow/reservedregions}/RegionsChangeEvent.kt

@@ -1,4 +1,4 @@
-package com.reservedregions
+package com.appandflow.reservedregions
 
 import com.facebook.react.bridge.Arguments
 import com.facebook.react.bridge.WritableMap
@@ -12,6 +12,8 @@ internal class RegionsChangeEvent(
 ) : Event<RegionsChangeEvent>(surfaceId, viewTag) {
   override fun getEventName() = NAME
 
+  override fun experimental_isSynchronous() = true
+
   override fun getEventData(): WritableMap {
     val payload = Arguments.createMap()
     val regionArray = Arguments.createArray()

package/android/src/main/java/com/{reservedregions → appandflow/reservedregions}/ReservedRegion.kt

@@ -1,4 +1,4 @@
-package com.reservedregions
+package com.appandflow.reservedregions
 
 import android.graphics.Rect
 

package/android/src/main/java/com/{reservedregions → appandflow/reservedregions}/ReservedRegionsPackage.kt

@@ -1,4 +1,4 @@
-package com.reservedregions
+package com.appandflow.reservedregions
 
 import com.facebook.react.BaseReactPackage
 import com.facebook.react.bridge.NativeModule

package/android/src/main/java/com/{reservedregions → appandflow/reservedregions}/ReservedRegionsView.kt

@@ -1,51 +1,96 @@
-package com.reservedregions
+package com.appandflow.reservedregions
 
 import android.content.Context
 import android.graphics.Rect
 import android.os.Build
 import android.view.ViewTreeObserver
-import android.view.WindowInsets
 import androidx.core.content.ContextCompat
 import androidx.core.util.Consumer
+import androidx.window.WindowSdkExtensions
 import androidx.window.java.layout.WindowInfoTrackerCallbackAdapter
 import androidx.window.layout.FoldingFeature
 import androidx.window.layout.WindowInfoTracker
 import androidx.window.layout.WindowLayoutInfo
+import com.facebook.react.bridge.UIManager
+import com.facebook.react.bridge.UIManagerListener
+import com.facebook.react.common.annotations.UnstableReactNativeAPI
 import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.UIManagerHelper
 import com.facebook.react.views.view.ReactViewGroup
 import kotlin.math.max
 import kotlin.math.min
 
 internal typealias RegionsChangeHandler = (ReservedRegionsView, List<ReservedRegion>) -> Unit
 
-class ReservedRegionsView(context: Context) : ReactViewGroup(context), ViewTreeObserver.OnPreDrawListener {
+@OptIn(UnstableReactNativeAPI::class)
+class ReservedRegionsView(context: Context) : ReactViewGroup(context), ViewTreeObserver.OnPreDrawListener, UIManagerListener {
+  private var uiManager: UIManager? = null
   private var tracker: WindowInfoTrackerCallbackAdapter? = null
   private val layoutInfoConsumer = Consumer<WindowLayoutInfo> { info ->
     foldingFeatures = info.displayFeatures.filterIsInstance<FoldingFeature>()
-    updateRegions()
+    foldingFeaturesReady = true
+    invalidate()
   }
   private var foldingFeatures: List<FoldingFeature> = emptyList()
+  private var foldingFeaturesReady = false
   private var lastRegions: List<ReservedRegion>? = null
+  private var awaitingFirstMount = true
   private var onRegionsChange: RegionsChangeHandler? = null
 
+  override fun willDispatchViewUpdates(uiManager: UIManager) {}
+
+  override fun willMountItems(uiManager: UIManager) {}
+
+  override fun didScheduleMountItems(uiManager: UIManager) {}
+
+  override fun didDispatchMountItems(uiManager: UIManager) {}
+
+  override fun didMountItems(uiManager: UIManager) {
+    if (awaitingFirstMount) updateRegions()
+  }
+
   override fun onAttachedToWindow() {
     super.onAttachedToWindow()
+    uiManager = UIManagerHelper.getUIManagerForReactTag(UIManagerHelper.getReactContext(this), id)
+    awaitingFirstMount = true
+    // React Native's FabricMountingManager.cpp applies layout before installing a view's event
+    // emitter inside one mount batch, so onLayout cannot dispatch a synchronous event on first
+    // mount; didMountItems is the earliest point after the emitter exists and before the event
+    // beat. It runs for every mount batch in the app, so it is removed after the first delivery.
+    uiManager?.addUIManagerEventListener(this)
     viewTreeObserver.addOnPreDrawListener(this)
+    foldingFeatures = emptyList()
+    foldingFeaturesReady = false
+    lastRegions = null
     val activity = (context as? ThemedReactContext)?.currentActivity
     if (activity != null) {
-      tracker = WindowInfoTrackerCallbackAdapter(WindowInfoTracker.getOrCreate(context))
+      val windowTracker = WindowInfoTracker.getOrCreate(context)
+      if (WindowSdkExtensions.getInstance().extensionVersion >= 9) {
+        foldingFeatures = windowTracker.getCurrentWindowLayoutInfo(activity)
+          .displayFeatures.filterIsInstance<FoldingFeature>()
+        foldingFeaturesReady = true
+      }
+      tracker = WindowInfoTrackerCallbackAdapter(windowTracker)
       tracker?.addWindowLayoutInfoListener(activity, ContextCompat.getMainExecutor(context), layoutInfoConsumer)
+    } else {
+      foldingFeaturesReady = true
     }
-    updateRegions()
   }
 
   override fun onDetachedFromWindow() {
+    uiManager?.removeUIManagerEventListener(this)
+    uiManager = null
     tracker?.removeWindowLayoutInfoListener(layoutInfoConsumer)
     tracker = null
     viewTreeObserver.removeOnPreDrawListener(this)
     super.onDetachedFromWindow()
   }
 
+  override fun onLayout(changed: Boolean, left: Int, top: Int, right: Int, bottom: Int) {
+    super.onLayout(changed, left, top, right, bottom)
+    if (!awaitingFirstMount) updateRegions()
+  }
+
   override fun onPreDraw(): Boolean {
     updateRegions()
     return true
@@ -53,12 +98,13 @@ class ReservedRegionsView(context: Context) : ReactViewGroup(context), ViewTreeO
 
   internal fun setOnRegionsChangeHandler(handler: RegionsChangeHandler) {
     onRegionsChange = handler
-    updateRegions()
+    lastRegions = null
+    invalidate()
   }
 
-  private fun updateRegions() {
-    val handler = onRegionsChange ?: return
-    if (!isAttachedToWindow || width == 0 || height == 0) return
+  private fun updateRegions(): Boolean {
+    val handler = onRegionsChange ?: return false
+    if (!isAttachedToWindow || !foldingFeaturesReady || width == 0 || height == 0) return false
 
     val windowLocation = IntArray(2)
     getLocationInWindow(windowLocation)
@@ -70,13 +116,7 @@ class ReservedRegionsView(context: Context) : ReactViewGroup(context), ViewTreeO
       regions.add(ReservedRegion("division", frame, feature.occlusionType == FoldingFeature.OcclusionType.FULL))
     }
 
-    if (Build.VERSION.SDK_INT >= 35) {
-      rootWindowInsets?.getBoundingRects(WindowInsets.Type.displayCutout())?.forEach { bounds ->
-        clippedFrame(bounds, windowLocation[0], windowLocation[1])?.let { frame ->
-          regions.add(ReservedRegion("occlusion", frame))
-        }
-      }
-    } else if (Build.VERSION.SDK_INT >= 28) {
+    if (Build.VERSION.SDK_INT >= 28) {
       val screenLocation = IntArray(2)
       getLocationOnScreen(screenLocation)
       rootWindowInsets?.displayCutout?.boundingRects?.forEach { bounds ->
@@ -86,10 +126,14 @@ class ReservedRegionsView(context: Context) : ReactViewGroup(context), ViewTreeO
       }
     }
 
-    if (regions != lastRegions) {
-      lastRegions = regions
-      handler(this, regions)
+    if (regions == lastRegions) return false
+    lastRegions = regions
+    handler(this, regions)
+    if (awaitingFirstMount) {
+      awaitingFirstMount = false
+      uiManager?.removeUIManagerEventListener(this)
     }
+    return true
   }
 
   private fun clippedFrame(bounds: Rect, originX: Int, originY: Int): Rect? {

package/android/src/main/java/com/{reservedregions → appandflow/reservedregions}/ReservedRegionsViewManager.kt

@@ -1,4 +1,4 @@
-package com.reservedregions
+package com.appandflow.reservedregions
 
 import com.facebook.react.bridge.ReactContext
 import com.facebook.react.module.annotations.ReactModule

package/ios/ReservedRegionsView.mm

@@ -1,9 +1,6 @@
 #import "ReservedRegionsView.h"
 
-#import <objc/message.h>
-
 #import <react/renderer/components/ReservedRegionsViewSpec/ComponentDescriptors.h>
-#import <react/renderer/components/ReservedRegionsViewSpec/EventEmitters.h>
 #import <react/renderer/components/ReservedRegionsViewSpec/Props.h>
 #import <react/renderer/components/ReservedRegionsViewSpec/RCTComponentViewHelpers.h>
 
@@ -25,6 +22,17 @@ using namespace facebook::react;
   if (self = [super initWithFrame:frame]) {
     static const auto defaultProps = std::make_shared<const ReservedRegionsViewProps>();
     _props = defaultProps;
+#if defined(__IPHONE_27_1) && __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_27_1
+    if (@available(iOS 27.1, *)) {
+      // UIKit posts no reserved-region change notification, so hinge updates schedule the re-query.
+      __weak __typeof(self) weakSelf = self;
+      UIHingeInteraction *hingeInteraction =
+          [[UIHingeInteraction alloc] initWithUpdateHandler:^(UIHingeInteraction *, UIHingeInteractionUpdate *) {
+            [weakSelf setNeedsLayout];
+          }];
+      [self addInteraction:hingeInteraction];
+    }
+#endif
   }
   return self;
 }
@@ -38,62 +46,62 @@ using namespace facebook::react;
 - (void)didMoveToWindow
 {
   [super didMoveToWindow];
-  [self updateRegions];
+  [self setNeedsLayout];
+}
+
+- (void)updateEventEmitter:(EventEmitter::Shared const &)eventEmitter
+{
+  [super updateEventEmitter:eventEmitter];
+  [self setNeedsLayout];
 }
 
 - (void)updateRegions
 {
-  if (self.window == nil || !_eventEmitter) {
+  if (self.window == nil || !_eventEmitter || CGSizeEqualToSize(self.bounds.size, CGSizeZero)) {
     return;
   }
 
-  // UIView reserved region selectors first ship in the iOS 27.1 SDK.
-  SEL querySelector = NSSelectorFromString(@"reservedRegionsOfKind:options:");
-  Class kindClass = NSClassFromString(@"UIViewReservedRegionKind");
   NSMutableArray<NSDictionary *> *regions = [NSMutableArray new];
-
-  if ([self respondsToSelector:querySelector] && kindClass != nil) {
-    NSArray<NSDictionary<NSString *, NSString *> *> *kinds = @[
-      @{@"selector": @"divisionRegionKind", @"kind": @"division"},
-      @{@"selector": @"occlusionRegionKind", @"kind": @"occlusion"},
+#if defined(__IPHONE_27_1) && __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_27_1
+  if (@available(iOS 27.1, *)) {
+    NSArray<UIViewReservedRegionKind *> *kinds = @[
+      UIViewReservedRegionKind.divisionRegionKind,
+      UIViewReservedRegionKind.occlusionRegionKind,
     ];
-
-    for (NSDictionary<NSString *, NSString *> *entry in kinds) {
-      SEL kindSelector = NSSelectorFromString(entry[@"selector"]);
-      if (![kindClass respondsToSelector:kindSelector]) {
-        continue;
-      }
-
-      id kind = ((id (*)(id, SEL))objc_msgSend)(kindClass, kindSelector);
-      NSArray *results = ((NSArray *(*)(id, SEL, id, NSUInteger))objc_msgSend)(self, querySelector, kind, 0);
-      for (id region in results) {
-        if (![region respondsToSelector:@selector(frame)]) {
-          continue;
-        }
-        CGRect frame = [[region valueForKey:@"frame"] CGRectValue];
-        [regions addObject:@{
-          @"kind": entry[@"kind"],
-          @"frame": [NSValue valueWithCGRect:frame],
-        }];
+    NSArray<NSString *> *names = @[@"division", @"occlusion"];
+    for (NSUInteger index = 0; index < kinds.count; index++) {
+      for (UIViewReservedRegion *region in [self reservedRegionsOfKind:kinds[index]
+                                                              options:UIViewReservedRegionQueryOptionsNone]) {
+        [regions addObject:@{@"kind": names[index], @"frame": [NSValue valueWithCGRect:region.frame]}];
       }
     }
   }
+#endif
 
   if ([_currentRegions isEqualToArray:regions]) {
     return;
   }
   _currentRegions = [regions copy];
 
-  ReservedRegionsViewEventEmitter::OnRegionsChange event;
+  auto regionPayloads = folly::dynamic::array();
   for (NSDictionary *region in regions) {
     CGRect frame = [region[@"frame"] CGRectValue];
-    event.regions.push_back({
-        [region[@"kind"] UTF8String],
-        {frame.origin.x, frame.origin.y, frame.size.width, frame.size.height},
-        false,
-    });
+    regionPayloads.push_back(folly::dynamic::object
+        ("kind", [region[@"kind"] UTF8String])
+        ("frame", folly::dynamic::object
+            ("x", frame.origin.x)
+            ("y", frame.origin.y)
+            ("width", frame.size.width)
+            ("height", frame.size.height))
+        ("occludesContent", false));
   }
-  std::static_pointer_cast<ReservedRegionsViewEventEmitter const>(_eventEmitter)->onRegionsChange(event);
+  auto eventEmitter = _eventEmitter;
+  eventEmitter->experimental_flushSync([eventEmitter, regions = std::move(regionPayloads)]() mutable {
+    eventEmitter->dispatchEvent(
+        "regionsChange",
+        folly::dynamic::object("regions", std::move(regions)),
+        RawEvent::Category::Discrete);
+  });
 }
 
 - (void)prepareForRecycle

package/lib/module/ReservedRegionsView.js

@@ -1,11 +1,19 @@
 "use strict";
 
+import { useEffect } from 'react';
 import { View } from 'react-native';
 import { jsx as _jsx } from "react/jsx-runtime";
 export function ReservedRegionsView({
-  onRegionsChange: _onRegionsChange,
+  onRegionsChange,
   ...props
 }) {
+  useEffect(() => {
+    onRegionsChange?.({
+      nativeEvent: {
+        regions: []
+      }
+    });
+  }, [onRegionsChange]);
   return /*#__PURE__*/_jsx(View, {
     ...props
   });

package/lib/module/ReservedRegionsView.js.map

@@ -1 +1 @@
-{"version":3,"names":["View","jsx","_jsx","ReservedRegionsView","onRegionsChange","_onRegionsChange","props"],"sourceRoot":"../../src","sources":["ReservedRegionsView.tsx"],"mappings":";;AAAA,SAASA,IAAI,QAAwB,cAAc;AAAC,SAAAC,GAAA,IAAAC,IAAA;AAOpD,OAAO,SAASC,mBAAmBA,CAAC;EAClCC,eAAe,EAAEC,gBAAgB;EACjC,GAAGC;AACqB,CAAC,EAAE;EAC3B,oBAAOJ,IAAA,CAACF,IAAI;IAAA,GAAKM;EAAK,CAAG,CAAC;AAC5B","ignoreList":[]}
+{"version":3,"names":["useEffect","View","jsx","_jsx","ReservedRegionsView","onRegionsChange","props","nativeEvent","regions"],"sourceRoot":"../../src","sources":["ReservedRegionsView.tsx"],"mappings":";;AAAA,SAASA,SAAS,QAAQ,OAAO;AACjC,SAASC,IAAI,QAAwB,cAAc;AAAC,SAAAC,GAAA,IAAAC,IAAA;AAOpD,OAAO,SAASC,mBAAmBA,CAAC;EAAEC,eAAe;EAAE,GAAGC;AAAgC,CAAC,EAAE;EAC3FN,SAAS,CAAC,MAAM;IACdK,eAAe,GAAG;MAAEE,WAAW,EAAE;QAAEC,OAAO,EAAE;MAAG;IAAE,CAAC,CAAC;EACrD,CAAC,EAAE,CAACH,eAAe,CAAC,CAAC;EACrB,oBAAOF,IAAA,CAACF,IAAI;IAAA,GAAKK;EAAK,CAAG,CAAC;AAC5B","ignoreList":[]}

package/lib/module/ReservedRegionsViewNativeComponent.ts

@@ -1,8 +1,4 @@
-import {
-  codegenNativeComponent,
-  type CodegenTypes,
-  type ViewProps,
-} from 'react-native';
+import { codegenNativeComponent, type CodegenTypes, type ViewProps } from 'react-native';
 
 export type RegionsChangeEvent = Readonly<{
   regions: {

package/lib/module/index.js

@@ -14,29 +14,37 @@ export function ReservedRegionsProvider({
   children,
   ...props
 }) {
-  const [regions, setRegions] = React.useState([]);
+  const [snapshot, setSnapshot] = React.useState({
+    regions: [],
+    isReady: false
+  });
+  const onRegionsChange = React.useCallback(event => {
+    const regions = event.nativeEvent.regions.flatMap(region => {
+      if (region.kind === 'division') {
+        return [{
+          kind: 'division',
+          frame: region.frame,
+          occludesContent: region.occludesContent
+        }];
+      }
+      if (region.kind === 'occlusion') {
+        return [{
+          kind: 'occlusion',
+          frame: region.frame
+        }];
+      }
+      return [];
+    });
+    setSnapshot({
+      regions,
+      isReady: true
+    });
+  }, []);
   return /*#__PURE__*/_jsx(ReservedRegionsContext.Provider, {
-    value: regions,
+    value: snapshot,
     children: /*#__PURE__*/_jsx(ReservedRegionsView, {
       ...props,
-      onRegionsChange: event => {
-        setRegions(event.nativeEvent.regions.flatMap(region => {
-          if (region.kind === 'division') {
-            return [{
-              kind: 'division',
-              frame: region.frame,
-              occludesContent: region.occludesContent
-            }];
-          }
-          if (region.kind === 'occlusion') {
-            return [{
-              kind: 'occlusion',
-              frame: region.frame
-            }];
-          }
-          return [];
-        }));
-      },
+      onRegionsChange: onRegionsChange,
       children: children
     })
   });
@@ -44,10 +52,29 @@ export function ReservedRegionsProvider({
 
 /** Returns active regions reported by the nearest ReservedRegionsProvider. */
 export function useReservedRegions() {
-  const regions = React.useContext(ReservedRegionsContext);
-  if (regions === null) {
+  const snapshot = React.useContext(ReservedRegionsContext);
+  if (snapshot === null) {
     throw new Error('useReservedRegions must be used inside ReservedRegionsProvider');
   }
-  return regions;
+  return snapshot.regions;
+}
+
+/**
+ * Whether the nearest provider has reported its first measurement, including an empty
+ * result. Remains true for that provider's lifetime; does not imply platform support.
+ */
+export function useReservedRegionsReady() {
+  const snapshot = React.useContext(ReservedRegionsContext);
+  if (snapshot === null) {
+    throw new Error('useReservedRegionsReady must be used inside ReservedRegionsProvider');
+  }
+  return snapshot.isReady;
+}
+
+/** Renders children after the nearest provider reports its first measurement. */
+export function ReservedRegionsGate({
+  children
+}) {
+  return useReservedRegionsReady() ? children : null;
 }
 //# sourceMappingURL=index.js.map

package/lib/module/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["React","ReservedRegionsView","jsx","_jsx","ReservedRegionsContext","createContext","ReservedRegionsProvider","children","props","regions","setRegions","useState","Provider","value","onRegionsChange","event","nativeEvent","flatMap","region","kind","frame","occludesContent","useReservedRegions","useContext","Error"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":";;AAAA,OAAO,KAAKA,KAAK,MAAM,OAAO;AAE9B,SAASC,mBAAmB,QAAQ,uBAAuB;;AAE3D;;AAYA;AAAA,SAAAC,GAAA,IAAAC,IAAA;AAiBA,MAAMC,sBAAsB,gBAAGJ,KAAK,CAACK,aAAa,CAEhD,IAAI,CAAC;;AAEP;AACA,OAAO,SAASC,uBAAuBA,CAAC;EACtCC,QAAQ;EACR,GAAGC;AACM,CAAC,EAAqB;EAC/B,MAAM,CAACC,OAAO,EAAEC,UAAU,CAAC,GAAGV,KAAK,CAACW,QAAQ,CAA4B,EAAE,CAAC;EAE3E,oBACER,IAAA,CAACC,sBAAsB,CAACQ,QAAQ;IAACC,KAAK,EAAEJ,OAAQ;IAAAF,QAAA,eAC9CJ,IAAA,CAACF,mBAAmB;MAAA,GACdO,KAAK;MACTM,eAAe,EAAGC,KAAK,IAAK;QAC1BL,UAAU,CACRK,KAAK,CAACC,WAAW,CAACP,OAAO,CAACQ,OAAO,CAAEC,MAAM,IAAuB;UAC9D,IAAIA,MAAM,CAACC,IAAI,KAAK,UAAU,EAAE;YAC9B,OAAO,CACL;cACEA,IAAI,EAAE,UAAmB;cACzBC,KAAK,EAAEF,MAAM,CAACE,KAAK;cACnBC,eAAe,EAAEH,MAAM,CAACG;YAC1B,CAAC,CACF;UACH;UACA,IAAIH,MAAM,CAACC,IAAI,KAAK,WAAW,EAAE;YAC/B,OAAO,CAAC;cAAEA,IAAI,EAAE,WAAoB;cAAEC,KAAK,EAAEF,MAAM,CAACE;YAAM,CAAC,CAAC;UAC9D;UACA,OAAO,EAAE;QACX,CAAC,CACH,CAAC;MACH,CAAE;MAAAb,QAAA,EAEDA;IAAQ,CACU;EAAC,CACS,CAAC;AAEtC;;AAEA;AACA,OAAO,SAASe,kBAAkBA,CAAA,EAA8B;EAC9D,MAAMb,OAAO,GAAGT,KAAK,CAACuB,UAAU,CAACnB,sBAAsB,CAAC;EACxD,IAAIK,OAAO,KAAK,IAAI,EAAE;IACpB,MAAM,IAAIe,KAAK,CACb,gEACF,CAAC;EACH;EACA,OAAOf,OAAO;AAChB","ignoreList":[]}
+{"version":3,"names":["React","ReservedRegionsView","jsx","_jsx","ReservedRegionsContext","createContext","ReservedRegionsProvider","children","props","snapshot","setSnapshot","useState","regions","isReady","onRegionsChange","useCallback","event","nativeEvent","flatMap","region","kind","frame","occludesContent","Provider","value","useReservedRegions","useContext","Error","useReservedRegionsReady","ReservedRegionsGate"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":";;AAAA,OAAO,KAAKA,KAAK,MAAM,OAAO;AAE9B,SAASC,mBAAmB,QAAQ,uBAAuB;;AAG3D;;AAYA;AAAA,SAAAC,GAAA,IAAAC,IAAA;AAsBA,MAAMC,sBAAsB,gBAAGJ,KAAK,CAACK,aAAa,CAAiC,IAAI,CAAC;;AAExF;AACA,OAAO,SAASC,uBAAuBA,CAAC;EAAEC,QAAQ;EAAE,GAAGC;AAAiB,CAAC,EAAqB;EAC5F,MAAM,CAACC,QAAQ,EAAEC,WAAW,CAAC,GAAGV,KAAK,CAACW,QAAQ,CAA0B;IAAEC,OAAO,EAAE,EAAE;IAAEC,OAAO,EAAE;EAAM,CAAC,CAAC;EACxG,MAAMC,eAAe,GAAGd,KAAK,CAACe,WAAW,CAAEC,KAA0C,IAAK;IACxF,MAAMJ,OAAO,GAAGI,KAAK,CAACC,WAAW,CAACL,OAAO,CAACM,OAAO,CAAEC,MAAM,IAAuB;MAC9E,IAAIA,MAAM,CAACC,IAAI,KAAK,UAAU,EAAE;QAC9B,OAAO,CAAC;UAAEA,IAAI,EAAE,UAAU;UAAEC,KAAK,EAAEF,MAAM,CAACE,KAAK;UAAEC,eAAe,EAAEH,MAAM,CAACG;QAAgB,CAAC,CAAC;MAC7F;MACA,IAAIH,MAAM,CAACC,IAAI,KAAK,WAAW,EAAE;QAC/B,OAAO,CAAC;UAAEA,IAAI,EAAE,WAAW;UAAEC,KAAK,EAAEF,MAAM,CAACE;QAAM,CAAC,CAAC;MACrD;MACA,OAAO,EAAE;IACX,CAAC,CAAC;IACFX,WAAW,CAAC;MAAEE,OAAO;MAAEC,OAAO,EAAE;IAAK,CAAC,CAAC;EACzC,CAAC,EAAE,EAAE,CAAC;EAEN,oBACEV,IAAA,CAACC,sBAAsB,CAACmB,QAAQ;IAACC,KAAK,EAAEf,QAAS;IAAAF,QAAA,eAC/CJ,IAAA,CAACF,mBAAmB;MAAA,GAAKO,KAAK;MAAEM,eAAe,EAAEA,eAAgB;MAAAP,QAAA,EAC9DA;IAAQ,CACU;EAAC,CACS,CAAC;AAEtC;;AAEA;AACA,OAAO,SAASkB,kBAAkBA,CAAA,EAA8B;EAC9D,MAAMhB,QAAQ,GAAGT,KAAK,CAAC0B,UAAU,CAACtB,sBAAsB,CAAC;EACzD,IAAIK,QAAQ,KAAK,IAAI,EAAE;IACrB,MAAM,IAAIkB,KAAK,CAAC,gEAAgE,CAAC;EACnF;EACA,OAAOlB,QAAQ,CAACG,OAAO;AACzB;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASgB,uBAAuBA,CAAA,EAAY;EACjD,MAAMnB,QAAQ,GAAGT,KAAK,CAAC0B,UAAU,CAACtB,sBAAsB,CAAC;EACzD,IAAIK,QAAQ,KAAK,IAAI,EAAE;IACrB,MAAM,IAAIkB,KAAK,CAAC,qEAAqE,CAAC;EACxF;EACA,OAAOlB,QAAQ,CAACI,OAAO;AACzB;;AAEA;AACA,OAAO,SAASgB,mBAAmBA,CAAC;EAAEtB;AAAkC,CAAC,EAAmB;EAC1F,OAAOqB,uBAAuB,CAAC,CAAC,GAAGrB,QAAQ,GAAG,IAAI;AACpD","ignoreList":[]}

package/lib/typescript/src/ReservedRegionsView.d.ts

@@ -5,5 +5,5 @@ export type ReservedRegionsViewProps = ViewProps & {
         nativeEvent: RegionsChangeEvent;
     }) => void;
 };
-export declare function ReservedRegionsView({ onRegionsChange: _onRegionsChange, ...props }: ReservedRegionsViewProps): import("react").JSX.Element;
+export declare function ReservedRegionsView({ onRegionsChange, ...props }: ReservedRegionsViewProps): import("react").JSX.Element;
 //# sourceMappingURL=ReservedRegionsView.d.ts.map

package/lib/typescript/src/ReservedRegionsView.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ReservedRegionsView.d.ts","sourceRoot":"","sources":["../../../src/ReservedRegionsView.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAE/E,MAAM,MAAM,wBAAwB,GAAG,SAAS,GAAG;IACjD,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,WAAW,EAAE,kBAAkB,CAAA;KAAE,KAAK,IAAI,CAAC;CACxE,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,EAClC,eAAe,EAAE,gBAAgB,EACjC,GAAG,KAAK,EACT,EAAE,wBAAwB,+BAE1B"}
+{"version":3,"file":"ReservedRegionsView.d.ts","sourceRoot":"","sources":["../../../src/ReservedRegionsView.tsx"],"names":[],"mappings":"AACA,OAAO,EAAQ,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAE/E,MAAM,MAAM,wBAAwB,GAAG,SAAS,GAAG;IACjD,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,WAAW,EAAE,kBAAkB,CAAA;KAAE,KAAK,IAAI,CAAC;CACxE,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,EAAE,eAAe,EAAE,GAAG,KAAK,EAAE,EAAE,wBAAwB,+BAK1F"}

package/lib/typescript/src/ReservedRegionsViewNativeComponent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ReservedRegionsViewNativeComponent.d.ts","sourceRoot":"","sources":["../../../src/ReservedRegionsViewNativeComponent.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,cAAc,CAAC;AAEtB,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE;YACL,CAAC,EAAE,YAAY,CAAC,MAAM,CAAC;YACvB,CAAC,EAAE,YAAY,CAAC,MAAM,CAAC;YACvB,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC;YAC3B,MAAM,EAAE,YAAY,CAAC,MAAM,CAAC;SAC7B,CAAC;QACF,eAAe,EAAE,OAAO,CAAC;KAC1B,EAAE,CAAC;CACL,CAAC,CAAC;AAEH,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC5C,eAAe,CAAC,EAAE,YAAY,CAAC,kBAAkB,CAAC,kBAAkB,CAAC,CAAC;CACvE;;AAED,wBAA0E"}
+{"version":3,"file":"ReservedRegionsViewNativeComponent.d.ts","sourceRoot":"","sources":["../../../src/ReservedRegionsViewNativeComponent.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,YAAY,EAAE,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzF,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE;YACL,CAAC,EAAE,YAAY,CAAC,MAAM,CAAC;YACvB,CAAC,EAAE,YAAY,CAAC,MAAM,CAAC;YACvB,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC;YAC3B,MAAM,EAAE,YAAY,CAAC,MAAM,CAAC;SAC7B,CAAC;QACF,eAAe,EAAE,OAAO,CAAC;KAC1B,EAAE,CAAC;CACL,CAAC,CAAC;AAEH,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC5C,eAAe,CAAC,EAAE,YAAY,CAAC,kBAAkB,CAAC,kBAAkB,CAAC,CAAC;CACvE"}

package/lib/typescript/src/index.d.ts

@@ -29,4 +29,11 @@ export type ReservedRegion = Readonly<{
 export declare function ReservedRegionsProvider({ children, ...props }: ViewProps): React.JSX.Element;
 /** Returns active regions reported by the nearest ReservedRegionsProvider. */
 export declare function useReservedRegions(): readonly ReservedRegion[];
+/**
+ * Whether the nearest provider has reported its first measurement, including an empty
+ * result. Remains true for that provider's lifetime; does not imply platform support.
+ */
+export declare function useReservedRegionsReady(): boolean;
+/** Renders children after the nearest provider reports its first measurement. */
+export declare function ReservedRegionsGate({ children }: React.PropsWithChildren): React.ReactNode;
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAG9C,qFAAqF;AACrF,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,8CAA8C;IAC9C,CAAC,EAAE,MAAM,CAAC;IACV,6CAA6C;IAC7C,CAAC,EAAE,MAAM,CAAC;IACV,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC;AAEH,2DAA2D;AAC3D,MAAM,MAAM,cAAc,GACtB,QAAQ,CAAC;IACP,sDAAsD;IACtD,IAAI,EAAE,UAAU,CAAC;IACjB,gEAAgE;IAChE,KAAK,EAAE,mBAAmB,CAAC;IAC3B,yDAAyD;IACzD,eAAe,EAAE,OAAO,CAAC;CAC1B,CAAC,GACF,QAAQ,CAAC;IACP,gEAAgE;IAChE,IAAI,EAAE,WAAW,CAAC;IAClB,iEAAiE;IACjE,KAAK,EAAE,mBAAmB,CAAC;CAC5B,CAAC,CAAC;AAMP,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,EACtC,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CA+B/B;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,IAAI,SAAS,cAAc,EAAE,CAQ9D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAI9C,qFAAqF;AACrF,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,8CAA8C;IAC9C,CAAC,EAAE,MAAM,CAAC;IACV,6CAA6C;IAC7C,CAAC,EAAE,MAAM,CAAC;IACV,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC;AAEH,2DAA2D;AAC3D,MAAM,MAAM,cAAc,GACtB,QAAQ,CAAC;IACP,sDAAsD;IACtD,IAAI,EAAE,UAAU,CAAC;IACjB,gEAAgE;IAChE,KAAK,EAAE,mBAAmB,CAAC;IAC3B,yDAAyD;IACzD,eAAe,EAAE,OAAO,CAAC;CAC1B,CAAC,GACF,QAAQ,CAAC;IACP,gEAAgE;IAChE,IAAI,EAAE,WAAW,CAAC;IAClB,iEAAiE;IACjE,KAAK,EAAE,mBAAmB,CAAC;CAC5B,CAAC,CAAC;AASP,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,EAAE,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAsB5F;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,IAAI,SAAS,cAAc,EAAE,CAM9D;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAMjD;AAED,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,EAAE,QAAQ,EAAE,EAAE,KAAK,CAAC,iBAAiB,GAAG,KAAK,CAAC,SAAS,CAE1F"}

package/package.json

@@ -1,16 +1,19 @@
 {
   "name": "react-native-reserved-regions",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.3",
   "description": "Provider-scoped reserved display regions for React Native",
-  "main": "./lib/module/index.js",
-  "types": "./lib/typescript/src/index.d.ts",
-  "exports": {
-    ".": {
-      "react-native-reserved-regions-source": "./src/index.tsx",
-      "types": "./lib/typescript/src/index.d.ts",
-      "default": "./lib/module/index.js"
-    },
-    "./package.json": "./package.json"
+  "keywords": [
+    "android",
+    "ios",
+    "react-native"
+  ],
+  "homepage": "https://github.com/appandflow/react-native-reserved-regions#readme",
+  "bugs": "https://github.com/appandflow/react-native-reserved-regions/issues",
+  "license": "MIT",
+  "author": "Janic Duplessis <janicduplessis@gmail.com> (https://github.com/janicduplessis)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/appandflow/react-native-reserved-regions.git"
   },
   "files": [
     "src",
@@ -31,80 +34,63 @@
     "!**/__mocks__",
     "!**/.*"
   ],
-  "scripts": {
-    "example": "yarn workspace react-native-reserved-regions-example",
-    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
-    "prepare": "bob build",
-    "typecheck": "tsc",
-    "lint": "eslint \"**/*.{js,ts,tsx}\"",
-    "test": "jest"
+  "main": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "react-native-reserved-regions-source": "./src/index.tsx",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
   },
-  "keywords": [
-    "react-native",
-    "ios",
-    "android"
-  ],
-  "author": "Janic Duplessis <janicduplessis@gmail.com> (https://github.com/janicduplessis)",
-  "license": "MIT",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
-    "@eslint/compat": "^2.1.0",
-    "@eslint/eslintrc": "^3.3.6",
-    "@eslint/js": "^9.39.5",
     "@jest/globals": "^29.7.0",
     "@react-native/babel-preset": "0.88.0-rc.1",
-    "@react-native/eslint-config": "0.86.2",
     "@react-native/jest-preset": "0.86.2",
     "@types/react": "^19.2.0",
     "@types/react-test-renderer": "^19.1.0",
     "del-cli": "^7.0.0",
-    "eslint": "^9.39.5",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-ft-flow": "^3.0.11",
-    "eslint-plugin-prettier": "^5.5.6",
     "jest": "^29.7.0",
-    "prettier": "^3.9.6",
+    "oxfmt": "0.65.0",
+    "oxlint": "1.80.0",
     "react": "19.3.0",
     "react-native": "0.88.0-rc.1",
     "react-native-builder-bob": "^0.43.1",
     "react-test-renderer": "19.3.0",
-    "turbo": "^2.10.8",
-    "typescript": "^6.0.3"
+    "typescript": "7.0.2"
   },
   "peerDependencies": {
     "react": "*",
     "react-native": "*"
   },
-  "workspaces": [
-    "example"
-  ],
-  "packageManager": "yarn@4.11.0",
-  "react-native-builder-bob": {
-    "source": "src",
-    "output": "lib",
-    "targets": [
-      [
-        "module",
-        {
-          "esm": true
-        }
-      ],
-      [
-        "typescript",
-        {
-          "project": "tsconfig.build.json"
-        }
+  "jest": {
+    "modulePathIgnorePatterns": [
+      "<rootDir>/example/node_modules",
+      "<rootDir>/lib/",
+      "<rootDir>/website/"
+    ],
+    "preset": "@react-native/jest-preset",
+    "testEnvironmentOptions": {
+      "customExportConditions": [
+        "require",
+        "react-native",
+        "react-native-reserved-regions-source"
       ]
-    ]
+    }
+  },
+  "engines": {
+    "node": ">=22.18.0"
   },
   "codegenConfig": {
     "name": "ReservedRegionsViewSpec",
     "type": "all",
     "jsSrcsDir": "src",
     "android": {
-      "javaPackageName": "com.reservedregions"
+      "javaPackageName": "com.appandflow.reservedregions"
     },
     "ios": {
       "components": {
@@ -114,27 +100,6 @@
       }
     }
   },
-  "prettier": {
-    "quoteProps": "consistent",
-    "singleQuote": true,
-    "tabWidth": 2,
-    "trailingComma": "es5",
-    "useTabs": false
-  },
-  "jest": {
-    "preset": "@react-native/jest-preset",
-    "testEnvironmentOptions": {
-      "customExportConditions": [
-        "require",
-        "react-native",
-        "react-native-reserved-regions-source"
-      ]
-    },
-    "modulePathIgnorePatterns": [
-      "<rootDir>/example/node_modules",
-      "<rootDir>/lib/"
-    ]
-  },
   "create-react-native-library": {
     "type": "fabric-view",
     "languages": "kotlin-objc",
@@ -143,5 +108,37 @@
       "jest"
     ],
     "version": "0.63.1"
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "scripts": {
+    "example": "pnpm --filter react-native-reserved-regions-example",
+    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint .",
+    "test": "jest --runInBand --watchman=false",
+    "build": "bob build",
+    "lint:fix": "oxlint --fix .",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "e2e:android": "node e2e/android.mjs",
+    "docs:build": "pnpm --filter reserved-regions-docs build",
+    "docs:start": "pnpm --filter reserved-regions-docs start"
   }
-}
+}

package/src/ReservedRegionsView.tsx

@@ -1,3 +1,4 @@
+import { useEffect } from 'react';
 import { View, type ViewProps } from 'react-native';
 import type { RegionsChangeEvent } from './ReservedRegionsViewNativeComponent';
 
@@ -5,9 +6,9 @@ export type ReservedRegionsViewProps = ViewProps & {
   onRegionsChange?: (event: { nativeEvent: RegionsChangeEvent }) => void;
 };
 
-export function ReservedRegionsView({
-  onRegionsChange: _onRegionsChange,
-  ...props
-}: ReservedRegionsViewProps) {
+export function ReservedRegionsView({ onRegionsChange, ...props }: ReservedRegionsViewProps) {
+  useEffect(() => {
+    onRegionsChange?.({ nativeEvent: { regions: [] } });
+  }, [onRegionsChange]);
   return <View {...props} />;
 }

package/src/ReservedRegionsViewNativeComponent.ts

@@ -1,8 +1,4 @@
-import {
-  codegenNativeComponent,
-  type CodegenTypes,
-  type ViewProps,
-} from 'react-native';
+import { codegenNativeComponent, type CodegenTypes, type ViewProps } from 'react-native';
 
 export type RegionsChangeEvent = Readonly<{
   regions: {

package/src/index.tsx

@@ -1,6 +1,7 @@
 import * as React from 'react';
 import type { ViewProps } from 'react-native';
 import { ReservedRegionsView } from './ReservedRegionsView';
+import type { RegionsChangeEvent } from './ReservedRegionsViewNativeComponent';
 
 /** A rectangle in logical points relative to the nearest ReservedRegionsProvider. */
 export type ReservedRegionFrame = Readonly<{
@@ -31,41 +32,32 @@ export type ReservedRegion =
       frame: ReservedRegionFrame;
     }>;
 
-const ReservedRegionsContext = React.createContext<
-  readonly ReservedRegion[] | null
->(null);
+type ReservedRegionsSnapshot = Readonly<{
+  regions: readonly ReservedRegion[];
+  isReady: boolean;
+}>;
+
+const ReservedRegionsContext = React.createContext<ReservedRegionsSnapshot | null>(null);
 
 /** Makes active reserved regions available to descendants in provider coordinates. */
-export function ReservedRegionsProvider({
-  children,
-  ...props
-}: ViewProps): React.JSX.Element {
-  const [regions, setRegions] = React.useState<readonly ReservedRegion[]>([]);
+export function ReservedRegionsProvider({ children, ...props }: ViewProps): React.JSX.Element {
+  const [snapshot, setSnapshot] = React.useState<ReservedRegionsSnapshot>({ regions: [], isReady: false });
+  const onRegionsChange = React.useCallback((event: { nativeEvent: RegionsChangeEvent }) => {
+    const regions = event.nativeEvent.regions.flatMap((region): ReservedRegion[] => {
+      if (region.kind === 'division') {
+        return [{ kind: 'division', frame: region.frame, occludesContent: region.occludesContent }];
+      }
+      if (region.kind === 'occlusion') {
+        return [{ kind: 'occlusion', frame: region.frame }];
+      }
+      return [];
+    });
+    setSnapshot({ regions, isReady: true });
+  }, []);
 
   return (
-    <ReservedRegionsContext.Provider value={regions}>
-      <ReservedRegionsView
-        {...props}
-        onRegionsChange={(event) => {
-          setRegions(
-            event.nativeEvent.regions.flatMap((region): ReservedRegion[] => {
-              if (region.kind === 'division') {
-                return [
-                  {
-                    kind: 'division' as const,
-                    frame: region.frame,
-                    occludesContent: region.occludesContent,
-                  },
-                ];
-              }
-              if (region.kind === 'occlusion') {
-                return [{ kind: 'occlusion' as const, frame: region.frame }];
-              }
-              return [];
-            })
-          );
-        }}
-      >
+    <ReservedRegionsContext.Provider value={snapshot}>
+      <ReservedRegionsView {...props} onRegionsChange={onRegionsChange}>
         {children}
       </ReservedRegionsView>
     </ReservedRegionsContext.Provider>
@@ -74,11 +66,26 @@ export function ReservedRegionsProvider({
 
 /** Returns active regions reported by the nearest ReservedRegionsProvider. */
 export function useReservedRegions(): readonly ReservedRegion[] {
-  const regions = React.useContext(ReservedRegionsContext);
-  if (regions === null) {
-    throw new Error(
-      'useReservedRegions must be used inside ReservedRegionsProvider'
-    );
+  const snapshot = React.useContext(ReservedRegionsContext);
+  if (snapshot === null) {
+    throw new Error('useReservedRegions must be used inside ReservedRegionsProvider');
   }
-  return regions;
+  return snapshot.regions;
+}
+
+/**
+ * Whether the nearest provider has reported its first measurement, including an empty
+ * result. Remains true for that provider's lifetime; does not imply platform support.
+ */
+export function useReservedRegionsReady(): boolean {
+  const snapshot = React.useContext(ReservedRegionsContext);
+  if (snapshot === null) {
+    throw new Error('useReservedRegionsReady must be used inside ReservedRegionsProvider');
+  }
+  return snapshot.isReady;
+}
+
+/** Renders children after the nearest provider reports its first measurement. */
+export function ReservedRegionsGate({ children }: React.PropsWithChildren): React.ReactNode {
+  return useReservedRegionsReady() ? children : null;
 }