@granite-js/react-native 1.0.43 → 1.0.45

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @granite-js/react-native
 
+## 1.0.45
+
+### Patch Changes
+
+- @granite-js/blur-view@1.0.45
+- @granite-js/brownfield-module@1.0.45
+- @granite-js/cli@1.0.45
+- @granite-js/jest@1.0.45
+- @granite-js/mpack@1.0.45
+- @granite-js/plugin-core@1.0.45
+- @granite-js/style-utils@1.0.45
+- @granite-js/video@1.0.45
+
+## 1.0.44
+
+### Patch Changes
+
+- e97fe95: Use an unrestricted native peer range instead of an exact workspace constraint, preventing compatible updates from causing an unintended major release.
+- 23a710f: Read navigation focus through `useSyncExternalStore` so focus changes between rendering and subscription are not missed by `useIsFocusedSafely`, `useVisibility`, or visibility effects. Preserve the focused fallback when no navigation context is available.
+
+  Visibility effects follow committed visibility snapshots with React's effect setup and cleanup lifecycle.
+
+- 92a23a8: Add `useVisibilityEffect` to run an effect while a screen is visible and clean it up when visibility is lost, the callback changes, or the component unmounts.
+
+  Deprecate `useVisibilityChange` without changing its behavior. Use `useVisibilityEffect` for effects with cleanup, or `useVisibility` with React's `useEffect` for explicit visibility change handling.
+
+- Updated dependencies [e97fe95]
+  - @granite-js/blur-view@1.0.44
+  - @granite-js/jest@1.0.44
+  - @granite-js/brownfield-module@1.0.44
+  - @granite-js/cli@1.0.44
+  - @granite-js/mpack@1.0.44
+  - @granite-js/plugin-core@1.0.44
+  - @granite-js/style-utils@1.0.44
+  - @granite-js/video@1.0.44
+
 ## 1.0.43
 
 ### Patch Changes

package/dist/visibility/index.d.ts

@@ -3,5 +3,6 @@ export * from './useIsAppForeground';
 export * from './useVisibility';
 export * from './useVisibilityChanged';
 export * from './useVisibilityChange';
+export * from './useVisibilityEffect';
 export * from './VisibilityProvider';
 export * from './onVisibilityChanged';

package/dist/visibility/react-navigation/useIsFocusedSafely.d.ts

@@ -9,6 +9,7 @@
  * A Hook that safely uses `useIsFocused` provided by `@react-navigation/native`.
  * This Hook is based on `useIsFocused` from `@react-navigation/native`, but modified to not throw errors when `navigation` or `root` objects are `null` or `undefined`.
  * It ensures that users don't see errors even when the code is used in environments where `@react-navigation/native` is not used.
+ * Focus is read as an external store snapshot so changes between rendering and subscription are observed.
  *
  * @returns {boolean} - Returns the focus state of the current screen.
  * @example

package/dist/visibility/useVisibilityChange.d.ts

@@ -14,6 +14,7 @@ export type VisibilityCallback = (state: VisibilityState) => void;
  * @public
  * @category Screen Control
  * @name useVisibilityChange
+ * @deprecated Use `useVisibilityEffect` for effects with cleanup, or `useVisibility` with React's `useEffect` to handle visibility changes.
  * @kind function
  * @description
  * Calls a callback function with the visibility state when the screen's visibility changes.

package/dist/visibility/useVisibilityEffect.d.ts

