[compiler] Simplify ref mutation validation to single forward pass

Rewrites ValidateNoRefAccessInRender to use a simpler single-pass algorithm
that only validates ref mutations (reads are now handled separately by
ValidateNoImpureValuesInRender).

The new approach:
- Tracks refs and ref values through the function
- Identifies functions that mutate refs (directly or transitively)
- Only errors when ref-mutating functions are called at the top level
- Supports null-guard exception: mutations inside `if (ref.current == null)`
  are allowed for the initialization pattern

This reduces ~700 lines of complex fixpoint iteration to ~400 lines of
straightforward forward data-flow analysis.

compiler/.claude/settings.local.json

@@ -8,11 +8,7 @@
       "Bash(echo:*)",
       "Bash(done)",
       "Bash(cat:*)",
-      "Bash(sl revert:*)",
-      "Bash(yarn workspace snap run build:*)",
-      "Bash(yarn tsc:*)",
-      "Bash(yarn snap:build)",
-      "Bash(timeout 30 yarn snap:*)"
+      "Bash(sl revert:*)"
     ],
     "deny": [],
     "ask": []

compiler/CHANGELOG.md

@@ -1,7 +1,3 @@
-## Pending
-
-* Improve impurity and ref validation, reducing false positives [#35298](https://github.com/facebook/react/pull/35298) by [@josephsavona](https://github.com/josephsavona)
-
 ## 19.1.0-rc.2 (May 14, 2025)
 
 ## babel-plugin-react-compiler

compiler/CLAUDE.md

@@ -19,16 +19,10 @@ This document contains knowledge about the React Compiler gathered during develo
 # Run all tests
 yarn snap
 
-# Run tests matching a pattern
-# Example: yarn snap -p 'error.*'
+# Run specific test by pattern
 yarn snap -p <pattern>
 
-# Run a single fixture in debug mode. Use the path relative to the __tests__/fixtures/compiler directory
-# For each step of compilation, outputs the step name and state of the compiled program
-# Example: yarn snap -p simple.js -d
-yarn snap -p <file-basename> -d
-
-# Update fixture outputs (also works with -p)
+# Update fixture outputs
 yarn snap -u
 ```
 

compiler/packages/babel-plugin-react-compiler/src/CompilerError.ts

@@ -132,6 +132,12 @@ export class CompilerDiagnostic {
     return new CompilerDiagnostic({...options, details: []});
   }
 
+  clone(): CompilerDiagnostic {
+    const cloned = CompilerDiagnostic.create({...this.options});
+    cloned.options.details = [...this.options.details];
+    return cloned;
+  }
+
   get reason(): CompilerDiagnosticOptions['reason'] {
     return this.options.reason;
   }

compiler/packages/babel-plugin-react-compiler/src/HIR/Globals.ts

@@ -626,7 +626,7 @@ const TYPED_GLOBALS: Array<[string, BuiltInType]> = [
   // TODO: rest of Global objects
 ];
 
-const createRenderHookAliasing: (
+const RenderHookAliasing: (
   reason: ValueReason,
 ) => AliasingSignatureConfig = reason => ({
   receiver: '@receiver',
@@ -745,12 +745,12 @@ const useEffectEvent = addHook(
       returns: '@return',
       temporaries: [],
       effects: [
+        {kind: 'Assign', from: '@value', into: '@return'},
         {
           kind: 'Freeze',
           value: '@value',
           reason: ValueReason.HookCaptured,
         },
-        {kind: 'Assign', from: '@value', into: '@return'},
       ],
     },
   },
@@ -769,7 +769,7 @@ const REACT_APIS: Array<[string, BuiltInType]> = [
         hookKind: 'useContext',
         returnValueKind: ValueKind.Frozen,
         returnValueReason: ValueReason.Context,
-        aliasing: createRenderHookAliasing(ValueReason.Context),
+        aliasing: RenderHookAliasing(ValueReason.Context),
       },
       BuiltInUseContextHookId,
     ),
@@ -784,7 +784,7 @@ const REACT_APIS: Array<[string, BuiltInType]> = [
       hookKind: 'useState',
       returnValueKind: ValueKind.Frozen,
       returnValueReason: ValueReason.State,
-      aliasing: createRenderHookAliasing(ValueReason.State),
+      aliasing: RenderHookAliasing(ValueReason.State),
     }),
   ],
   [
@@ -797,7 +797,7 @@ const REACT_APIS: Array<[string, BuiltInType]> = [
       hookKind: 'useActionState',
       returnValueKind: ValueKind.Frozen,
       returnValueReason: ValueReason.State,
-      aliasing: createRenderHookAliasing(ValueReason.HookCaptured),
+      aliasing: RenderHookAliasing(ValueReason.HookCaptured),
     }),
   ],
   [
@@ -810,7 +810,7 @@ const REACT_APIS: Array<[string, BuiltInType]> = [
       hookKind: 'useReducer',
       returnValueKind: ValueKind.Frozen,
       returnValueReason: ValueReason.ReducerState,
-      aliasing: createRenderHookAliasing(ValueReason.ReducerState),
+      aliasing: RenderHookAliasing(ValueReason.ReducerState),
     }),
   ],
   [
@@ -822,22 +822,6 @@ const REACT_APIS: Array<[string, BuiltInType]> = [
       calleeEffect: Effect.Read,
       hookKind: 'useRef',
       returnValueKind: ValueKind.Mutable,
-      aliasing: {
-        receiver: '@receiver',
-        params: [],
-        rest: '@rest',
-        returns: '@return',
-        temporaries: [],
-        effects: [
-          {
-            kind: 'Create',
-            into: '@return',
-            value: ValueKind.Mutable,
-            reason: ValueReason.KnownReturnSignature,
-          },
-          {kind: 'Capture', from: '@rest', into: '@return'},
-        ],
-      },
     }),
   ],
   [
@@ -860,7 +844,7 @@ const REACT_APIS: Array<[string, BuiltInType]> = [
       calleeEffect: Effect.Read,
       hookKind: 'useMemo',
       returnValueKind: ValueKind.Frozen,
-      aliasing: createRenderHookAliasing(ValueReason.HookCaptured),
+      aliasing: RenderHookAliasing(ValueReason.HookCaptured),
     }),
   ],
   [
@@ -868,16 +852,11 @@ const REACT_APIS: Array<[string, BuiltInType]> = [
     addHook(DEFAULT_SHAPES, {
       positionalParams: [],
       restParam: Effect.Freeze,
-      returnType: {
-        kind: 'Function',
-        isConstructor: false,
-        return: {kind: 'Poly'},
-        shapeId: null,
-      },
+      returnType: {kind: 'Poly'},
       calleeEffect: Effect.Read,
       hookKind: 'useCallback',
       returnValueKind: ValueKind.Frozen,
-      aliasing: createRenderHookAliasing(ValueReason.HookCaptured),
+      aliasing: RenderHookAliasing(ValueReason.HookCaptured),
     }),
   ],
   [
@@ -937,7 +916,7 @@ const REACT_APIS: Array<[string, BuiltInType]> = [
       calleeEffect: Effect.Read,
       hookKind: 'useTransition',
       returnValueKind: ValueKind.Frozen,
-      aliasing: createRenderHookAliasing(ValueReason.HookCaptured),
+      aliasing: RenderHookAliasing(ValueReason.HookCaptured),
     }),
   ],
   [
@@ -950,7 +929,7 @@ const REACT_APIS: Array<[string, BuiltInType]> = [
       hookKind: 'useOptimistic',
       returnValueKind: ValueKind.Frozen,
       returnValueReason: ValueReason.State,
-      aliasing: createRenderHookAliasing(ValueReason.HookCaptured),
+      aliasing: RenderHookAliasing(ValueReason.HookCaptured),
     }),
   ],
   [
@@ -964,7 +943,7 @@ const REACT_APIS: Array<[string, BuiltInType]> = [
         returnType: {kind: 'Poly'},
         calleeEffect: Effect.Read,
         returnValueKind: ValueKind.Frozen,
-        aliasing: createRenderHookAliasing(ValueReason.HookCaptured),
+        aliasing: RenderHookAliasing(ValueReason.HookCaptured),
       },
       BuiltInUseOperatorId,
     ),

compiler/packages/babel-plugin-react-compiler/src/HIR/PrintHIR.ts

@@ -983,7 +983,15 @@ export function printAliasingEffect(effect: AliasingEffect): string {
           return `...${printPlaceForAliasEffect(arg.place)}`;
         })
         .join(', ');
-      return `Apply ${printPlaceForAliasEffect(effect.into)} = ${receiverCallee}(${args})`;
+      let signature = '';
+      if (effect.signature != null) {
+        if (effect.signature.aliasing != null) {
+          signature = printAliasingSignature(effect.signature.aliasing);
+        } else {
+          signature = JSON.stringify(effect.signature, null, 2);
+        }
+      }
+      return `Apply ${printPlaceForAliasEffect(effect.into)} = ${receiverCallee}(${args})${signature != '' ? '\n     ' : ''}${signature}`;
     }
     case 'Freeze': {
       return `Freeze ${printPlaceForAliasEffect(effect.value)} ${effect.reason}`;

compiler/packages/babel-plugin-react-compiler/src/Inference/InferMutationAliasingEffects.ts

@@ -29,6 +29,7 @@ import {
   isArrayType,
   isJsxOrJsxUnionType,
   isMapType,
+  isMutableEffect,
   isPrimitiveType,
   isRefOrRefValue,
   isSetType,
@@ -1093,8 +1094,6 @@ function applyEffect(
       break;
     }
     case 'Apply': {
-      effects.push(effect);
-
       const functionValues = state.values(effect.function);
       if (
         functionValues.length === 1 &&
@@ -2202,8 +2201,14 @@ function computeSignatureForInstruction(
           if (isUseRefType(place.identifier)) {
             continue;
           }
-          if (place.identifier.type.kind !== 'Function') {
-            // Functions are checked independently
+          if (place.identifier.type.kind === 'Function') {
+            if (isJsxOrJsxUnionType(place.identifier.type.return)) {
+              effects.push({
+                kind: 'Render',
+                place,
+              });
+            }
+          } else {
             effects.push({
               kind: 'Render',
               place,

compiler/packages/babel-plugin-react-compiler/src/Inference/InferMutationAliasingRanges.ts

@@ -20,7 +20,6 @@ import {
   Place,
   isPrimitiveType,
   isUseRefType,
-  isJsxOrJsxUnionType,
 } from '../HIR/HIR';
 import {
   eachInstructionLValue,
@@ -397,7 +396,17 @@ export function inferMutationAliasingRanges(
             break;
           }
           case 'Apply': {
-            break;
+            CompilerError.invariant(false, {
+              reason: `[AnalyzeFunctions] Expected Apply effects to be replaced with more precise effects`,
+              description: null,
+              details: [
+                {
+                  kind: 'error',
+                  loc: effect.function.loc,
+                  message: null,
+                },
+              ],
+            });
           }
           case 'MutateTransitive':
           case 'MutateConditionally':
@@ -579,10 +588,7 @@ export function inferMutationAliasingRanges(
     }
   }
 
-  if (
-    errors.hasAnyErrors() &&
-    (!isFunctionExpression || isJsxOrJsxUnionType(fn.returns.identifier.type))
-  ) {
+  if (errors.hasAnyErrors() && !isFunctionExpression) {
     return Err(errors);
   }
   return Ok(functionEffects);

compiler/packages/babel-plugin-react-compiler/src/Validation/ValidateNoImpureValuesInRender.ts

@@ -5,36 +5,43 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {CompilerDiagnostic, CompilerError} from '..';
+import prettyFormat from 'pretty-format';
+import {CompilerDiagnostic, CompilerError, Effect} from '..';
 import {
   areEqualSourceLocations,
   HIRFunction,
   IdentifierId,
   InstructionId,
   isJsxType,
+  isRefValueType,
   isUseRefType,
 } from '../HIR';
-import {AliasingEffect, hashEffect} from '../Inference/AliasingEffects';
+import {
+  eachInstructionLValue,
+  eachInstructionValueOperand,
+} from '../HIR/visitors';
+import {AliasingEffect} from '../Inference/AliasingEffects';
 import {createControlDominators} from '../Inference/ControlDominators';
 import {isMutable} from '../ReactiveScopes/InferReactiveScopeVariables';
 import {Err, Ok, Result} from '../Utils/Result';
-import {getOrInsertWith} from '../Utils/utils';
+import {
+  assertExhaustive,
+  getOrInsertWith,
+  Set_filter,
+  Set_subtract,
+} from '../Utils/utils';
+import {printInstruction} from '../HIR/PrintHIR';
 
 type ImpureEffect = Extract<AliasingEffect, {kind: 'Impure'}>;
 type RenderEffect = Extract<AliasingEffect, {kind: 'Render'}>;
 type FunctionCache = Map<HIRFunction, Map<string, ImpuritySignature>>;
-type ImpuritySignature = {
-  effects: Map<IdentifierId, ImpureEffect>;
-  error: CompilerError;
-  returns: IdentifierId;
-};
+type ImpuritySignature = {effects: Array<ImpureEffect>; error: CompilerError};
 
 export function validateNoImpureValuesInRender(
   fn: HIRFunction,
 ): Result<void, CompilerError> {
   const impure = new Map<IdentifierId, ImpureEffect>();
-  const impureFunctions = new Map<IdentifierId, ImpuritySignature>();
-  const result = inferImpureValues(fn, impure, impureFunctions, new Map());
+  const result = inferImpureValues(fn, impure, new Map());
 
   if (result.error.hasAnyErrors()) {
     return Err(result.error);
@@ -45,23 +52,15 @@ export function validateNoImpureValuesInRender(
 function inferFunctionExpressionMemo(
   fn: HIRFunction,
   impure: Map<IdentifierId, ImpureEffect>,
-  impureFunctions: Map<IdentifierId, ImpuritySignature>,
   cache: FunctionCache,
 ): ImpuritySignature {
   const key = fn.context
-    .map(
-      place =>
-        `${place.identifier.id}:${impure.has(place.identifier.id)}:${Array.from(
-          impureFunctions.get(place.identifier.id)?.effects ?? new Map(),
-        )
-          .map(([id, effect]) => `${id}=>${effect.into.identifier.id}`)
-          .join(',')}`,
-    )
+    .map(place => `${place.identifier.id}:${impure.has(place.identifier.id)}`)
     .join(',');
   return getOrInsertWith(
     getOrInsertWith(cache, fn, () => new Map()),
     key,
-    () => inferImpureValues(fn, impure, impureFunctions, cache),
+    () => inferImpureValues(fn, impure, cache),
   );
 }
 
@@ -69,7 +68,6 @@ function processEffects(
   id: InstructionId,
   effects: Array<AliasingEffect>,
   impure: Map<IdentifierId, ImpureEffect>,
-  impureFunctions: Map<IdentifierId, ImpuritySignature>,
   cache: FunctionCache,
 ): boolean {
   let hasChanges = false;
@@ -111,30 +109,6 @@ function processEffects(
             hasChanges = true;
           }
         }
-        if (
-          (effect.kind === 'Alias' ||
-            effect.kind === 'Assign' ||
-            effect.kind === 'ImmutableCapture') &&
-          !rendered.has(effect.into.identifier.id) &&
-          !isJsxType(effect.into.identifier.type)
-        ) {
-          const functionEffect = impureFunctions.get(effect.from.identifier.id);
-          if (
-            functionEffect != null &&
-            !impureFunctions.has(effect.into.identifier.id)
-            /*
-             * TODO: check if the function signature has changed (should be rare)
-             * ||
-             *   !areEqualFunctionSignatures(
-             *     impureFunctions.get(effect.into.identifier.id)!.effects,
-             *     functionEffect.effects,
-             *   )
-             */
-          ) {
-            impureFunctions.set(effect.into.identifier.id, functionEffect);
-            hasChanges = true;
-          }
-        }
         break;
       }
       case 'Impure': {
@@ -151,44 +125,26 @@ function processEffects(
         const result = inferFunctionExpressionMemo(
           effect.function.loweredFunc.func,
           impure,
-          impureFunctions,
           cache,
         );
         if (result.error.hasAnyErrors()) {
           break;
         }
-        const previousResult = impureFunctions.get(effect.into.identifier.id);
-        if (
-          previousResult == null ||
-          !areEqualFunctionSignatures(result.effects, previousResult.effects)
-        ) {
-          impureFunctions.set(effect.into.identifier.id, result);
+        const impureEffect: ImpureEffect | null =
+          result.effects.find(
+            (functionEffect: AliasingEffect): functionEffect is ImpureEffect =>
+              functionEffect.kind === 'Impure' &&
+              functionEffect.into.identifier.id ===
+                effect.function.loweredFunc.func.returns.identifier.id,
+          ) ?? null;
+        if (impureEffect != null) {
+          impure.set(effect.into.identifier.id, impureEffect);
           hasChanges = true;
         }
         break;
       }
-      case 'Apply': {
-        const functionSignature = impureFunctions.get(
-          effect.function.identifier.id,
-        );
-        if (functionSignature != null) {
-          for (const [id, functionEffect] of functionSignature.effects) {
-            if (!impure.has(id)) {
-              impure.set(id, functionEffect);
-              hasChanges = true;
-            }
-            if (
-              id === functionSignature.returns &&
-              !impure.has(effect.into.identifier.id)
-            ) {
-              impure.set(effect.into.identifier.id, functionEffect);
-              hasChanges = true;
-            }
-          }
-        }
-        break;
-      }
       case 'MaybeAlias':
+      case 'Apply':
       case 'Create':
       case 'Freeze':
       case 'Mutate':
@@ -207,7 +163,6 @@ function processEffects(
 function inferImpureValues(
   fn: HIRFunction,
   impure: Map<IdentifierId, ImpureEffect>,
-  impureFunctions: Map<IdentifierId, ImpuritySignature>,
   cache: FunctionCache,
 ): ImpuritySignature {
   const getBlockControl = createControlDominators(fn, place => {
@@ -215,15 +170,14 @@ function inferImpureValues(
   });
 
   let hasChanges = false;
-  let iterations = 0;
   do {
     hasChanges = false;
 
-    if (iterations++ > 100) {
-      throw new Error('too many iterations');
-    }
-
     for (const block of fn.body.blocks.values()) {
+      const controlPlace = getBlockControl(block.id);
+      const controlImpureEffect =
+        controlPlace != null ? impure.get(controlPlace.identifier.id) : null;
+
       for (const phi of block.phis) {
         if (impure.has(phi.place.identifier.id)) {
           // Already marked impure on a previous pass
@@ -255,38 +209,11 @@ function inferImpureValues(
         }
       }
 
-      /**
-       * TODO: consider propagating impurity for assignments/mutations that
-       * are controlled by an impure value.
-       *
-       * ```
-       * const controlPlace = getBlockControl(block.id);
-       * const controlImpureEffect =
-       *   controlPlace != null ? impure.get(controlPlace.identifier.id) : null;
-       * ```
-       *
-       * Example
-       *
-       * This should error since we know the semantics of array.push, it's a definite
-       * Mutate and definite Capture, not maybemutate+maybecapture:
-       *
-       * ```
-       * let x = [];
-       * if (Date.now() < START_DATE) {
-       *   x.push(1);
-       * }
-       * return <Foo x={x} />
-       * ```
-       */
       for (const instr of block.instructions) {
+        const _impure = new Set(impure.keys());
         hasChanges =
-          processEffects(
-            instr.id,
-            instr.effects ?? [],
-            impure,
-            impureFunctions,
-            cache,
-          ) || hasChanges;
+          processEffects(instr.id, instr.effects ?? [], impure, cache) ||
+          hasChanges;
       }
       if (block.terminal.kind === 'return' && block.terminal.effects != null) {
         hasChanges =
@@ -294,7 +221,6 @@ function inferImpureValues(
             block.terminal.id,
             block.terminal.effects,
             impure,
-            impureFunctions,
             cache,
           ) || hasChanges;
       }
@@ -306,19 +232,10 @@ function inferImpureValues(
     name: 'ValidateNoImpureValuesInRender',
     value: JSON.stringify(Array.from(impure.keys()).sort(), null, 2),
   });
-  fn.env.logger?.debugLogIRs?.({
-    kind: 'debug',
-    name: 'ValidateNoImpureValuesInRender (function)',
-    value: JSON.stringify(Array.from(impureFunctions.keys()).sort(), null, 2),
-  });
 
   const error = new CompilerError();
   function validateRenderEffect(effect: RenderEffect): void {
-    let impureEffect = impure.get(effect.place.identifier.id);
-    if (impureEffect == null) {
-      const functionSignature = impureFunctions.get(effect.place.identifier.id);
-      impureEffect = functionSignature?.effects.get(functionSignature.returns);
-    }
+    const impureEffect = impure.get(effect.place.identifier.id);
     if (impureEffect == null) {
       return;
     }
@@ -350,7 +267,6 @@ function inferImpureValues(
         const result = inferFunctionExpressionMemo(
           value.loweredFunc.func,
           impure,
-          impureFunctions,
           cache,
         );
         if (result.error.hasAnyErrors()) {
@@ -371,26 +287,21 @@ function inferImpureValues(
       }
     }
   }
-  const impureEffects: Map<IdentifierId, ImpureEffect> = new Map();
+  const impureEffects: Array<ImpureEffect> = [];
   for (const param of [...fn.context, ...fn.params, fn.returns]) {
     const place = param.kind === 'Identifier' ? param : param.place;
     const impureEffect = impure.get(place.identifier.id);
     if (impureEffect != null) {
-      impureEffects.set(place.identifier.id, impureEffect);
+      impureEffects.push({
+        kind: 'Impure',
+        into: impureEffect.into,
+        category: impureEffect.category,
+        reason: impureEffect.reason,
+        description: impureEffect.description,
+        sourceMessage: impureEffect.sourceMessage,
+        usageMessage: impureEffect.usageMessage,
+      });
     }
   }
-  return {effects: impureEffects, error, returns: fn.returns.identifier.id};
-}
-
-function areEqualFunctionSignatures(
-  sig1: Map<IdentifierId, ImpureEffect>,
-  sig2: Map<IdentifierId, ImpureEffect>,
-): boolean {
-  return (
-    sig1.size === sig2.size &&
-    Array.from(sig1).every(
-      ([id, effect]) =>
-        sig2.has(id) && hashEffect(effect) === hashEffect(sig2.get(id)!),
-    )
-  );
+  return {effects: impureEffects, error};
 }

compiler/packages/babel-plugin-react-compiler/src/Validation/ValidateNoRefAccessInRender.md

@@ -1,137 +0,0 @@
-# ValidateNoRefAccessInRender
-
-This document summarizes the design and key learnings for the ref mutation validation pass.
-
-## Purpose
-
-Validates that a function does not mutate a ref value during render. This ensures React components follow the rules of React by not writing to `ref.current` during the render phase.
-
-## Key Concepts
-
-### Ref vs RefValue
-
-- **Ref**: The ref object itself (e.g., `useRef()` return value). Has type `React.RefObject<T>`.
-- **RefValue**: The `.current` property of a ref. This is the mutable value that should not be accessed during render.
-
-The validation tracks both using a `RefInfo` type with a `refId` that correlates refs with their `.current` values.
-
-### What Constitutes a Mutation
-
-A mutation is any `PropertyStore` or `ComputedStore` instruction where:
-1. The target object is a known ref (tracked in the `refs` map)
-2. OR the target object has a ref type (`isUseRefType`)
-
-### Allowed Patterns
-
-1. **Event handlers and effect callbacks**: Functions that are not called at the top level during render can mutate refs freely.
-
-2. **Null-guard initialization**: The pattern `if (ref.current == null) { ref.current = value; }` is allowed because it's a common lazy initialization pattern that only runs once.
-
-## Algorithm: Single Forward Data-Flow Pass
-
-The validation uses a single forward pass over all blocks:
-
-### Phase 1: Track Refs
-- Initialize refs from function params and context (captured variables)
-- Process phi nodes to propagate ref info through control flow joins
-- Track refs through LoadLocal, StoreLocal, PropertyLoad operations
-
-### Phase 2: Detect Null Guards
-- Track nullable values (null literals, undefined)
-- Track binary comparisons of `ref.current` to null (`==`, `===`, `!=`, `!==`)
-- Mark blocks as "safe" for specific refs when inside null-guard branches
-- Propagate safety through control flow until fallthrough
-
-### Phase 3: Validate Mutations
-- For PropertyStore/ComputedStore on refs:
-  - If inside a null-guard for this ref: allow (but track for duplicate detection)
-  - If at top level: error immediately
-  - If in nested function: track for later (error if function is called)
-
-### Phase 4: Track Ref-Mutating Functions
-- When a FunctionExpression mutates a ref, track it in `refMutatingFunctions`
-- When such a function is called at top level, report the error at the mutation site
-
-## Key Data Structures
-
-```typescript
-// Correlates refs with their .current values
-type RefInfo = {
-  kind: 'Ref' | 'RefValue';
-  refId: number;
-};
-
-// Tracks null-guard conditions
-type GuardInfo = {
-  refId: number;
-  isEquality: boolean; // true for ==, ===; false for !=, !==
-};
-
-// Information about a mutation (for error reporting)
-type MutationInfo = {
-  loc: SourceLocation;
-  isCurrentProperty: boolean;
-};
-```
-
-## Error Reporting
-
-### Error Location
-
-Errors highlight the **entire instruction** (e.g., `ref.current = value`), not just the ref identifier. This is achieved by using `instr.loc` instead of `value.object.loc`.
-
-### Duplicate Initialization
-
-When a ref is initialized more than once inside a null-guard:
-1. Primary error: Points to the second initialization
-2. Secondary error: Points to the first initialization with "Ref was first initialized here"
-
-### Transitive Mutations
-
-When a function that mutates refs is called during render:
-- The error points to the mutation site inside the function
-- Not the call site (the call site is what triggers the check)
-
-## Edge Cases and Patterns
-
-### Unary NOT on Guards
-
-The `!` operator inverts guard polarity:
-```javascript
-if (!ref.current) { ... }  // Same as: if (ref.current == null)
-```
-
-### Nested Functions
-
-Functions defined during render but not called are allowed to mutate refs:
-```javascript
-// OK - onClick is not called during render
-const onClick = () => { ref.current = value; };
-return <button onClick={onClick} />;
-```
-
-### Props with Ref Type
-
-Refs can come from props. The validation handles `props.ref` by checking type information.
-
-## Limitations / Known Gaps
-
-The following patterns are NOT currently validated by this pass:
-
-1. **Impure values in render**: `Date.now()`, `Math.random()` flowing into render context (handled by `ValidateNoImpureValuesInRender`)
-
-2. **useState/useReducer callbacks**: These hooks call their initializer functions during render, so ref access inside them should error. This requires special hook semantics.
-
-3. **Ref reads during render**: This pass focuses on mutations. Ref reads are handled separately.
-
-## Testing
-
-Test fixtures use naming conventions:
-- `error.*.ts` - Fixtures expected to produce compilation errors
-- Regular names - Fixtures expected to compile successfully
-
-Run tests with:
-```bash
-yarn snap -p <pattern> --nodebug    # Run specific tests
-yarn snap -p <pattern> --nodebug -u # Update expected output
-```

compiler/packages/babel-plugin-react-compiler/src/Validation/ValidateNoRefAccessInRender.ts

@@ -11,7 +11,7 @@ import {
   HIRFunction,
   IdentifierId,
   Instruction,
-  SourceLocation,
+  Place,
   isRefValueType,
   isUseRefType,
 } from '../HIR';
@@ -64,7 +64,7 @@ type GuardInfo = {
 
 // Information about a mutation found in a function
 type MutationInfo = {
-  loc: SourceLocation;
+  place: Place;
   isCurrentProperty: boolean;
 };
 
@@ -77,10 +77,7 @@ export function validateNoRefAccessInRender(
   // Track which identifiers are functions that mutate refs
   const refMutatingFunctions = new Map<IdentifierId, MutationInfo>();
 
-  // Track first initialization location for each ref (by refId)
-  const refInitLocations = new Map<number, SourceLocation>();
-
-  validateFunction(fn, refs, refMutatingFunctions, refInitLocations, true, errors);
+  validateFunction(fn, refs, refMutatingFunctions, true, errors);
 
   if (errors.hasAnyErrors()) {
     return Err(errors);
@@ -92,7 +89,6 @@ function validateFunction(
   fn: HIRFunction,
   refs: Map<IdentifierId, RefInfo>,
   refMutatingFunctions: Map<IdentifierId, MutationInfo>,
-  refInitLocations: Map<number, SourceLocation>,
   isTopLevel: boolean,
   errors: CompilerError,
 ): MutationInfo | null {
@@ -163,7 +159,6 @@ function validateFunction(
         nullables,
         guards,
         refMutatingFunctions,
-        refInitLocations,
         safeRefIds,
         isTopLevel,
         errors,
@@ -177,20 +172,16 @@ function validateFunction(
     if (block.terminal.kind === 'if') {
       const guard = guards.get(block.terminal.test.identifier.id);
       if (guard != null) {
-        /*
-         * For equality checks (==, ===), consequent is safe (condition true = ref is null)
-         * For inequality checks (!=, !==), alternate is safe (condition false = ref is null)
-         */
+        // For equality checks (==, ===), consequent is safe (condition true = ref is null)
+        // For inequality checks (!=, !==), alternate is safe (condition false = ref is null)
         const safeBlock = guard.isEquality
           ? block.terminal.consequent
           : block.terminal.alternate;
         const fallthrough = block.terminal.fallthrough;
 
-        /*
-         * Propagate safety through control flow using a queue
-         * Stop when we reach the fallthrough (end of the guarded region)
-         */
-        const queue: Array<BlockId> = [safeBlock];
+        // Propagate safety through control flow using a queue
+        // Stop when we reach the fallthrough (end of the guarded region)
+        const queue: BlockId[] = [safeBlock];
         const visited = new Set<BlockId>();
         while (queue.length > 0) {
           const blockId = queue.shift()!;
@@ -226,7 +217,6 @@ function processInstruction(
   nullables: Set<IdentifierId>,
   guards: Map<IdentifierId, GuardInfo>,
   refMutatingFunctions: Map<IdentifierId, MutationInfo>,
-  refInitLocations: Map<number, SourceLocation>,
   safeRefIds: Set<number>,
   isTopLevel: boolean,
   errors: CompilerError,
@@ -349,27 +339,17 @@ function processInstruction(
         const isNullGuardInit =
           isCurrentProperty && refId != null && safeRefIds.has(refId);
 
-        if (isNullGuardInit && refId != null) {
-          // Check if this ref was already initialized
-          const firstInitLoc = refInitLocations.get(refId);
-          if (firstInitLoc != null) {
-            // Error: duplicate initialization
-            errors.pushDiagnostic(
-              makeDuplicateRefInitError(instr.loc, firstInitLoc),
-            );
-            return {loc: instr.loc, isCurrentProperty};
-          }
-          // Track this as the first initialization
-          refInitLocations.set(refId, instr.loc);
-        } else if (!isNullGuardInit) {
+        if (!isNullGuardInit) {
           const mutation: MutationInfo = {
-            loc: instr.loc,
+            place: value.object,
             isCurrentProperty,
           };
 
           if (isTopLevel) {
             // Direct mutation at top level - error immediately
-            errors.pushDiagnostic(makeRefMutationError(mutation.loc));
+            errors.pushDiagnostic(
+              makeRefMutationError(mutation.place, mutation.isCurrentProperty),
+            );
           }
           return mutation;
         }
@@ -385,22 +365,21 @@ function processInstruction(
       const mutationInfo = refMutatingFunctions.get(callee.identifier.id);
       if (mutationInfo != null && isTopLevel) {
         // Calling a ref-mutating function at top level - error
-        errors.pushDiagnostic(makeRefMutationError(mutationInfo.loc));
+        errors.pushDiagnostic(
+          makeRefMutationError(mutationInfo.place, mutationInfo.isCurrentProperty),
+        );
       }
       break;
     }
 
     case 'FunctionExpression':
     case 'ObjectMethod': {
-      /*
-       * Recursively validate function expressions
-       * Pass isTopLevel=false since these are nested functions
-       */
+      // Recursively validate function expressions
+      // Pass isTopLevel=false since these are nested functions
       const mutation = validateFunction(
         value.loweredFunc.func,
         refs,
         refMutatingFunctions,
-        refInitLocations,
         false,
         errors,
       );
@@ -418,41 +397,33 @@ function processInstruction(
   return null;
 }
 
-function makeRefMutationError(loc: SourceLocation): CompilerDiagnostic {
-  return CompilerDiagnostic.create({
+function makeRefMutationError(
+  place: Place,
+  isCurrentProperty: boolean,
+): CompilerDiagnostic {
+  const diagnostic = CompilerDiagnostic.create({
     category: ErrorCategory.Refs,
-    reason: 'Cannot access refs during render',
+    reason: 'Mutating refs during render is not allowed',
     description: REF_ERROR_DESCRIPTION,
   }).withDetails({
     kind: 'error',
-    loc,
-    message: 'Cannot update ref during render',
+    loc: place.loc,
+    message: 'Cannot mutate ref during render',
   });
-}
 
-function makeDuplicateRefInitError(
-  loc: SourceLocation,
-  firstInitLoc: SourceLocation,
-): CompilerDiagnostic {
-  return CompilerDiagnostic.create({
-    category: ErrorCategory.Refs,
-    reason: 'Cannot access refs during render',
-    description: REF_ERROR_DESCRIPTION,
-  })
-    .withDetails({
-      kind: 'error',
-      loc,
-      message: 'Ref is initialized more than once during render',
-    })
-    .withDetails({
-      kind: 'error',
-      loc: firstInitLoc,
-      message: 'Ref was first initialized here',
+  if (isCurrentProperty) {
+    diagnostic.withDetails({
+      kind: 'hint',
+      message:
+        'Refs may be mutated during render if initialized with `if (ref.current == null)`',
     });
+  }
+
+  return diagnostic;
 }
 
 export const REF_ERROR_DESCRIPTION =
-  'React refs are values that are not needed for rendering. Refs should only be accessed ' +
-  'outside of render, such as in event handlers or effects. ' +
-  'Accessing a ref value (the `current` property) during render can cause your component ' +
-  'not to update as expected (https://react.dev/reference/react/useRef)';
+  'React refs are mutable containers that should only be mutated outside of render, ' +
+  'such as in event handlers or effects. Mutating a ref during render can cause ' +
+  'bugs because the mutation may not be associated with a particular render. ' +
+  'See https://react.dev/reference/react/useRef';

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/access-ref-in-render-mutate-object-with-ref-function.expect.md

@@ -1,51 +0,0 @@
-
-## Input
-
-```javascript
-import {useRef} from 'react';
-
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses an impure value during render.
- */
-function Component() {
-  const ref = useRef(null);
-  const object = {};
-  object.foo = () => ref.current;
-  const refValue = object.foo();
-  return <div>{refValue}</div>;
-}
-
-```
-
-## Code
-
-```javascript
-import { c as _c } from "react/compiler-runtime";
-import { useRef } from "react";
-
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses an impure value during render.
- */
-function Component() {
-  const $ = _c(2);
-  const ref = useRef(null);
-  const object = {};
-  object.foo = () => ref.current;
-  const refValue = object.foo();
-  let t0;
-  if ($[0] !== refValue) {
-    t0 = <div>{refValue}</div>;
-    $[0] = refValue;
-    $[1] = t0;
-  } else {
-    t0 = $[1];
-  }
-  return t0;
-}
-
-```
-      
-### Eval output
-(kind: exception) Fixture not implemented

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/capture-ref-for-mutation.expect.md

@@ -1,74 +0,0 @@
-
-## Input
-
-```javascript
-import {useRef} from 'react';
-import {addOne} from 'shared-runtime';
-
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses an impure value during render.
- */
-function useKeyCommand() {
-  const currentPosition = useRef(0);
-  const handleKey = direction => () => {
-    const position = currentPosition.current;
-    const nextPosition = direction === 'left' ? addOne(position) : position;
-    currentPosition.current = nextPosition;
-  };
-  const moveLeft = {
-    handler: handleKey('left')(),
-  };
-  const moveRight = {
-    handler: handleKey('right')(),
-  };
-  return [moveLeft, moveRight];
-}
-
-export const FIXTURE_ENTRYPOINT = {
-  fn: useKeyCommand,
-  params: [],
-};
-
-```
-
-## Code
-
-```javascript
-import { c as _c } from "react/compiler-runtime";
-import { useRef } from "react";
-import { addOne } from "shared-runtime";
-
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses an impure value during render.
- */
-function useKeyCommand() {
-  const $ = _c(1);
-  const currentPosition = useRef(0);
-  let t0;
-  if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
-    const handleKey = (direction) => () => {
-      const position = currentPosition.current;
-      const nextPosition = direction === "left" ? addOne(position) : position;
-      currentPosition.current = nextPosition;
-    };
-    const moveLeft = { handler: handleKey("left")() };
-    const moveRight = { handler: handleKey("right")() };
-    t0 = [moveLeft, moveRight];
-    $[0] = t0;
-  } else {
-    t0 = $[0];
-  }
-  return t0;
-}
-
-export const FIXTURE_ENTRYPOINT = {
-  fn: useKeyCommand,
-  params: [],
-};
-
-```
-      
-### Eval output
-(kind: ok) [{},{}]

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/capturing-ref-returning-function-in-rendered-object.expect.md

@@ -1,60 +0,0 @@
-
-## Input
-
-```javascript
-import {useRef} from 'react';
-import {Stringify} from 'shared-runtime';
-
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses an impure value during render.
- */
-function Component(props) {
-  const ref = useRef(props.value);
-  const object = {};
-  object.foo = () => ref.current;
-  return <Stringify object={object} shouldInvokeFns={true} />;
-}
-
-export const FIXTURE_ENTRYPOINT = {
-  fn: Component,
-  params: [{value: 42}],
-};
-
-```
-
-## Code
-
-```javascript
-import { c as _c } from "react/compiler-runtime";
-import { useRef } from "react";
-import { Stringify } from "shared-runtime";
-
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses an impure value during render.
- */
-function Component(props) {
-  const $ = _c(1);
-  const ref = useRef(props.value);
-  let t0;
-  if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
-    const object = {};
-    object.foo = () => ref.current;
-    t0 = <Stringify object={object} shouldInvokeFns={true} />;
-    $[0] = t0;
-  } else {
-    t0 = $[0];
-  }
-  return t0;
-}
-
-export const FIXTURE_ENTRYPOINT = {
-  fn: Component,
-  params: [{ value: 42 }],
-};
-
-```
-      
-### Eval output
-(kind: ok) <div>{"object":{"foo":{"kind":"Function","result":42}},"shouldInvokeFns":true}</div>

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.capture-ref-for-mutation.expect.md

@@ -0,0 +1,53 @@
+
+## Input
+
+```javascript
+import {useRef} from 'react';
+import {addOne} from 'shared-runtime';
+
+function useKeyCommand() {
+  const currentPosition = useRef(0);
+  const handleKey = direction => () => {
+    const position = currentPosition.current;
+    const nextPosition = direction === 'left' ? addOne(position) : position;
+    currentPosition.current = nextPosition;
+  };
+  const moveLeft = {
+    handler: handleKey('left')(),
+  };
+  const moveRight = {
+    handler: handleKey('right')(),
+  };
+  return [moveLeft, moveRight];
+}
+
+export const FIXTURE_ENTRYPOINT = {
+  fn: useKeyCommand,
+  params: [],
+};
+
+```
+
+
+## Error
+
+```
+Found 1 error:
+
+Error: Mutating refs during render is not allowed
+
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
+
+error.capture-ref-for-mutation.ts:9:4
+   7 |     const position = currentPosition.current;
+   8 |     const nextPosition = direction === 'left' ? addOne(position) : position;
+>  9 |     currentPosition.current = nextPosition;
+     |     ^^^^^^^^^^^^^^^ Cannot mutate ref during render
+  10 |   };
+  11 |   const moveLeft = {
+  12 |     handler: handleKey('left')(),
+
+Refs may be mutated during render if initialized with `if (ref.current == null)`
+```
+          
+      

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.capture-ref-for-mutation.tsx

@@ -1,10 +1,6 @@
 import {useRef} from 'react';
 import {addOne} from 'shared-runtime';
 
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses an impure value during render.
- */
 function useKeyCommand() {
   const currentPosition = useRef(0);
   const handleKey = direction => () => {

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.hook-ref-value.expect.md

@@ -24,7 +24,7 @@ Found 1 error:
 
 Error: Cannot access ref value during render
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
 error.hook-ref-value.ts:5:22
   3 | function Component(props) {

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-access-ref-during-render.expect.md

@@ -19,7 +19,7 @@ Found 1 error:
 
 Error: Cannot access ref value during render
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
 error.invalid-access-ref-during-render.ts:5:9
   3 |   const ref = useRef(null);

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-access-ref-in-reducer.expect.md

@@ -22,7 +22,7 @@ export const FIXTURE_ENTRYPOINT = {
 ## Error
 
 ```
-Found 2 errors:
+Found 1 error:
 
 Error: Cannot access ref value during render
 
@@ -37,28 +37,6 @@ error.invalid-access-ref-in-reducer.ts:5:29
   7 |   return <Stringify state={state} />;
   8 | }
 
