stream-chat-react-native-core 10.0.0-rc.1 → 10.0.0-rc.3

package/src/ai-components/voice-visualization/styles.ts

@@ -0,0 +1,42 @@
+import { LEVEL_RESPONSE, type LevelResponse } from './driver';
+
+/**
+ * What tells the glow and the wave apart besides how they draw, as on iOS.
+ *
+ * - `levelResponse`: the wave's height tracks the level directly, so it follows it smoothly;
+ *   per-syllable jumps would make it jitter. The glow follows it closely.
+ * - `maxScale`: the densest it renders. The glow is soft all over, so 2x is enough; the wave's
+ *   thin line is drawn at the screen's own scale, up to 3x, to stay crisp.
+ * - `contains`: whether a point, centred and normalized to the shorter side with y up, is on the
+ *   shape rather than the empty space around it.
+ */
+export type VoiceVisualizationStyle = {
+  contains: (x: number, y: number) => boolean;
+  /** The shape's bounds as a share of the shorter side, for the area that takes touches. */
+  hitArea: { width: number; height: number };
+  levelResponse: LevelResponse;
+  maxScale: number;
+};
+
+/** How far from the centre a tap still lands on the globe, as a share of the shorter side. */
+const GLOBE_REACH = 0.32;
+
+export const GLOW_STYLE: VoiceVisualizationStyle = {
+  contains: (x, y) => {
+    'worklet';
+    return Math.hypot(x, y) < GLOBE_REACH;
+  },
+  hitArea: { height: 2 * GLOBE_REACH, width: 2 * GLOBE_REACH },
+  levelResponse: LEVEL_RESPONSE.steady,
+  maxScale: 2,
+};
+
+export const WAVE_STYLE: VoiceVisualizationStyle = {
+  contains: (x, y) => {
+    'worklet';
+    return Math.abs(x) < 0.5 && Math.abs(y) < 0.14;
+  },
+  hitArea: { height: 0.28, width: 1 },
+  levelResponse: LEVEL_RESPONSE.smooth,
+  maxScale: 3,
+};

package/src/ai-components/voice-visualization/types.ts

@@ -0,0 +1,44 @@
+import type { ViewProps } from 'react-native';
+
+import type { SharedValue } from 'react-native-reanimated';
+
+/**
+ * What a voice agent is doing, which a voice visualization shows as motion.
+ *
+ * The states differ only in how a visualization moves, never in its colors, and changing the
+ * state eases from one motion into the next.
+ *
+ * - `idle`: waiting to be spoken to, a calm, barely-there shimmer.
+ * - `connecting`: not ready yet, a loader sweep with a pulsing breath.
+ * - `listening`: hearing somebody, a gentle expand and contract.
+ * - `thinking`: working on an answer, a slow turn or a travelling wave.
+ * - `speaking`: talking, strong motion that ebbs and pauses like speech.
+ */
+export type VoiceAgentState = 'idle' | 'connecting' | 'listening' | 'thinking' | 'speaking';
+
+export type VoiceVisualizationProps = Omit<ViewProps, 'children'> & {
+  /** What the agent is doing, which sets how the visualization moves. */
+  state: VoiceAgentState;
+  /**
+   * The level of whoever is talking, from 0 to 1, read once a frame on the UI thread. Feed it at
+   * 15 Hz or more for the visualization to move with the words; `null` animates speech on its own.
+   * See `useDictationAudioLevel` for the level of the microphone while dictating.
+   */
+  audioLevel?: SharedValue<number | null>;
+  /**
+   * One to five colors. Past five are ignored, and colors that cannot be read are skipped. When
+   * omitted or empty, the theme's `voiceVisualization.colors` are used.
+   */
+  colors?: string[];
+  /** From 0 to 2: how far and how fast it moves. Colors never change with it. Defaults to 1. */
+  expressivity?: number;
+  /**
+   * What screen readers read as the value for each state, for example to translate them. Defaults
+   * to "Ready", "Connecting", "Listening", "Thinking" and "Speaking". The label, "Voice agent", is
+   * `accessibilityLabel`.
+   */
+  stateLabels?: Partial<Record<VoiceAgentState, string>>;
+};
+
+/** A color as hue (a fraction of a turn), saturation and value, each from 0 to 1. */
+export type Hsv = { hue: number; saturation: number; value: number };

