From 996773cfbf30ef3d60670be8183cbf1dc7d6f3dc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= <mdjastrzebski@gmail.com>
Date: Mon, 12 Oct 2026 12:25:49 +0200
Subject: [PATCH 1/2] chore: add references to react, react-native, rtl/dtl,
 expensify app as git submodules

---
 .gitmodules                          | 20 ++++++++++++++++++++
 .oxfmtrc.json                        |  2 +-
 AGENTS.md                            | 17 +++++++++++++++++
 contributing/build-and-validation.md |  1 +
 eslint.config.mjs                    |  9 ++++++++-
 jest.config.js                       |  3 ++-
 package.json                         |  4 ++--
 refs/dom-testing-library             |  1 +
 refs/expensify-app                   |  1 +
 refs/react                           |  1 +
 refs/react-native                    |  1 +
 refs/react-testing-library           |  1 +
 12 files changed, 56 insertions(+), 5 deletions(-)
 create mode 100644 .gitmodules
 create mode 160000 refs/dom-testing-library
 create mode 160000 refs/expensify-app
 create mode 160000 refs/react
 create mode 160000 refs/react-native
 create mode 160000 refs/react-testing-library

diff --git a/.gitmodules b/.gitmodules
new file mode 100644
index 000000000..fd1b113a4
--- /dev/null
+++ b/.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
diff --git a/.oxfmtrc.json b/.oxfmtrc.json
index dcdc60d7f..510e08bf8 100644
--- a/.oxfmtrc.json
+++ b/.oxfmtrc.json
@@ -11,5 +11,5 @@
     ]
   },
   "sortPackageJson": false,
-  "ignorePatterns": ["node_modules/", ".yarn", "codemods/**/tests/fixtures/**"]
+  "ignorePatterns": ["node_modules/", ".yarn", "refs/", "codemods/**/tests/fixtures/**"]
 }
diff --git a/AGENTS.md b/AGENTS.md
index 223aab95b..af37c4cfe 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -27,6 +27,23 @@
   - [Example app regeneration](contributing/example-apps.md)
   - [Git, releases, and PR workflow](contributing/git-workflow.md)
 
+## Reference sources
+
+Upstream sources are checked out as shallow git submodules under `refs/` for code research. Read and 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, test renderer, and RN renderer in `packages/`)
+- `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), a large production React Native app with about 1,000 test files that use this library (in `tests/ui/`, `tests/unit/`, `tests/perf-test/`). Use it to see how real-world tests call the API and to judge the impact of behavior or API changes. Check its `package.json` for the version it uses.
+
+Notes:
+
+- Treat `refs/` as read-only. Never edit files there or import from it in `src/`.
+- Submodules track upstream `main`, which can differ from the versions installed in `node_modules/`. For behavior that must match what this library runs against, check the installed package in `node_modules/` too.
+- 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
diff --git a/contributing/build-and-validation.md b/contributing/build-and-validation.md
index 15f8b720e..953ffa076 100644
--- a/contributing/build-and-validation.md
+++ b/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/`: upstream sources (React, React Native, Testing Library) and the Expensify app as a real-world test suite, as shallow git submodules, for reading only. Fetch them with `git submodule update --init --depth 1`.
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 160322fa5..893704448 100644
--- a/eslint.config.mjs
+++ b/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,
diff --git a/jest.config.js b/jest.config.js
index 4549c54f6..978adc0fc 100644
--- a/jest.config.js
+++ b/jest.config.js
@@ -1,7 +1,8 @@
 module.exports = {
   preset: '@react-native/jest-preset',
   setupFilesAfterEnv: ['./jest-setup.ts'],
-  testPathIgnorePatterns: ['dist/', 'examples/', 'experiments-app/', 'codemods/'],
+  testPathIgnorePatterns: ['dist/', 'examples/', 'experiments-app/', 'codemods/', 'refs/'],
+  modulePathIgnorePatterns: ['<rootDir>/refs/'],
   testTimeout: 60000,
   transformIgnorePatterns: ['/node_modules/(?!(@react-native|react-native)/).*/'],
   snapshotSerializers: ['@relmify/jest-serializer-strip-ansi/always'],
diff --git a/package.json b/package.json
index a0bd21dae..db2db8305 100644
--- a/package.json
+++ b/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",
diff --git a/refs/dom-testing-library b/refs/dom-testing-library
new file mode 160000
index 000000000..6049cc0bc
--- /dev/null
+++ b/refs/dom-testing-library
@@ -0,0 +1 @@
+Subproject commit 6049cc0bc7cf2201625c476c95fa6299d0e2fa8b
diff --git a/refs/expensify-app b/refs/expensify-app
new file mode 160000
index 000000000..8976530e6
--- /dev/null
+++ b/refs/expensify-app
@@ -0,0 +1 @@
+Subproject commit 8976530e6b70985b157f8245f5c9d0d6ae3d043d
diff --git a/refs/react b/refs/react
new file mode 160000
index 000000000..b618bbb44
--- /dev/null
+++ b/refs/react
@@ -0,0 +1 @@
+Subproject commit b618bbb4422693bbb8d387180687b3f510300f42
diff --git a/refs/react-native b/refs/react-native
new file mode 160000
index 000000000..db42fda57
--- /dev/null
+++ b/refs/react-native
@@ -0,0 +1 @@
+Subproject commit db42fda57495eecb35fa2fa8f09a0f6c42ec2434
diff --git a/refs/react-testing-library b/refs/react-testing-library
new file mode 160000
index 000000000..20ce75f29
--- /dev/null
+++ b/refs/react-testing-library
@@ -0,0 +1 @@
+Subproject commit 20ce75f2907ca0e5c5a8ae595c0e9a4e368c7800

From f5064375b1318c699f832e4b0194de3cdaea0ea4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Maciej=20Jastrze=CC=A8bski?= <mdjastrzebski@gmail.com>
Date: Mon, 12 Oct 2026 12:39:24 +0200
Subject: [PATCH 2/2] review tweaks

---
 .vscode/settings.json                |  5 ++++-
 AGENTS.md                            | 11 ++++++-----
 contributing/build-and-validation.md |  2 +-
 jest.config.js                       |  2 +-
 4 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/.vscode/settings.json b/.vscode/settings.json
index 7bf049879..0611e36e4 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -8,5 +8,8 @@
     "Uncapitalize",
     "valuenow",
     "valuetext"
-  ]
+  ],
+  "search.exclude": {
+    "refs/**": true
+  }
 }