-error.invalid-access-ref-in-reducer.ts:5:35
-  3 | function Component(props) {
-  4 |   const ref = useRef(props.value);
-> 5 |   const [state] = useReducer(() => ref.current, null);
-    |                                    ^^^^^^^^^^^ Ref is initially accessed
-  6 |
-  7 |   return <Stringify state={state} />;
-  8 | }
-
-Error: Cannot access ref value during render
-
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
-
-error.invalid-access-ref-in-reducer.ts:7:27
-   5 |   const [state] = useReducer(() => ref.current, null);
-   6 |
->  7 |   return <Stringify state={state} />;
-     |                            ^^^^^ Ref value is used during render
-   8 | }
-   9 |
-  10 | export const FIXTURE_ENTRYPOINT = {
-
 error.invalid-access-ref-in-reducer.ts:5:35
   3 | function Component(props) {
   4 |   const ref = useRef(props.value);

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-access-ref-in-render-mutate-object-with-ref-function.expect.md

@@ -0,0 +1,45 @@
+
+## Input
+
+```javascript
+import {useRef} from 'react';
+
+function Component() {
+  const ref = useRef(null);
+  const object = {};
+  object.foo = () => ref.current;
+  const refValue = object.foo();
+  return <div>{refValue}</div>;
+}
+
+```
+
+
+## Error
+
+```
+Found 1 error:
+
+Error: Cannot access ref value during render
+
+React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+
+error.invalid-access-ref-in-render-mutate-object-with-ref-function.ts:8:15
+   6 |   object.foo = () => ref.current;
+   7 |   const refValue = object.foo();
+>  8 |   return <div>{refValue}</div>;
+     |                ^^^^^^^^ Ref value is used during render
+   9 | }
+  10 |
+
+error.invalid-access-ref-in-render-mutate-object-with-ref-function.ts:6:21
+  4 |   const ref = useRef(null);
+  5 |   const object = {};
+> 6 |   object.foo = () => ref.current;
+    |                      ^^^^^^^^^^^ Ref is initially accessed
+  7 |   const refValue = object.foo();
+  8 |   return <div>{refValue}</div>;
+  9 | }
+```
+          
+      

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-access-ref-in-render-mutate-object-with-ref-function.js

@@ -1,9 +1,5 @@
 import {useRef} from 'react';
 
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses an impure value during render.
- */
 function Component() {
   const ref = useRef(null);
   const object = {};

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-access-ref-in-state-initializer.expect.md

@@ -22,7 +22,7 @@ export const FIXTURE_ENTRYPOINT = {
 ## Error
 
 ```
-Found 2 errors:
+Found 1 error:
 
 Error: Cannot access ref value during render
 
@@ -37,28 +37,6 @@ error.invalid-access-ref-in-state-initializer.ts:5:27
   7 |   return <Stringify state={state} />;
   8 | }
 
-error.invalid-access-ref-in-state-initializer.ts:5:33
-  3 | function Component(props) {
-  4 |   const ref = useRef(props.value);
-> 5 |   const [state] = useState(() => ref.current);
-    |                                  ^^^^^^^^^^^ Ref is initially accessed
-  6 |
-  7 |   return <Stringify state={state} />;
-  8 | }
-
-Error: Cannot access ref value during render
-
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
-
-error.invalid-access-ref-in-state-initializer.ts:7:27
-   5 |   const [state] = useState(() => ref.current);
-   6 |
->  7 |   return <Stringify state={state} />;
-     |                            ^^^^^ Ref value is used during render
-   8 | }
-   9 |
-  10 | export const FIXTURE_ENTRYPOINT = {
-
 error.invalid-access-ref-in-state-initializer.ts:5:33
   3 | function Component(props) {
   4 |   const ref = useRef(props.value);

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-aliased-ref-in-callback-invoked-during-render-.expect.md

@@ -23,7 +23,7 @@ Found 1 error:
 
 Error: Cannot access ref value during render
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
 error.invalid-aliased-ref-in-callback-invoked-during-render-.ts:7:37
    5 |     const aliasedRef = ref;

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-assign-current-inferred-ref-during-render.expect.md

@@ -20,17 +20,19 @@ component Example() {
 ```
 Found 1 error:
 
-Error: Cannot access refs during render
+Error: Mutating refs during render is not allowed
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
   4 | component Example() {
   5 |   const fooRef = makeObject_Primitives();
 > 6 |   fooRef.current = true;
-    |   ^^^^^^^^^^^^^^ Cannot update ref during render
+    |   ^^^^^^ Cannot mutate ref during render
   7 |
   8 |   return <Stringify foo={fooRef} />;
   9 | }
+
+Refs may be mutated during render if initialized with `if (ref.current == null)`
 ```
           
       

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-capturing-ref-returning-function-in-rendered-object.expect.md

@@ -0,0 +1,51 @@
+
+## Input
+
+```javascript
+import {useRef} from 'react';
+import {Stringify} from 'shared-runtime';
+
+function Component(props) {
+  const ref = useRef(props.value);
+  const object = {};
+  object.foo = () => ref.current;
+  return <Stringify object={object} shouldInvokeFns={true} />;
+}
+
+export const FIXTURE_ENTRYPOINT = {
+  fn: Component,
+  params: [{value: 42}],
+};
+
+```
+
+
+## Error
+
+```
+Found 1 error:
+
+Error: Cannot access ref value during render
+
+React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+
+error.invalid-capturing-ref-returning-function-in-rendered-object.ts:8:28
+   6 |   const object = {};
+   7 |   object.foo = () => ref.current;
+>  8 |   return <Stringify object={object} shouldInvokeFns={true} />;
+     |                             ^^^^^^ Ref value is used during render
+   9 | }
+  10 |
+  11 | export const FIXTURE_ENTRYPOINT = {
+
+error.invalid-capturing-ref-returning-function-in-rendered-object.ts:7:21
+   5 |   const ref = useRef(props.value);
+   6 |   const object = {};
+>  7 |   object.foo = () => ref.current;
+     |                      ^^^^^^^^^^^ Ref is initially accessed
+   8 |   return <Stringify object={object} shouldInvokeFns={true} />;
+   9 | }
+  10 |
+```
+          
+      

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-capturing-ref-returning-function-in-rendered-object.js

@@ -1,10 +1,6 @@
 import {useRef} from 'react';
 import {Stringify} from 'shared-runtime';
 
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses an impure value during render.
- */
 function Component(props) {
   const ref = useRef(props.value);
   const object = {};

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-disallow-mutating-ref-in-render.expect.md

@@ -18,18 +18,20 @@ function Component() {
 ```
 Found 1 error:
 
-Error: Cannot access refs during render
+Error: Mutating refs during render is not allowed
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
 error.invalid-disallow-mutating-ref-in-render.ts:4:2
   2 | function Component() {
   3 |   const ref = useRef(null);
 > 4 |   ref.current = false;
-    |   ^^^^^^^^^^^ Cannot update ref during render
+    |   ^^^ Cannot mutate ref during render
   5 |
   6 |   return <button ref={ref} />;
   7 | }
+
+Refs may be mutated during render if initialized with `if (ref.current == null)`
 ```
           
       

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-disallow-mutating-refs-in-render-transitive.expect.md

@@ -23,18 +23,20 @@ function Component() {
 ```
 Found 1 error:
 
-Error: Cannot access refs during render
+Error: Mutating refs during render is not allowed
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
 error.invalid-disallow-mutating-refs-in-render-transitive.ts:6:4
   4 |
   5 |   const setRef = () => {
 > 6 |     ref.current = false;
-    |     ^^^^^^^^^^^ Cannot update ref during render
+    |     ^^^ Cannot mutate ref during render
   7 |   };
   8 |   const changeRef = setRef;
   9 |   changeRef();
+
+Refs may be mutated during render if initialized with `if (ref.current == null)`
 ```
           
       

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-impure-functions-in-render-indirect-via-mutation.expect.md

@@ -6,11 +6,6 @@
 
 import {arrayPush, identity, makeArray} from 'shared-runtime';
 
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses an impure value during render. The impurity is lost
- * when passed through external function calls.
- */
 function Component() {
   const getDate = () => Date.now();
   const now = getDate();
@@ -31,22 +26,22 @@ Error: Cannot access impure value during render
 
 Calling an impure function can produce unstable results that update unpredictably when the component happens to re-render. (https://react.dev/reference/rules/components-and-hooks-must-be-pure#components-and-hooks-must-be-idempotent).
 
-error.invalid-impure-functions-in-render-indirect-via-mutation.ts:15:23
-  13 |   const array = [];
-  14 |   arrayPush(array, now);
-> 15 |   return <Foo hasDate={array} />;
+error.invalid-impure-functions-in-render-indirect-via-mutation.ts:10:23
+   8 |   const array = [];
+   9 |   arrayPush(array, now);
+> 10 |   return <Foo hasDate={array} />;
      |                        ^^^^^ Cannot access impure value during render
-  16 | }
-  17 |
+  11 | }
+  12 |
 
-error.invalid-impure-functions-in-render-indirect-via-mutation.ts:11:24
-   9 |  */
-  10 | function Component() {
-> 11 |   const getDate = () => Date.now();
-     |                         ^^^^^^^^^^ `Date.now` is an impure function.
-  12 |   const now = getDate();
-  13 |   const array = [];
-  14 |   arrayPush(array, now);
+error.invalid-impure-functions-in-render-indirect-via-mutation.ts:6:24
+  4 |
+  5 | function Component() {
+> 6 |   const getDate = () => Date.now();
+    |                         ^^^^^^^^^^ `Date.now` is an impure function.
+  7 |   const now = getDate();
+  8 |   const array = [];
+  9 |   arrayPush(array, now);
 ```
           
       

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-impure-functions-in-render-indirect-via-mutation.js

@@ -2,11 +2,6 @@
 
 import {arrayPush, identity, makeArray} from 'shared-runtime';
 
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses an impure value during render. The impurity is lost
- * when passed through external function calls.
- */
 function Component() {
   const getDate = () => Date.now();
   const now = getDate();

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-impure-functions-in-render-indirect.expect.md

@@ -0,0 +1,46 @@
+
+## Input
+
+```javascript
+// @validateNoImpureFunctionsInRender
+
+import {identity, makeArray} from 'shared-runtime';
+
+function Component() {
+  const getDate = () => Date.now();
+  const array = makeArray(getDate());
+  const hasDate = identity(array);
+  return <Foo hasDate={hasDate} />;
+}
+
+```
+
+
+## Error
+
+```
+Found 1 error:
+
+Error: Cannot access impure value during render
+
+Calling an impure function can produce unstable results that update unpredictably when the component happens to re-render. (https://react.dev/reference/rules/components-and-hooks-must-be-pure#components-and-hooks-must-be-idempotent).
+
+error.invalid-impure-functions-in-render-indirect.ts:9:23
+   7 |   const array = makeArray(getDate());
+   8 |   const hasDate = identity(array);
+>  9 |   return <Foo hasDate={hasDate} />;
+     |                        ^^^^^^^ Cannot access impure value during render
+  10 | }
+  11 |
+
+error.invalid-impure-functions-in-render-indirect.ts:6:24
+  4 |
+  5 | function Component() {
+> 6 |   const getDate = () => Date.now();
+    |                         ^^^^^^^^^^ `Date.now` is an impure function.
+  7 |   const array = makeArray(getDate());
+  8 |   const hasDate = identity(array);
+  9 |   return <Foo hasDate={hasDate} />;
+```
+          
+      

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-impure-functions-in-render-indirect.js

@@ -2,11 +2,6 @@
 
 import {identity, makeArray} from 'shared-runtime';
 
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses an impure value during render. The impurity is lost
- * when passed through external function calls.
- */
 function Component() {
   const getDate = () => Date.now();
   const array = makeArray(getDate());

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-impure-functions-in-render-via-function-call-2.expect.md

@@ -0,0 +1,52 @@
+
+## Input
+
+```javascript
+// @validateNoImpureFunctionsInRender
+
+import {identity, makeArray} from 'shared-runtime';
+
+function Component() {
+  const now = () => Date.now();
+  const f = () => {
+    // this should error but we currently lose track of the impurity bc
+    // the impure value comes from behind a call
+    const array = makeArray(now());
+    const hasDate = identity(array);
+    return hasDate;
+  };
+  const hasDate = f();
+  return <Foo hasDate={hasDate} />;
+}
+
+```
+
+
+## Error
+
+```
+Found 1 error:
+
+Error: Cannot access impure value during render
+
+Calling an impure function can produce unstable results that update unpredictably when the component happens to re-render. (https://react.dev/reference/rules/components-and-hooks-must-be-pure#components-and-hooks-must-be-idempotent).
+
+error.invalid-impure-functions-in-render-via-function-call-2.ts:15:23
+  13 |   };
+  14 |   const hasDate = f();
+> 15 |   return <Foo hasDate={hasDate} />;
+     |                        ^^^^^^^ Cannot access impure value during render
+  16 | }
+  17 |
+
+error.invalid-impure-functions-in-render-via-function-call-2.ts:6:20
+  4 |
+  5 | function Component() {
+> 6 |   const now = () => Date.now();
+    |                     ^^^^^^^^^^ `Date.now` is an impure function.
+  7 |   const f = () => {
+  8 |     // this should error but we currently lose track of the impurity bc
+  9 |     // the impure value comes from behind a call
+```
+          
+      

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-impure-functions-in-render-via-function-call-2.js

@@ -2,14 +2,11 @@
 
 import {identity, makeArray} from 'shared-runtime';
 
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses an impure value during render. The impurity is lost
- * when passed through external function calls.
- */
 function Component() {
   const now = () => Date.now();
   const f = () => {
+    // this should error but we currently lose track of the impurity bc
+    // the impure value comes from behind a call
     const array = makeArray(now());
     const hasDate = identity(array);
     return hasDate;

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-impure-functions-in-render-via-render-helper-typed.expect.md

@@ -7,7 +7,7 @@
 import {typedArrayPush, typedIdentity} from 'shared-runtime';
 
 function Component() {
-  const now = () => Date.now();
+  const now = Date.now();
   const renderItem = () => {
     const array = [];
     typedArrayPush(array, now());
@@ -29,20 +29,19 @@ Error: Cannot access impure value during render
 
 Calling an impure function can produce unstable results that update unpredictably when the component happens to re-render. (https://react.dev/reference/rules/components-and-hooks-must-be-pure#components-and-hooks-must-be-idempotent).
 
-error.invalid-impure-functions-in-render-via-render-helper-typed.ts:11:25
-   9 |     typedArrayPush(array, now());
-  10 |     const hasDate = typedIdentity(array);
-> 11 |     return <Bar hasDate={hasDate} />;
-     |                          ^^^^^^^ Cannot access impure value during render
+error.invalid-impure-functions-in-render-via-render-helper-typed.ts:13:26
+  11 |     return <Bar hasDate={hasDate} />;
   12 |   };
-  13 |   return <Foo renderItem={renderItem} />;
+> 13 |   return <Foo renderItem={renderItem} />;
+     |                           ^^^^^^^^^^ Cannot access impure value during render
   14 | }
+  15 |
 
-error.invalid-impure-functions-in-render-via-render-helper-typed.ts:6:20
+error.invalid-impure-functions-in-render-via-render-helper-typed.ts:6:14
   4 |
   5 | function Component() {
-> 6 |   const now = () => Date.now();
-    |                     ^^^^^^^^^^ `Date.now` is an impure function.
+> 6 |   const now = Date.now();
+    |               ^^^^^^^^^^ `Date.now` is an impure function.
   7 |   const renderItem = () => {
   8 |     const array = [];
   9 |     typedArrayPush(array, now());

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-impure-functions-in-render-via-render-helper-typed.js

@@ -3,7 +3,7 @@
 import {typedArrayPush, typedIdentity} from 'shared-runtime';
 
 function Component() {
-  const now = () => Date.now();
+  const now = Date.now();
   const renderItem = () => {
     const array = [];
     typedArrayPush(array, now());

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-impure-functions-in-render-via-render-helper.expect.md

@@ -0,0 +1,49 @@
+
+## Input
+
+```javascript
+// @validateNoImpureFunctionsInRender
+
+import {identity, makeArray} from 'shared-runtime';
+
+function Component() {
+  const now = Date.now();
+  const renderItem = () => {
+    const array = makeArray(now);
+    const hasDate = identity(array);
+    return <Bar hasDate={hasDate} />;
+  };
+  return <Foo renderItem={renderItem} />;
+}
+
+```
+
+
+## Error
+
+```
+Found 1 error:
+
+Error: Cannot access impure value during render
+
+Calling an impure function can produce unstable results that update unpredictably when the component happens to re-render. (https://react.dev/reference/rules/components-and-hooks-must-be-pure#components-and-hooks-must-be-idempotent).
+
+error.invalid-impure-functions-in-render-via-render-helper.ts:12:26
+  10 |     return <Bar hasDate={hasDate} />;
+  11 |   };
+> 12 |   return <Foo renderItem={renderItem} />;
+     |                           ^^^^^^^^^^ Cannot access impure value during render
+  13 | }
+  14 |
+
+error.invalid-impure-functions-in-render-via-render-helper.ts:6:14
+  4 |
+  5 | function Component() {
+> 6 |   const now = Date.now();
+    |               ^^^^^^^^^^ `Date.now` is an impure function.
+  7 |   const renderItem = () => {
+  8 |     const array = makeArray(now);
+  9 |     const hasDate = identity(array);
+```
+          
+      

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-impure-functions-in-render-via-render-helper.js

@@ -6,8 +6,6 @@ function Component() {
   const now = Date.now();
   const renderItem = () => {
     const array = makeArray(now);
-    // we don't have an alias signature for identity(), so we optimistically
-    // assume this doesn't propagate the impurity
     const hasDate = identity(array);
     return <Bar hasDate={hasDate} />;
   };

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-impure-value-in-render-helper.expect.md

@@ -17,7 +17,7 @@ function Component() {
 ## Error
 
 ```
-Found 2 errors:
+Found 1 error:
 
 Error: Cannot access impure value during render
 
@@ -32,27 +32,6 @@ error.invalid-impure-value-in-render-helper.ts:5:17
   7 |   return <div>{render()}</div>;
   8 | }
 
-error.invalid-impure-value-in-render-helper.ts:3:20
-  1 | // @validateNoImpureFunctionsInRender
-  2 | function Component() {
-> 3 |   const now = () => Date.now();
-    |                     ^^^^^^^^^^ `Date.now` is an impure function.
-  4 |   const render = () => {
-  5 |     return <div>{now()}</div>;
-  6 |   };
-
-Error: Cannot access impure value during render
-
-Calling an impure function can produce unstable results that update unpredictably when the component happens to re-render. (https://react.dev/reference/rules/components-and-hooks-must-be-pure#components-and-hooks-must-be-idempotent).
-
-error.invalid-impure-value-in-render-helper.ts:7:15
-  5 |     return <div>{now()}</div>;
-  6 |   };
-> 7 |   return <div>{render()}</div>;
-    |                ^^^^^^^^ Cannot access impure value during render
-  8 | }
-  9 |
-
 error.invalid-impure-value-in-render-helper.ts:3:20
   1 | // @validateNoImpureFunctionsInRender
   2 | function Component() {

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-pass-ref-to-function.expect.md

@@ -0,0 +1,34 @@
+
+## Input
+
+```javascript
+// @validateRefAccessDuringRender
+function Component(props) {
+  const ref = useRef(null);
+  const x = foo(ref);
+  return x.current;
+}
+
+```
+
+
+## Error
+
+```
+Found 1 error:
+
+Error: Cannot access refs during render
+
+React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+
+error.invalid-pass-ref-to-function.ts:4:16
+  2 | function Component(props) {
+  3 |   const ref = useRef(null);
+> 4 |   const x = foo(ref);
+    |                 ^^^ Passing a ref to a function may read its value during render
+  5 |   return x.current;
+  6 | }
+  7 |
+```
+          
+      

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-pass-ref-to-function.js

@@ -0,0 +1,6 @@
+// @validateRefAccessDuringRender
+function Component(props) {
+  const ref = useRef(null);
+  const x = foo(ref);
+  return x.current;
+}

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-read-ref-prop-in-render-destructure.expect.md

@@ -18,7 +18,7 @@ Found 1 error:
 
 Error: Cannot access ref value during render
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
 error.invalid-read-ref-prop-in-render-destructure.ts:4:15
   2 | function Component({ref}) {

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-read-ref-prop-in-render-property-load.expect.md

@@ -18,7 +18,7 @@ Found 1 error:
 
 Error: Cannot access ref value during render
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
 error.invalid-read-ref-prop-in-render-property-load.ts:4:15
   2 | function Component(props) {

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-ref-access-render-unary.expect.md

@@ -26,7 +26,7 @@ Found 1 error:
 
 Error: Cannot access ref value during render
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
    5 |   const r = useRef(null);
    6 |   const current = !r.current;

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-ref-in-callback-invoked-during-render.expect.md

@@ -22,7 +22,7 @@ Found 1 error:
 
 Error: Cannot access ref value during render
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
 error.invalid-ref-in-callback-invoked-during-render.ts:6:37
   4 |   const renderItem = item => {

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-ref-initialization-unary-not.expect.md

@@ -25,17 +25,19 @@ export const FIXTURE_ENTRYPOINT = {
 ```
 Found 1 error:
 
-Error: Cannot access refs during render
+Error: Mutating refs during render is not allowed
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
    5 |   const r = useRef(null);
    6 |   if (!r.current) {
 >  7 |     r.current = 1;
-     |     ^^^^^^^^^ Cannot update ref during render
+     |     ^ Cannot mutate ref during render
    8 |   }
    9 | }
   10 |
+
+Refs may be mutated during render if initialized with `if (ref.current == null)`
 ```
           
       

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-ref-value-as-props.expect.md

@@ -18,7 +18,7 @@ Found 1 error:
 
 Error: Cannot access ref value during render
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
 error.invalid-ref-value-as-props.ts:4:19
   2 | function Component(props) {

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-set-and-read-ref-during-render.expect.md

@@ -19,7 +19,7 @@ Found 1 error:
 
 Error: Cannot access ref value during render
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
 error.invalid-set-and-read-ref-during-render.ts:5:9
   3 |   const ref = useRef(null);

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-set-and-read-ref-nested-property-during-render.expect.md

@@ -19,7 +19,7 @@ Found 1 error:
 
 Error: Cannot access ref value during render
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
 error.invalid-set-and-read-ref-nested-property-during-render.ts:5:9
   3 |   const ref = useRef({inner: null});

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-use-ref-added-to-dep-without-type-info.expect.md

@@ -0,0 +1,53 @@
+
+## Input
+
+```javascript
+// @validateRefAccessDuringRender
+function Foo({a}) {
+  const ref = useRef();
+  // type information is lost here as we don't track types of fields
+  const val = {ref};
+  // without type info, we don't know that val.ref.current is a ref value so we
+  // *would* end up depending on val.ref.current
+  // however, this is an instance of accessing a ref during render and is disallowed
+  // under React's rules, so we reject this input
+  const x = {a, val: val.ref.current};
+
+  return <VideoList videos={x} />;
+}
+
+```
+
+
+## Error
+
+```
+Found 2 errors:
+
+Error: Cannot access refs during render
+
+React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+
+error.invalid-use-ref-added-to-dep-without-type-info.ts:10:21
+   8 |   // however, this is an instance of accessing a ref during render and is disallowed
+   9 |   // under React's rules, so we reject this input
+> 10 |   const x = {a, val: val.ref.current};
+     |                      ^^^^^^^^^^^^^^^ Cannot access ref value during render
+  11 |
+  12 |   return <VideoList videos={x} />;
+  13 | }
+
+Error: Cannot access refs during render
+
+React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+
+error.invalid-use-ref-added-to-dep-without-type-info.ts:12:28
+  10 |   const x = {a, val: val.ref.current};
+  11 |
+> 12 |   return <VideoList videos={x} />;
+     |                             ^ Cannot access ref value during render
+  13 | }
+  14 |
+```
+          
+      

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-use-ref-added-to-dep-without-type-info.js

@@ -0,0 +1,13 @@
+// @validateRefAccessDuringRender
+function Foo({a}) {
+  const ref = useRef();
+  // type information is lost here as we don't track types of fields
+  const val = {ref};
+  // without type info, we don't know that val.ref.current is a ref value so we
+  // *would* end up depending on val.ref.current
+  // however, this is an instance of accessing a ref during render and is disallowed
+  // under React's rules, so we reject this input
+  const x = {a, val: val.ref.current};
+
+  return <VideoList videos={x} />;
+}

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-write-but-dont-read-ref-in-render.expect.md

@@ -19,18 +19,20 @@ function useHook({value}) {
 ```
 Found 1 error:
 
-Error: Cannot access refs during render
+Error: Mutating refs during render is not allowed
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
 error.invalid-write-but-dont-read-ref-in-render.ts:5:2
   3 |   const ref = useRef(null);
   4 |   // Writing to a ref in render is against the rules:
 > 5 |   ref.current = value;
-    |   ^^^^^^^^^^^ Cannot update ref during render
+    |   ^^^ Cannot mutate ref during render
   6 |   // returning a ref is allowed, so this alone doesn't trigger an error:
   7 |   return ref;
   8 | }
+
+Refs may be mutated during render if initialized with `if (ref.current == null)`
 ```
           
       

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.invalid-write-ref-prop-in-render.expect.md

@@ -17,18 +17,20 @@ function Component(props) {
 ```
 Found 1 error:
 
-Error: Cannot access refs during render
+Error: Mutating refs during render is not allowed
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
 error.invalid-write-ref-prop-in-render.ts:4:2
   2 | function Component(props) {
   3 |   const ref = props.ref;
 > 4 |   ref.current = true;
-    |   ^^^^^^^^^^^ Cannot update ref during render
+    |   ^^^ Cannot mutate ref during render
   5 |   return <div>{value}</div>;
   6 | }
   7 |
+
+Refs may be mutated during render if initialized with `if (ref.current == null)`
 ```
           
       

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.ref-initialization-arbitrary.expect.md

@@ -27,17 +27,19 @@ export const FIXTURE_ENTRYPOINT = {
 ```
 Found 1 error:
 
-Error: Cannot access refs during render
+Error: Mutating refs during render is not allowed
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
    7 |   const r = useRef(DEFAULT_VALUE);
    8 |   if (r.current == DEFAULT_VALUE) {
 >  9 |     r.current = 1;
-     |     ^^^^^^^^^ Cannot update ref during render
+     |     ^ Cannot mutate ref during render
   10 |   }
   11 | }
   12 |
+
+Refs may be mutated during render if initialized with `if (ref.current == null)`
 ```
           
       

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.ref-initialization-call-2.expect.md

@@ -0,0 +1,41 @@
+
+## Input
+
+```javascript
+//@flow
+import {useRef} from 'react';
+
+component C() {
+  const r = useRef(null);
+  if (r.current == null) {
+    f(r);
+  }
+}
+
+export const FIXTURE_ENTRYPOINT = {
+  fn: C,
+  params: [{}],
+};
+
+```
+
+
+## Error
+
+```
+Found 1 error:
+
+Error: Cannot access refs during render
+
+React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+
+   5 |   const r = useRef(null);
+   6 |   if (r.current == null) {
+>  7 |     f(r);
+     |       ^ Passing a ref to a function may read its value during render
+   8 |   }
+   9 | }
+  10 |
+```
+          
+      

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.ref-initialization-call-2.js

@@ -1,10 +1,6 @@
 //@flow
 import {useRef} from 'react';
 
-/**
- * Allowed: we aren't sure that the ref.current value flows into the render
- * output, so we optimistically assume it's safe
- */
 component C() {
   const r = useRef(null);
   if (r.current == null) {

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.ref-initialization-call.expect.md

@@ -0,0 +1,41 @@
+
+## Input
+
+```javascript
+//@flow
+import {useRef} from 'react';
+
+component C() {
+  const r = useRef(null);
+  if (r.current == null) {
+    f(r.current);
+  }
+}
+
+export const FIXTURE_ENTRYPOINT = {
+  fn: C,
+  params: [{}],
+};
+
+```
+
+
+## Error
+
+```
+Found 1 error:
+
+Error: Cannot access refs during render
+
+React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+
+   5 |   const r = useRef(null);
+   6 |   if (r.current == null) {
+>  7 |     f(r.current);
+     |       ^^^^^^^^^ Passing a ref to a function may read its value during render
+   8 |   }
+   9 | }
+  10 |
+```
+          
+      

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.ref-initialization-call.js

@@ -1,10 +1,6 @@
 //@flow
 import {useRef} from 'react';
 
-/**
- * Allowed: we aren't sure that the ref.current value flows into the render
- * output, so we optimistically assume it's safe
- */
 component C() {
   const r = useRef(null);
   if (r.current == null) {

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.ref-initialization-linear.expect.md

@@ -24,27 +24,35 @@ export const FIXTURE_ENTRYPOINT = {
 ## Error
 
 ```
-Found 1 error:
+Found 2 errors:
 
-Error: Cannot access refs during render
+Error: Mutating refs during render is not allowed
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
-
-   6 |   if (r.current == null) {
-   7 |     r.current = 42;
->  8 |     r.current = 42;
-     |     ^^^^^^^^^ Ref is initialized more than once during render
-   9 |   }
-  10 | }
-  11 |
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
    5 |   const r = useRef(null);
    6 |   if (r.current == null) {
 >  7 |     r.current = 42;
-     |     ^^^^^^^^^ Ref was first initialized here
+     |     ^ Cannot mutate ref during render
    8 |     r.current = 42;
    9 |   }
   10 | }
+
+Refs may be mutated during render if initialized with `if (ref.current == null)`
+
+Error: Mutating refs during render is not allowed
+
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
+
+   6 |   if (r.current == null) {
+   7 |     r.current = 42;
+>  8 |     r.current = 42;
+     |     ^ Cannot mutate ref during render
+   9 |   }
+  10 | }
+  11 |
+
+Refs may be mutated during render if initialized with `if (ref.current == null)`
 ```
           
       

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.ref-initialization-nonif.expect.md

@@ -26,17 +26,19 @@ export const FIXTURE_ENTRYPOINT = {
 ```
 Found 1 error:
 
-Error: Cannot access refs during render
+Error: Mutating refs during render is not allowed
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
    6 |   const guard = r.current == null;
    7 |   if (guard) {
 >  8 |     r.current = 1;
-     |     ^^^^^^^^^ Cannot update ref during render
+     |     ^ Cannot mutate ref during render
    9 |   }
   10 | }
   11 |
+
+Refs may be mutated during render if initialized with `if (ref.current == null)`
 ```
           
       

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.ref-initialization-other.expect.md

@@ -26,17 +26,19 @@ export const FIXTURE_ENTRYPOINT = {
 ```
 Found 1 error:
 
-Error: Cannot access refs during render
+Error: Mutating refs during render is not allowed
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
    6 |   const r2 = useRef(null);
    7 |   if (r.current == null) {
 >  8 |     r2.current = 1;
-     |     ^^^^^^^^^^ Cannot update ref during render
+     |     ^^ Cannot mutate ref during render
    9 |   }
   10 | }
   11 |
+
+Refs may be mutated during render if initialized with `if (ref.current == null)`
 ```
           
       

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.ref-initialization-post-access-2.expect.md

@@ -0,0 +1,44 @@
+
+## Input
+
+```javascript
+//@flow
+import {useRef} from 'react';
+
+component C() {
+  const r = useRef(null);
+  if (r.current == null) {
+    r.current = 1;
+  }
+  f(r.current);
+}
+
+export const FIXTURE_ENTRYPOINT = {
+  fn: C,
+  params: [{}],
+};
+
+```
+
+
+## Error
+
+```
+Found 1 error:
+
+Error: Mutating refs during render is not allowed
+
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
+
+   5 |   const r = useRef(null);
+   6 |   if (r.current == null) {
+>  7 |     r.current = 1;
+     |     ^ Cannot mutate ref during render
+   8 |   }
+   9 |   f(r.current);
+  10 | }
+
+Refs may be mutated during render if initialized with `if (ref.current == null)`
+```
+          
+      

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.ref-initialization-post-access-2.js

@@ -1,10 +1,6 @@
 //@flow
 import {useRef} from 'react';
 
-/**
- * Allowed: we aren't sure that the ref.current value flows into the render
- * output, so we optimistically assume it's safe
- */
 component C() {
   const r = useRef(null);
   if (r.current == null) {

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.ref-initialization-post-access.expect.md

@@ -26,17 +26,19 @@ export const FIXTURE_ENTRYPOINT = {
 ```
 Found 1 error:
 
-Error: Cannot access refs during render
+Error: Mutating refs during render is not allowed
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
    7 |     r.current = 1;
    8 |   }
 >  9 |   r.current = 1;