package/src/ai-components/voice-visualization/useReduceMotion.ts

@@ -0,0 +1,34 @@
+import { useEffect, useState } from 'react';
+import { AccessibilityInfo } from 'react-native';
+
+/**
+ * Whether the system asks for less motion: Reduce Motion on iOS, animations off on Android. It
+ * follows the setting while mounted.
+ *
+ * The AI entry point cannot reach the core SDK's own hook, which also only applies once its
+ * accessibility layer is enabled; the voice visualizations always honour the setting, as on iOS
+ * and Android.
+ */
+export const useReduceMotion = () => {
+  const [reduceMotion, setReduceMotion] = useState(false);
+
+  useEffect(() => {
+    let mounted = true;
+    AccessibilityInfo.isReduceMotionEnabled?.()
+      .then((enabled) => {
+        // It starts off; only turning it on needs a render.
+        if (mounted && enabled) setReduceMotion(true);
+      })
+      .catch(() => undefined);
+    const subscription = AccessibilityInfo.addEventListener?.(
+      'reduceMotionChanged',
+      setReduceMotion,
+    );
+    return () => {
+      mounted = false;
+      subscription?.remove();
+    };
+  }, []);
+
+  return reduceMotion;
+};

package/src/ai-components/voice-visualization/useVoiceVisualization.ts

