@@ -2161,3 +2161,46 @@ Verified: Original and HD started through `open` + launcher, 1200–1500 frames,
 clean exit, 0 traps; portable copy signed (`codesign --verify --strict`), no
 quarantine, runs from its embedded data; user prefs and registry unchanged.
 `tools/session.sh` opens NFSU2.app with `NFSU2_SKIP_LAUNCHER=1 NFSU2_ENGINE=…`.
+
+## 2026-10-26: HD black screen at start, Spotlight, menu car
+
+### HD: ~8 s black screen on the first start of a build (fixed)
+
+The game creates all its pixel shaders while it boots; each was translated and
+compiled from MSL source on the spot, one after another. With a cold Metal cache
+(the first start of every new build, or after macOS clears the cache) that held
+the first frames back: measured, the first 150 frames took 10.0 s in the HD build
+(more variants per shader) against 2.4 s with a warm cache. Now `metal_register_ps`
+starts each compile in the background (up to 8 at once: the Metal compiler runs
+them in parallel), and a draw waits only for the shader it needs; a draw that
+needs a shader still waiting in the queue compiles it itself right away
+(`ps_wait` / `ps_run`). Cold HD start: 150 frames in 3.1 s. Menu frames differ
+from the old path no more than two runs of the old path differ from each other.
+`PSASYNC=0`: old behaviour. Note for measurements: total process time is
+misleading on a cold cache, Metal writes its cache at exit; time the frames.
+
+### Spotlight opens 3-7 s late while the game runs (open)
+
+Measured (user at the keyboard, ~15 runs): Spotlight's UI process ("Siri AI" on
+macOS 27) is backgrounded (darwinbg, priority 4) while hidden and gets the
+Cmd+Space ~5 s late; once it has it, it opens fast. Not the cause: the system
+shortcut block (`NFSKISAYOL=0` was worse), Game Mode (`GCSupportsGameMode=false`
+kept it off, still slow), GPU load (menu ~9 %), `framebufferOnly`
+(`FBONLY=1`: readable middle texture + one copy pass, validated with the Metal
+debug layer), disk I/O (a few KB/s), CPU cluster load (E-cluster ~62 %). A
+control app presenting 120 Hz full screen with the same layer settings does NOT
+slow Spotlight, so it is something in the engine; `FPSCAP=10` makes it fast,
+`FPSCAP=60` does not. Next: grow the control app towards the engine (threads,
+wakeups ~1160/s, GPU work) until Spotlight slows. Test switches: `FPSCAP=<n>`,
+`BGFPS=<n>` (cap only while another app is in front), `FBONLY=1`. The layer is
+now explicitly opaque.
+
+### Menu car headlights
+
+The main menu's 350Z (no profile) shows a large pale lilac highlight over the
+hood front and headlights from the first frame on, and it stays after visiting
+car select. Isolated with `SKIPPS`/`SKIPDRAW`: car = ps 265 (draws 167-285 in
+frame 1650); the headlight lenses are draws 213-222 (light atlas texture 813,
+64x64, complete with 4 mips; 807 = tail lights); the highlight itself is the
+scene's reflection on the body panels, not a missing texture and not post
+processing. Not decided whether anything is wrong without a reference image.
@@ -40,7 +40,8 @@ The game boots, reaches the menus, and races are playable with sound.
 
 ### Known limitations
 