-     |   ^^^^^^^^^ Cannot update ref during render
+     |   ^ Cannot mutate ref during render
   10 | }
   11 |
   12 | export const FIXTURE_ENTRYPOINT = {
+
+Refs may be mutated during render if initialized with `if (ref.current == null)`
 ```
           
       

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.ref-optional.expect.md

@@ -24,7 +24,7 @@ Found 1 error:
 
 Error: Cannot access ref value during render
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
 error.ref-optional.ts:5:9
   3 | function Component(props) {

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.ref-value-in-custom-component-event-handler-wrapper.expect.md

@@ -0,0 +1,69 @@
+
+## Input
+
+```javascript
+// @enableInferEventHandlers
+import {useRef} from 'react';
+
+// Simulates a custom component wrapper
+function CustomForm({onSubmit, children}: any) {
+  return <form onSubmit={onSubmit}>{children}</form>;
+}
+
+// Simulates react-hook-form's handleSubmit
+function handleSubmit<T>(callback: (data: T) => void) {
+  return (event: any) => {
+    event.preventDefault();
+    callback({} as T);
+  };
+}
+
+function Component() {
+  const ref = useRef<HTMLInputElement>(null);
+
+  const onSubmit = (data: any) => {
+    // This should error: passing function with ref access to custom component
+    // event handler, even though it would be safe on a native <form>
+    if (ref.current !== null) {
+      console.log(ref.current.value);
+    }
+  };
+
+  return (
+    <>
+      <input ref={ref} />
+      <CustomForm onSubmit={handleSubmit(onSubmit)}>
+        <button type="submit">Submit</button>
+      </CustomForm>
+    </>
+  );
+}
+
+export const FIXTURE_ENTRYPOINT = {
+  fn: Component,
+  params: [{}],
+};
+
+```
+
+
+## Error
+
+```
+Found 1 error:
+
+Error: Cannot access refs during render
+
+React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+
+error.ref-value-in-custom-component-event-handler-wrapper.ts:31:41
+  29 |     <>
+  30 |       <input ref={ref} />
+> 31 |       <CustomForm onSubmit={handleSubmit(onSubmit)}>
+     |                                          ^^^^^^^^ Passing a ref to a function may read its value during render
+  32 |         <button type="submit">Submit</button>
+  33 |       </CustomForm>
+  34 |     </>
+```
+          
+      

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.ref-value-in-custom-component-event-handler-wrapper.tsx

@@ -18,8 +18,8 @@ function Component() {
   const ref = useRef<HTMLInputElement>(null);
 
   const onSubmit = (data: any) => {
-    // Allowed: we aren't sure that the ref.current value flows into the render
-    // output, so we optimistically assume it's safe
+    // This should error: passing function with ref access to custom component
+    // event handler, even though it would be safe on a native <form>
     if (ref.current !== null) {
       console.log(ref.current.value);
     }

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.ref-value-in-event-handler-wrapper.expect.md

@@ -0,0 +1,64 @@
+
+## Input
+
+```javascript
+// @enableInferEventHandlers
+import {useRef} from 'react';
+
+// Simulates a handler wrapper
+function handleClick(value: any) {
+  return () => {
+    console.log(value);
+  };
+}
+
+function Component() {
+  const ref = useRef(null);
+
+  // This should still error: passing ref.current directly to a wrapper
+  // The ref value is accessed during render, not in the event handler
+  return (
+    <>
+      <input ref={ref} />
+      <button onClick={handleClick(ref.current)}>Click</button>
+    </>
+  );
+}
+
+export const FIXTURE_ENTRYPOINT = {
+  fn: Component,
+  params: [{}],
+};
+
+```
+
+
+## Error
+
+```
+Found 1 error:
+
+Error: Cannot access ref value during render
+
+React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+
+error.ref-value-in-event-handler-wrapper.ts:19:6
+  17 |     <>
+  18 |       <input ref={ref} />
+> 19 |       <button onClick={handleClick(ref.current)}>Click</button>
+     |       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Ref value is used during render
+  20 |     </>
+  21 |   );
+  22 | }
+
+error.ref-value-in-event-handler-wrapper.ts:19:35
+  17 |     <>
+  18 |       <input ref={ref} />
+> 19 |       <button onClick={handleClick(ref.current)}>Click</button>
+     |                                    ^^^^^^^^^^^ Ref is initially accessed
+  20 |     </>
+  21 |   );
+  22 | }
+```
+          
+      

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.ref-value-in-event-handler-wrapper.tsx

@@ -11,8 +11,8 @@ function handleClick(value: any) {
 function Component() {
   const ref = useRef(null);
 
-  // Allowed: we aren't sure that the ref.current value flows into the render
-  // output, so we optimistically assume it's safe
+  // This should still error: passing ref.current directly to a wrapper
+  // The ref value is accessed during render, not in the event handler
   return (
     <>
       <input ref={ref} />

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.todo-useCallback-set-ref-nested-property-ref-modified-later-preserve-memoization.expect.md

@@ -33,15 +33,15 @@ export const FIXTURE_ENTRYPOINT = {
 ```
 Found 1 error:
 
