fix(usePlaybackOptions): clear screen regions when screenRegions is unset

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@snap/react-camera-kit",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "React Camera Kit for web applications",
   "type": "module",
   "main": "./dist/cjs/index.js",

src/LensPlayer.tsx

@@ -60,11 +60,14 @@ export interface LensPlayerProps {
   muted?: boolean;
 
   /**
-   * Configuration object containing the current set of screen regions.
+   * Configuration object containing the complete set of active screen regions.
    *
    * Screen regions define areas of the screen that have special meaning for Lens rendering,
    * such as safe rendering areas, UI button locations, keyboard areas, etc. This allows lenses
    * to adapt their content placement based on the host application's UI layout.
+   *
+   * This value is applied as a full replacement set: regions not included in the object are
+   * removed. Pass `undefined` or omit this option to clear all screen regions.
    */
   screenRegions?: ScreenRegions;
 

src/usePlaybackOptions.test.ts

@@ -202,11 +202,35 @@ describe("usePlaybackOptions", () => {
       });
     });
 
-    it("should not set screen regions when undefined", () => {
+    it("should clear screen regions when undefined", async () => {
       const options: PlaybackOptions = {};
       renderHook(() => usePlaybackOptions(options));
 
-      expect(mockSetScreenRegions).not.toHaveBeenCalled();
+      await waitFor(() => {
+        expect(mockSetScreenRegions).toHaveBeenCalledWith({});
+      });
+    });
+
+    it("should clear screen regions when they change from set to undefined", async () => {
+      const regions: any = {
+        safeRenderArea: { top: 0, left: 0, bottom: 1, right: 1 },
+      };
+
+      const { rerender } = renderHook(({ screenRegions }) => usePlaybackOptions({ screenRegions }), {
+        initialProps: { screenRegions: regions },
+      });
+
+      await waitFor(() => {
+        expect(mockSetScreenRegions).toHaveBeenCalledWith(regions);
+      });
+
+      mockSetScreenRegions.mockClear();
+
+      rerender({ screenRegions: undefined });
+
+      await waitFor(() => {
+        expect(mockSetScreenRegions).toHaveBeenCalledWith({});
+      });
     });
 
     it("should update screen regions when changed", async () => {

src/usePlaybackOptions.ts

@@ -21,11 +21,14 @@ export interface PlaybackOptions {
   muted?: boolean;
 
   /**
-   * Configuration object containing the current set of screen regions.
+   * Configuration object containing the complete set of active screen regions.
    *
    * Screen regions define areas of the screen that have special meaning for Lens rendering,
    * such as safe rendering areas, UI button locations, keyboard areas, etc. This allows lenses
    * to adapt their content placement based on the host application's UI layout.
+   *
+   * This value is applied as a full replacement set: regions not included in the object are
+   * removed. Pass `undefined` or omit this option to clear all screen regions.
    */
   screenRegions?: ScreenRegions;
 
@@ -78,9 +81,9 @@ export function usePlaybackOptions(options: PlaybackOptions) {
   }, [currentSession, sdkStatus, options.muted, setMuted, log]);
 
   useEffect(() => {
-    if (sdkStatus !== "ready" || !currentSession || !options.screenRegions) return;
-
-    setScreenRegions(options.screenRegions).catch((error) => {
+    if (sdkStatus !== "ready" || !currentSession) return;
+    // Coalesce to {} so clearing the prop clears the regions — setScreenRegions replaces the full set.
+    setScreenRegions(options.screenRegions ?? {}).catch((error) => {
       log.error("screen_regions_apply_failed", { screenRegions: options.screenRegions }, error);
     });
   }, [currentSession, sdkStatus, options.screenRegions, setScreenRegions, log]);