@oxyhq/bloom 1.13.0 → 1.14.1

package/src/avatar/Avatar.tsx

@@ -10,8 +10,8 @@ import { Z_INDEX } from '../styles/z-index';
 import { useAvatarPlaceholder } from './context';
 import { LiveBadge } from './LiveBadge';
 import { AvatarRing, getRingOuterSize } from './AvatarRing';
-import { SQUIRCLE_PATH } from './squircle-path';
-import type { AvatarProps, AvatarRingConfig } from './types';
+import { resolveAvatarShape } from './resolve-shape';
+import type { AvatarProps, AvatarRingConfig, AvatarShapePath } from './types';
 
 // Google Contacts-inspired palette used to pick a deterministic background
 // color for name-based placeholder avatars.
@@ -45,10 +45,19 @@ import DEFAULT_AVATAR_IMAGE from './default-avatar';
 
 let clipIdCounter = 0;
 
-function SquircleImage({
+/**
+ * Renders the avatar image clipped to an arbitrary outline.
+ *
+ * The path and the SVG viewport share one coordinate space, so a 0–1 squircle
+ * and a 0–100 named shape both work without rewriting their numbers: the
+ * viewport is declared at the path's own scale and the whole thing is drawn at
+ * `size` pixels.
+ */
+function ClippedImage({
   uri,
   fallbackSource,
   size,
+  shape,
   fallbackColor,
   placeholderIcon,
   name,
@@ -57,6 +66,7 @@ function SquircleImage({
   uri?: string;
   fallbackSource?: AvatarProps['fallbackSource'];
   size: number;
+  shape: AvatarShapePath;
   fallbackColor: string;
   placeholderIcon?: React.ReactNode;
   name?: string;
@@ -71,6 +81,8 @@ function SquircleImage({
     );
   }
 
+  const span = shape.viewBox ?? 1;
+
   return (
     <>
       {/* Hidden RN Image for error detection on remote URIs */}
@@ -81,16 +93,16 @@ function SquircleImage({
           onError={onError}
         />
       )}
-      <Svg width={size} height={size} viewBox="0 0 1 1">
+      <Svg width={size} height={size} viewBox={`0 0 ${span} ${span}`}>
         <Defs>
           <ClipPath id={clipId}>
-            <Path d={SQUIRCLE_PATH} />
+            <Path d={shape.d} />
           </ClipPath>
         </Defs>
         <SvgImage
           href={href}
-          width={1}
-          height={1}
+          width={span}
+          height={span}
           preserveAspectRatio="xMidYMid slice"
           clipPath={`url(#${clipId})`}
         />
@@ -183,6 +195,10 @@ const AvatarComponent: React.FC<AvatarProps> = ({
   const theme = useTheme();
   const placeholderConfig = useAvatarPlaceholder();
   const radius = size / 2;
+  // `null` means "a circle", which is drawn with borderRadius and never reaches
+  // the SVG renderer. Memoised so an inline `shape={{ d: … }}` object literal
+  // does not produce a new clip descriptor on every render.
+  const clipShape = useMemo(() => resolveAvatarShape(shape), [shape]);
   const hasName = typeof name === 'string' && name.trim().length > 0;
   // Priority: explicit placeholderColor > deterministic color from name > theme default.
   const fallbackColor =
@@ -265,7 +281,7 @@ const AvatarComponent: React.FC<AvatarProps> = ({
   const ringElement = resolvedRing ? (
     <AvatarRing
       size={size}
-      shape={shape}
+      shape={clipShape}
       colors={resolvedRing.colors}
       width={ringWidth}
       gap={ringGap}
@@ -278,11 +294,12 @@ const AvatarComponent: React.FC<AvatarProps> = ({
   // fills the container exactly.
   const avatarBox = (
     <View style={[styles.avatarBox, { width: size, height: size }]}>
-      {shape === 'squircle' ? (
-        <SquircleImage
+      {clipShape ? (
+        <ClippedImage
           uri={effectiveUri}
           fallbackSource={fallbackSource}
           size={size}
+          shape={clipShape}
           fallbackColor={fallbackColor}
           placeholderIcon={resolvedPlaceholderIcon}
           name={name}

package/src/avatar/AvatarRing.tsx

@@ -3,8 +3,8 @@ import { View, StyleSheet } from 'react-native';
 import Svg, { Circle, Defs, LinearGradient, Path, Stop } from 'react-native-svg';
 
 import { Z_INDEX } from '../styles/z-index';
-import { SQUIRCLE_PATH } from './squircle-path';
-import type { AvatarRingGradientDirection, AvatarShape } from './types';
+import type { ResolvedAvatarShape } from './resolve-shape';
+import type { AvatarRingGradientDirection } from './types';
 
 // Module counter for unique gradient element ids — mirrors the `clipIdCounter`
 // pattern in `Avatar.tsx`. Deterministic (no `Math.random()`) so ids are stable
@@ -25,8 +25,8 @@ export function getRingOuterSize(size: number, width: number, gap: number): numb
 interface AvatarRingProps {
   /** Avatar diameter in px (the inner content size, before any gap). */
   size: number;
-  /** Matches the avatar shape. */
-  shape: AvatarShape;
+  /** The avatar's resolved outline, or `null` for a circle. */
+  shape: ResolvedAvatarShape;
   /** Solid ring: one color. Gradient ring: 2+ colors. */
   colors: string | string[];
   /** Ring stroke width in px. */
@@ -79,10 +79,10 @@ const AvatarRingComponent: React.FC<AvatarRingProps> = ({
   // box; drawn as a plain border it is a full circle → radius `outer / 2`.
   const ringRadius = outer / 2;
 
-  // SVG is only needed for gradients (both shapes) and for the squircle
-  // outline. A solid circle ring is a plain bordered View — cheaper, and it
-  // keeps the common case off the SVG renderer entirely.
-  const needsSvg = wantsGradient || shape === 'squircle';
+  // SVG is only needed for gradients and for non-circular outlines. A solid
+  // circle ring is a plain bordered View — cheaper, and it keeps the common
+  // case off the SVG renderer entirely.
+  const needsSvg = wantsGradient || shape !== null;
 
   if (!needsSvg) {
     return (
@@ -127,15 +127,22 @@ const AvatarRingComponent: React.FC<AvatarRingProps> = ({
     { zIndex: gap > 0 ? Z_INDEX.base : Z_INDEX.raised },
   ];
 
-  if (shape === 'squircle') {
-    // The path lives in 0–1 space, so the stroke width is expressed in the same
-    // units; center-stroking it and letting the viewport clip the outer half
-    // yields a ~`width`-px band on the inner edge of the outer box.
+  if (shape !== null) {
+    // The path lives in its own square space, so the stroke width has to be
+    // expressed in those units too: one unit is `outer / span` px. Center-
+    // stroking and letting the viewport clip the outer half yields a
+    // ~`width`-px band on the inner edge of the outer box, hence the doubling.
+    const span = shape.viewBox ?? 1;
     return (
       <View pointerEvents="none" style={overlayStyle}>
-        <Svg width={outer} height={outer} viewBox="0 0 1 1">
+        <Svg width={outer} height={outer} viewBox={`0 0 ${span} ${span}`}>
           {gradientDefs}
-          <Path d={SQUIRCLE_PATH} fill="none" stroke={stroke} strokeWidth={(width / outer) * 2} />
+          <Path
+            d={shape.d}
+            fill="none"
+            stroke={stroke}
+            strokeWidth={(width / outer) * 2 * span}
+          />
         </Svg>
       </View>
     );

package/src/avatar/index.ts

@@ -4,7 +4,14 @@ export type { AvatarPlaceholderConfig } from './context';
 export type {
   AvatarProps,
   AvatarShape,
+  AvatarShapePath,
   AvatarRingConfig,
   AvatarRingGradientDirection,
 } from './types';
 export { defaultAvatarSource } from './default-avatar';
+export {
+  AVATAR_SHAPE_PATHS,
+  AVATAR_SHAPE_LABELS,
+  NAMED_SHAPE_VIEW_BOX,
+} from './shape-paths';
+export type { AvatarShapeName } from './shape-paths';

package/src/avatar/resolve-shape.ts

@@ -0,0 +1,33 @@
+import { SQUIRCLE_PATH } from './squircle-path';
+import { AVATAR_SHAPE_PATHS, NAMED_SHAPE_VIEW_BOX } from './shape-paths';
+import type { AvatarShape, AvatarShapePath } from './types';
+
+/**
+ * A shape reduced to what the renderers need: either nothing (a circle, drawn
+ * with `borderRadius` and no SVG at all) or one outline plus the size of the
+ * square space it is drawn in.
+ */
+export type ResolvedAvatarShape = AvatarShapePath | null;
+
+/**
+ * Turns the public `shape` prop into an outline.
+ *
+ * Returns `null` for a circle so callers can keep the cheap `borderRadius`
+ * path — the common case never touches `react-native-svg`. An unknown string
+ * also returns `null`: a shape name that does not resolve should degrade to a
+ * plain circular avatar, never to a blank hole where a face should be.
+ */
+export function resolveAvatarShape(shape: AvatarShape | AvatarShapePath | undefined): ResolvedAvatarShape {
+  if (!shape || shape === 'circle') return null;
+
+  if (typeof shape !== 'string') {
+    return { d: shape.d, viewBox: shape.viewBox ?? 1 };
+  }
+
+  if (shape === 'squircle') {
+    return { d: SQUIRCLE_PATH, viewBox: 1 };
+  }
+
+  const named = AVATAR_SHAPE_PATHS[shape];
+  return named ? { d: named, viewBox: NAMED_SHAPE_VIEW_BOX } : null;
+}

package/src/avatar/shape-paths.ts

@@ -0,0 +1,150 @@
+/**
+ * Named avatar outlines.
+ *
+ * Each entry is an SVG path drawn in a 100×100 square coordinate space, scaled
+ * at render time to the avatar's pixel size. That space is declared once in
+ * {@link NAMED_SHAPE_VIEW_BOX} rather than baked into the numbers, so the paths
+ * can be read and edited at human-friendly magnitudes. The built-in squircle
+ * lives in `squircle-path.ts` and uses a 0–1 space; both are supported because
+ * {@link AvatarShapePath} carries its own `viewBox`.
+ *
+ * `circle` is deliberately absent: a circular avatar is rendered with
+ * `borderRadius` and never reaches the SVG renderer.
+ */
+
+/** Side length of the coordinate space every path below is drawn in. */
+export const NAMED_SHAPE_VIEW_BOX = 100;
+
+export type AvatarShapeName =
+  | 'square' | 'slanted' | 'arch' | 'semicircle'
+  | 'oval' | 'pill' | 'triangle' | 'arrow' | 'fan'
+  | 'diamond' | 'clamshell' | 'pentagon' | 'gem' | 'very-sunny'
+  | 'sunny' | '4-sided-cookie' | '6-sided-cookie' | '7-sided-cookie'
+  | '9-sided-cookie' | '12-sided-cookie' | '4-leaf-clover'
+  | '8-leaf-clover' | 'burst' | 'soft-burst' | 'boom' | 'soft-boom'
+  | 'flower' | 'puffy' | 'puffy-diamond' | 'ghost-ish'
+  | 'pixel-circle' | 'pixel-triangle' | 'bun' | 'heart';
+
+export const AVATAR_SHAPE_PATHS: Record<AvatarShapeName, string> = {
+  // --- Basic ---
+  square:
+    'M12 0H88Q100 0 100 12V88Q100 100 88 100H12Q0 100 0 88V12Q0 0 12 0Z',
+  slanted:
+    'M22 0H88Q100 0 100 12V78Q100 100 78 100H12Q0 100 0 88V22Q0 0 22 0Z',
+  arch:
+    'M50 0Q100 0 100 50V88Q100 100 88 100H12Q0 100 0 88V50Q0 0 50 0Z',
+  semicircle:
+    'M0 50A50 50 0 0 1 100 50V88Q100 100 88 100H12Q0 100 0 88Z',
+
+  // --- Organic ---
+  oval:
+    'M50 2C78 2 96 22 96 50S78 98 50 98S4 78 4 50S22 2 50 2Z',
+  pill:
+    'M34 4H66Q96 4 96 34V66Q96 96 66 96H34Q4 96 4 66V34Q4 4 34 4Z',
+  triangle:
+    'M50 5L95 90Q97 95 92 95H8Q3 95 5 90Z',
+  arrow:
+    'M50 0L100 45Q100 52 94 52H68V92Q68 100 58 100H42Q32 100 32 92V52H6Q0 52 0 45Z',
+  fan:
+    'M50 8Q90 8 96 48Q100 78 70 96Q50 108 30 96Q0 78 4 48Q10 8 50 8Z',
+
+  // --- Geometric ---
+  diamond:
+    'M50 2L96 50L50 98L4 50Z',
+  clamshell:
+    'M10 20Q10 4 26 4H74Q90 4 90 20V60Q90 96 50 96Q10 96 10 60Z',
+  pentagon:
+    'M50 2L97 36L79 96H21L3 36Z',
+  gem:
+    'M30 4H70L98 36L50 98L2 36Z',
+
+  // --- Sunny/Cookie ---
+  'very-sunny':
+    'M50 0L58 20L78 6L72 28L96 22L82 42L100 50L82 58L96 78L72 72L78 94L58 80L50 100L42 80L22 94L28 72L4 78L18 58L0 50L18 42L4 22L28 28L22 6L42 20Z',
+  sunny:
+    'M50 4L60 24L80 10L74 32L98 28L84 48L100 50L84 52L98 72L74 68L80 90L60 76L50 96L40 76L20 90L26 68L2 72L16 52L0 50L16 48L2 28L26 32L20 10L40 24Z',
+  '4-sided-cookie':
+    'M50 2Q76 22 76 50Q76 78 50 98Q24 78 24 50Q24 22 50 2Z',
+  '6-sided-cookie':
+    'M50 2Q72 10 82 30Q92 52 80 74Q66 96 44 96Q22 96 10 74Q-2 52 10 30Q22 10 50 2Z',
+  '7-sided-cookie':
+    'M50 2Q70 6 84 22Q96 40 94 62Q90 82 74 94Q56 102 38 96Q20 88 10 70Q2 50 8 32Q18 10 50 2Z',
+  '9-sided-cookie':
+    'M50 2Q64 4 76 14Q86 26 92 42Q94 58 88 72Q78 86 64 94Q50 98 36 94Q22 86 12 72Q6 58 8 42Q14 26 24 14Q36 4 50 2Z',
+  '12-sided-cookie':
+    'M50 2L62 6L74 14L84 26L90 40L92 54L88 68L80 80L68 88L54 92L40 90L28 84L18 72L10 58L8 44L12 30L20 18L32 10L44 4Z',
+
+  // --- Nature ---
+  '4-leaf-clover':
+    'M50 4Q70 4 70 26Q96 26 96 50Q96 74 70 74Q70 96 50 96Q30 96 30 74Q4 74 4 50Q4 26 30 26Q30 4 50 4Z',
+  '8-leaf-clover':
+    'M50 2Q60 16 72 8Q84 16 80 30Q96 32 92 46Q100 60 86 66Q92 80 78 84Q76 98 60 92Q52 100 42 92Q28 98 24 84Q10 80 16 66Q2 60 10 46Q6 32 22 30Q18 16 30 8Q42 16 50 2Z',
+  burst:
+    'M50 0L56 30L80 6L62 34L100 26L70 44L100 50L70 56L100 74L62 66L80 94L56 70L50 100L44 70L20 94L38 66L0 74L30 56L0 50L30 44L0 26L38 34L20 6L44 30Z',
+  'soft-burst':
+    'M50 4L58 28L78 8L66 32L96 24L76 44L98 50L76 56L96 76L66 68L78 92L58 72L50 96L42 72L22 92L34 68L4 76L24 56L2 50L24 44L4 24L34 32L22 8L42 28Z',
+  boom:
+    'M50 0L54 18L62 2L60 20L76 6L68 24L88 14L76 30L98 24L82 38L100 38L86 46L100 50L86 54L100 62L82 62L98 76L76 70L88 86L68 76L76 94L60 80L62 98L54 82L50 100L46 82L38 98L40 80L24 94L32 76L12 86L24 70L2 76L18 62L0 62L14 54L0 50L14 46L0 38L18 38L2 24L24 30L12 14L32 24L24 6L40 20L38 2L46 18Z',
+  'soft-boom':
+    'M50 4L56 22L68 6L64 26L82 14L74 32L94 24L82 40L100 36L86 48L100 50L86 52L100 64L82 60L94 76L74 68L82 86L64 74L68 94L56 78L50 96L44 78L32 94L36 74L18 86L26 68L6 76L18 60L0 64L14 52L0 50L14 48L0 36L18 40L6 24L26 32L18 14L36 26L32 6L44 22Z',
+  flower:
+    'M50 4Q62 18 72 10Q82 18 76 32Q90 30 88 44Q98 50 88 56Q90 70 76 68Q82 82 72 90Q62 82 50 96Q38 82 28 90Q18 82 24 68Q10 70 12 56Q2 50 12 44Q10 30 24 32Q18 18 28 10Q38 18 50 4Z',
+  puffy:
+    'M34 6Q50-4 66 6Q84 6 90 22Q104 34 96 50Q104 66 90 78Q84 94 66 94Q50 104 34 94Q16 94 10 78Q-4 66 4 50Q-4 34 10 22Q16 6 34 6Z',
+  'puffy-diamond':
+    'M50 2Q66 10 72 4Q86 12 84 28Q98 32 94 48Q100 64 86 70Q88 86 72 88Q62 98 48 94Q34 100 26 86Q12 88 8 72Q-2 62 6 48Q0 32 16 28Q14 12 28 4Q38 10 50 2Z',
+
+  // --- Fun ---
+  'ghost-ish':
+    'M20 96V40Q20 4 50 4Q80 4 80 40V96L70 86L60 96L50 86L40 96L30 86Z',
+  'pixel-circle':
+    'M30 4H70V4H86V14H96V30H100V70H96V86H86V96H70V100H30V96H14V86H4V70H0V30H4V14H14V4H30Z',
+  'pixel-triangle':
+    'M42 4H58V18H70V32H82V46H94V60H100V100H0V60H6V46H18V32H30V18H42Z',
+  bun:
+    'M12 54Q-4 24 20 8Q44-6 68 8Q92 22 94 50Q96 72 76 88Q56 100 36 96Q14 90 12 54Z',
+  heart:
+    'M50 90C25 70 2 55 2 32Q2 10 24 6Q40 2 50 18Q60 2 76 6Q98 10 98 32Q98 55 75 70Z',
+};
+
+/**
+ * Display labels for the named shapes, in the order a picker should show them.
+ * Exported so consumers building a shape picker do not re-derive the order (or
+ * the capitalisation) themselves.
+ */
+export const AVATAR_SHAPE_LABELS: { name: AvatarShapeName; label: string }[] = [
+  { name: 'square', label: 'Square' },
+  { name: 'slanted', label: 'Slanted' },
+  { name: 'arch', label: 'Arch' },
+  { name: 'semicircle', label: 'Semicircle' },
+  { name: 'oval', label: 'Oval' },
+  { name: 'pill', label: 'Pill' },
+  { name: 'triangle', label: 'Triangle' },
+  { name: 'arrow', label: 'Arrow' },
+  { name: 'fan', label: 'Fan' },
+  { name: 'diamond', label: 'Diamond' },
+  { name: 'clamshell', label: 'Clamshell' },
+  { name: 'pentagon', label: 'Pentagon' },
+  { name: 'gem', label: 'Gem' },
+  { name: 'very-sunny', label: 'Very Sunny' },
+  { name: 'sunny', label: 'Sunny' },
+  { name: '4-sided-cookie', label: '4-Sided Cookie' },
+  { name: '6-sided-cookie', label: '6-Sided Cookie' },
+  { name: '7-sided-cookie', label: '7-Sided Cookie' },
+  { name: '9-sided-cookie', label: '9-Sided Cookie' },
+  { name: '12-sided-cookie', label: '12-Sided Cookie' },
+  { name: '4-leaf-clover', label: '4-Leaf Clover' },
+  { name: '8-leaf-clover', label: '8-Leaf Clover' },
+  { name: 'burst', label: 'Burst' },
+  { name: 'soft-burst', label: 'Soft Burst' },
+  { name: 'boom', label: 'Boom' },
+  { name: 'soft-boom', label: 'Soft Boom' },
+  { name: 'flower', label: 'Flower' },
+  { name: 'puffy', label: 'Puffy' },
+  { name: 'puffy-diamond', label: 'Puffy Diamond' },
+  { name: 'ghost-ish', label: 'Ghost-ish' },
+  { name: 'pixel-circle', label: 'Pixel Circle' },
+  { name: 'pixel-triangle', label: 'Pixel Triangle' },
+  { name: 'bun', label: 'Bun' },
+  { name: 'heart', label: 'Heart' },
+];

package/src/avatar/types.ts

@@ -3,7 +3,30 @@ import type { ImageSourcePropType, StyleProp, ViewStyle, ImageStyle } from 'reac
 // Referenced by the `variant` prop docs below.
 import type { ImageResolver } from '../image-resolver/context';
 
-export type AvatarShape = 'circle' | 'squircle';
+import type { AvatarShapeName } from './shape-paths';
+
+/**
+ * Built-in avatar outlines: the two originals plus the named registry in
+ * `shape-paths.ts`. Any of these can be passed as a plain string.
+ */
+export type AvatarShape = 'circle' | 'squircle' | AvatarShapeName;
+
+/**
+ * A caller-supplied outline, for shapes that are not in the built-in registry.
+ *
+ * The path is clipped against the avatar box, so it should fill its coordinate
+ * space edge to edge; anything outside is cut off rather than scaled to fit.
+ */
+export interface AvatarShapePath {
+  /** SVG path data (the `d` attribute) describing a closed outline. */
+  d: string;
+  /**
+   * Side length of the square coordinate space `d` is drawn in — 100 for a
+   * path written over a 0–100 grid, 1 for one written over a 0–1 grid.
+   * Defaults to 1.
+   */
+  viewBox?: number;
+}
 
 /** Gradient sweep direction for a multi-color {@link AvatarRingConfig}. */
 export type AvatarRingGradientDirection = 'diagonal' | 'horizontal' | 'vertical';
@@ -45,8 +68,14 @@ export interface AvatarProps {
   verified?: boolean;
   /** Custom verified badge icon (rendered at bottom-right) */
   verifiedIcon?: ReactNode;
-  /** Shape of the avatar (defaults to 'circle'). 'squircle' requires react-native-svg. */
-  shape?: AvatarShape;
+  /**
+   * Shape of the avatar (defaults to `'circle'`). Accepts a built-in name —
+   * `'squircle'`, `'heart'`, `'pentagon'`, … see {@link AvatarShapeName} — or an
+   * {@link AvatarShapePath} with your own outline. Everything except `'circle'`
+   * clips through `react-native-svg`; a name that does not resolve falls back to
+   * a circle.
+   */
+  shape?: AvatarShape | AvatarShapePath;
   /** Container style */
   style?: StyleProp<ViewStyle>;
   /** Image style (circle shape only) */

package/src/media-flight/MediaSurface.tsx

@@ -25,7 +25,7 @@ import {
 import { Image } from 'expo-image';
 import Animated from 'react-native-reanimated';
 
-import { SLOT_IDENTITY_CHURN_LIMIT } from './constants';
+import { SLOT_IDENTITY_CHURN_LIMIT, SLOT_IDENTITY_CHURN_WINDOW_MS } from './constants';
 import { handOffFlight } from './store';
 import type { MediaSurfaceContent, MediaVideoSlot } from './types';
 import {
@@ -149,17 +149,61 @@ export const MediaSurface = memo(function MediaSurface({
   // supports.
   const [mountedSurfaceType] = useState(surfaceType);
 
-  // A slot rebuilt on every render republishes this surface to the layer on
-  // every render, which nothing at runtime reports — the picture is correct and
-  // the app is doing work in proportion to how often its rows re-render. The
-  // counter lives in an effect rather than in render: a render-phase ref write
-  // makes the React Compiler bail on the whole component.
-  const slotChurn = useRef(0);
+  // A slot rebuilt on every render re-renders this surface — and on web
+  // republishes the shared node — every time the row it lives in renders, which
+  // nothing at runtime reports: the picture is correct and the app is just
+  // doing work in proportion to its render count.
+  //
+  // What is counted is a RUN of consecutive commits that each carried a new
+  // slot, NOT how many times the slot has ever changed. The lifetime count
+  // cannot tell the defect from a correctly memoised slot: Bloom's own
+  // documented example lists `isWatched` in its deps, so its identity changes
+  // once per activation of a long-lived surface, and any such consumer reaches
+  // any fixed lifetime total eventually. It would then be told to do the thing
+  // it is already doing, with no way to make the warning stop — which is worse
+  // than not warning, because the advice is unsatisfiable. A slot rebuilt per
+  // render is different in kind: it is new on EVERY commit, including the ones
+  // where nothing it reads changed.
+  //
+  // The run must also be FAST, and that second condition is what covers the
+  // consumer who memoised everything else too. With `content` and the rest
+  // stable, `memo` skips the renders where only the parent changed, so this
+  // component commits ONLY when the slot changes — every commit carries a new
+  // slot and the run never breaks, even though there is nothing to fix and no
+  // cost to pay. Rate is what tells them apart, and it is what the warning was
+  // ever about: a slot rebuilt per render churns as fast as its row renders,
+  // while one rebuilt when its state changes moves at the speed of a finger.
+  //
+  // All three refs are written from effects rather than in render: a
+  // render-phase ref write makes the React Compiler bail on the whole
+  // component. The first effect fires only when the identity changed, and the
+  // second — declared after it, and with no dependency array, so it runs on
+  // every commit — is what reads that mark and either extends the run or
+  // clears it.
+  const slotChangedInCommit = useRef(false);
+  const slotChurnRun = useRef(0);
+  const slotChurnRunStartedAt = useRef(0);
   useEffect(() => {
-    if (renderVideo === undefined) return;
-    slotChurn.current += 1;
-    if (slotChurn.current === SLOT_IDENTITY_CHURN_LIMIT) warnSlotNotMemoised();
+    slotChangedInCommit.current = true;
   }, [renderVideo]);
+  useEffect(() => {
+    if (renderVideo === undefined || !slotChangedInCommit.current) {
+      slotChurnRun.current = 0;
+      return;
+    }
+    slotChangedInCommit.current = false;
+    const now = Date.now();
+    if (
+      slotChurnRun.current === 0 ||
+      now - slotChurnRunStartedAt.current > SLOT_IDENTITY_CHURN_WINDOW_MS
+    ) {
+      slotChurnRun.current = 1;
+      slotChurnRunStartedAt.current = now;
+      return;
+    }
+    slotChurnRun.current += 1;
+    if (slotChurnRun.current === SLOT_IDENTITY_CHURN_LIMIT) warnSlotNotMemoised();
+  });
 
   // Both arms report the same fact — "there is a picture here now" — because the
   // destination of a flight can be either, and a caller should not have to know
@@ -252,10 +296,12 @@ function warnSlotNotMemoised(): void {
   hasWarnedAboutSlotChurn = true;
   // eslint-disable-next-line no-console
   console.warn(
-    `[Bloom] A \`renderVideo\` slot changed identity ${SLOT_IDENTITY_CHURN_LIMIT} times. ` +
-      'It is part of what a media host publishes to the flight layer and is compared by ' +
-      'identity, so a slot rebuilt on every render republishes the surface on every render. ' +
-      'Wrap it in `useCallback` with the props it actually reads.',
+    `[Bloom] A \`renderVideo\` slot was a NEW function on ${SLOT_IDENTITY_CHURN_LIMIT} ` +
+      'consecutive renders, including ones where nothing it reads changed. The slot is ' +
+      'compared by identity — on web it is part of what a media host publishes to the ' +
+      'flight layer — so one rebuilt per render re-renders the surface per render. Wrap ' +
+      'it in `useCallback` with the props it actually reads. A slot that changes when ' +
+      'those props change is fine and does not reach this.',
   );
 }
 

package/src/media-flight/constants.ts

@@ -32,16 +32,41 @@ export const SURFACE_MOUNT_TIMEOUT_MS = 250;
  */
 
 /**
- * How many times a video slot may change identity before Bloom says so.
+ * How many CONSECUTIVE renders a video slot may arrive new on before Bloom says
+ * so.
  *
- * `renderVideo` is part of what a host publishes to the layer and is compared
- * by identity, so an unmemoised slot republishes on every render of the row it
- * lives in — silently, and only under load. Five is well past any legitimate
- * cause (a mute toggle, a fit change) and far below the churn of a slot rebuilt
- * per render in a scrolling feed.
+ * `renderVideo` is compared by identity — and on web it is part of what a host
+ * publishes to the layer — so an unmemoised slot re-renders the surface on
+ * every render of the row it lives in, silently and only under load.
+ *
+ * Consecutive, never a lifetime total. A correctly memoised slot changes
+ * identity whenever the state it reads changes (`isWatched` on a reel slide,
+ * say), so ANY fixed lifetime total is reached eventually by a consumer with
+ * nothing to fix — and the warning's own advice, `useCallback` over the props
+ * the slot reads, is what such a consumer already wrote. Five in a row is
+ * unreachable that way: it takes five commits where nothing the slot reads
+ * changed and the slot was rebuilt anyway.
  */
 export const SLOT_IDENTITY_CHURN_LIMIT = 5;
 
+/**
+ * How long a run of {@link SLOT_IDENTITY_CHURN_LIMIT} new slots may take and
+ * still be reported (ms).
+ *
+ * "Consecutive" alone is not enough for the consumer who memoised the surface's
+ * other props as well: `memo` then skips every render where only the parent
+ * changed, so the surface commits ONLY when the slot changes and the run never
+ * breaks — with nothing to fix and, because the renders were skipped, no cost
+ * paid either.
+ *
+ * Rate is what separates them, and it is what the warning was always about. A
+ * slot rebuilt per render changes as fast as its row renders, which in a
+ * scrolling feed is five times in a fraction of a frame budget. A slot rebuilt
+ * when the state it reads changes moves at the speed of a finger, and half a
+ * second is far too short for five activations of ONE surface.
+ */
+export const SLOT_IDENTITY_CHURN_WINDOW_MS = 500;
+
 /**
  * How far a media element may sit from the box it is supposed to fill, in px,
  * before Bloom says so.

package/src/media-flight/types.ts

@@ -276,9 +276,14 @@ export interface MediaVideoSlotProps<P extends VideoPlayerLike = VideoPlayerLike
  * So the consumer may build the element instead, with Bloom deciding only what
  * it has to: which player, and a style that fills the box.
  *
- * MEMOISE IT (`useCallback`). The slot is part of what a host publishes to the
- * layer, compared by identity — a new function every render republishes every
+ * MEMOISE IT (`useCallback`), over the state the element actually reads. The
+ * slot is compared by identity — and on web it is part of what a host publishes
+ * to the layer — so a new function every render re-renders the surface every
  * render. Correct either way, wasteful if you skip it.
+ *
+ * It is expected to change when that state does; only a slot rebuilt on renders
+ * where nothing it reads changed is the mistake, and that is the only one Bloom
+ * warns about.
  */
 export type MediaVideoSlot<P extends VideoPlayerLike = VideoPlayerLike> = (
   props: MediaVideoSlotProps<P>,