[pull] main from facebook:main

.claude/instructions.md

@@ -0,0 +1,46 @@
+# React
+
+**Scope**: All code EXCEPT `/compiler/` (compiler has its own instructions).
+
+## Project Structure
+
+| Directory | Purpose |
+|-----------|---------|
+| `/packages/` | Publishable packages (react, react-dom, scheduler, etc.) |
+| `/scripts/` | Build, test, and development scripts |
+| `/fixtures/` | Test applications for manual testing |
+| `/compiler/` | React Compiler (separate sub-project) |
+
+## Key Packages
+
+| Package | Purpose |
+|---------|---------|
+| `react` | Core React library |
+| `react-dom` | DOM renderer |
+| `react-reconciler` | Core reconciliation algorithm |
+| `scheduler` | Cooperative scheduling |
+| `react-server-dom-*` | Server Components |
+| `react-devtools-*` | Developer Tools |
+| `react-refresh` | Fast Refresh runtime |
+
+## Requirements
+
+- **Node**: Must be installed. Stop and prompt user if missing.
+- **Package Manager**: Use `yarn` only.
+
+## Verification
+
+**IMPORTANT**: Use `/verify` to validate all changes before committing.
+
+## Commands
+
+| Command  | Purpose              |
+|----------|----------------------|
+| `/fix`   | Lint and format code |
+| `/test`  | Run tests            |
+| `/flow`  | Type check with Flow |
+| `/flags` | Check feature flags  |
+
+## Building
+
+Builds are handled by CI. Do not run locally unless instructed.

.claude/settings.json

@@ -0,0 +1,44 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [[ \"$PWD\" != */compiler* ]]; then cat .claude/instructions.md 2>/dev/null || true; fi"
+          }
+        ]
+      }
+    ]
+  },
+  "permissions": {
+    "allow": [
+      "Skill(extract-errors)",
+      "Skill(feature-flags)",
+      "Skill(fix)",
+      "Skill(flags)",
+      "Skill(flow)",
+      "Skill(test)",
+      "Skill(verify)",
+      "Bash(yarn test:*)",
+      "Bash(yarn test-www:*)",
+      "Bash(yarn test-classic:*)",
+      "Bash(yarn test-stable:*)",
+      "Bash(yarn linc:*)",
+      "Bash(yarn lint:*)",
+      "Bash(yarn flow:*)",
+      "Bash(yarn prettier:*)",
+      "Bash(yarn build:*)",
+      "Bash(yarn extract-errors:*)",
+      "Bash(yarn flags:*)"
+    ],
+    "deny": [
+      "Bash(yarn download-build:*)",
+      "Bash(yarn download-build-for-head:*)",
+      "Bash(npm:*)",
+      "Bash(pnpm:*)",
+      "Bash(bun:*)",
+      "Bash(npx:*)"
+    ]
+  }
+}

.claude/skills/extract-errors/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: extract-errors
+description: Use when adding new error messages to React, or seeing "unknown error code" warnings.
+---
+
+# Extract Error Codes
+
+## Instructions
+
+1. Run `yarn extract-errors`
+2. Report if any new errors need codes assigned
+3. Check if error codes are up to date

