Run browser tests locally: Playwright 1.64.1 in .venv, scripts switch to it on their own

The browser tests and screenshot tools now work with plain python3 on a machine whose
system Python refuses pip installs: tools/use_venv.py re-runs them with the repo's .venv.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/PROJECT_MAP.md

@@ -21,7 +21,8 @@ src/ui/               the browser shell: input, HUD, build menu, notebook, setti
 test/                 headless suites (t_*.js) and their harness; browser tests (play.py,
                       t_smooth.py); run_all.py
 tools/                shot.py (screenshots), where.py, map.py, perf.py, playthrough.py,
-                      scenes/ (screenshot setups), experiments/ (measurements and reports)
+                      use_venv.py (switches browser scripts to .venv), scenes/ (screenshot
+                      setups), experiments/ (measurements and reports)
 docs/                 this map, DESIGN.md, TESTING.md, systems/ (notes per system),
                       history/ (the owner's requests), agent-log.md
 dist/, shots/         build output and screenshots (not committed)
@@ -456,6 +457,7 @@ The frame loop and boot.
 - `tools/perf.py`: Times the renderer and the simulation in a headless browser: light, drawWorld (with and without light and glow), the pixel upload and blit, and one simulation tick, in ms. Rebuild first.
 - `tools/playthrough.py`: Headless browser run: load the page, start a world, play a little, take screenshots.
 - `tools/shot.py`: Screenshot the game in a headless browser, after setting up a scene with JavaScript.
+- `tools/use_venv.py`: Let browser scripts run with plain python3 by switching to the repo's .venv.
 - `tools/where.py`: Turn a line number in dist/index.html into the source file and line it came from.
 - `tools/experiments/cast_sunk_mold.js`: Block-sized bit mold sunk into the ground with a stone furnace built over its funnel.
 - `tools/experiments/factory_cost.js`: What does a running factory cost when the player is somewhere else? Builds K self-running modules in a generated world, far from the bot, and measures simulation time per tick. Each module: a coal + copper-ore furnace burning in a stone-block box, a spring feeding a water wheel, a shaft carrying its power to a 10-block belt that hauls sand off a hopper.

docs/TESTING.md

@@ -60,6 +60,7 @@ diff -r /tmp/before /tmp/after
 
 ## Browser tests
 
+- They need the `.venv` from README.md → Develop; plain `python3` switches to it on its own.
 - `test/play.py` (about 2.5 minutes) builds a world through the title screen and plays it with real
   input. It checks the tools, building, copy/cut/paste, undo, the build menu, filters, pipes,
   the notebook and market, saving and continuing, exporting and importing a world file, the

docs/agent-log.md

@@ -4,6 +4,25 @@ What agents have done, newest first. Add an entry for every piece of work: the d
 note or request it was for, what changed, the files touched, the tests run, and anything left
 open or not verified. Keep each entry short; the git history has the details.
 
+## 2026-10-23: browser tests run locally (Claude Code, with Codex)
+
+Request: get the browser tests, Playwright and Chromium working on the owner's Arch machine
+(Python 3.14 refuses a system-wide pip install).
+
+- Playwright 1.64.1 and its Chromium 156 (revision 1248) are in an in-repo `.venv/` made with uv.
+
+- Added `tools/use_venv.py` and called it before Playwright imports in `tools/shot.py`,
+  `tools/perf.py`, `tools/playthrough.py`, `test/play.py` and `test/t_smooth.py`.
+  The `sys.prefix` guard prevents an exec loop if the venv lacks Playwright.
+- Updated `requirements.txt`, `.gitignore`, `README.md`, `AGENTS.md`, `docs/TESTING.md`
+  and `docs/PROJECT_MAP.md` for Playwright 1.64.1 and venv setup.
+- Checks: regenerated the project map and ran `tools/map.py --check`.
+- Tests run with plain `python3`: `test/run_all.py --browser` all passed (11 headless suites,
+  `play.py` 101 checks, `t_smooth.py` 8 checks) on the newer Chromium; `tools/shot.py` shots
+  of the stone-uses scene look right in both looks. With `.venv` moved away, `play.py` exits
+  with the setup message instead of a traceback.
+- Open: nothing.
+
 ## 2026-10-23: export from claude.ai to a local repository (Claude, in claude.ai)
 
 Request: split the source into small files, deduplicate and tidy a little, test fully, and