@@ -39,14 +39,30 @@ The upstream documentation source of truth is `docs/src/api/*.md` in the playwri
 
 ### 2. Bump the driver pin, download it, and generate api.json
 
-You need a nearby `microsoft/playwright` checkout for the docs walk and for
-codegen. Point `PW_SRC_DIR` at it and check out the release branch for the new
-version there (the branch has the release's docs plus any cherry-picks):
+The docs walk and codegen read the upstream docs from a `microsoft/playwright`
+checkout at `$PW_SRC_DIR`. **Use a separate checkout that exists only for
+rolls, on the exact release branch you roll to**: `release-<new>`, the
+`major.minor` of the new `DRIVER_VERSION` (the branch has the release's docs
+plus any cherry-picks). Never point `PW_SRC_DIR` at a checkout that someone
+works in: on `main` or a feature branch the docs differ, and the generator
+silently emits that API instead of the release's.
 
 ```sh
-export PW_SRC_DIR=../playwright
-git -C "$PW_SRC_DIR" fetch origin 'release-*:release-*'
-git -C "$PW_SRC_DIR" checkout release-<new>      # e.g. release-1.62
+export PW_SRC_DIR=../playwright-for-python      # the roll checkout, nothing else
+# First roll on this machine: clone it (no npm install needed).
+git clone https://github.com/microsoft/playwright.git "$PW_SRC_DIR"
+# Every roll: move it to the release branch.
+git -C "$PW_SRC_DIR" fetch origin
+git -C "$PW_SRC_DIR" checkout release-<new>     # e.g. release-1.62
+git -C "$PW_SRC_DIR" merge --ff-only origin/release-<new>
+```
+
+Check the checkout before you generate, and again before you commit:
+
+```sh
+git -C "$PW_SRC_DIR" rev-parse --abbrev-ref HEAD                  # must print release-<new>
+git -C "$PW_SRC_DIR" status --porcelain                           # must print nothing
+git -C "$PW_SRC_DIR" rev-parse HEAD origin/release-<new>          # both lines must be equal
 ```
 
 Then bump the pins and assemble the driver:
@@ -73,7 +89,7 @@ the walk.
 
 ### 3. Identify the commit range
 
-Use the nearby `microsoft/playwright` checkout at `$PW_SRC_DIR` (from step 2).
+Use the roll checkout at `$PW_SRC_DIR` (from step 2).
 Bring it up to date and ensure release branches/tags are present before walking
 the range:
 
@@ -220,7 +236,7 @@ Tick the box in `/tmp/roll-<new>-commits.md` with one line: `[x] <sha> <subject>
 ### 5. Regenerate
 
 ```sh
-PW_SRC_DIR=../playwright ./scripts/update_api.sh   # PW_SRC_DIR already exported in step 2
+./scripts/update_api.sh   # uses PW_SRC_DIR from step 2; run the checkout checks there first
 ```
 
 The script, for `sync` and then `async`:
@@ -248,10 +264,10 @@ Failure modes and fixes:
 | mypy: `Unexpected keyword argument "z" for "y" of "XImpl"` | New parameter or option on an existing method. | Add the kwarg (docs camelCase name) in `_impl/`. If Python must not have it, `skipArgs`. |
 | mypy: incompatible argument type in `_generated.py` | The docs type changed, or `_impl/` declares a narrower type. | Match the type in `_impl/`, or record a `typeOverrides` entry for a justified divergence. |
 | generator: `No Python name for the struct at X.y.z` | A new inline `[Object]` with no `* alias:` in the docs. | Add the TypedDict and name it: `alias-python` upstream, or `structNamesByPlace` / `structRenames`. |
+| `_generated.py` gains or loses members that the commit walk never mentioned | `PW_SRC_DIR` is not on `release-<new>` (for example on `main` or a feature branch), or is behind `origin/release-<new>`. | Run the checkout checks from step 2, fix the checkout, regenerate. |
 | generator: `Unknown docs type "T" at X.y` | A docs type the type table in `generate_api.js` (`toPy`) does not know. | Add it to `toPy`. |
 | generator: `required parameter z follows an optional one` | The docs order params so that Python would need a default before a non-default. | Add a `positional` entry with the Python order. |
 | generator: `the entry "…" no longer matches anything; remove it` | An upstream change made a rules entry unnecessary (or renamed what it points at). | Delete it, or re-key it to the new docs name. |
-| generator: `legacy_order.json: … has no …; remove it` | A member or parameter in the temporary legacy order was removed or renamed upstream. | Delete that name from `scripts/codegen/legacy_order.json`. New members need no entry; they go last. |
 | `pyright … reportInconsistentOverload` (single-event class) | A class gained its first event, so there is one `Literal[…]` overload + impl, which pyright wants ≥2 of. | The generator already handles this — `emitEvents` adds a second `@typing.overload` with `event: str` when a class has exactly one event. |
 | `pre-commit` keeps reformatting `_generated.py` on each run | First run after regen always reformats once; rerun until idle. | `pre-commit run --all-files` to settle. |
 | A kwarg in `_impl/` that the docs don't mention (e.g. legacy name from a doc rename) | Nothing fails: the generator simply never passes it. | If the param is positional with no default, just rename it in `_impl/`. Check `packages/protocol/spec/*.yml` and the server dispatcher — if the wire field renamed too, also update the channel-send dict key. Only use `extraOptions` for genuinely hidden internal kwargs (`default_browser_type`). |
@@ -279,6 +295,8 @@ For each PORT, add one async test and a matching sync test. Conventions:
 
 ### 8. Final verification
 
+Repeat the checkout checks from step 2: the committed `_generated.py` must come from `release-<new>`.
+
 ```sh
 pre-commit run --all-files
 mypy playwright                 # 2 pre-existing errors in _json_pipe.py and _artifact.py are unrelated
 
@@ -12,13 +12,12 @@ Python bindings for [Playwright](https://playwright.dev). The Python client talk
 - `playwright/async_api/_generated.py`, `playwright/sync_api/_generated.py` — **auto-generated** from the upstream API docs. Never edit by hand; rerun `./scripts/update_api.sh` after a roll or after changing `scripts/codegen/`.
 - `scripts/codegen/generate_api.js` — the generator. A Node.js script that loads the upstream doc parser (`utils/doclint/api_parser.js`) from `$PW_SRC_DIR`, filters the docs for Python, and writes the whole public API: signatures, types, docstrings, event overloads, and the calls into `_impl/`. It does not read `_impl/`.
 - `scripts/codegen/python_rules.js` — the Python facts that the docs do not contain (positional parameters, struct names, type overrides, hidden members). Policy: the shipped Python API wins; each entry is a candidate for an upstream docs fix, and the generator fails on entries that no longer match anything. Every entry needs a one-line rationale comment above it.
-- `scripts/codegen/legacy_order.json` — **temporary**. The old generator's order of classes, members, keyword-only parameters and union members. The generator applies it, and more old habits marked `TEMPORARY` in the generator, so that the switch to the docs generator has a small diff. New members go last. If the generator reports an entry that no longer matches, remove the entry. A follow-up change deletes the file and the `TEMPORARY` code.
 - `scripts/codegen/compare_api.py` — compares two generated files (signatures, annotations, call bodies, docstrings) and lists every difference. Use it to check that a generator change does not change the API.
 - `tests/async/`, `tests/sync/` — pytest suites. Most new tests are added to the async file with a sync mirror.
 - `DRIVER_VERSION` — the single source of truth for which Playwright release the driver is assembled from (one line, the `playwright-core` npm version, e.g. `1.61.0`, no `v` prefix). Read by `setup.py`, `scripts/build_driver.py`, and CI. The wheel build downloads `playwright-core` at this version from npm plus the matching Node.js binary and assembles the per-platform bundles — no source build. The version is baked into the staged bundle filenames (`driver/playwright-<version>-<suffix>.zip`), so it doubles as the build cache key.
 - `NODE_VERSION` — the Node.js version bundled with the driver (one line, e.g. `24.16.0`). Maintained at roll time by `scripts/update_node_version.py` (latest LTS, mirroring upstream's `utils/build/update-playwright-node.mjs`).
 - `scripts/build_driver.py` — assembles the per-platform driver bundles into `driver/` by downloading the `playwright-core` npm package (`DRIVER_VERSION`) and the official Node.js binaries (`NODE_VERSION`). Fetches `playwright-core` with `npm pack` (needs Node.js/npm on PATH; honours a root `.npmrc`) and the Node.js binaries over plain HTTP; invoked from `setup.py`'s `bdist_wheel` with the target platform's suffix (no arg builds all six).
-- The API docs are **not** shipped in the bundle. `scripts/update_api.sh` reads them from a nearby `microsoft/playwright` checkout (`$PW_SRC_DIR`, at the release branch for `DRIVER_VERSION`). Needed only when regenerating the API, never at runtime.
+- The API docs are **not** shipped in the bundle. `scripts/update_api.sh` reads them from a separate `microsoft/playwright` checkout (`$PW_SRC_DIR`) on the exact release branch for `DRIVER_VERSION`, never from a checkout on `main` or a feature branch. Needed only when regenerating the API, never at runtime.
 - `ROLLING.md`, `CONTRIBUTING.md` — human-facing setup and roll docs.
 
 ## Setup
 
@@ -76,13 +76,14 @@ For more details look at the [CI configuration](./.github/workflows/ci.yml).
 ### Regenerating APIs
 
 `update_api.sh` generates `playwright/{async,sync}_api/_generated.py` from the
-API docs in a nearby `microsoft/playwright` checkout (at the release branch
-matching `DRIVER_VERSION`); point `PW_SRC_DIR` at it. The generator is
+API docs in a separate `microsoft/playwright` checkout on the exact release
+branch for `DRIVER_VERSION` (for example `release-1.64`); point `PW_SRC_DIR`
+at it. The generator is
 `scripts/codegen/generate_api.js`; Python facts that the docs do not contain
 live in `scripts/codegen/python_rules.js`.
 
 ```bash
-PW_SRC_DIR=../playwright ./scripts/update_api.sh
+PW_SRC_DIR=../playwright-for-python ./scripts/update_api.sh
 pre-commit run --all-files
 ```
 
 
@@ -13,7 +13,7 @@ pip install -e .
 ```
 * change the driver pin in `DRIVER_VERSION` (the `playwright-core` npm version, e.g. `1.61.0`) and refresh `NODE_VERSION`: `python scripts/update_node_version.py`
 * download the new driver: `python -m build --wheel` (fetches `playwright-core` via `npm pack` + the matching Node.js binary and assembles the bundle; no source build).
-* generate API from the docs (needs a nearby `microsoft/playwright` checkout at the release branch for the new version, e.g. `release-1.64`): `PW_SRC_DIR=../playwright ./scripts/update_api.sh`
+* generate API from the docs. This needs a separate `microsoft/playwright` checkout used only for rolls, on the exact release branch for the new version (e.g. `release-1.64`), clean and up to date with `origin`: `PW_SRC_DIR=../playwright-for-python ./scripts/update_api.sh`
 * run `mypy playwright`: every error in `_generated.py` points at an implementation method in `playwright/_impl/` that lacks a new member or option. Implement it there, or record the difference in `scripts/codegen/python_rules.js`.
 * commit changes & send PR
 * wait for bots to pass & merge the PR