-Error: Cannot access refs during render
+Error: Mutating refs during render is not allowed
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
 error.todo-useCallback-set-ref-nested-property-ref-modified-later-preserve-memoization.ts:14:2
   12 |
   13 |   // The ref is modified later, extending its range and preventing memoization of onChange
 > 14 |   ref.current.inner = null;
-     |   ^^^^^^^^^^^^^^^^^ Cannot update ref during render
+     |   ^^^^^^^^^^^ Cannot mutate ref during render
   15 |
   16 |   return <input onChange={onChange} />;
   17 | }

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.useCallback-accesses-ref-mutated-later-via-function-preserve-memoization.expect.md

@@ -36,15 +36,15 @@ export const FIXTURE_ENTRYPOINT = {
 ```
 Found 1 error:
 
-Error: Cannot access refs during render
+Error: Mutating refs during render is not allowed
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
 error.useCallback-accesses-ref-mutated-later-via-function-preserve-memoization.ts:15:4
   13 |   // The ref is modified later, extending its range and preventing memoization of onChange
   14 |   const reset = () => {
 > 15 |     ref.current.inner = null;
-     |     ^^^^^^^^^^^^^^^^^ Cannot update ref during render
+     |     ^^^^^^^^^^^ Cannot mutate ref during render
   16 |   };
   17 |   reset();
   18 |

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.useCallback-set-ref-nested-property-dont-preserve-memoization.expect.md

@@ -32,15 +32,15 @@ export const FIXTURE_ENTRYPOINT = {
 ```
 Found 1 error:
 
-Error: Cannot access refs during render
+Error: Mutating refs during render is not allowed
 
-React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef.
 
 error.useCallback-set-ref-nested-property-dont-preserve-memoization.ts:13:2
   11 |   });
   12 |
 > 13 |   ref.current.inner = null;