-- **Exactly one build of `SPEED2.EXE` is supported** (see [Requirements](#requirements)).
+- **Exactly one build of `SPEED2.EXE` is supported**, the European v1.2 one
+  (see [Game versions](#game-versions)).
   Game addresses are hard-coded in the runtime, and the pipeline relies on a
   property of that particular file (below).
 - Videos are skipped: there is no VP6 decoder.
@@ -158,12 +159,61 @@ HD build draws about 18 W.
   | | |
   |---|---|
   | File | `SPEED2.EXE`, 4,788,224 bytes |
-  | Build | European v1.2 executable without the CD check |
+  | Build | **European** (PAL) v1.2 executable without the CD check, built Feb 9 2005 |
   | SHA-256 | `8f6a9ae2c4cfa01181d2fd755d99c6f4b7103f60273908ea1de1e719dfe2a297` |
 
-  Other builds (for example the US retail executable) have not been tested and
-  will not work without changes. The app checks the file at startup and says so
-  instead of crashing; `NFSU2_ANY_EXE=1` skips the check.
+  The app checks the file at startup and says so instead of crashing;
+  `NFSU2_ANY_EXE=1` skips the check.
+
+### Game versions
+
+The recompiled code and the addresses in the runtime belong to one executable,
+so every other build of `SPEED2.EXE` needs its own lifting pass and address
+table. The game *data* is a separate matter (see the note under the table).
+
+| `SPEED2.EXE` | Size | SHA-256 | Status |
+|---|---|---|---|
+| European v1.2, no CD check | 4,788,224 | `8f6a9ae2c4cfa01181d2fd755d99c6f4b7103f60273908ea1de1e719dfe2a297` | **Supported** |
+| North American v1.2, no CD check (the build most PC mods target) | 4,800,512 | `f9dd86c054878ce6276beb07c1fd61874f7a1e4bf1f241b084c65b73e24168a7` | Not supported yet. Same Feb 9 2005 build; the data addresses match ours, the code is shifted by small amounts. Planned. |
+| US v1.0 retail disc | 5,987,981 | `2cbd698fee8338a13d1891bc17d27e6641b4b9dd40580de818594b9140222899` | **Cannot be supported.** Protected by SafeDisc: the code section is encrypted on disc and only decrypted at run time, so there is nothing to recompile. |
+
+The retail disc executable carries the disc's copy protection, and the official
+v1.2 patch most likely keeps it (not verified here). A static recompiler needs
+readable machine code, so the port cannot use a protected executable, and this
+project does not remove copy protection.
+
+**Data from the discs.** The US discs and the European release share 1,218 of
+their ~1,250 files byte for byte. The differences are the region's cars (the US
+release has `CARS/CIVIC` and `CARS/RSX`; the European one has `CARS/CORSA` and
+`CARS/PEUGOT106`), the per-language movies, `FRONTEND/FrontB.lzc` and
+`server.dll`.
+
+**US data works with the supported executable.** The game's region is a
+constant in the executable (`0` in the US build, `6` in the European one), and
+it decides which of the region-only cars exist. Left at the European value, US
+data hangs on the "Loading" screen as soon as a race picks a Corsa or a 106. The
+runtime therefore looks at the data at startup: if `CARS/CIVIC` and `CARS/RSX`
+are there but `CARS/CORSA` and `CARS/PEUGOT106` are not, it switches the game to
+the US region (log line `region: North American data`). Tested on US disc data:
+races load, the Civic is in the Quick Race car list and the Mazda is called
+Miata, as in the US release; the region check hides the Corsa and 106.
+`NFSU2_REGION=na` or `eu` forces either region.
+
+### Installing from the PC discs on a Mac
+
+The discs hold the game in plain zip files, so the Windows installer is not
+needed. With the two disc images (`.cue`/`.bin`, `.iso`, or the disc folders):
+
+```bash
+brew install sevenzip     # only needed for .bin/.iso images
+python3 tools/install_from_discs.py ~/Games/NFSU2 "Disc 1.cue" "Disc 2.cue"
+```
+
+This writes a normal game folder (about 1.7 GB) that the launcher can point at.
+It copies the disc's `SPEED2.EXE` too, but see the table above: the launcher
+accepts only the supported executable. With that executable in the folder, the
+US disc data plays in the US region (see "US data works with the supported
+executable" above).
 
 ## Build and run
 
@@ -247,9 +297,15 @@ game files inside (about 1.4 GB). It runs on its own; saves stay in
 so keep it for yourself.
 
 **Which version of the game does it need?**
-The Windows PC version, with the exact `SPEED2.EXE` listed under
-[Requirements](#requirements). Other builds, including the console versions,
-are not supported.
+The Windows PC version, with the European v1.2 `SPEED2.EXE` listed under
+[Requirements](#requirements). The North American v1.2 executable is not
+supported yet; the US v1.0 disc executable cannot be (it is copy-protected).
+Console versions are not supported. See [Game versions](#game-versions).
+
+**I only have the PC discs. Can I install them on a Mac?**
+Yes, without Windows: `tools/install_from_discs.py` unpacks the disc images
+into a game folder. See [Installing from the PC discs on a
+Mac](#installing-from-the-pc-discs-on-a-mac).
 
 **Does it work on Intel Macs?**
 No. Only Apple Silicon is targeted and tested.
 
@@ -8,6 +8,9 @@ if [ -n "$NFSU2_DATA" ]; then
   if [ -d "$NFSU2_DATA" ]; then EXE="$NFSU2_DATA/SPEED2.EXE"; else EXE="$NFSU2_DATA"; fi
 fi
 [ -f "$EXE" ] || { echo "SPEED2.EXE not found: $EXE"; exit 1; }
+# NFSU2_REGION=na|eu: the game's region.  Default: detected from the data's region
+#   cars (CARS/CIVIC + RSX without CORSA + PEUGOT106 = North American, e.g. US discs).
+#   See runtime/overrides.c, region_install.
 # TWO BUILDS (see link.sh):
 #   ./run.sh [mode]          original  (out/nfsu2_boot)
 #   NFSHD=1 ./run.sh [mode]  HD        (out/nfsu2_hd_boot) -- graphics improvements
@@ -51,7 +54,7 @@ unset AUTOKEY AUTOCLICK FORCESWITCH FETICK GAMELOG DUMPFRAME BOOTFLOW \
       FPSCSV AUTOKEYSTOP VCLOCK VCLOCK_MAXD DECLLOG CULLWIND RSLOG NOFOG BLITQUAD RESSCAN ASPFIX ASPLOG PSHIST MIPLIN NOANISO LODMAX \
       RTIDLOG DRAWVPS ZSHARELOG XFORMAT CAMLOG HD_SSR_DEBUG VIEWLOG HD_RTPROBE HD_RTPROBE2 HD_RT_STAGE HD_RT_NOTEX HD_RT_PLAIN HD_RT_ONLYCX HD_RT_SLOWBUILD HD_RT_LOG HD_RT_DUMPTAB HD_RT_STRESS HD_COMP HD_MSLAZY HD_REORDER HD_RT_AB HD_RT_FIX HD_RT_POISON FORCERAIN FORCETOD FORCETOD_STATE GPUWIN PASSPROF PASSPROF_MODE GPUVSDUMP \
       SNDMUTE YAKALAKARE DRAWLIST NODRAW LIMFREE ABTEST PASSPROF_CSV HD_MBLOG HD_RT_DLOG HD_RT_ONLY HD_RTPROBE2_HER \
-      STALL MEMDUMP REGFIRST ADAPTERID
+      STALL MEMDUMP REGFIRST ADAPTERID FPSCAP BGFPS FBONLY
 
 export FIXMAT="${FIXMAT:-1}"
 export NOMOVIES="${NOMOVIES:-1}"
 
@@ -86,6 +86,12 @@ static int resolve_in(const char *root, const char *win, char *out, size_t outsz
     return !missing;
 }
 
+/* Does the game folder hold this file?  Windows-style path, case-insensitive. */
+int fileio_game_file_exists(const char *win){
+    char p[1024]; struct stat st;
+    return resolve_in(g_root, win, p, sizeof p) && stat(p, &st) == 0 && S_ISREG(st.st_mode);
+}
+
 /* --- write root (save layer) ---------------------------------------------
  * The game writes its saves and profiles into its OWN folder ("C:\NFSU2\NFS
  * Underground 2\<name>\<name>").  Writing there deletes the saves when a new