chore: reference sources to react, react-native, testing-libraries, etc

.gitmodules

@@ -0,0 +1,20 @@
+[submodule "refs/dom-testing-library"]
+	path = refs/dom-testing-library
+	url = https://github.com/testing-library/dom-testing-library.git
+	shallow = true
+[submodule "refs/react-testing-library"]
+	path = refs/react-testing-library
+	url = https://github.com/testing-library/react-testing-library.git
+	shallow = true
+[submodule "refs/react-native"]
+	path = refs/react-native
+	url = https://github.com/facebook/react-native.git
+	shallow = true
+[submodule "refs/react"]
+	path = refs/react
+	url = https://github.com/facebook/react.git
+	shallow = true
+[submodule "refs/expensify-app"]
+	path = refs/expensify-app
+	url = https://github.com/Expensify/App.git
+	shallow = true

.oxfmtrc.json

@@ -11,5 +11,5 @@
     ]
   },
   "sortPackageJson": false,
-  "ignorePatterns": ["node_modules/", ".yarn", "codemods/**/tests/fixtures/**"]
+  "ignorePatterns": ["node_modules/", ".yarn", "refs/", "codemods/**/tests/fixtures/**"]
 }

.vscode/settings.json

@@ -8,5 +8,8 @@
     "Uncapitalize",
     "valuenow",
     "valuetext"
-  ]
+  ],
+  "search.exclude": {
+    "refs/**": true
+  }
 }

AGENTS.md

@@ -27,6 +27,24 @@
   - [Example app regeneration](contributing/example-apps.md)
   - [Git, releases, and PR workflow](contributing/git-workflow.md)
 
+## Reference sources
+
+`refs/` holds upstream sources as shallow git submodules. Search them to see how upstream implements something (event dispatch, renderer internals, query semantics) instead of guessing or fetching from the web.
+
+- `refs/react-native/`: [facebook/react-native](https://github.com/facebook/react-native) (core components in `packages/react-native/Libraries/`)
+- `refs/react/`: [facebook/react](https://github.com/facebook/react) (reconciler and RN renderer in `packages/`). RNTL renders through [`test-renderer`](https://github.com/mdjastrzebski/test-renderer), not the deprecated `react-test-renderer` found here.
+- `refs/dom-testing-library/`: [testing-library/dom-testing-library](https://github.com/testing-library/dom-testing-library) (queries, `fireEvent`, `waitFor`)
+- `refs/react-testing-library/`: [testing-library/react-testing-library](https://github.com/testing-library/react-testing-library) (`render`, `act` integration)
+- `refs/expensify-app/`: [Expensify/App](https://github.com/Expensify/App), about 1,000 test files using this library (`tests/ui/`, `tests/unit/`, `tests/perf-test/`). Use it to see real-world API usage and judge the impact of changes. It is on RNTL v13 (see its `package.json`), so syntax differs from v14: `render` and `fireEvent` are sync there.
+
+Notes:
+
+- `refs/` is read-only. Never edit it or import from it in `src/`.
+- Submodules are pinned to fixed commits and can differ from `node_modules/`. For behavior this library runs against, check `node_modules/`.
+- Refresh with `git submodule update --remote --depth 1`. Moved refs show as modified pointers in `git status`. Bump them in their own PR, never in unrelated work.
+- If `refs/` is empty, ask the human to run `git submodule update --init --depth 1`.
+- Tooling ignores `refs/` (Jest, ESLint, oxfmt, `tsc`). Keep it that way when changing configs.
+
 ## Agent rules
 
 ### Git restrictions

contributing/build-and-validation.md

@@ -29,3 +29,4 @@ After changing docs, run `yarn docs:generate` and commit the result together wit
 - `examples/`: example Expo apps
 - `codemods/`: codemods for upgrading user code
 - `contributing/`: these guides
+- `refs/`: read-only git submodules of upstream sources and the Expensify app. Fetch with `git submodule update --init --depth 1`.

eslint.config.mjs

@@ -21,7 +21,14 @@ const patchedCallstackConfig = callstackConfig.map((configItem) => {
 
 export default [
   {
-    ignores: ['dist/', 'experiments-rtl/', 'website/', 'eslint.config.mjs', 'jest-setup.ts'],
+    ignores: [
+      'dist/',
+      'refs/',
+      'experiments-rtl/',
+      'website/',
+      'eslint.config.mjs',
+      'jest-setup.ts',
+    ],
   },
   ...patchedCallstackConfig,
   ...tseslint.configs.strict,

jest.config.js

@@ -2,6 +2,7 @@ module.exports = {
   preset: '@react-native/jest-preset',
   setupFilesAfterEnv: ['./jest-setup.ts'],
   testPathIgnorePatterns: ['dist/', 'examples/', 'experiments-app/', 'codemods/'],
+  modulePathIgnorePatterns: ['<rootDir>/refs/'],
   testTimeout: 60000,
   transformIgnorePatterns: ['/node_modules/(?!(@react-native|react-native)/).*/'],
   snapshotSerializers: ['@relmify/jest-serializer-strip-ansi/always'],

package.json

@@ -33,8 +33,8 @@
     "typecheck": "tsc",
     "typecheck:react-19_2": "tsc -p tsconfig.react-19_2.json",
     "lint": "eslint src --cache",
-    "format:check": "oxfmt --check .",
-    "format:fix": "oxfmt --write .",
+    "format:check": "oxfmt --check --disable-nested-config .",
+    "format:fix": "oxfmt --write --disable-nested-config .",
     "validate": "yarn typecheck && yarn test && yarn lint && yarn format:check",
     "validate:examples": "yarn --cwd examples/basic validate && yarn --cwd examples/cookbook validate",
     "validate:all": "yarn validate && yarn validate:examples && yarn docs:check && yarn --cwd website validate && yarn --cwd experiments-app validate",