-     |   ^^^^^^^^^^^^^^^^^ Cannot update ref during render
+     |   ^^^^^^^^^^^ Cannot mutate ref during render
   14 |
   15 |   return <input onChange={onChange} />;
   16 | }

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.validate-mutate-ref-arg-in-render.expect.md

@@ -0,0 +1,39 @@
+
+## Input
+
+```javascript
+// @validateRefAccessDuringRender:true
+function Foo(props, ref) {
+  console.log(ref.current);
+  return <div>{props.bar}</div>;
+}
+
+export const FIXTURE_ENTRYPOINT = {
+  fn: Foo,
+  params: [{bar: 'foo'}, {ref: {cuurrent: 1}}],
+  isComponent: true,
+};
+
+```
+
+
+## Error
+
+```
+Found 1 error:
+
+Error: Cannot access refs during render
+
+React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+
+error.validate-mutate-ref-arg-in-render.ts:3:14
+  1 | // @validateRefAccessDuringRender:true
+  2 | function Foo(props, ref) {
+> 3 |   console.log(ref.current);
+    |               ^^^^^^^^^^^ Passing a ref to a function may read its value during render
+  4 |   return <div>{props.bar}</div>;
+  5 | }
+  6 |
+```
+          
+      

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/error.validate-mutate-ref-arg-in-render.js