diff --git a/AGENTS.md b/AGENTS.md
index af37c4cfe..b05393aa7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -29,18 +29,19 @@
 
 ## Reference sources
 
-Upstream sources are checked out as shallow git submodules under `refs/` for code research. Read and search them to see how upstream implements something (event dispatch, renderer internals, query semantics) instead of guessing or fetching from the web.
+`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, test renderer, and RN renderer in `packages/`)
+- `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), a large production React Native app with about 1,000 test files that use this library (in `tests/ui/`, `tests/unit/`, `tests/perf-test/`). Use it to see how real-world tests call the API and to judge the impact of behavior or API changes. Check its `package.json` for the version it uses.
+- `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:
 
-- Treat `refs/` as read-only. Never edit files there or import from it in `src/`.
-- Submodules track upstream `main`, which can differ from the versions installed in `node_modules/`. For behavior that must match what this library runs against, check the installed package in `node_modules/` too.
+- `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.
 
diff --git a/contributing/build-and-validation.md b/contributing/build-and-validation.md
index 953ffa076..83394325d 100644
--- a/contributing/build-and-validation.md
+++ b/contributing/build-and-validation.md
@@ -29,4 +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/`: upstream sources (React, React Native, Testing Library) and the Expensify app as a real-world test suite, as shallow git submodules, for reading only. Fetch them with `git submodule update --init --depth 1`.
+- `refs/`: read-only git submodules of upstream sources and the Expensify app. Fetch with `git submodule update --init --depth 1`.
diff --git a/jest.config.js b/jest.config.js
index 978adc0fc..b47157dd6 100644
--- a/jest.config.js
+++ b/jest.config.js
@@ -1,7 +1,7 @@
 module.exports = {
   preset: '@react-native/jest-preset',
   setupFilesAfterEnv: ['./jest-setup.ts'],
-  testPathIgnorePatterns: ['dist/', 'examples/', 'experiments-app/', 'codemods/', 'refs/'],
+  testPathIgnorePatterns: ['dist/', 'examples/', 'experiments-app/', 'codemods/'],
   modulePathIgnorePatterns: ['<rootDir>/refs/'],
   testTimeout: 60000,
   transformIgnorePatterns: ['/node_modules/(?!(@react-native|react-native)/).*/'],