stream-chat-react-native-core 9.9.1 → 9.9.2-beta.2

package/src/components/ChannelDetails/components/navigation-section/MediaList.tsx

@@ -1,12 +1,5 @@
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import {
-  ActivityIndicator,
-  FlatList,
-  type FlatListProps,
-  StyleSheet,
-  useWindowDimensions,
-  View,
-} from 'react-native';
+import { ActivityIndicator, FlatList, type FlatListProps, StyleSheet, View } from 'react-native';
 
 import {
   formatMessage,
@@ -30,6 +23,7 @@ import { useTheme } from '../../../../contexts/themeContext/ThemeContext';
 import { useTranslationContext } from '../../../../contexts/translationContext/TranslationContext';
 import { getNotificationErrorOptions } from '../../../../hooks/actions/useChannelActions';
 import { useStateStore } from '../../../../hooks/useStateStore';
+import { useWindowContentWidth } from '../../../../hooks/useWindowContentWidth';
 import { isVideoPlayerAvailable } from '../../../../native';
 import { primitives } from '../../../../theme';
 import { FileTypes } from '../../../../types/types';
@@ -41,9 +35,6 @@ import { NotificationTargetProvider } from '../../../Notifications/NotificationT
 import { EmptyList } from '../../../UIComponents/EmptyList';
 import { type MediaTile, useMediaList } from '../../hooks/useMediaList';
 
-const NUMBER_OF_COLUMNS = 3;
-const GRID_GAP = primitives.spacingXxxs;
-
 export type MediaListProps = {
   /**
    * Besides the existing default behavior of the media list, you can attach additional props to
@@ -60,6 +51,9 @@ export type MediaListProps = {
   searchSource?: MessageSearchSource;
 };
 
+const NUMBER_OF_COLUMNS = 3;
+const GRID_GAP = primitives.spacingXxxs;
+
 const keyExtractor = (item: MediaTile, index: number) => `${item.message.id}-${index}`;
 
 const listStateSelector = (state: SearchSourceState<MessageResponse>) => ({
@@ -77,7 +71,7 @@ const MediaListContent = ({ additionalFlatListProps }: MediaListProps) => {
     },
   } = useTheme();
   const styles = useStyles();
-  const { width } = useWindowDimensions();
+  const width = useWindowContentWidth();
   const { icons, MediaItem } = useComponentsContext();
 
   const { addNotification } = useNotificationApi();
@@ -128,7 +122,6 @@ const MediaListContent = ({ additionalFlatListProps }: MediaListProps) => {
 
   const tiles = useMediaList(messages);
 
-  // Tile side length: full width minus the inter-column gaps, split across the columns.
   const tileSize = useMemo(
     () => (width - GRID_GAP * (NUMBER_OF_COLUMNS - 1)) / NUMBER_OF_COLUMNS,
     [width],

package/src/components/ChannelDetails/components/navigation-section/MediaListLoadingSkeleton.tsx

@@ -1,7 +1,8 @@
 import React, { useMemo } from 'react';
-import { StyleSheet, useWindowDimensions, View } from 'react-native';
+import { StyleSheet, View } from 'react-native';
 
 import { useTheme } from '../../../../contexts/themeContext/ThemeContext';
+import { useWindowContentWidth } from '../../../../hooks/useWindowContentWidth';
 import { primitives } from '../../../../theme';
 import { NativeShimmerView } from '../../../UIComponents/NativeShimmerView';
 
@@ -17,7 +18,8 @@ export const MediaListLoadingSkeleton = () => {
   const {
     theme: { semantics },
   } = useTheme();
-  const { width } = useWindowDimensions();
+  // Same derivation as `MediaList`, so the skeleton's tiles match the grid that replaces it.
+  const width = useWindowContentWidth();
   const styles = useStyles();
 
   const tileSize = (width - GRID_GAP * (NUMBER_OF_COLUMNS - 1)) / NUMBER_OF_COLUMNS;

package/src/components/ImageGallery/components/ImageGalleryFooter.tsx

@@ -127,7 +127,10 @@ export const ImageGalleryFooterWithContext = (props: ImageGalleryFooterProps) =>
       pointerEvents={'box-none'}
       style={styles.wrapper}
     >
-      <ReanimatedSafeAreaView edges={['bottom']} style={[styles.container, footerStyle]}>
+      <ReanimatedSafeAreaView
+        edges={['bottom', 'left', 'right']}
+        style={[styles.container, footerStyle]}
+      >
         {asset.type === FileTypes.Video ? (
           ImageGalleryVideoControls ? (
             <ImageGalleryVideoControls attachmentId={asset.id} />

package/src/components/ImageGallery/components/ImageGalleryHeader.tsx

@@ -18,6 +18,23 @@ import { ImageGalleryState } from '../../../state-store/image-gallery-state-stor
 import { primitives } from '../../../theme';
 import { getDateString } from '../../../utils/i18n/getDateString';
 import { Button } from '../../ui/Button/Button';
+import { SafeAreaView } from '../../UIComponents/SafeAreaViewWrapper';
+
+// Never called - it exists only so `ReturnType` below can name the animated component's type.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- used in type position only
+const createAnimatedSafeAreaViewType = () => Animated.createAnimatedComponent(SafeAreaView);
+
+/**
+ * A frame-aware wrapper, matching `ImageGalleryFooter`. `SafeAreaView` compares the window inset
+ * against its own measured frame, so a nested instance contributes nothing once an ancestor has
+ * already narrowed the subtree - unlike `useSafeAreaInsets`, which is window-global and would
+ * double-pad this header inside `ChannelDetailsModal`, which insets its own root.
+ *
+ * `createAnimatedComponent` is guarded because a stripped-down Reanimated mock may not provide it.
+ */
+const ReanimatedSafeAreaView = (
+  Animated.createAnimatedComponent ? Animated.createAnimatedComponent(SafeAreaView) : SafeAreaView
+) as ReturnType<typeof createAnimatedSafeAreaViewType>;
 
 const imageGallerySelector = (state: ImageGalleryState) => ({
   asset: state.assets[state.currentIndex],
@@ -69,7 +86,10 @@ export const ImageGalleryHeader = (props: ImageGalleryHeaderProps) => {
       onLayout={(event) => setHeight(event.nativeEvent.layout.height)}
       pointerEvents={'box-none'}
     >
-      <Animated.View style={[styles.container, { paddingTop: topInset }, headerStyle]}>
+      <ReanimatedSafeAreaView
+        edges={['left', 'right']}
+        style={[styles.container, { paddingTop: topInset }, headerStyle]}
+      >
         <View style={styles.innerContainer}>
           <View style={styles.leftContainer}>
             <Button
@@ -90,7 +110,7 @@ export const ImageGalleryHeader = (props: ImageGalleryHeaderProps) => {
           </View>
           <View style={styles.rightContainer} accessibilityLabel='Right element' />
         </View>
-      </Animated.View>
+      </ReanimatedSafeAreaView>
     </View>
   );
 };

package/src/components/ImageGallery/components/ImageGrid.tsx

@@ -6,7 +6,7 @@ import type { ImageGalleryGridProps } from './types';
 import { useImageGalleryContext } from '../../../contexts/imageGalleryContext/ImageGalleryContextBase';
 import { useTheme } from '../../../contexts/themeContext/ThemeContext';
 import { useStateStore } from '../../../hooks/useStateStore';
-import { useViewport } from '../../../hooks/useViewport';
+import { useWindowContentWidth } from '../../../hooks/useWindowContentWidth';
 import type {
   ImageGalleryAsset,
   ImageGalleryState,
@@ -33,12 +33,12 @@ export type GridImageItem = ImageGalleryAsset & {
 
 const GridImage = ({ item }: { item: GridImageItem }) => {
   const styles = useStyles();
-  const { vw } = useViewport();
+  const contentWidth = useWindowContentWidth();
   const { ...restItem } = item;
 
   const { numberOfImageGalleryGridColumns, selectAndClose, thumb_url, type, uri } = restItem;
 
-  const size = vw(100) / (numberOfImageGalleryGridColumns || 3) - 2;
+  const size = contentWidth / (numberOfImageGalleryGridColumns || 3) - 2;
 
   return (
     <Pressable accessibilityLabel='Grid Image' onPress={selectAndClose}>
@@ -76,6 +76,8 @@ export const ImageGalleryGrid = (props: ImageGalleryGridProps) => {
   } = useTheme();
   const styles = useStyles();
 
+  const columns = numberOfImageGalleryGridColumns || 3;
+
   const imageGridItems = assets.map((photo, index) => ({
     ...photo,
     numberOfImageGalleryGridColumns,
@@ -91,7 +93,8 @@ export const ImageGalleryGrid = (props: ImageGalleryGridProps) => {
       contentContainerStyle={styles.contentContainer}
       data={imageGridItems as GridImageItem[]}
       keyExtractor={(item, index) => `${item.uri}-${index}`}
-      numColumns={numberOfImageGalleryGridColumns || 3}
+      key={columns}
+      numColumns={columns}
       renderItem={renderItem}
       style={container}
     />

package/src/components/KeyboardCompatibleView/KeyboardCompatibleView.tsx

@@ -215,11 +215,13 @@ export class KeyboardCompatibleView extends React.Component<
   };
 
   _handleAppStateChange = (nextAppState: AppStateStatus) => {
-    if (this.state.appState.match(/inactive|background/) && nextAppState === 'active') {
+    // `inactive` is visible-but-unfocused (Split View), so it must not tear down the listeners.
+    // Mirrors `useAppStateListener`.
+    if (this.state.appState === 'background' && nextAppState === 'active') {
       this.setKeyboardListeners();
     }
 
-    if (nextAppState.match(/inactive|background/)) {
+    if (nextAppState === 'background') {
       this.unsetKeyboardListeners();
     }
 

package/src/components/Message/MessageItemView/MessageItemView.tsx

@@ -128,7 +128,7 @@ export type MessageItemViewPropsWithContext = Pick<
   >;
 
 const MessageItemViewWithContext = (props: MessageItemViewPropsWithContext) => {
-  const { width } = Dimensions.get('screen');
+  const { width } = Dimensions.get('window');
   const {
     alignment,
     channel,

package/src/components/UIComponents/BottomSheetModal.tsx

@@ -45,6 +45,7 @@ import { useResolvedModalAccessibilityProps } from '../../a11y/hooks/useResolved
 import { BottomSheetProvider } from '../../contexts/bottomSheetContext/BottomSheetContext';
 import { useTheme } from '../../contexts/themeContext/ThemeContext';
 import { useScreenOrientation, useStableCallback } from '../../hooks';
+import { useHorizontalInsets } from '../../hooks/useHorizontalInsets';
 import { primitives } from '../../theme';
 
 const supportedOrientations: ModalProps['supportedOrientations'] = [
@@ -661,6 +662,7 @@ const useStyles = () => {
   const {
     theme: { semantics },
   } = useTheme();
+  const horizontalInsets = useHorizontalInsets();
   return useMemo(
     () =>
       StyleSheet.create({
@@ -671,6 +673,10 @@ const useStyles = () => {
         },
         contentContainer: {
           flex: 1,
+          // A RN `Modal` is its own native window, so a consumer's `SafeAreaView` never reaches
+          // this - it insets itself. Spread rather than assigned: a `paddingLeft: 0` longhand
+          // would override a themed `paddingHorizontal` for that side.
+          ...horizontalInsets,
         },
         handle: {
           alignSelf: 'center',
@@ -691,6 +697,6 @@ const useStyles = () => {
           flex: 1,
         },
       }),
-    [semantics.backgroundCoreScrim, semantics.backgroundCoreElevation1],
+    [semantics.backgroundCoreScrim, semantics.backgroundCoreElevation1, horizontalInsets],
   );
 };

package/src/components/UIComponents/SafeAreaViewWrapper.tsx

@@ -27,7 +27,7 @@ export const SafeAreaViewWrapper = ({
 }: PropsWithChildren<{ style: ViewStyle }> & SafeAreaViewProps) => {
   return (
     <SafeAreaProvider>
-      <SafeAreaView edges={['bottom', 'top']} style={style} {...restProps}>
+      <SafeAreaView edges={['bottom', 'left', 'right', 'top']} style={style} {...restProps}>
         {children}
       </SafeAreaView>
     </SafeAreaProvider>

package/src/hooks/__tests__/useAppStateListener.test.tsx

@@ -5,54 +5,87 @@ import { renderHook, waitFor } from '@testing-library/react-native';
 import { useAppStateListener } from '../useAppStateListener';
 
 describe('useAppStateListener', () => {
-  const onForegroundFn = jest.fn();
-  const onBackgroundFn = jest.fn();
-  const addEventListenerSpy = jest.spyOn(AppState, 'addEventListener');
-  AppState.currentState = 'active';
-
-  it.each<[AppStateStatus, jest.Mock, number]>([
-    ['background', onBackgroundFn, 1],
-    ['active', onForegroundFn, 1],
-    ['inactive', onBackgroundFn, 2],
-    ['active', onForegroundFn, 2],
-    ['background', onBackgroundFn, 3],
-  ])(
-    'Appropriate callback called when appstate is changed to %s)',
-    async (newAppState, expectedCallback, times) => {
-      renderHook(
-        (props: {
-          onBackground?: (() => void) | undefined;
-          onForeground?: (() => void) | undefined;
-        }) => useAppStateListener(props.onForeground, props.onBackground),
-        {
-          initialProps: {
-            onBackground: onBackgroundFn,
-            onForeground: onForegroundFn,
-          },
-        },
-      );
-      const appStateOnChangeMockFunc = addEventListenerSpy.mock.calls[0][1];
-
-      appStateOnChangeMockFunc(newAppState);
-      await waitFor(() => {
-        expect(expectedCallback).toHaveBeenCalledTimes(times);
-      });
-    },
-  );
-  it('check unmount behavior', async () => {
+  const renderListener = (onForegroundFn: jest.Mock, onBackgroundFn: jest.Mock) => {
+    const addEventListenerSpy = jest.spyOn(AppState, 'addEventListener');
+    addEventListenerSpy.mockClear();
+    const utils = renderHook(() => useAppStateListener(onForegroundFn, onBackgroundFn));
+    const emit = addEventListenerSpy.mock.calls[0][1] as (state: AppStateStatus) => void;
+    return { ...utils, addEventListenerSpy, emit };
+  };
+
+  beforeEach(() => {
     jest.clearAllMocks();
-    const { unmount } = renderHook(
-      (props: {
-        onBackground?: (() => void) | undefined;
-        onForeground?: (() => void) | undefined;
-      }) => useAppStateListener(props.onForeground, props.onBackground),
-      {
-        initialProps: {
-          onBackground: onBackgroundFn,
-          onForeground: onForegroundFn,
-        },
-      },
-    );
+    AppState.currentState = 'active';
+  });
+
+  it('calls onBackground when the app is backgrounded', async () => {
+    const onForeground = jest.fn();
+    const onBackground = jest.fn();
+    const { emit } = renderListener(onForeground, onBackground);
+
+    emit('inactive');
+    emit('background');
+
+    await waitFor(() => {
+      expect(onBackground).toHaveBeenCalledTimes(1);
+    });
+    expect(onForeground).not.toHaveBeenCalled();
+  });
+
+  it('calls onForeground when the app returns to active from background', async () => {
+    const onForeground = jest.fn();
+    const onBackground = jest.fn();
+    const { emit } = renderListener(onForeground, onBackground);
+
+    emit('inactive');
+    emit('background');
+    emit('inactive');
+    emit('active');
+
+    await waitFor(() => {
+      expect(onForeground).toHaveBeenCalledTimes(1);
+    });
+    expect(onBackground).toHaveBeenCalledTimes(1);
+  });
+
+  // Regression: an app in Split View sits `inactive` while fully visible. Treating that as
+  // backgrounded closed the WebSocket while the user was reading the chat.
+  it('does NOT treat `inactive` as backgrounded', async () => {
+    const onForeground = jest.fn();
+    const onBackground = jest.fn();
+    const { emit } = renderListener(onForeground, onBackground);
+
+    emit('inactive');
+    emit('active');
+    emit('inactive');
+
+    await waitFor(() => {
+      expect(onBackground).not.toHaveBeenCalled();
+    });
+    expect(onForeground).not.toHaveBeenCalled();
+  });
+
+  it('fires each callback once per transition even with repeated events', async () => {
+    const onForeground = jest.fn();
+    const onBackground = jest.fn();
+    const { emit } = renderListener(onForeground, onBackground);
+
+    emit('background');
+    emit('background');
+    emit('active');
+    emit('active');
+
+    await waitFor(() => {
+      expect(onBackground).toHaveBeenCalledTimes(1);
+    });
+    expect(onForeground).toHaveBeenCalledTimes(1);
+  });
+
+  it('check unmount behavior', async () => {
+    const onForeground = jest.fn();
+    const onBackground = jest.fn();
+    const { addEventListenerSpy, unmount } = renderListener(onForeground, onBackground);
+
     const { remove: appStateOnChangeSubscriptionRemoveMockFunc } =
       addEventListenerSpy.mock.results[0].value;
 

package/src/hooks/messagePreview/__tests__/useMessagePreviewText.test.tsx

@@ -0,0 +1,59 @@
+import React, { PropsWithChildren } from 'react';
+
+import { renderHook, waitFor } from '@testing-library/react-native';
+
+import type { Attachment } from 'stream-chat';
+
+import { Chat } from '../../../components/Chat/Chat';
+import { initiateClientWithChannels } from '../../../mock-builders/api/initiateClientWithChannels';
+import {
+  generateAudioAttachment,
+  generateFileAttachment,
+  generateImageAttachment,
+} from '../../../mock-builders/attachments';
+import { generateMessage } from '../../../mock-builders/generator/message';
+import { useMessagePreviewText } from '../useMessagePreviewText';
+
+describe('useMessagePreviewText', () => {
+  const render = async (message: ReturnType<typeof generateMessage>) => {
+    const { client } = await initiateClientWithChannels();
+    const wrapper = ({ children }: PropsWithChildren) => <Chat client={client}>{children}</Chat>;
+    const { result } = renderHook(() => useMessagePreviewText({ message }), { wrapper });
+    return result;
+  };
+
+  const withAttachments = (attachments?: Attachment[]) =>
+    generateMessage({ attachments, text: '' });
+
+  // Drafts can have no text and no attachments; they rendered "{{count}} Files" / "0 Audios".
+  it.each([
+    ['absent', undefined],
+    ['empty', []],
+  ])('returns an empty preview when attachments are %s', async (_, attachments) => {
+    const result = await render(withAttachments(attachments));
+    expect(result.current).toBe('');
+  });
+
+  it('counts mixed attachments as files', async () => {
+    const result = await render(
+      withAttachments([generateImageAttachment(), generateFileAttachment()]),
+    );
+    // Counted copy comes from the translations, which load asynchronously.
+    await waitFor(() => expect(result.current).toBe('2 Files'));
+  });
+
+  it('counts audio-only attachments as audios', async () => {
+    const result = await render(
+      withAttachments([generateAudioAttachment(), generateAudioAttachment()]),
+    );
+    // Counted copy comes from the translations, which load asynchronously.
+    await waitFor(() => expect(result.current).toBe('2 Audios'));
+  });
+
+  it('prefers the message text over its attachments', async () => {
+    const result = await render(
+      generateMessage({ attachments: [generateFileAttachment()], text: 'hello' }),
+    );
+    expect(result.current).toBe('hello');
+  });
+});

package/src/hooks/messagePreview/useMessagePreviewText.tsx

@@ -64,6 +64,10 @@ export const useMessagePreviewText = ({
     return message.text;
   }
 
+  if (!attachmentsLength) {
+    return '';
+  }
+
   if (onlyImages) {
     if (images?.length === 1) {
       return t('Photo');

package/src/hooks/useAppStateListener.ts

@@ -5,8 +5,8 @@ export const useAppStateListener = (onForeground?: () => void, onBackground?: ()
   // React Native 0.87 widened `AppState.currentState` to `string | null | undefined` (it was
   // `AppStateStatus` up to 0.86). Normalise once here so the comparisons below stay total on
   // every supported version.
-  const appStateRef = useRef<AppStateStatus>(
-    (AppState.currentState as AppStateStatus | null | undefined) ?? 'unknown',
+  const isBackgroundedRef = useRef(
+    ((AppState.currentState as AppStateStatus | null | undefined) ?? 'unknown') === 'background',
   );
   const onForegroundRef = useRef(onForeground);
   const onBackgroundRef = useRef(onBackground);
@@ -17,13 +17,21 @@ export const useAppStateListener = (onForeground?: () => void, onBackground?: ()
 
   useEffect(() => {
     const handleAppStateChange = (nextAppState: AppStateStatus) => {
-      const prevAppState = appStateRef.current;
-      if (prevAppState.match(/inactive|background/) && nextAppState === 'active') {
+      // Only `background` is backgrounded. `inactive` is visible-but-unfocused, and from iOS 27 an
+      // app in Split View stays `inactive` the whole time it is side by side. Transitions pass
+      // through `inactive` in both directions, so ignoring it still observes both.
+      if (nextAppState === 'background') {
+        if (!isBackgroundedRef.current) {
+          isBackgroundedRef.current = true;
+          onBackgroundRef.current?.();
+        }
+        return;
+      }
+
+      if (nextAppState === 'active' && isBackgroundedRef.current) {
+        isBackgroundedRef.current = false;
         onForegroundRef.current?.();
-      } else if (prevAppState === 'active' && nextAppState.match(/inactive|background/)) {
-        onBackgroundRef.current?.();
       }
-      appStateRef.current = nextAppState;
     };
     const subscription = AppState.addEventListener('change', handleAppStateChange);
 

package/src/hooks/useHorizontalInsets.ts

@@ -0,0 +1,37 @@
+import { useMemo } from 'react';
+import { ViewStyle } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+
+/**
+ * Horizontal safe area padding for a surface that spans the full window width.
+ *
+ * **Only for surfaces an integrator cannot wrap.** Everything the SDK renders in-tree is left
+ * alone: the integrator wraps their screen in a `SafeAreaView` and the whole subtree - including
+ * absolutely positioned children, which track their containing block's border box - narrows with
+ * it. Applying this to an in-tree surface double-pads it for every integrator who already wraps.
+ *
+ * In practice that leaves React Native's own `Modal`, which renders in a separate native window.
+ * A bottom sheet or an overlay is *not* automatically out of reach - check where it actually
+ * mounts. Prefer a `SafeAreaView` (see `ImageGalleryHeader`/`Footer`) wherever one fits: it
+ * compares the window inset against its own measured frame, so a nested instance contributes
+ * nothing once an ancestor has narrowed the subtree. This hook reads `useSafeAreaInsets`, which is
+ * window-global and has no such protection.
+ *
+ * `left` and `right` are never collapsed into one value: from iOS 27 the system stacks its controls
+ * down a single edge, so the two differ (measured 0 and 84 on iPhone Duo).
+ *
+ * A side whose inset is 0 is omitted rather than emitted as `paddingLeft: 0`, because a longhand
+ * overrides a `padding` shorthand for that side - emitting a zero would silently drop padding the
+ * component or a consumer's theme had already set.
+ */
+export const useHorizontalInsets = (): ViewStyle => {
+  const { left, right } = useSafeAreaInsets();
+
+  return useMemo<ViewStyle>(
+    () => ({
+      ...(left > 0 ? { paddingLeft: left } : null),
+      ...(right > 0 ? { paddingRight: right } : null),
+    }),
+    [left, right],
+  );
+};

package/src/hooks/useScreenDimensions.ts

@@ -6,6 +6,13 @@ import { Dimensions, ScaledSize } from 'react-native';
  * a percentage of the screen height (vh) and viewport width (vw). It
  * dynamically updates dimensions on changes in device orientation.
  *
+ * @deprecated These are percentages of the *screen*, not of the window the app is laid out in. The
+ * two diverge once the window is resizable (Split View, fold/unfold, Android multi-window): we
+ * measured an 834pt screen behind a 417pt window, and an outer 466pt screen behind a 951pt window.
+ *
+ * Use {@link useViewport}, the same API measured against the window, or `onLayout` on your own view
+ * inside a component that does not fill the window.
+ *
  * @returns {Object} An object containing functions vh and vw.
  */
 export const useScreenDimensions = (rounded?: boolean) => {

package/src/hooks/useWindowContentWidth.ts

@@ -0,0 +1,31 @@
+import { useSafeAreaFrame, useSafeAreaInsets } from 'react-native-safe-area-context';
+
+/**
+ * Width available to a surface that spans the window, minus the horizontal safe area.
+ *
+ * Deliberately *not* measured. `onLayout` reports a frame after the window has already resized, so
+ * anything sized from it - tile sizes in a grid, for instance - visibly resizes a frame late on a
+ * rotation or a fold.
+ *
+ * The frame comes from `useSafeAreaFrame`, not `useWindowDimensions`: the frame and the insets are
+ * delivered by the *same* native event and set in the same handler, so they update together in one
+ * render. Mixing `Dimensions` with the insets desyncs them - the window width lands first and the
+ * insets a render later, producing an extra intermediate size (and, for anything deriving an image
+ * URL from it, an extra fetch).
+ *
+ * Assumes the caller fills the window. A component rendered inside a narrower container must pass
+ * that container's width via `containerWidth`, or measure it itself and accept the frame of lag
+ * that comes with measuring.
+ *
+ * @param containerWidth Width of the surface, when it is known and narrower than the window.
+ *
+ * @example
+ * const contentWidth = useWindowContentWidth();
+ * const tileSize = contentWidth / columns;
+ */
+export const useWindowContentWidth = (containerWidth?: number) => {
+  const { width: frameWidth } = useSafeAreaFrame();
+  const { left, right } = useSafeAreaInsets();
+
+  return containerWidth ?? frameWidth - left - right;
+};

package/src/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "9.9.1"
+  "version": "9.9.2-beta.2"
 }