@@ -1,7 +1,5 @@
 // @validateRefAccessDuringRender:true
-
 function Foo(props, ref) {
-  // Allowed: the value is not guaranteed to flow into something that's rendered
   console.log(ref.current);
   return <div>{props.bar}</div>;
 }

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/impure-functions-in-render-indirect.expect.md

@@ -1,56 +0,0 @@
-
-## Input
-
-```javascript
-// @validateNoImpureFunctionsInRender
-
-import {identity, makeArray} from 'shared-runtime';
-
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses an impure value during render. The impurity is lost
- * when passed through external function calls.
- */
-function Component() {
-  const getDate = () => Date.now();
-  const array = makeArray(getDate());
-  const hasDate = identity(array);
-  return <Foo hasDate={hasDate} />;
-}
-
-```
-
-## Code
-
-```javascript
-import { c as _c } from "react/compiler-runtime"; // @validateNoImpureFunctionsInRender
-
-import { identity, makeArray } from "shared-runtime";
-
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses an impure value during render. The impurity is lost
- * when passed through external function calls.
- */
-function Component() {
-  const $ = _c(1);
-  const getDate = _temp;
-  let t0;
-  if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
-    const array = makeArray(getDate());
-    const hasDate = identity(array);
-    t0 = <Foo hasDate={hasDate} />;
-    $[0] = t0;
-  } else {
-    t0 = $[0];
-  }
-  return t0;
-}
-function _temp() {
-  return Date.now();
-}
-
-```
-      
-### Eval output
-(kind: exception) Fixture not implemented

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/impure-functions-in-render-via-function-call-2.expect.md

@@ -1,64 +0,0 @@
-
-## Input
-
-```javascript
-// @validateNoImpureFunctionsInRender
-
-import {identity, makeArray} from 'shared-runtime';
-
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses an impure value during render. The impurity is lost
- * when passed through external function calls.
- */
-function Component() {
-  const now = () => Date.now();
-  const f = () => {
-    const array = makeArray(now());
-    const hasDate = identity(array);
-    return hasDate;
-  };
-  const hasDate = f();
-  return <Foo hasDate={hasDate} />;
-}
-
-```
-
-## Code
-
-```javascript
-import { c as _c } from "react/compiler-runtime"; // @validateNoImpureFunctionsInRender
-
-import { identity, makeArray } from "shared-runtime";
-
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses an impure value during render. The impurity is lost
- * when passed through external function calls.
- */
-function Component() {
-  const $ = _c(1);
-  const now = _temp;
-  let t0;
-  if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
-    const f = () => {
-      const array = makeArray(now());
-      const hasDate = identity(array);
-      return hasDate;
-    };
-    const hasDate_0 = f();
-    t0 = <Foo hasDate={hasDate_0} />;
-    $[0] = t0;
-  } else {
-    t0 = $[0];
-  }
-  return t0;
-}
-function _temp() {
-  return Date.now();
-}
-
-```
-      
-### Eval output
-(kind: exception) Fixture not implemented

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/infer-effect-dependencies/bailout-retry/mutate-after-useeffect-ref-access.expect.md