@@ -0,0 +1,34 @@
+import { type EffectCallback } from 'react';
+/**
+ * @public
+ * @category Screen Control
+ * @name useVisibilityEffect
+ * @description
+ * Runs an effect while the screen is visible, using the visibility state from `useVisibility`.
+ * Cleans up when the screen becomes hidden, the effect callback changes, or the component unmounts.
+ * Like `useEffect`, setup and cleanup run after a render is committed. The callback must be synchronous
+ * and may return a cleanup function. Use `useCallback` to avoid restarting on unrelated renders.
+ * Effects follow the visibility snapshot from the committed render; later focus changes apply on a subsequent commit.
+ * Unlike `useVisibilityChange`, a returned cleanup function is registered with React.
+ * Effect ordering between different screens is not guaranteed; navigation events do not invoke this callback synchronously.
+ *
+ * @param {EffectCallback} effect - Sets up the effect and optionally returns its cleanup function.
+ * @example
+ * ```tsx
+ * import { useCallback } from 'react';
+ * import { BackHandler } from 'react-native';
+ * import { useVisibilityEffect } from '@granite-js/react-native';
+ *
+ * function Screen({ onBack }: { onBack: () => boolean }) {
+ *   useVisibilityEffect(
+ *     useCallback(() => {
+ *       const subscription = BackHandler.addEventListener('hardwareBackPress', onBack);
+ *       return () => subscription.remove();
+ *     }, [onBack])
+ *   );
+ *
+ *   return null;
+ * }
+ * ```
+ */
+export declare function useVisibilityEffect(effect: EffectCallback): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@granite-js/react-native",
-  "version": "1.0.43",
+  "version": "1.0.45",
   "description": "The Granite Framework",
   "bin": {
     "granite": "./bin/cli.js"
@@ -91,8 +91,8 @@
     "@babel/core": "7.28.5",
     "@babel/preset-env": "7.28.5",
     "@babel/preset-typescript": "7.28.5",
-    "@granite-js/native": "1.0.43",
-    "@granite-js/vitest": "1.0.43",
+    "@granite-js/native": "1.0.45",
+    "@granite-js/vitest": "1.0.45",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.1.0",
     "@types/babel__core": "^7",
@@ -114,21 +114,21 @@
     "zod": "^4.1.12"
   },
   "peerDependencies": {
-    "@granite-js/native": "1.0.43",
+    "@granite-js/native": "*",
     "@types/react": "*",
     "brick-module": "*",
     "react": "*",
     "react-native": "*"
   },
   "dependencies": {
-    "@granite-js/blur-view": "1.0.43",
-    "@granite-js/brownfield-module": "1.0.43",
-    "@granite-js/cli": "1.0.43",
-    "@granite-js/jest": "1.0.43",
-    "@granite-js/mpack": "1.0.43",
-    "@granite-js/plugin-core": "1.0.43",
-    "@granite-js/style-utils": "1.0.43",
-    "@granite-js/video": "1.0.43",
+    "@granite-js/blur-view": "1.0.45",
+    "@granite-js/brownfield-module": "1.0.45",
+    "@granite-js/cli": "1.0.45",
+    "@granite-js/jest": "1.0.45",
+    "@granite-js/mpack": "1.0.45",
+    "@granite-js/plugin-core": "1.0.45",
+    "@granite-js/style-utils": "1.0.45",
+    "@granite-js/video": "1.0.45",
     "@standard-schema/spec": "^1.0.0",
     "es-toolkit": "^1.39.8",
     "react-native-url-polyfill": "3.0.0"

package/src/visibility/index.ts

@@ -3,5 +3,6 @@ export * from './useIsAppForeground';
 export * from './useVisibility';
 export * from './useVisibilityChanged';
 export * from './useVisibilityChange';
+export * from './useVisibilityEffect';
 export * from './VisibilityProvider';
-export * from './onVisibilityChanged';
+export * from './onVisibilityChanged';

package/src/visibility/react-navigation/useIsFocusedSafely.spec.tsx

@@ -0,0 +1,216 @@
+import { act, cleanup, render, renderHook } from '@testing-library/react';
+import { type EffectCallback, type ReactNode, useEffect, useLayoutEffect } from 'react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { useIsFocusedSafely } from './useIsFocusedSafely';
+import { AppStateProvider } from '../useIsAppForeground';
+import { VisibilityChangedProvider } from '../useVisibilityChanged';
+import { useVisibilityEffect } from '../useVisibilityEffect';
+
+function createNavigation(initialFocus: boolean) {
+  let focused = initialFocus;
+  const listeners = { focus: new Set<() => void>(), blur: new Set<() => void>() };
+  return {
+    isFocused: () => focused,
+    addListener(event: 'focus' | 'blur', listener: () => void) {
+      listeners[event].add(listener);
+      return () => {
+        listeners[event].delete(listener);
+      };
+    },
+    setFocused(value: boolean) {
+      focused = value;
+      listeners[value ? 'focus' : 'blur'].forEach((listener) => listener());
+    },
+    listenerCount: () => listeners.focus.size + listeners.blur.size,
+  };
+}
+
+let navigation: ReturnType<typeof createNavigation> | undefined;
+vi.mock('./useNavigationSafely', () => ({ useNavigationSafely: () => navigation }));
+
+beforeEach(() => {
+  navigation = undefined;
+});
+afterEach(cleanup);
+
+describe('useIsFocusedSafely', () => {
+  it('returns true without a navigation context', () => {
+    const { result } = renderHook(useIsFocusedSafely);
+    expect(result.current).toBe(true);
+  });
+
+  it.each([false, true])('reads the initial focus snapshot (%s)', (focused) => {
+    navigation = createNavigation(focused);
+    const { result } = renderHook(useIsFocusedSafely);
+    expect(result.current).toBe(focused);
+  });
+
+  it.each([false, true])('detects a change from %s before its subscription starts', (initiallyFocused) => {
+    const store = createNavigation(initiallyFocused);
+    navigation = store;
+    function CommitChange({ children }: { readonly children: ReactNode }) {
+      useLayoutEffect(() => {
+        expect(store.listenerCount()).toBe(0);
+        store.setFocused(!initiallyFocused);
+      }, []);
+      return children;
+    }
+    const { result } = renderHook(useIsFocusedSafely, { wrapper: CommitChange });
+    expect(result.current).toBe(!initiallyFocused);
+  });
+
+  it('reads the current snapshot for focus and blur notifications', () => {
+    const store = createNavigation(false);
+    navigation = store;
+    const { result } = renderHook(useIsFocusedSafely);
+    act(() => store.setFocused(true));
+    expect(result.current).toBe(true);
+    act(() => store.setFocused(false));
+    expect(result.current).toBe(false);
+  });
+
+  it('replaces subscriptions when navigation changes and removes them on unmount', () => {
+    const first = createNavigation(true);
+    const second = createNavigation(false);
+    navigation = first;
+    const { result, rerender, unmount } = renderHook(useIsFocusedSafely);
+    expect(first.listenerCount()).toBe(2);
+    navigation = second;
+    rerender();
+    expect(first.listenerCount()).toBe(0);
+    expect(second.listenerCount()).toBe(2);
+    expect(result.current).toBe(false);
+    act(() => first.setFocused(false));
+    expect(result.current).toBe(false);
+    act(() => second.setFocused(true));
+    expect(result.current).toBe(true);
+    unmount();
+    expect(second.listenerCount()).toBe(0);
+  });
+
+  it('restores the fallback when navigation is removed', () => {
+    const store = createNavigation(false);
+    navigation = store;
+    const { result, rerender } = renderHook(useIsFocusedSafely);
+    navigation = undefined;
+    rerender();
+    expect(result.current).toBe(true);
+    expect(store.listenerCount()).toBe(0);
+  });
+
+  it.each([false, true])('follows committed focus snapshots for visibility effects (initially %s)', (initiallyFocused) => {
+    const store = createNavigation(initiallyFocused);
+    navigation = store;
+    const dispose = vi.fn();
+    const effect = vi.fn(() => dispose);
+    function Consumer() {
+      useVisibilityEffect(effect);
+      return null;
+    }
+    function CommitChange() {
+      useLayoutEffect(() => store.setFocused(!initiallyFocused), []);
+      return null;
+    }
+    const { unmount } = render(
+      <AppStateProvider>
+        <VisibilityChangedProvider isVisible={true}>
+          <Consumer />
+          <CommitChange />
+        </VisibilityChangedProvider>
+      </AppStateProvider>
+    );
+    expect(effect).toHaveBeenCalledTimes(1);
+    expect(dispose).toHaveBeenCalledTimes(initiallyFocused ? 1 : 0);
+    unmount();
+    expect(dispose).toHaveBeenCalledTimes(1);
+    expect(store.listenerCount()).toBe(0);
+  });
+
+  it.each(['mount', 'callback replacement'] as const)(
+    'keeps the committed visibility effect active across rapid refocus during %s',
+    (scenario) => {
+      const store = createNavigation(true);
+      navigation = store;
+      const firstDispose = vi.fn();
+      const firstEffect = vi.fn(() => firstDispose);
+      const dispose = vi.fn();
+      const effect = vi.fn(() => dispose);
+      function Consumer({ callback }: { readonly callback: EffectCallback }) {
+        useVisibilityEffect(callback);
+        return null;
+      }
+      function CommitChange({ changeFocus }: { readonly changeFocus: boolean }) {
+        useLayoutEffect(() => {
+          if (changeFocus) {
+            store.setFocused(false);
+          }
+        }, [changeFocus]);
+        useEffect(() => {
+          if (changeFocus) {
+            expect(effect).toHaveBeenCalledTimes(1);
+            store.setFocused(true);
+            // Refocusing must not restart the effect from the visible commit.
+            expect(effect).toHaveBeenCalledTimes(1);
+            expect(dispose).not.toHaveBeenCalled();
+          }
+        }, [changeFocus]);
+        return null;
+      }
+      const screen = (changeFocus: boolean) => (
+        <AppStateProvider>
+          <VisibilityChangedProvider isVisible={true}>
+            <Consumer callback={changeFocus ? effect : firstEffect} />
+            <CommitChange changeFocus={changeFocus} />
+          </VisibilityChangedProvider>
+        </AppStateProvider>
+      );
+      const { rerender, unmount } = render(screen(scenario === 'mount'));
+      rerender(screen(true));
+      expect(effect).toHaveBeenCalledTimes(1);
+      expect(firstDispose).toHaveBeenCalledTimes(scenario === 'mount' ? 0 : 1);
+      expect(store.listenerCount()).toBe(2);
+
+      rerender(screen(true));
+      expect(effect).toHaveBeenCalledTimes(1);
+      expect(dispose).not.toHaveBeenCalled();
+
+      unmount();
+      expect(dispose).toHaveBeenCalledTimes(1);
+      expect(store.listenerCount()).toBe(0);
+    }
+  );
+
+  it('cleans up and restarts visibility effects as focus snapshots are committed', () => {
+    const store = createNavigation(true);
+    navigation = store;
+    const dispose = vi.fn();
+    const effect = vi.fn(() => dispose);
+    function Consumer() {
+      useVisibilityEffect(effect);
+      return null;
+    }
+    function CommitChange() {
+      useLayoutEffect(() => store.setFocused(false), []);
+      return null;
+    }
+    const { unmount } = render(
+      <AppStateProvider>
+        <VisibilityChangedProvider isVisible={true}>
+          <Consumer />
+          <CommitChange />
+        </VisibilityChangedProvider>
+      </AppStateProvider>
+    );
+    expect(effect).toHaveBeenCalledTimes(1);
+    expect(dispose).toHaveBeenCalledTimes(1);
+    expect(store.listenerCount()).toBe(2);
+
+    act(() => store.setFocused(true));
+    expect(effect).toHaveBeenCalledTimes(2);
+    act(() => store.setFocused(false));
+    expect(dispose).toHaveBeenCalledTimes(2);
+    unmount();
+    expect(dispose).toHaveBeenCalledTimes(2);
+    expect(store.listenerCount()).toBe(0);
+  });
+});

package/src/visibility/react-navigation/useIsFocusedSafely.tsx

@@ -1,4 +1,4 @@
-import { useDebugValue, useEffect, useState } from 'react';
+import { useCallback, useDebugValue, useSyncExternalStore } from 'react';
 import { useNavigationSafely } from './useNavigationSafely';
 
 /**
@@ -12,6 +12,7 @@ import { useNavigationSafely } from './useNavigationSafely';
  * A Hook that safely uses `useIsFocused` provided by `@react-navigation/native`.
  * This Hook is based on `useIsFocused` from `@react-navigation/native`, but modified to not throw errors when `navigation` or `root` objects are `null` or `undefined`.
  * It ensures that users don't see errors even when the code is used in environments where `@react-navigation/native` is not used.
+ * Focus is read as an external store snapshot so changes between rendering and subscription are observed.
  *
  * @returns {boolean} - Returns the focus state of the current screen.
  * @example
@@ -22,37 +23,22 @@ import { useNavigationSafely } from './useNavigationSafely';
  */
 export function useIsFocusedSafely(): boolean {
   const navigation = useNavigationSafely();
-  const isNavigationFocused = () => navigation?.isFocused() ?? true;
-
-  const [isFocused, setIsFocused] = useState(isNavigationFocused());
-
-  const valueToReturn = isNavigationFocused();
-
-  if (isFocused !== valueToReturn) {
-    // If the value has changed since the last render, we need to update it.
-    // This could happen if we missed an update from the event listeners during re-render.
-    // React will process this update immediately, so the old subscription value won't be committed.
-    // It is still nice to avoid returning a mismatched value though, so let's override the return value.
-    // This is the same logic as in https://github.com/facebook/react/tree/master/packages/use-subscription
-    setIsFocused(valueToReturn);
-  }
-
-  useEffect(() => {
-    if (navigation == null) {
-      return;
-    }
-
-    const unsubscribeFocus = navigation.addListener('focus', () => setIsFocused(true));
-
-    const unsubscribeBlur = navigation.addListener('blur', () => setIsFocused(false));
-
-    return () => {
-      unsubscribeFocus();
-      unsubscribeBlur();
-    };
-  }, [navigation]);
-
-  useDebugValue(valueToReturn);
-
-  return valueToReturn;
+  const getSnapshot = useCallback(() => navigation?.isFocused() ?? true, [navigation]);
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => {
+      const unsubscribeFocus = navigation?.addListener('focus', onStoreChange);
+      const unsubscribeBlur = navigation?.addListener('blur', onStoreChange);
+
+      return () => {
+        unsubscribeFocus?.();
+        unsubscribeBlur?.();
+      };
+    },
+    [navigation]
+  );
+
+  const isFocused = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  useDebugValue(isFocused);
+
+  return isFocused;
 }

