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

package/README.md

@@ -5,15 +5,19 @@ 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.2` is the functional release candidate. Install the explicit version
+once publication is verified; until then, run the repository example.
+
 ```sh
-npm install react-native-reserved-regions
+npm install react-native-reserved-regions@0.1.0-alpha.2
 ```
 
 On iOS, install pods in your app's `ios` directory. Android links automatically through React Native autolinking.
@@ -21,13 +25,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 +50,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:
 
@@ -68,22 +71,48 @@ A division splits the available display. `occludesContent` tells you whether con
 
 ## 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.
+
 ## 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,45 +1,80 @@
-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 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) {
+    // Fabric installs event emitters after layout; its event beat runs before pre-draw.
+    updateRegions()
+  }
+
   override fun onAttachedToWindow() {
     super.onAttachedToWindow()
+    uiManager = UIManagerHelper.getUIManagerForReactTag(UIManagerHelper.getReactContext(this), id)
+    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)
@@ -53,12 +88,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
+    if (!isAttachedToWindow || !foldingFeaturesReady || width == 0 || height == 0) return
 
     val windowLocation = IntArray(2)
     getLocationInWindow(windowLocation)
@@ -70,13 +106,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 ->

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>
 
@@ -38,62 +35,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,22 @@ 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;
 }
 //# 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"],"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","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,9 @@ 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;
 //# 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"}

package/package.json

@@ -1,16 +1,19 @@
 {
   "name": "react-native-reserved-regions",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.2",
   "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,36 @@
       "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 .",
+    "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,21 @@ 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 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 regions;
+  return snapshot.isReady;
 }