@@ -47,7 +47,7 @@ export const FIXTURE_ENTRYPOINT = {
 ## Logs
 
 ```
-{"kind":"CompileError","fnLoc":{"start":{"line":6,"column":0,"index":158},"end":{"line":11,"column":1,"index":331},"filename":"mutate-after-useeffect-ref-access.ts"},"detail":{"options":{"category":"Refs","reason":"Cannot access refs during render","description":"React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef)","details":[{"kind":"error","loc":{"start":{"line":9,"column":2,"index":289},"end":{"line":9,"column":20,"index":307},"filename":"mutate-after-useeffect-ref-access.ts"},"message":"Cannot update ref during render"}]}}}
+{"kind":"CompileError","fnLoc":{"start":{"line":6,"column":0,"index":158},"end":{"line":11,"column":1,"index":331},"filename":"mutate-after-useeffect-ref-access.ts"},"detail":{"options":{"category":"Refs","reason":"Mutating refs during render is not allowed","description":"React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef","details":[{"kind":"error","loc":{"start":{"line":9,"column":2,"index":289},"end":{"line":9,"column":16,"index":303},"filename":"mutate-after-useeffect-ref-access.ts"},"message":"Cannot mutate ref during render"}]}}}
 {"kind":"AutoDepsDecorations","fnLoc":{"start":{"line":8,"column":2,"index":237},"end":{"line":8,"column":50,"index":285},"filename":"mutate-after-useeffect-ref-access.ts"},"decorations":[{"start":{"line":8,"column":24,"index":259},"end":{"line":8,"column":30,"index":265},"filename":"mutate-after-useeffect-ref-access.ts","identifierName":"arrRef"}]}
 {"kind":"CompileSuccess","fnLoc":{"start":{"line":6,"column":0,"index":158},"end":{"line":11,"column":1,"index":331},"filename":"mutate-after-useeffect-ref-access.ts"},"fnName":"Component","memoSlots":0,"memoBlocks":0,"memoValues":0,"prunedMemoBlocks":0,"prunedMemoValues":0}
 ```

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/new-mutability/mutate-after-useeffect-ref-access.expect.md

@@ -47,7 +47,7 @@ export const FIXTURE_ENTRYPOINT = {
 ## Logs
 
 ```
-{"kind":"CompileError","fnLoc":{"start":{"line":6,"column":0,"index":190},"end":{"line":11,"column":1,"index":363},"filename":"mutate-after-useeffect-ref-access.ts"},"detail":{"options":{"category":"Refs","reason":"Cannot access refs during render","description":"React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef)","details":[{"kind":"error","loc":{"start":{"line":9,"column":2,"index":321},"end":{"line":9,"column":20,"index":339},"filename":"mutate-after-useeffect-ref-access.ts"},"message":"Cannot update ref during render"}]}}}
+{"kind":"CompileError","fnLoc":{"start":{"line":6,"column":0,"index":190},"end":{"line":11,"column":1,"index":363},"filename":"mutate-after-useeffect-ref-access.ts"},"detail":{"options":{"category":"Refs","reason":"Mutating refs during render is not allowed","description":"React refs are mutable containers that should only be mutated outside of render, such as in event handlers or effects. Mutating a ref during render can cause bugs because the mutation may not be associated with a particular render. See https://react.dev/reference/react/useRef","details":[{"kind":"error","loc":{"start":{"line":9,"column":2,"index":321},"end":{"line":9,"column":16,"index":335},"filename":"mutate-after-useeffect-ref-access.ts"},"message":"Cannot mutate ref during render"}]}}}
 {"kind":"AutoDepsDecorations","fnLoc":{"start":{"line":8,"column":2,"index":269},"end":{"line":8,"column":50,"index":317},"filename":"mutate-after-useeffect-ref-access.ts"},"decorations":[{"start":{"line":8,"column":24,"index":291},"end":{"line":8,"column":30,"index":297},"filename":"mutate-after-useeffect-ref-access.ts","identifierName":"arrRef"}]}
 {"kind":"CompileSuccess","fnLoc":{"start":{"line":6,"column":0,"index":190},"end":{"line":11,"column":1,"index":363},"filename":"mutate-after-useeffect-ref-access.ts"},"fnName":"Component","memoSlots":0,"memoBlocks":0,"memoValues":0,"prunedMemoBlocks":0,"prunedMemoValues":0}
 ```

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/pass-ref-to-function.expect.md

@@ -1,45 +0,0 @@
-
-## Input
-
-```javascript
-// @validateRefAccessDuringRender
-
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses a ref during render. The return type of foo() is unknown.
- */
-function Component(props) {
-  const ref = useRef(null);
-  const x = foo(ref);
-  return x.current;
-}
-
-```
-
-## Code
-
-```javascript
-import { c as _c } from "react/compiler-runtime"; // @validateRefAccessDuringRender
-
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses a ref during render. The return type of foo() is unknown.
- */
-function Component(props) {
-  const $ = _c(1);
-  const ref = useRef(null);
-  let t0;
-  if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
-    t0 = foo(ref);
-    $[0] = t0;
-  } else {
-    t0 = $[0];
-  }
-  const x = t0;
-  return x.current;
-}
-
-```
-      
-### Eval output
-(kind: exception) Fixture not implemented

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/pass-ref-to-function.js

@@ -1,11 +0,0 @@
-// @validateRefAccessDuringRender
-
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses a ref during render. The return type of foo() is unknown.
- */
-function Component(props) {
-  const ref = useRef(null);
-  const x = foo(ref);
-  return x.current;
-}

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/preserve-memo-validation/error.maybe-mutable-ref-not-preserved.expect.md

@@ -0,0 +1,42 @@
+
+## Input
+
+```javascript
+// @validatePreserveExistingMemoizationGuarantees:true
+
+import {useRef, useMemo} from 'react';
+import {makeArray} from 'shared-runtime';
+
+function useFoo() {
+  const r = useRef();
+  return useMemo(() => makeArray(r), []);
+}
+
+export const FIXTURE_ENTRYPOINT = {
+  fn: useFoo,
+  params: [],
+};
+
+```
+
+
+## Error
+
+```
+Found 1 error:
+
+Error: Cannot access refs during render
+
+React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+
+error.maybe-mutable-ref-not-preserved.ts:8:33
+   6 | function useFoo() {
+   7 |   const r = useRef();
+>  8 |   return useMemo(() => makeArray(r), []);
+     |                                  ^ Passing a ref to a function may read its value during render
+   9 | }
+  10 |
+  11 | export const FIXTURE_ENTRYPOINT = {
+```
+          
+      

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/preserve-memo-validation/error.maybe-mutable-ref-not-preserved.ts

@@ -3,10 +3,6 @@
 import {useRef, useMemo} from 'react';
 import {makeArray} from 'shared-runtime';
 
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses an impure value during render.
- */
 function useFoo() {
   const r = useRef();
   return useMemo(() => makeArray(r), []);

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/preserve-memo-validation/error.useMemo-with-refs.flow.expect.md

@@ -0,0 +1,37 @@
+
+## Input
+
+```javascript
+// @flow @validatePreserveExistingMemoizationGuarantees
+import {identity} from 'shared-runtime';
+
+component Component(disableLocalRef, ref) {
+  const localRef = useFooRef();
+  const mergedRef = useMemo(() => {
+    return disableLocalRef ? ref : identity(ref, localRef);
+  }, [disableLocalRef, ref, localRef]);
+  return <div ref={mergedRef} />;
+}
+
+```
+
+
+## Error
+
+```
+Found 1 error:
+
+Error: Cannot access refs during render
+
+React refs are values that are not needed for rendering. Refs should only be accessed outside of render, such as in event handlers or effects. Accessing a ref value (the `current` property) during render can cause your component not to update as expected (https://react.dev/reference/react/useRef).
+
+   5 |   const localRef = useFooRef();
+   6 |   const mergedRef = useMemo(() => {
+>  7 |     return disableLocalRef ? ref : identity(ref, localRef);
+     |                                             ^^^ Passing a ref to a function may read its value during render
+   8 |   }, [disableLocalRef, ref, localRef]);
+   9 |   return <div ref={mergedRef} />;
+  10 | }
+```
+          
+      

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/preserve-memo-validation/maybe-mutable-ref-not-preserved.expect.md

@@ -1,59 +0,0 @@
-
-## Input
-
-```javascript
-// @validatePreserveExistingMemoizationGuarantees:true
-
-import {useRef, useMemo} from 'react';
-import {makeArray} from 'shared-runtime';
-
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses an impure value during render.
- */
-function useFoo() {
-  const r = useRef();
-  return useMemo(() => makeArray(r), []);
-}
-
-export const FIXTURE_ENTRYPOINT = {
-  fn: useFoo,
-  params: [],
-};
-
-```
-
-## Code
-
-```javascript
-import { c as _c } from "react/compiler-runtime"; // @validatePreserveExistingMemoizationGuarantees:true
-
-import { useRef, useMemo } from "react";
-import { makeArray } from "shared-runtime";
-
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses an impure value during render.
- */
-function useFoo() {
-  const $ = _c(1);
-  const r = useRef();
-  let t0;
-  if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
-    t0 = makeArray(r);
-    $[0] = t0;
-  } else {
-    t0 = $[0];
-  }
-  return t0;
-}
-
-export const FIXTURE_ENTRYPOINT = {
-  fn: useFoo,
-  params: [],
-};
-
-```
-      
-### Eval output
-(kind: ok) [{}]

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/preserve-memo-validation/useMemo-with-refs.flow.expect.md

@@ -1,52 +0,0 @@
-
-## Input
-
-```javascript
-// @flow @validatePreserveExistingMemoizationGuarantees
-import {identity} from 'shared-runtime';
-
-component Component(disableLocalRef, ref) {
-  const localRef = useFooRef();
-  const mergedRef = useMemo(() => {
-    return disableLocalRef ? ref : identity(ref, localRef);
-  }, [disableLocalRef, ref, localRef]);
-  return <div ref={mergedRef} />;
-}
-
-```
-
-## Code
-
-```javascript
-import { c as _c } from "react/compiler-runtime";
-import { identity } from "shared-runtime";
-
-const Component = React.forwardRef(Component_withRef);
-function Component_withRef(t0, ref) {
-  const $ = _c(6);
-  const { disableLocalRef } = t0;
-  const localRef = useFooRef();
-  let t1;
-  if ($[0] !== disableLocalRef || $[1] !== localRef || $[2] !== ref) {
-    t1 = disableLocalRef ? ref : identity(ref, localRef);
-    $[0] = disableLocalRef;
-    $[1] = localRef;
-    $[2] = ref;
-    $[3] = t1;
-  } else {
-    t1 = $[3];
-  }
-  const mergedRef = t1;
-  let t2;
-  if ($[4] !== mergedRef) {
-    t2 = <div ref={mergedRef} />;
-    $[4] = mergedRef;
-    $[5] = t2;
-  } else {
-    t2 = $[5];
-  }
-  return t2;
-}
-
-```
-      

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/ref-initialization-call-2.expect.md

@@ -1,46 +0,0 @@
-
-## Input
-
-```javascript
-//@flow
-import {useRef} from 'react';
-
-/**
- * Allowed: we aren't sure that the ref.current value flows into the render
- * output, so we optimistically assume it's safe
- */
-component C() {
-  const r = useRef(null);
-  if (r.current == null) {
-    f(r);
-  }
-}
-
-export const FIXTURE_ENTRYPOINT = {
-  fn: C,
-  params: [{}],
-};
-
-```
-
-## Code
-
-```javascript
-import { useRef } from "react";
-
-function C() {
-  const r = useRef(null);
-  if (r.current == null) {
-    f(r);
-  }
-}
-
-export const FIXTURE_ENTRYPOINT = {
-  fn: C,
-  params: [{}],
-};
-
-```
-      
-### Eval output
-(kind: exception) f is not defined

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/ref-initialization-call.expect.md

@@ -1,46 +0,0 @@
-
-## Input
-
-```javascript
-//@flow
-import {useRef} from 'react';
-
-/**
- * Allowed: we aren't sure that the ref.current value flows into the render
- * output, so we optimistically assume it's safe
- */
-component C() {
-  const r = useRef(null);
-  if (r.current == null) {
-    f(r.current);
-  }
-}
-
-export const FIXTURE_ENTRYPOINT = {
-  fn: C,
-  params: [{}],
-};
-
-```
-
-## Code
-
-```javascript
-import { useRef } from "react";
-
-function C() {
-  const r = useRef(null);
-  if (r.current == null) {
-    f(r.current);
-  }
-}
-
-export const FIXTURE_ENTRYPOINT = {
-  fn: C,
-  params: [{}],
-};
-
-```
-      
-### Eval output
-(kind: exception) f is not defined

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/ref-initialization-post-access-2.expect.md

@@ -1,49 +0,0 @@
-
-## Input
-
-```javascript
-//@flow
-import {useRef} from 'react';
-
-/**
- * Allowed: we aren't sure that the ref.current value flows into the render
- * output, so we optimistically assume it's safe
- */
-component C() {
-  const r = useRef(null);
-  if (r.current == null) {
-    r.current = 1;
-  }
-  f(r.current);
-}
-
-export const FIXTURE_ENTRYPOINT = {
-  fn: C,
-  params: [{}],
-};
-
-```
-
-## Code
-
-```javascript
-import { useRef } from "react";
-
-function C() {
-  const r = useRef(null);
-  if (r.current == null) {
-    r.current = 1;
-  }
-
-  f(r.current);
-}
-
-export const FIXTURE_ENTRYPOINT = {
-  fn: C,
-  params: [{}],
-};
-
-```
-      
-### Eval output
-(kind: exception) f is not defined

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/ref-value-in-custom-component-event-handler-wrapper.expect.md

@@ -1,121 +0,0 @@
-
-## Input
-
-```javascript
-// @enableInferEventHandlers
-import {useRef} from 'react';
-
-// Simulates a custom component wrapper
-function CustomForm({onSubmit, children}: any) {
-  return <form onSubmit={onSubmit}>{children}</form>;
-}
-
-// Simulates react-hook-form's handleSubmit
-function handleSubmit<T>(callback: (data: T) => void) {
-  return (event: any) => {
-    event.preventDefault();
-    callback({} as T);
-  };
-}
-
-function Component() {
-  const ref = useRef<HTMLInputElement>(null);
-
-  const onSubmit = (data: any) => {
-    // Allowed: we aren't sure that the ref.current value flows into the render
-    // output, so we optimistically assume it's safe
-    if (ref.current !== null) {
-      console.log(ref.current.value);
-    }
-  };
-
-  return (
-    <>
-      <input ref={ref} />
-      <CustomForm onSubmit={handleSubmit(onSubmit)}>
-        <button type="submit">Submit</button>
-      </CustomForm>
-    </>
-  );
-}
-
-export const FIXTURE_ENTRYPOINT = {
-  fn: Component,
-  params: [{}],
-};
-
-```
-
-## Code
-
-```javascript
-import { c as _c } from "react/compiler-runtime"; // @enableInferEventHandlers
-import { useRef } from "react";
-
-// Simulates a custom component wrapper
-function CustomForm(t0) {
-  const $ = _c(3);
-  const { onSubmit, children } = t0;
-  let t1;
-  if ($[0] !== children || $[1] !== onSubmit) {
-    t1 = <form onSubmit={onSubmit}>{children}</form>;
-    $[0] = children;
-    $[1] = onSubmit;
-    $[2] = t1;
-  } else {
-    t1 = $[2];
-  }
-  return t1;
-}
-
-// Simulates react-hook-form's handleSubmit
-function handleSubmit(callback) {
-  const $ = _c(2);
-  let t0;
-  if ($[0] !== callback) {
-    t0 = (event) => {
-      event.preventDefault();
-      callback({} as T);
-    };
-    $[0] = callback;
-    $[1] = t0;
-  } else {
-    t0 = $[1];
-  }
-  return t0;
-}
-
-function Component() {
-  const $ = _c(1);
-  const ref = useRef(null);
-  let t0;
-  if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
-    const onSubmit = (data) => {
-      if (ref.current !== null) {
-        console.log(ref.current.value);
-      }
-    };
-    t0 = (
-      <>
-        <input ref={ref} />
-        <CustomForm onSubmit={handleSubmit(onSubmit)}>
-          <button type="submit">Submit</button>
-        </CustomForm>
-      </>
-    );
-    $[0] = t0;
-  } else {
-    t0 = $[0];
-  }
-  return t0;
-}
-
-export const FIXTURE_ENTRYPOINT = {
-  fn: Component,
-  params: [{}],
-};
-
-```
-      
-### Eval output
-(kind: ok) <input><form><button type="submit">Submit</button></form>

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/ref-value-in-event-handler-wrapper.expect.md

@@ -1,83 +0,0 @@
-
-## Input
-
-```javascript
-// @enableInferEventHandlers
-import {useRef} from 'react';
-
-// Simulates a handler wrapper
-function handleClick(value: any) {
-  return () => {
-    console.log(value);
-  };
-}
-
-function Component() {
-  const ref = useRef(null);
-
-  // Allowed: we aren't sure that the ref.current value flows into the render
-  // output, so we optimistically assume it's safe
-  return (
-    <>
-      <input ref={ref} />
-      <button onClick={handleClick(ref.current)}>Click</button>
-    </>
-  );
-}
-
-export const FIXTURE_ENTRYPOINT = {
-  fn: Component,
-  params: [{}],
-};
-
-```
-
-## Code
-
-```javascript
-import { c as _c } from "react/compiler-runtime"; // @enableInferEventHandlers
-import { useRef } from "react";
-
-// Simulates a handler wrapper
-function handleClick(value) {
-  const $ = _c(2);
-  let t0;
-  if ($[0] !== value) {
-    t0 = () => {
-      console.log(value);
-    };
-    $[0] = value;
-    $[1] = t0;
-  } else {
-    t0 = $[1];
-  }
-  return t0;
-}
-
-function Component() {
-  const $ = _c(1);
-  const ref = useRef(null);
-  let t0;
-  if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
-    t0 = (
-      <>
-        <input ref={ref} />
-        <button onClick={handleClick(ref.current)}>Click</button>
-      </>
-    );
-    $[0] = t0;
-  } else {
-    t0 = $[0];
-  }
-  return t0;
-}
-
-export const FIXTURE_ENTRYPOINT = {
-  fn: Component,
-  params: [{}],
-};
-
-```
-      
-### Eval output
-(kind: ok) <input><button>Click</button>

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/use-ref-added-to-dep-without-type-info.expect.md

@@ -1,59 +0,0 @@
-
-## Input
-
-```javascript
-// @validateRefAccessDuringRender
-
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses a ref during render. Type info is lost when ref is
- * stored in an object field.
- */
-function Foo({a}) {
-  const ref = useRef();
-  const val = {ref};
-  const x = {a, val: val.ref.current};
-
-  return <VideoList videos={x} />;
-}
-
-```
-
-## Code
-
-```javascript
-import { c as _c } from "react/compiler-runtime"; // @validateRefAccessDuringRender
-
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses a ref during render. Type info is lost when ref is
- * stored in an object field.
- */
-function Foo(t0) {
-  const $ = _c(3);
-  const { a } = t0;
-  const ref = useRef();
-  let t1;
-  if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
-    t1 = { ref };
-    $[0] = t1;
-  } else {
-    t1 = $[0];
-  }
-  const val = t1;
-  let t2;
-  if ($[1] !== a) {
-    const x = { a, val: val.ref.current };
-    t2 = <VideoList videos={x} />;
-    $[1] = a;
-    $[2] = t2;
-  } else {
-    t2 = $[2];
-  }
-  return t2;
-}
-
-```
-      
-### Eval output
-(kind: exception) Fixture not implemented

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/use-ref-added-to-dep-without-type-info.js

@@ -1,14 +0,0 @@
-// @validateRefAccessDuringRender
-
-/**
- * Allowed: we don't have sufficient type information to be sure that
- * this accesses a ref during render. Type info is lost when ref is
- * stored in an object field.
- */
-function Foo({a}) {
-  const ref = useRef();
-  const val = {ref};
-  const x = {a, val: val.ref.current};
-
-  return <VideoList videos={x} />;
-}

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/valid-uncertain-impure-functions-in-render-via-render-helper.expect.md

@@ -1,51 +0,0 @@
-
-## Input
-
-```javascript
-// @validateNoImpureFunctionsInRender
-
-import {identity, makeArray} from 'shared-runtime';
-
-function Component() {
-  const now = Date.now();
-  const renderItem = () => {
-    const array = makeArray(now);
-    // we don't have an alias signature for identity(), so we optimistically
-    // assume this doesn't propagate the impurity
-    const hasDate = identity(array);
-    return <Bar hasDate={hasDate} />;
-  };
-  return <Foo renderItem={renderItem} />;
-}
-
-```
-
-## Code
-
-```javascript
-import { c as _c } from "react/compiler-runtime"; // @validateNoImpureFunctionsInRender
-
-import { identity, makeArray } from "shared-runtime";
-
-function Component() {
-  const $ = _c(1);
-  let t0;
-  if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
-    const now = Date.now();
-    const renderItem = () => {
-      const array = makeArray(now);
-      const hasDate = identity(array);
-      return <Bar hasDate={hasDate} />;
-    };
-    t0 = <Foo renderItem={renderItem} />;
-    $[0] = t0;
-  } else {
-    t0 = $[0];
-  }
-  return t0;
-}
-
-```
-      
-### Eval output
-(kind: exception) Fixture not implemented

compiler/packages/babel-plugin-react-compiler/src/__tests__/fixtures/compiler/validate-mutate-ref-arg-in-render.expect.md

@@ -1,51 +0,0 @@
-
-## Input
-
-```javascript
-// @validateRefAccessDuringRender:true
-
-function Foo(props, ref) {
-  // Allowed: the value is not guaranteed to flow into something that's rendered
-  console.log(ref.current);
-  return <div>{props.bar}</div>;
-}
-
-export const FIXTURE_ENTRYPOINT = {
-  fn: Foo,
-  params: [{bar: 'foo'}, {ref: {cuurrent: 1}}],
-  isComponent: true,
-};
-
-```
-
-## Code
-
-```javascript
-import { c as _c } from "react/compiler-runtime"; // @validateRefAccessDuringRender:true
-
-function Foo(props, ref) {
-  const $ = _c(2);
-
-  console.log(ref.current);
-  let t0;
-  if ($[0] !== props.bar) {
-    t0 = <div>{props.bar}</div>;
-    $[0] = props.bar;
-    $[1] = t0;
-  } else {
-    t0 = $[1];
-  }
-  return t0;
-}
-
-export const FIXTURE_ENTRYPOINT = {
-  fn: Foo,
-  params: [{ bar: "foo" }, { ref: { cuurrent: 1 } }],
-  isComponent: true,
-};
-
-```
-      
-### Eval output
-(kind: ok) <div>foo</div>
-logs: [undefined]

compiler/packages/eslint-plugin-react-compiler/__tests__/NoRefAccessInRender-tests.ts

@@ -27,7 +27,7 @@ testRule(
         return value;
       }
     `,
-        errors: [makeTestCaseError('Cannot access ref value during render')],
+        errors: [makeTestCaseError('Cannot access refs during render')],
       },
     ],
   },

compiler/packages/snap/src/constants.ts

@@ -26,3 +26,5 @@ export const FIXTURES_PATH = path.join(
   'compiler',
 );
 export const SNAPSHOT_EXTENSION = '.expect.md';
+export const FILTER_FILENAME = 'testfilter.txt';
+export const FILTER_PATH = path.join(PROJECT_ROOT, FILTER_FILENAME);

compiler/packages/snap/src/fixture-utils.ts

@@ -8,7 +8,7 @@
 import fs from 'fs/promises';
 import * as glob from 'glob';
 import path from 'path';
-import {FIXTURES_PATH, SNAPSHOT_EXTENSION} from './constants';
+import {FILTER_PATH, FIXTURES_PATH, SNAPSHOT_EXTENSION} from './constants';
 
 const INPUT_EXTENSIONS = [
   '.js',
@@ -22,9 +22,19 @@ const INPUT_EXTENSIONS = [
 ];
 
 export type TestFilter = {
+  debug: boolean;
   paths: Array<string>;
 };
 
+async function exists(file: string): Promise<boolean> {
+  try {
+    await fs.access(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function stripExtension(filename: string, extensions: Array<string>): string {
   for (const ext of extensions) {
     if (filename.endsWith(ext)) {
@@ -34,6 +44,37 @@ function stripExtension(filename: string, extensions: Array<string>): string {
   return filename;
 }
 
+export async function readTestFilter(): Promise<TestFilter | null> {
+  if (!(await exists(FILTER_PATH))) {
+    throw new Error(`testfilter file not found at \`${FILTER_PATH}\``);
+  }
+
+  const input = await fs.readFile(FILTER_PATH, 'utf8');
+  const lines = input.trim().split('\n');
+
+  let debug: boolean = false;
+  const line0 = lines[0];
+  if (line0 != null) {
+    // Try to parse pragmas
+    let consumedLine0 = false;
+    if (line0.indexOf('@only') !== -1) {
+      consumedLine0 = true;
+    }
+    if (line0.indexOf('@debug') !== -1) {
+      debug = true;
+      consumedLine0 = true;
+    }
+
+    if (consumedLine0) {
+      lines.shift();
+    }
+  }
+  return {
+    debug,
+    paths: lines.filter(line => !line.trimStart().startsWith('//')),
+  };
+}
+
 export function getBasename(fixture: TestFixture): string {
   return stripExtension(path.basename(fixture.inputPath), INPUT_EXTENSIONS);
 }