package/src/visibility/useVisibilityChange.ts

@@ -20,6 +20,7 @@ export type VisibilityCallback = (state: VisibilityState) => void;
  * @public
  * @category Screen Control
  * @name useVisibilityChange
+ * @deprecated Use `useVisibilityEffect` for effects with cleanup, or `useVisibility` with React's `useEffect` to handle visibility changes.
  * @kind function
  * @description
  * Calls a callback function with the visibility state when the screen's visibility changes.
@@ -67,4 +68,3 @@ export function useVisibilityChange(callback: VisibilityCallback) {
     callback(isVisible ? 'visible' : 'hidden');
   }, [callback, isVisible, prevValue]);
 }
-

package/src/visibility/useVisibilityEffect.spec.tsx

@@ -0,0 +1,160 @@
+import { cleanup, render } from '@testing-library/react';
+import { type EffectCallback, type ReactNode } from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { AppStateProvider } from './useIsAppForeground';
+import { VisibilityChangedProvider } from './useVisibilityChanged';
+import * as visibility from './useVisibilityEffect';
+
+const navigation = vi.hoisted(() => ({ focused: true }));
+vi.mock('./react-navigation/useIsFocusedSafely', () => ({
+  useIsFocusedSafely: () => navigation.focused,
+}));
+
+function Consumer({ effect }: { readonly effect: EffectCallback }) {
+  visibility.useVisibilityEffect(effect);
+  return null;
+}
+
+function Boundary({ visible, children }: { readonly visible: boolean; readonly children: ReactNode }) {
+  return (
+    <AppStateProvider>
+      <VisibilityChangedProvider isVisible={visible}>{children}</VisibilityChangedProvider>
+    </AppStateProvider>
+  );
+}
+
+function screen(visible: boolean, effect: EffectCallback) {
+  return (
+    <Boundary visible={visible}>
+      <Consumer effect={effect} />
+    </Boundary>
+  );
+}
+
+afterEach(() => {
+  cleanup();
+  navigation.focused = true;
+});
+
+describe('useVisibilityEffect', () => {
+  it('exports a visibility effect hook', () => {
+    expect(visibility).toHaveProperty('useVisibilityEffect', expect.any(Function));
+  });
+
+  it('does not set up or clean up an effect when mounted and unmounted hidden', () => {
+    const dispose = vi.fn();
+    const effect = vi.fn(() => dispose);
+    const { unmount } = render(screen(false, effect));
+    unmount();
+    expect(effect).not.toHaveBeenCalled();
+    expect(dispose).not.toHaveBeenCalled();
+  });
+
+  it('sets up on visible mount and cleans up on direct unmount', () => {
+    const dispose = vi.fn();
+    const effect = vi.fn(() => dispose);
+    const { unmount } = render(screen(true, effect));
+    expect(effect).toHaveBeenCalledTimes(1);
+    unmount();
+    expect(dispose).toHaveBeenCalledTimes(1);
+  });
+
+  it('cleans up when hidden and sets up again when visible', () => {
+    const dispose = vi.fn();
+    const effect = vi.fn(() => dispose);
+    const { rerender, unmount } = render(screen(true, effect));
+    rerender(screen(false, effect));
+    expect(dispose).toHaveBeenCalledTimes(1);
+    rerender(screen(true, effect));
+    expect(effect).toHaveBeenCalledTimes(2);
+    unmount();
+    expect(dispose).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not clean up again when unmounted after becoming hidden', () => {
+    const dispose = vi.fn();
+    const { rerender, unmount } = render(screen(true, () => dispose));
+    rerender(screen(false, () => dispose));
+    unmount();
+    expect(dispose).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps a stable effect running across visible rerenders', () => {
+    const dispose = vi.fn();
+    const effect = vi.fn(() => dispose);
+    const { rerender } = render(screen(true, effect));
+    rerender(screen(true, effect));
+    expect(effect).toHaveBeenCalledTimes(1);
+    expect(dispose).not.toHaveBeenCalled();
+  });
+
+  it('cleans up the previous callback before running its replacement while visible', () => {
+    const events: string[] = [];
+    const first = () => {
+      events.push('first setup');
+      return () => {
+        events.push('first cleanup');
+      };
+    };
+    const second = () => {
+      events.push('second setup');
+    };
+    const { rerender } = render(screen(true, first));
+    rerender(screen(true, second));
+    expect(events).toEqual(['first setup', 'first cleanup', 'second setup']);
+  });
+
+  it('uses the latest callback when it becomes visible after a hidden update', () => {
+    const first = vi.fn();
+    const second = vi.fn();
+    const { rerender } = render(screen(false, first));
+    rerender(screen(false, second));
+    expect(first).not.toHaveBeenCalled();
+    expect(second).not.toHaveBeenCalled();
+    rerender(screen(true, second));
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+
+  it('allows an effect without a cleanup function', () => {
+    const effect = vi.fn(() => {});
+    const { rerender, unmount } = render(screen(true, effect));
+    rerender(screen(false, effect));
+    unmount();
+    expect(effect).toHaveBeenCalledTimes(1);
+  });
+
+  it('cleans up when navigator focus is lost while native visibility stays true', () => {
+    const dispose = vi.fn();
+    const effect = vi.fn(() => dispose);
+    const { rerender } = render(screen(true, effect));
+    navigation.focused = false;
+    rerender(screen(true, effect));
+    expect(dispose).toHaveBeenCalledTimes(1);
+    navigation.focused = true;
+    rerender(screen(true, effect));
+    expect(effect).toHaveBeenCalledTimes(2);
+  });
+
+  it('keeps sibling visibility boundaries independent', () => {
+    const firstDispose = vi.fn();
+    const secondDispose = vi.fn();
+    const first = vi.fn(() => firstDispose);
+    const second = vi.fn(() => secondDispose);
+    const tree = (firstVisible: boolean) => (
+      <>
+        <Boundary visible={firstVisible}>
+          <Consumer effect={first} />
+        </Boundary>
+        <Boundary visible={true}>
+          <Consumer effect={second} />
+        </Boundary>
+      </>
+    );
+    const { rerender } = render(tree(true));
+    rerender(tree(false));
+    expect(firstDispose).toHaveBeenCalledTimes(1);
+    expect(secondDispose).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+});

package/src/visibility/useVisibilityEffect.ts

@@ -0,0 +1,46 @@
+import { type EffectCallback, useEffect } from 'react';
+import { useVisibility } from './useVisibility';
+
+/**
+ * @public
+ * @category Screen Control
+ * @name useVisibilityEffect
+ * @description
+ * Runs an effect while the screen is visible, using the visibility state from `useVisibility`.
+ * Cleans up when the screen becomes hidden, the effect callback changes, or the component unmounts.
+ * Like `useEffect`, setup and cleanup run after a render is committed. The callback must be synchronous
+ * and may return a cleanup function. Use `useCallback` to avoid restarting on unrelated renders.
+ * Effects follow the visibility snapshot from the committed render; later focus changes apply on a subsequent commit.
+ * Unlike `useVisibilityChange`, a returned cleanup function is registered with React.
+ * Effect ordering between different screens is not guaranteed; navigation events do not invoke this callback synchronously.
+ *
+ * @param {EffectCallback} effect - Sets up the effect and optionally returns its cleanup function.
+ * @example
+ * ```tsx
+ * import { useCallback } from 'react';
+ * import { BackHandler } from 'react-native';
+ * import { useVisibilityEffect } from '@granite-js/react-native';
+ *
+ * function Screen({ onBack }: { onBack: () => boolean }) {
+ *   useVisibilityEffect(
+ *     useCallback(() => {
+ *       const subscription = BackHandler.addEventListener('hardwareBackPress', onBack);
+ *       return () => subscription.remove();
+ *     }, [onBack])
+ *   );
+ *
+ *   return null;
+ * }
+ * ```
+ */
+export function useVisibilityEffect(effect: EffectCallback): void {
+  const isVisible = useVisibility();
+
+  useEffect(() => {
+    if (!isVisible) {
+      return;
+    }
+
+    return effect();
+  }, [effect, isVisible]);
+}