.claude/skills/feature-flags/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: feature-flags
+description: Use when feature flag tests fail, flags need updating, understanding @gate pragmas, debugging channel-specific test failures, or adding new flags to React.
+---
+
+# React Feature Flags
+
+## Flag Files
+
+| File | Purpose |
+|------|---------|
+| `packages/shared/ReactFeatureFlags.js` | Default flags (canary), `__EXPERIMENTAL__` overrides |
+| `packages/shared/forks/ReactFeatureFlags.www.js` | www channel, `__VARIANT__` overrides |
+| `packages/shared/forks/ReactFeatureFlags.native-fb.js` | React Native, `__VARIANT__` overrides |
+| `packages/shared/forks/ReactFeatureFlags.test-renderer.js` | Test renderer |
+
+## Gating Tests
+
+### `@gate` pragma (test-level)
+
+Use when the feature is completely unavailable without the flag:
+
+```javascript
+// @gate enableViewTransition
+it('supports view transitions', () => {
+  // This test only runs when enableViewTransition is true
+  // and is SKIPPED (not failed) when false
+});
+```
+
+### `gate()` inline (assertion-level)
+
+Use when the feature exists but behavior differs based on flag:
+
+```javascript
+it('renders component', async () => {
+  await act(() => root.render(<App />));
+
+  if (gate(flags => flags.enableNewBehavior)) {
+    expect(container.textContent).toBe('new output');
+  } else {
+    expect(container.textContent).toBe('legacy output');
+  }
+});
+```
+
+## Adding a New Flag
+
+1. Add to `ReactFeatureFlags.js` with default value
+2. Add to each fork file (`*.www.js`, `*.native-fb.js`, etc.)
+3. If it should vary in www/RN, set to `__VARIANT__` in the fork file
+4. Gate tests with `@gate flagName` or inline `gate()`
+
+## Checking Flag States
+
+Use `/flags` to view states across channels. See the `flags` skill for full command options.
+
+## `__VARIANT__` Flags (GKs)
+
+Flags set to `__VARIANT__` simulate gatekeepers - tested twice (true and false):
+
+```bash
+/test www <pattern>              # __VARIANT__ = true
+/test www variant false <pattern> # __VARIANT__ = false
+```
+
+## Debugging Channel-Specific Failures
+
+1. Run `/flags --diff <channel1> <channel2>` to compare values
+2. Check `@gate` conditions - test may be gated to specific channels
+3. Run `/test <channel> <pattern>` to isolate the failure
+4. Verify flag exists in all fork files if newly added
+
+## Common Mistakes
+
+- **Forgetting both variants** - Always test `www` AND `www variant false` for `__VARIANT__` flags
+- **Using @gate for behavior differences** - Use inline `gate()` if both paths should run
+- **Missing fork files** - New flags must be added to ALL fork files, not just the main one
+- **Wrong gate syntax** - It's `gate(flags => flags.name)`, not `gate('name')`

.claude/skills/fix/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: fix
+description: Use when you have lint errors, formatting issues, or before committing code to ensure it passes CI.
+---
+
+# Fix Lint and Formatting
+
+## Instructions
+
+1. Run `yarn prettier` to fix formatting
+2. Run `yarn linc` to check for remaining lint issues
+3. Report any remaining manual fixes needed
+
+## Common Mistakes
+
+- **Running prettier on wrong files** - `yarn prettier` only formats changed files
+- **Ignoring linc errors** - These will fail CI, fix them before committing

.claude/skills/flags/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: flags
+description: Use when you need to check feature flag states, compare channels, or debug why a feature behaves differently across release channels.
+---
+
+# Feature Flags
+
+Arguments:
+- $ARGUMENTS: Optional flags
+
+## Options
+
+| Option | Purpose |
+|--------|---------|
+| (none) | Show all flags across all channels |
+| `--diff <ch1> <ch2>` | Compare flags between channels |
+| `--cleanup` | Show flags grouped by cleanup status |
+| `--csv` | Output in CSV format |
+
+## Channels
+
+- `www`, `www-modern` - Meta internal
+- `canary`, `next`, `experimental` - OSS channels
+- `rn`, `rn-fb`, `rn-next` - React Native
+
+## Legend
+
+✅ enabled, ❌ disabled, 🧪 `__VARIANT__`, 📊 profiling-only
+
+## Instructions
+
+1. Run `yarn flags $ARGUMENTS`
+2. Explain the output to the user
+3. For --diff, highlight meaningful differences
+
+## Common Mistakes
+
+- **Forgetting `__VARIANT__` flags** - These are tested both ways in www; check both variants
+- **Comparing wrong channels** - Use `--diff` to see exact differences

.claude/skills/flow/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: flow
+description: Use when you need to run Flow type checking, or when seeing Flow type errors in React code.
+---
+
+# Flow Type Checking
+
+Arguments:
+- $ARGUMENTS: Renderer to check (default: dom-node)
+
+## Renderers
+
+| Renderer | When to Use |
+|----------|-------------|
+| `dom-node` | Default, recommended for most changes |
+| `dom-browser` | Browser-specific DOM code |
+| `native` | React Native |
+| `fabric` | React Native Fabric |
+
+## Instructions
+
+1. Run `yarn flow $ARGUMENTS` (use `dom-node` if no argument)
+2. Report type errors with file locations
+3. For comprehensive checking (slow), use `yarn flow-ci`
+
+## Common Mistakes
+
+- **Running without a renderer** - Always specify or use default `dom-node`
+- **Ignoring suppressions** - Check if `$FlowFixMe` comments are masking real issues
+- **Missing type imports** - Ensure types are imported from the correct package