compiler/packages/snap/src/runner-watch.ts

@@ -8,8 +8,8 @@
 import watcher from '@parcel/watcher';
 import path from 'path';
 import ts from 'typescript';
-import {FIXTURES_PATH, PROJECT_ROOT} from './constants';
-import {TestFilter} from './fixture-utils';
+import {FILTER_FILENAME, FIXTURES_PATH, PROJECT_ROOT} from './constants';
+import {TestFilter, readTestFilter} from './fixture-utils';
 import {execSync} from 'child_process';
 
 export function watchSrc(
@@ -117,10 +117,6 @@ export type RunnerState = {
   lastUpdate: number;
   mode: RunnerMode;
   filter: TestFilter | null;
-  debug: boolean;
-  // Input mode for interactive pattern entry
-  inputMode: 'none' | 'pattern';
-  inputBuffer: string;
 };
 
 function subscribeFixtures(
@@ -146,6 +142,26 @@ function subscribeFixtures(
   });
 }
 
+function subscribeFilterFile(
+  state: RunnerState,
+  onChange: (state: RunnerState) => void,
+) {
+  watcher.subscribe(PROJECT_ROOT, async (err, events) => {
+    if (err) {
+      console.error(err);
+      process.exit(1);
+    } else if (
+      events.findIndex(event => event.path.includes(FILTER_FILENAME)) !== -1
+    ) {
+      if (state.mode.filter) {
+        state.filter = await readTestFilter();
+        state.mode.action = RunnerAction.Test;
+        onChange(state);
+      }
+    }
+  });
+}
+
 function subscribeTsc(
   state: RunnerState,
   onChange: (state: RunnerState) => void,
@@ -184,67 +200,15 @@ function subscribeKeyEvents(
   onChange: (state: RunnerState) => void,
 ) {
   process.stdin.on('keypress', async (str, key) => {
-    // Handle input mode (pattern entry)
-    if (state.inputMode !== 'none') {
-      if (key.name === 'return') {
-        // Enter pressed - process input
-        const pattern = state.inputBuffer.trim();
-        state.inputMode = 'none';
-        state.inputBuffer = '';
-        process.stdout.write('\n');
-
-        if (pattern !== '') {
-          // Set the pattern as filter
-          state.filter = {paths: [pattern]};
-          state.mode.filter = true;
-          state.mode.action = RunnerAction.Test;
-          onChange(state);
-        }
-        // If empty, just exit input mode without changes
-        return;
-      } else if (key.name === 'escape') {
-        // Cancel input mode
-        state.inputMode = 'none';
-        state.inputBuffer = '';
-        process.stdout.write(' (cancelled)\n');
-        return;
-      } else if (key.name === 'backspace') {
-        if (state.inputBuffer.length > 0) {
-          state.inputBuffer = state.inputBuffer.slice(0, -1);
-          // Erase character: backspace, space, backspace
-          process.stdout.write('\b \b');
-        }
-        return;
-      } else if (str && !key.ctrl && !key.meta) {
-        // Regular character - accumulate and echo
-        state.inputBuffer += str;
-        process.stdout.write(str);
-        return;
-      }
-      return; // Ignore other keys in input mode
-    }
-
-    // Normal mode keypress handling
     if (key.name === 'u') {
       // u => update fixtures
       state.mode.action = RunnerAction.Update;
     } else if (key.name === 'q') {
       process.exit(0);
-    } else if (key.name === 'a') {
-      // a => exit filter mode and run all tests
-      state.mode.filter = false;
-      state.filter = null;
+    } else if (key.name === 'f') {
+      state.mode.filter = !state.mode.filter;
+      state.filter = state.mode.filter ? await readTestFilter() : null;
       state.mode.action = RunnerAction.Test;
-    } else if (key.name === 'd') {
-      // d => toggle debug logging
-      state.debug = !state.debug;
-      state.mode.action = RunnerAction.Test;
-    } else if (key.name === 'p') {
-      // p => enter pattern input mode
-      state.inputMode = 'pattern';
-      state.inputBuffer = '';
-      process.stdout.write('Pattern: ');
-      return; // Don't trigger onChange yet
     } else {
       // any other key re-runs tests
       state.mode.action = RunnerAction.Test;
@@ -255,33 +219,21 @@ function subscribeKeyEvents(
 
 export async function makeWatchRunner(
   onChange: (state: RunnerState) => void,
-  debugMode: boolean,
-  initialPattern?: string,
+  filterMode: boolean,
 ): Promise<void> {
-  // Determine initial filter state
-  let filter: TestFilter | null = null;
-  let filterEnabled = false;
-
-  if (initialPattern) {
-    filter = {paths: [initialPattern]};
-    filterEnabled = true;
-  }
-
-  const state: RunnerState = {
+  const state = {
     compilerVersion: 0,
     isCompilerBuildValid: false,
     lastUpdate: -1,
     mode: {
       action: RunnerAction.Test,
-      filter: filterEnabled,
+      filter: filterMode,
     },
-    filter,
-    debug: debugMode,
-    inputMode: 'none',
-    inputBuffer: '',
+    filter: filterMode ? await readTestFilter() : null,
   };
 
   subscribeTsc(state, onChange);
   subscribeFixtures(state, onChange);
   subscribeKeyEvents(state, onChange);
+  subscribeFilterFile(state, onChange);
 }

compiler/packages/snap/src/runner.ts

@@ -12,8 +12,8 @@ import * as readline from 'readline';
 import ts from 'typescript';
 import yargs from 'yargs';
 import {hideBin} from 'yargs/helpers';
-import {PROJECT_ROOT} from './constants';
-import {TestFilter, getFixtures} from './fixture-utils';
+import {FILTER_PATH, PROJECT_ROOT} from './constants';
+import {TestFilter, getFixtures, readTestFilter} from './fixture-utils';
 import {TestResult, TestResults, report, update} from './reporter';
 import {
   RunnerAction,
@@ -33,9 +33,9 @@ type RunnerOptions = {
   sync: boolean;
   workerThreads: boolean;
   watch: boolean;
+  filter: boolean;
   update: boolean;
   pattern?: string;
-  debug: boolean;
 };
 
 const opts: RunnerOptions = yargs
@@ -59,16 +59,18 @@ const opts: RunnerOptions = yargs
   .alias('u', 'update')
   .describe('update', 'Update fixtures')
   .default('update', false)
+  .boolean('filter')
+  .describe(
+    'filter',
+    'Only run fixtures which match the contents of testfilter.txt',
+  )
+  .default('filter', false)
   .string('pattern')
   .alias('p', 'pattern')
   .describe(
     'pattern',
     'Optional glob pattern to filter fixtures (e.g., "error.*", "use-memo")',
   )
-  .boolean('debug')
-  .alias('d', 'debug')
-  .describe('debug', 'Enable debug logging to print HIR for each pass')
-  .default('debug', false)
   .help('help')
   .strict()
   .parseSync(hideBin(process.argv)) as RunnerOptions;
@@ -80,15 +82,12 @@ async function runFixtures(
   worker: Worker & typeof runnerWorker,
   filter: TestFilter | null,
   compilerVersion: number,
-  debug: boolean,
-  requireSingleFixture: boolean,
 ): Promise<TestResults> {
   // We could in theory be fancy about tracking the contents of the fixtures
   // directory via our file subscription, but it's simpler to just re-read
   // the directory each time.
   const fixtures = await getFixtures(filter);
   const isOnlyFixture = filter !== null && fixtures.size === 1;
-  const shouldLog = debug && (!requireSingleFixture || isOnlyFixture);
 
   let entries: Array<[string, TestResult]>;
   if (!opts.sync) {
@@ -97,7 +96,12 @@ async function runFixtures(
     for (const [fixtureName, fixture] of fixtures) {
       work.push(
         worker
-          .transformFixture(fixture, compilerVersion, shouldLog, true)
+          .transformFixture(
+            fixture,
+            compilerVersion,
+            (filter?.debug ?? false) && isOnlyFixture,
+            true,
+          )
           .then(result => [fixtureName, result]),
       );
     }
@@ -109,7 +113,7 @@ async function runFixtures(
       let output = await runnerWorker.transformFixture(
         fixture,
         compilerVersion,
-        shouldLog,
+        (filter?.debug ?? false) && isOnlyFixture,
         true,
       );
       entries.push([fixtureName, output]);
@@ -124,7 +128,7 @@ async function onChange(
   worker: Worker & typeof runnerWorker,
   state: RunnerState,
 ) {
-  const {compilerVersion, isCompilerBuildValid, mode, filter, debug} = state;
+  const {compilerVersion, isCompilerBuildValid, mode, filter} = state;
   if (isCompilerBuildValid) {
     const start = performance.now();
 
@@ -138,8 +142,6 @@ async function onChange(
       worker,
       mode.filter ? filter : null,
       compilerVersion,
-      debug,
-      true, // requireSingleFixture in watch mode
     );
     const end = performance.now();
     if (mode.action === RunnerAction.Update) {
@@ -157,13 +159,11 @@ async function onChange(
   console.log(
     '\n' +
       (mode.filter
-        ? `Current mode = FILTER, pattern = "${filter?.paths[0] ?? ''}".`
+        ? `Current mode = FILTER, filter test fixtures by "${FILTER_PATH}".`
         : 'Current mode = NORMAL, run all test fixtures.') +
       '\nWaiting for input or file changes...\n' +
       'u     - update all fixtures\n' +
-      `d     - toggle (turn ${debug ? 'off' : 'on'}) debug logging\n` +
-      'p     - enter pattern to filter fixtures\n' +
-      (mode.filter ? 'a     - run all tests (exit filter mode)\n' : '') +
+      `f     - toggle (turn ${mode.filter ? 'off' : 'on'}) filter mode\n` +
       'q     - quit\n' +
       '[any] - rerun tests\n',
   );
@@ -180,16 +180,15 @@ export async function main(opts: RunnerOptions): Promise<void> {
   worker.getStderr().pipe(process.stderr);
   worker.getStdout().pipe(process.stdout);
 
-  // Check if watch mode should be enabled
-  const shouldWatch = opts.watch;
+  // If pattern is provided, force watch mode off and use pattern filter
+  const shouldWatch = opts.watch && opts.pattern == null;
+  if (opts.watch && opts.pattern != null) {
+    console.warn('NOTE: --watch is ignored when a --pattern is supplied');
+  }
 
   if (shouldWatch) {
-    makeWatchRunner(
-      state => onChange(worker, state),
-      opts.debug,
-      opts.pattern,
-    );
-    if (opts.pattern) {
+    makeWatchRunner(state => onChange(worker, state), opts.filter);
+    if (opts.filter) {
       /**
        * Warm up wormers when in watch mode. Loading the Forget babel plugin
        * and all of its transitive dependencies takes 1-3s (per worker) on a M1.
@@ -237,17 +236,14 @@ export async function main(opts: RunnerOptions): Promise<void> {
               let testFilter: TestFilter | null = null;
               if (opts.pattern) {
                 testFilter = {
+                  debug: true,
                   paths: [opts.pattern],
                 };
+              } else if (opts.filter) {
+                testFilter = await readTestFilter();
               }
 
-              const results = await runFixtures(
-                worker,
-                testFilter,
-                0,
-                opts.debug,
-                false, // no requireSingleFixture in non-watch mode
-              );
+              const results = await runFixtures(worker, testFilter, 0);
               if (opts.update) {
                 update(results);
                 isSuccess = true;