@@ -0,0 +1,153 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useColorScheme } from 'react-native';
+
+import {
+  type FrameInfo,
+  runOnUI,
+  useFrameCallback,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
+
+import {
+  advanceDriver,
+  createDriverState,
+  hoverDriver,
+  tapDriver,
+  type VoiceDriverInput,
+} from './driver';
+import { audioLevelInput, expressivityInput } from './math';
+import { FALLBACK_COLOR, luminance, toHsvPalette } from './palette';
+import type { VoiceVisualizationStyle } from './styles';
+import type { VoiceVisualizationProps } from './types';
+import { useReduceMotion } from './useReduceMotion';
+
+import { useTheme } from '../contexts';
+
+/** How long the visualization takes to fade in once its first frame is drawn, as on iOS. */
+const FADE_IN_MS = 300;
+
+/** Whether to draw for a dark background: the theme's backdrop when readable, else the scheme. */
+const useDark = (backdropColor: string | undefined) => {
+  const scheme = useColorScheme();
+  return useMemo(() => {
+    const backdrop = backdropColor ? luminance(backdropColor) : null;
+    if (backdrop !== null) return backdrop < 0.5 ? 1 : 0;
+    return scheme === 'dark' ? 1 : 0;
+  }, [backdropColor, scheme]);
+};
+
+/**
+ * A voice visualization's motion, advanced once a frame on the UI thread.
+ *
+ * The driver lives in a shared value the renderers derive from, so a frame redraws without
+ * re-rendering React, and `audioLevel` is read in the frame callback, so a level changing many
+ * times a second re-renders nothing either.
+ */
+export const useVoiceVisualization = (
+  { audioLevel, colors, expressivity, state }: VoiceVisualizationProps,
+  style: VoiceVisualizationStyle,
+) => {
+  const { theme } = useTheme();
+  const reduceMotion = useReduceMotion();
+  const themeColors = theme.voiceVisualization?.colors;
+  const dark = useDark(theme.voiceVisualization?.backdropColor);
+
+  const colorsKey = (colors ?? []).join('|');
+  const themeKey = (themeColors ?? []).join('|');
+  const palette = useMemo(() => {
+    const own = toHsvPalette(colors ?? []);
+    if (own.length) return own;
+    const fromTheme = toHsvPalette(themeColors ?? []);
+    return fromTheme.length ? fromTheme : toHsvPalette([FALLBACK_COLOR]);
+    // Keyed by the colors themselves, so a new array of the same colors changes nothing.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [colorsKey, themeKey]);
+
+  const input: VoiceDriverInput = {
+    audioLevel: null,
+    colors: palette,
+    expressivity: expressivityInput(expressivity),
+    reduceMotion,
+    state,
+  };
+
+  // Starts settled on the first input, so the first frame shows it rather than easing into it.
+  const [initialDriver] = useState(() => createDriverState(input, style.levelResponse));
+  const driver = useSharedValue(initialDriver);
+  const inputValue = useSharedValue(input);
+  const darkValue = useSharedValue(dark);
+  const opacity = useSharedValue(0);
+  const fadingIn = useSharedValue(false);
+
+  useEffect(() => {
+    inputValue.value = {
+      audioLevel: null,
+      colors: palette,
+      expressivity: expressivityInput(expressivity),
+      reduceMotion,
+      state,
+    };
+  }, [expressivity, inputValue, palette, reduceMotion, state]);
+
+  useEffect(() => {
+    darkValue.value = dark;
+  }, [dark, darkValue]);
+
+  const onFrame = useCallback(
+    (frame: FrameInfo) => {
+      'worklet';
+      const seconds = (frame.timeSincePreviousFrame ?? 0) / 1000;
+      const current = inputValue.value;
+      const level = audioLevelInput(audioLevel ? audioLevel.value : null);
+      const next = level === current.audioLevel ? current : { ...current, audioLevel: level };
+      driver.modify((d) => {
+        'worklet';
+        advanceDriver(d, next, seconds);
+        return d;
+      });
+      // It fades in once it has something to show, rather than flashing empty while the first
+      // frame lands.
+      if (!fadingIn.value) {
+        fadingIn.value = true;
+        opacity.value = withTiming(1, { duration: FADE_IN_MS });
+      }
+    },
+    [audioLevel, driver, fadingIn, inputValue, opacity],
+  );
+  useFrameCallback(onFrame);
+
+  /** A tap at a point centred and normalized to the shorter side, y up. */
+  const tap = useCallback(
+    (x: number, y: number) => {
+      runOnUI((tapX: number, tapY: number) => {
+        'worklet';
+        driver.modify((d) => {
+          'worklet';
+          tapDriver(d, inputValue.value, tapX, tapY);
+          return d;
+        });
+      })(x, y);
+    },
+    [driver, inputValue],
+  );
+
+  /** Where a pointer hovers, or null once it has left. */
+  const hover = useCallback(
+    (x: number | null, y: number | null) => {
+      runOnUI((hoverX: number | null, hoverY: number | null) => {
+        'worklet';
+        driver.modify((d) => {
+          'worklet';
+          hoverDriver(d, inputValue.value, hoverX, hoverY);
+          return d;
+        });
+      })(x, y);
+    },
+    [driver, inputValue],
+  );
+
+  return { dark: darkValue, driver, hover, opacity, tap };
+};
+
+export type VoiceVisualization = ReturnType<typeof useVoiceVisualization>;

package/src/ai-components/voice-visualization/waveGeometry.ts

@@ -0,0 +1,137 @@
+import { Skia, type SkPath } from '@shopify/react-native-skia';
+
+import { driverReact, driverScale, type VoiceDriverState } from './driver';
+import { clamp, mix, saturate, smoothstep, speechEnv, vivid } from './math';
+
+const POINTS = 160;
+export const WAVE_STOPS = 13;
+export const WAVE_START = -0.42;
+export const WAVE_END = 0.42;
+
+/** The stops' positions along the gradient, evenly spaced. */
+export const WAVE_POSITIONS = Array.from({ length: WAVE_STOPS }, (_, s) => s / (WAVE_STOPS - 1));
+
+const sq = (x: number) => {
+  'worklet';
+  return x * x;
+};
+
+const bandCenter = (i: number, seg: number, t: number) => {
+  'worklet';
+  switch (i) {
+    case 0:
+      return 0.5 * seg + 0.12 * Math.sin(t * 0.13);
+    case 1:
+      return 1.5 * seg + 0.13 * Math.sin(t * 0.11 + 2.1);
+    case 2:
+      return 2.5 * seg + 0.12 * Math.sin(t * 0.17 + 4.2);
+    case 3:
+      return 3.5 * seg + 0.12 * Math.sin(t * 0.15 + 1);
+    default:
+      return 4.5 * seg + 0.12 * Math.sin(t * 0.1 + 3.3);
+  }
+};
+
+/** The string's height above its centre line at each point, centred and normalized, y up. */
+export const waveHeights = (d: VoiceDriverState) => {
+  'worklet';
+  const t = d.time;
+  const react = driverReact(d);
+  const center = d.load * 0.3 * Math.sin(t * 1.3);
+  const freq = 24 + 26 * react + 10 * d.flow;
+  const speak = smoothstep(0.6, 1, react);
+  const drive = mix(speak * 0.26 * speechEnv(t), 0.3 * d.mic, d.voice);
+  const reach = 0.018 + 0.022 * react + drive + 0.14 * d.flow + 0.1 * d.load;
+  const tapAlive = d.tapAge < 1.5;
+  const hovered = d.hoverAmount > 0.001;
+  const xs: number[] = [];
+  const ys: number[] = [];
+  for (let i = 0; i <= POINTS; i++) {
+    const x = WAVE_START + ((WAVE_END - WAVE_START) * i) / POINTS;
+    let y = Math.exp(-sq((x - center) / 0.18)) * reach * Math.sin(x * freq - t * 5);
+    if (tapAlive) {
+      y +=
+        Math.exp(-sq((x - d.tapX) / 0.12)) *
+        Math.sin((x - d.tapX) * 40 - d.tapAge * 24) *
+        Math.exp(-d.tapAge * 2.6) *
+        0.05;
+    }
+    if (hovered) {
+      y +=
+        Math.exp(-sq((x - d.hoverX) / 0.12)) *
+        Math.sin((x - d.hoverX) * 40 - t * 7) *
+        d.hoverAmount *
+        0.04;
+    }
+    xs.push(x);
+    ys.push(y);
+  }
+  return { xs, ys };
+};
+
+type LegacyPath = SkPath & {
+  lineTo: (x: number, y: number) => void;
+  moveTo: (x: number, y: number) => void;
+};
+
+/**
+ * The wave as a path in a `width` by `height` canvas. Newer Skia versions build immutable paths with
+ * `PathBuilder`; earlier 2.x versions mutate `SkPath` itself.
+ */
+export const wavePath = (d: VoiceDriverState, width: number, height: number): SkPath => {
+  'worklet';
+  const m = Math.min(width, height);
+  const scale = driverScale(d);
+  const { xs, ys } = waveHeights(d);
+  const px = (i: number) => width / 2 + xs[i] * m * scale;
+  const py = (i: number) => height / 2 - ys[i] * m * scale;
+  if (Skia.PathBuilder) {
+    const builder = Skia.PathBuilder.Make();
+    builder.moveTo(px(0), py(0));
+    for (let i = 1; i < xs.length; i++) builder.lineTo(px(i), py(i));
+    return builder.build();
+  }
+  const path = Skia.Path.Make() as LegacyPath;
+  path.moveTo(px(0), py(0));
+  for (let i = 1; i < xs.length; i++) path.lineTo(px(i), py(i));
+  return path;
+};
+
+/**
+ * The string's colors at its gradient stops, as RGBA from 0 to 1: up to five bands drifting along
+ * it, weighed by how near their centres are, its ends fading out.
+ */
+export const waveColors = (d: VoiceDriverState, dark: number) => {
+  'worklet';
+  const band: number[][] = [];
+  for (let i = 0; i < 5; i++) {
+    const rgb = [0, 0, 0];
+    vivid(d.colors[i], dark, rgb);
+    band.push(rgb);
+  }
+  const seg = 1 / Math.max(d.count, 1);
+  const bandWidth = seg * 0.7;
+  const stops: Float32Array[] = [];
+  for (let s = 0; s < WAVE_STOPS; s++) {
+    const x = WAVE_START + ((WAVE_END - WAVE_START) * s) / (WAVE_STOPS - 1);
+    const gx = clamp(x + 0.5, 0, 1);
+    const color = [0, 0, 0];
+    let total = 1e-4;
+    for (let i = 0; i < 5; i++) {
+      const present = i === 0 ? 1 : clamp(d.count - i, 0, 1);
+      const weight = Math.exp(-sq((gx - bandCenter(i, seg, d.time)) / bandWidth)) * present;
+      for (let j = 0; j < 3; j++) color[j] += band[i][j] * weight;
+      total += weight;
+    }
+    for (let j = 0; j < 3; j++) color[j] /= total;
+    saturate(color, 1.2);
+    saturate(color, d.sat);
+    const alpha = clamp(smoothstep(0.4, 0.24, Math.abs(x)) * d.bright, 0, 1);
+    stops.push(new Float32Array([color[0], color[1], color[2], alpha]));
+  }
+  return stops;
+};
+
+/** The line is 0.6% of the shorter side, and never under 1.5 device pixels, as on Android and iOS. */
+export const waveStrokeWidth = (width: number, height: number, pixelRatio: number) =>
+  Math.max(0.006 * Math.min(width, height), 1.5 / pixelRatio);

package/src/components/AITypingIndicatorView/hooks/useAIState.ts

@@ -2,16 +2,16 @@ import { AIState, AIStates, Channel } from 'stream-chat';
 
 import { useStateStore } from '../../../hooks/useStateStore';
 
-// Re-export the canonical `AIStates` from the LLC so existing imports keep working
-// (`import { AIStates } from '.../AITypingIndicatorView'`).
+// Re-exports `AIStates` from `stream-chat` so it can be imported from this module.
 export { AIStates };
 
 const selector = (state: { aiState: AIState }) => ({ aiState: state.aiState });
 
 /**
- * A hook that returns the current state of the AI.
- * @param {Channel} channel - The channel for which we want to know the AI state.
- * @returns {{ aiState: AIState }} The current AI state for the given channel.
+ * Returns the AI state of `channel`, or the idle state when there is no channel state.
+ *
+ * @param channel The channel to read the AI state of.
+ * @returns The current AI state.
  */
 export const useAIState = (channel?: Channel): { aiState: AIState } =>
   useStateStore(channel?.state, selector) ?? { aiState: AIStates.Idle };

package/src/components/Accessibility/CompositeAccessibilityProbe.tsx

@@ -5,31 +5,19 @@ import { HiddenA11yText } from './HiddenA11yText';
 
 export type CompositeAccessibilityProbeProps = {
   /**
-   * The accessibility label that VoiceOver / TalkBack should announce for the
-   * wrapped content. When `undefined`, the probe is a no-op and the children
-   * render with no a11y modifications — use this to skip the wrapper when the
-   * SDK's a11y opt-in is off.
+   * Label that VoiceOver and TalkBack announce for the wrapped content. `undefined` renders the
+   * children unchanged.
    */
   label: string | undefined;
 };
 
 /**
- * Wraps decorative visual content with a single, cross platform stable
- * accessibility focus stop carrying the provided `label`.
+ * Gives decorative visual content (avatars, icons, composed graphics) a single screen reader focus
+ * stop that announces `label`, and hides the visual subtree from screen readers.
  *
- * iOS auto collapses descendants when a parent View is `accessible`, but on
- * Android `importantForAccessibility='no-hide-descendants'` on the parent
- * gets defeated by deeply nested descendants that set their own
- * `accessible={true}` (our SDK's `<Avatar>` does this). A zero size accessible
- * `<Text>` sidesteps that - Text is always accessible by default on both
- * platforms and carries the label cleanly, while the visual subtree is
- * marked decorative. More importantly, it's discoverable very very easily
- * by screen readers.
- *
- * Use this anywhere you have non-Text visual content (avatars, icons,
- * composed graphics) that should announce as a single semantic unit with a
- * curated label, rather than letting screen readers walk the visual tree
- * verbosely.
+ * The label lives on a visually hidden `<Text>` sibling because on Android a parent's
+ * `importantForAccessibility='no-hide-descendants'` is defeated by nested descendants that set
+ * `accessible` themselves, such as `<Avatar>`.
  */
 export const CompositeAccessibilityProbe = ({
   children,

package/src/components/Accessibility/HiddenA11yText.tsx

@@ -3,34 +3,24 @@ import { StyleSheet, Text } from 'react-native';
 
 export type HiddenA11yTextProps = {
   /**
-   * The text to inject into the accessibility tree. Rendered as actual Text
-   * content (not as `accessibilityLabel`) so the parent's compose loop on
-   * Android picks it up — Text without its own label isn't
-   * `isAccessibilityFocusable`, so it gets concatenated into the parent's
-   * announcement rather than being skipped as a drill-in target.
-   *
-   * Pass the result of `useA11yLabel(...)` directly: when SDK a11y is
-   * opt-out the value is `undefined` and the component renders nothing.
+   * Text added to the accessibility tree. It is rendered as `Text` content so that the parent's
+   * label composition on Android includes it. `undefined` (such as the result of `useA11yLabel`
+   * while accessibility is disabled) renders nothing.
    */
   label: string | undefined;
 };
 
 /**
- * A visually invisible Text that exists only to contribute extra information
- * to a screen reader's announcement. Use it inside a parent that auto-composes
- * descendant labels (Pressable, or any View with `accessible` + `accessibilityRole`)
- * to splice in supplementary state like "you reacted", "and N more", etc.
- *
- * Not for "this whole element should be one focus stop with a curated label" -
- * use `CompositeAccessibilityProbe` for that.
+ * Visually hidden text that adds information, such as "you reacted", to a screen reader
+ * announcement. Use it inside a parent that composes its descendants' labels (a `Pressable`, or a
+ * `View` with `accessible` and `accessibilityRole`). For one focus stop with a curated label, use
+ * `CompositeAccessibilityProbe`.
  */
 export const HiddenA11yText = ({ label }: HiddenA11yTextProps) => {
   if (!label) return null;
-  // Both content and accessibilityLabel are set to the same string. Content
-  // keeps the Text on the parent's compose loop (label-only would make it
-  // `isAccessibilityFocusable` and potentially skipped on Android — though
-  // the opacity:0 hidden style usually saves it). accessibilityLabel keeps
-  // testing-library `getByLabelText(...)` queries working.
+  // The label is both content and `accessibilityLabel`. Content keeps the Text in the parent's
+  // label composition on Android (a label-only Text is focusable and may be skipped); the label
+  // keeps testing-library `getByLabelText` queries working.
   return (
     <Text accessibilityLabel={label} style={styles.hidden}>
       {label}

package/src/components/Accessibility/NotificationAnnouncer.tsx

@@ -8,21 +8,14 @@ import { useNetworkConnectionState } from '../Chat/hooks/useNetworkConnectionSta
 import { useSettledWSConnectionHealth } from '../Chat/hooks/useWSConnectionState';
 
 /**
- * Mirrors stream-chat-react's `<NotificationAnnouncer />`. RN does not yet have a
- * unified Notification queue, so this component currently announces only
- * connection-state transitions (offline → online and back) gated on
- * `accessibility.announceConnectionState`. Per-channel error announcements can
- * be wired in by a future PR via `useChannelContext().error`.
- *
- * Renders nothing. Mount once inside `<Channel>` (or wherever the active chat
- * surface lives).
+ * Announces connection state transitions (connected, offline, reconnecting) to screen readers when
+ * `accessibility.announceConnectionState` is on. Renders nothing; mount once inside `<Channel>`.
  */
 export const NotificationAnnouncer = () => {
   const { announceConnectionState, enabled } = useAccessibilityContext();
   const isNetworkOnline = useNetworkConnectionState()?.isOnline;
   const isWSOnline = useSettledWSConnectionHealth();
-  // The socket is what 'connected' means to a chat user; the device network only decides which
-  // of the two offline messages is truthful.
+  // Online means the WebSocket is healthy; the network state only picks the offline message.
   const isOnline = !!isWSOnline;
   const announce = useAccessibilityAnnouncer();
   const { t } = useTranslationContext();

package/src/components/Accessibility/OverlayA11yShield.tsx

@@ -21,21 +21,14 @@ const useShouldActivateTrap = (): boolean => {
 };
 
 /**
- * Android only accessibility focus trap for the OverlayProvider's children
- * tree. iOS handles modal focus traps natively via `accessibilityViewIsModal`
- * on each overlay's root, but Android has no equivalent prop - the only
- * JS side mechanism is to mark siblings as `'no-hide-descendants'`.
+ * Android accessibility focus trap for the overlay host's children. iOS traps focus natively with
+ * `accessibilityViewIsModal` on each overlay root; Android can only mark siblings as
+ * `'no-hide-descendants'`.
  *
- * The shield wraps `{children}` in a single View whose `importantForAccessibility`
- * flips to `'no-hide-descendants'` whenever any focus trapping overlay is
- * active (the full screen image/video gallery or the message context menu).
- * When closed, the wrapper is a transparent passthrough.
- *
- * In terms of rerendering, only the wrapper View commits new props on overlay state
- * transitions. The `{children}` element reference is stable across renders,
- * so React reconciliation does not rerender any component below the wrapper.
- *
- * On iOS the wrapper is skipped entirely.
+ * Wraps `{children}` in a View that sets `importantForAccessibility='no-hide-descendants'` while an
+ * overlay (the image or video gallery, or the message context menu) is open and an accessibility
+ * service runs. Only the wrapper re-renders on overlay changes, since the `children` element is
+ * stable. On iOS it renders only the children.
  */
 export function OverlayA11yShield({ children }: PropsWithChildren) {
   const shouldActivateTrap = useShouldActivateTrap();

package/src/components/Accessibility/hooks/useIncomingMessageAnnouncements.ts

@@ -39,15 +39,16 @@ export type UseIncomingMessageAnnouncementsParams = {
 };
 
 /**
- * Mirrors stream-chat-react's `useIncomingMessageAnnouncements`:
- *  - 1 message → "New message from {{user}}"
- *  - >1 messages within throttle window → "{{count}} new messages"
- *  - Throttled to one announcement per second
- *  - Bounded `announcedMessageIds` set so a long-running session does not leak.
+ * Announces new messages from other users to screen readers: "New message from {{user}}" for one,
+ * "{{count}} new messages" for several within the one second throttle window.
  *
- * Subscribes to `channel.on('message.new')`. When AccessibilityContext.enabled
- * is false OR `announceNewMessages` is false, the hook is a no-op (no
- * subscription is opened, no listener cost is paid).
+ * Does nothing, and opens no subscription, unless accessibility and `announceNewMessages` are
+ * enabled. Announced message IDs are tracked to skip duplicates and cleared past 500 entries.
+ *
+ * @param params.activeThreadId The open thread, if any. Only its replies are announced; without
+ * it only non-reply messages are.
+ * @param params.channel The channel whose `message.new` events are observed.
+ * @param params.ownUserId The current user's ID. Their own messages are not announced.
  */
 export const useIncomingMessageAnnouncements = ({
   activeThreadId,

package/src/components/Accessibility/useAccessibilityAnnouncer.ts

@@ -17,11 +17,10 @@ export const AccessibilityAnnouncerContext = createContext<
 >(undefined);
 
 /**
- * Returns the imperative announcer. When called outside the AccessibilityProvider's
- * announcer context (which happens any time the SDK's a11y is disabled), this
- * returns a no-op.
+ * Returns the function that announces a message to the screen reader. Outside the announcer
+ * context, as when SDK accessibility is disabled, it is a no-op.
  *
- * Mirrors the React SDK's `useAriaLiveAnnouncer` so cross-SDK code reads the same.
+ * @returns The `announce` function.
  */
 export const useAccessibilityAnnouncer = (): AccessibilityAnnounce => {
   const contextValue = useContext(AccessibilityAnnouncerContext);

package/src/components/Attachment/Attachment.tsx

@@ -43,13 +43,9 @@ export type AttachmentPropsWithContext = Pick<
   'isAttachmentEqual' | 'myMessageTheme' | 'urlPreviewType'
 > &
   Pick<MessageContextValue, 'message'> & {
-    /**
-     * The attachment to render
-     */
+    /** The attachment to render. */
     attachment: AttachmentType;
-    /**
-     * The index of the attachment in the message
-     */
+    /** The index of the attachment in the message. */
     index?: number;
   };
 
@@ -81,7 +77,7 @@ const AttachmentWithContext = (props: AttachmentPropsWithContext) => {
     return <Gallery images={[attachment]} />;
   }
 
-  // The `!attachment.og_scrape_url` is added for cases, where the url preview is not an image but a video.
+  // URL previews (`og_scrape_url`) whose media is a video are excluded.
   if (isVideoAttachment(attachment) && !attachment.og_scrape_url) {
     return isVideoPlayerAvailable() ? (
       <Gallery videos={[attachment]} />
@@ -151,9 +147,7 @@ const MemoizedAttachment = React.memo(
 
 export type AttachmentProps = Partial<AttachmentPropsWithContext>;
 
-/**
- * Attachment - The message attachment
- */
+/** Renders a single message attachment according to its type. */
 export const Attachment = (props: AttachmentProps) => {
   const { attachment } = props;