.claude/skills/test/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: test
+description: Use when you need to run tests for React core. Supports source, www, stable, and experimental channels.
+---
+
+Run tests for the React codebase.
+
+Arguments:
+- $ARGUMENTS: Channel, flags, and test pattern
+
+Usage Examples:
+- `/test ReactFiberHooks` - Run with source channel (default)
+- `/test experimental ReactFiberHooks` - Run with experimental channel
+- `/test www ReactFiberHooks` - Run with www-modern channel
+- `/test www variant false ReactFiberHooks` - Test __VARIANT__=false
+- `/test stable ReactFiberHooks` - Run with stable channel
+- `/test classic ReactFiberHooks` - Run with www-classic channel
+- `/test watch ReactFiberHooks` - Run in watch mode (TDD)
+
+Release Channels:
+- `(default)` - Source/canary channel, uses ReactFeatureFlags.js defaults
+- `experimental` - Source/experimental channel with __EXPERIMENTAL__ flags = true
+- `www` - www-modern channel with __VARIANT__ flags = true
+- `www variant false` - www channel with __VARIANT__ flags = false
+- `stable` - What ships to npm
+- `classic` - Legacy www-classic (rarely needed)
+
+Instructions:
+1. Parse channel from arguments (default: source)
+2. Map to yarn command:
+   - (default) → `yarn test --silent --no-watchman <pattern>`
+   - experimental → `yarn test -r=experimental --silent --no-watchman <pattern>`
+   - stable → `yarn test-stable --silent --no-watchman <pattern>`
+   - classic → `yarn test-classic --silent --no-watchman <pattern>`
+   - www → `yarn test-www --silent --no-watchman <pattern>`
+   - www variant false → `yarn test-www --variant=false --silent --no-watchman <pattern>`
+3. Report test results and any failures
+
+Hard Rules:
+1. **Use --silent to see failures** - This limits the test output to only failures.
+2. **Use --no-watchman** - This is a common failure in sandboxing.
+
+Common Mistakes:
+- **Running without a pattern** - Runs ALL tests, very slow. Always specify a pattern.
+- **Forgetting both www variants** - Test `www` AND `www variant false` for `__VARIANT__` flags.
+- **Test skipped unexpectedly** - Check for `@gate` pragma; see `feature-flags` skill.

.claude/skills/verify/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: verify
+description: Use when you want to validate changes before committing, or when you need to check all React contribution requirements.
+---
+
+# Verification
+
+Run all verification steps.
+
+Arguments:
+- $ARGUMENTS: Test pattern for the test step
+
+## Instructions
+
+Run these first in sequence:
+1. Run `yarn prettier` - format code (stop if fails)
+2. Run `yarn linc` - lint changed files (stop if fails)
+
+Then run these with subagents in parallel:
+1. Use `/flow` to type check (stop if fails)
+2. Use `/test` to test changes in source (stop if fails)
+3. Use `/test www` to test changes in www (stop if fails)
+
+If all pass, show success summary. On failure, stop immediately and report the issue with suggested fixes.

.gitignore

@@ -24,7 +24,7 @@ chrome-user-data
 *.swp
 *.swo
 /tmp
-/worktrees
+/.worktrees
 .claude/*.local.*
 
 packages/react-devtools-core/dist

CLAUDE.md

@@ -0,0 +1,8 @@
+# React
+
+React is a JavaScript library for building user interfaces.
+
+## Monorepo Overview
+
+- **React**: All files outside `/compiler/`
+- **React Compiler**: `/compiler/` directory (has its own instructions)

compiler/.claude/settings.json

@@ -5,7 +5,14 @@
       "Bash(yarn snap:build)",
       "Bash(node scripts/enable-feature-flag.js:*)"
     ],
-    "deny": [],
-    "ask": []
+    "deny": [
+      "Skill(extract-errors)",
+      "Skill(feature-flags)",
+      "Skill(fix)",
+      "Skill(flags)",
+      "Skill(flow)",
+      "Skill(test)",
+      "Skill(verify)"
+    ]
   }
 }

compiler/CLAUDE.md

@@ -4,6 +4,8 @@ This document contains knowledge about the React Compiler gathered during develo
 
 ## Project Structure
 
+When modifying the compiler, you MUST read the documentation about that pass in `compiler/packages/babel-plugin-react-compiler/docs/passes/` to learn more about the role of that pass within the compiler.
+
 - `packages/babel-plugin-react-compiler/` - Main compiler package
   - `src/HIR/` - High-level Intermediate Representation types and utilities
   - `src/Inference/` - Effect inference passes (aliasing, mutation, etc.)