@@ -57,9 +57,9 @@ static void dump_init(void){
  * ~/Library/Logs/NFSU2/).  For scenes the user reaches but automated tests
  * can't produce (e.g. the end of a career race). */
 static _Atomic int g_dump_req;
-static long g_dump_req_f = -1;
+static long g_dump_req_f = -1, g_dump_req_end = -1;   /* Cmd+Shift+D: frames [f, end] */
 static int dump_wanted(long f){
-    if (f == g_dump_req_f) return 1;
+    if (g_dump_req_f >= 0 && f >= g_dump_req_f && f <= g_dump_req_end) return 1;
     for (int i = 0; i < g_dump_n; i++) if (g_dump_want[i] == (int)f) return 1;
     return 0;
 }
@@ -4491,35 +4491,58 @@ void metal_set_ps(int psid, const float *c32){
  * The game's own bytecode is translated to MSL and compiled here. */
 #define MAXVSF 512
 static id<MTLFunction> g_vsfn[MAXVSF];
+/* The compile runs WITHOUT the big lock (guest_blocking_begin): a new shader is
+ * compiled synchronously on the game thread when it is first drawn, and with the
+ * HD capture kernel that took 50-110 ms when a race started (2026-11-04 session:
+ * the sound threads waited 50-64 ms for the lock -> the sound stuttered between
+ * the loading screen and the race).  Nothing here touches guest memory; the
+ * results are stored after the lock is back.  VSCOMPILELOCK=1: keep the lock. */
 void metal_register_vs(int vsid, const char *msl){
     if (vsid <= 0 || vsid >= MAXVSF || !msl || !g_dev || g_vsfn[vsid]) return;
     @autoreleasepool {
         NSString *src = [kPrelude stringByAppendingString:
                          [NSString stringWithUTF8String:msl]];
         NSError *err = nil;
+        int guest_blocking_begin(void); void guest_blocking_end(void);
+        static int keep = -1; if (keep < 0) keep = ENVC("VSCOMPILELOCK") != NULL;
+        int yielded = keep ? 0 : guest_blocking_begin();
+        id<MTLFunction> vfn = nil;
+#if NFS_ENHANCED
+        id<MTLComputePipelineState> vsk = nil; NSError *ke = nil; int want_k = 0;
+#endif
         struct timespec _c0; if (g_perflog) clock_gettime(CLOCK_MONOTONIC, &_c0);
         id<MTLLibrary> lib = [g_dev newLibraryWithSource:src options:nil error:&err];
         if (g_perflog){ struct timespec _c1; clock_gettime(CLOCK_MONOTONIC, &_c1);
             perflog_event(PL_VS, (uint64_t)(_c1.tv_sec - _c0.tv_sec) * 1000000000ull + (uint64_t)_c1.tv_nsec - (uint64_t)_c0.tv_nsec, 0); }
+        char nm[32];
+        if (lib){
+            snprintf(nm, sizeof nm, "vs_%d", vsid);
+            vfn = [lib newFunctionWithName:[NSString stringWithUTF8String:nm]];
+#if NFS_ENHANCED
+            if (vsid < HD_MAXVSI && hd_rt_on()){
+                want_k = 1;
+                snprintf(nm, sizeof nm, "vsk_%d", vsid);
+                id<MTLFunction> kf = [lib newFunctionWithName:[NSString stringWithUTF8String:nm]];
+                if (kf) vsk = [g_dev newComputePipelineStateWithFunction:kf error:&ke];
+            }
+#endif
+        }
+        if (yielded) guest_blocking_end();
         if (!lib){
             static int shown = 0;
             if (shown < 5){ shown++;
                 fprintf(stderr, "vertex shader %d could not be compiled: %s\n", vsid,
                         err ? [[err localizedDescription] UTF8String] : "?"); }
             return;
         }
-        char nm[32]; snprintf(nm, sizeof nm, "vs_%d", vsid);
-        g_vsfn[vsid] = [lib newFunctionWithName:[NSString stringWithUTF8String:nm]];
-        if (!g_vsfn[vsid])
+        g_vsfn[vsid] = vfn;
+        if (!vfn)
             fprintf(stderr, "vertex shader %d: function not found\n", vsid);
 #if NFS_ENHANCED
-        if (vsid < HD_MAXVSI && hd_rt_on()){
-            snprintf(nm, sizeof nm, "vsk_%d", vsid);
-            id<MTLFunction> kf = [lib newFunctionWithName:[NSString stringWithUTF8String:nm]];
-            NSError *ke = nil;
-            if (kf) g_hd_vsk[vsid] = [g_dev newComputePipelineStateWithFunction:kf error:&ke];
-            if (!g_hd_vsk[vsid]) fprintf(stderr, "[HD] capture kernel vs_%d could not be built: %s\n", vsid,
-                                         ke ? [[ke localizedDescription] UTF8String] : "no function");
+        if (want_k){
+            g_hd_vsk[vsid] = vsk;
+            if (!vsk) fprintf(stderr, "[HD] capture kernel vs_%d could not be built: %s\n", vsid,
+                              ke ? [[ke localizedDescription] UTF8String] : "no function");
         }
 #endif
     }
@@ -6954,13 +6977,17 @@ + (unsigned long long)_d1.tv_nsec - (unsigned long long)_d0.tv_nsec);
                         { static long yk = -2; if (yk == -2){ const char *e = ENVC("YAKALAKARE"); yk = e ? atol(e) : -1; }
                           if (fno_pre == yk) atomic_store(&g_dump_req, 1); }   /* test of the shortcut */
                         if (atomic_exchange(&g_dump_req, 0)){
-                            g_dump_req_f = fno_pre;
+                            /* a burst of consecutive frames (CAPBURST, default 8): flicker
+                             * only shows between frames; the draw list is written for the first */
+                            static long burst = -1;
+                            if (burst < 0){ const char *e = ENVC("CAPBURST"); burst = e ? atol(e) : 8; if (burst < 1) burst = 1; if (burst > 64) burst = 64; }
+                            g_dump_req_f = fno_pre; g_dump_req_end = fno_pre + burst - 1;
                             if (!g_dump_n){ const char *pl = getenv("PERFLOG"), *h = getenv("HOME");
                                 if (pl && *pl) snprintf(g_dump_dir, sizeof g_dump_dir, "%s", pl);
                                 else snprintf(g_dump_dir, sizeof g_dump_dir, "%s/Library/Logs/NFSU2", h ? h : "/tmp"); }
-                            fprintf(stderr, "capture: frame %ld (Cmd+Shift+D) -> %s\n", fno_pre, g_dump_dir);
+                            fprintf(stderr, "capture: frames %ld-%ld (Cmd+Shift+D) -> %s\n", fno_pre, g_dump_req_end, g_dump_dir);
                         }
-                        int  dumpnow = (g_dump_n || g_dump_req_f == fno_pre) && dump_wanted(fno_pre);
+                        int  dumpnow = (g_dump_n || (g_dump_req_f >= 0 && fno_pre >= g_dump_req_f && fno_pre <= g_dump_req_end)) && dump_wanted(fno_pre);
                         /* GLYPHDUMP: screen box + UV of every quad.
                          * Goal: decode the TEXT the game writes and read its state. */
                         if (ENVC("GLYPHDUMP") && dumpnow && rb >= 0){
 
@@ -567,8 +567,10 @@ void sub_0050d510(CPU *c){
                 for (const char *t2 = tmp; *t2 && o < sizeof out - 2; t2++) out[o++] = *t2;
             }
             out[o] = 0;
-            fprintf(stderr, "  [game] %s%s", out,
-                    (o && out[o-1] == '\n') ? "" : "\n");
+            /* seconds on the PERFLOG clock (perflog.c), to line up with its CSVs */
+            { uint64_t perflog_now_us(void);
+              fprintf(stderr, "  [game %.3f] %s%s", perflog_now_us() / 1e6, out,
+                      (o && out[o-1] == '\n') ? "" : "\n"); }
             /* Inside SwitchFEngPackages ebx = the front-end package manager
              * ("this").  printf is called exactly at that point, so we catch the
              * pointer here for free; needed to force the transition. */
 
@@ -3,22 +3,37 @@
 #
 #   ./tools/session.sh            normal build
 #   ./tools/session.sh hd         HD build
+#   ./tools/session.sh hd all     HD build with every HD picture / reflection option on
+#
+# Besides PERFLOG every session records (light enough to play with):
+#   game log [game t]  GAMELOG (front-end transitions, on the PERFLOG clock)
+#   sound              SNDSTAT/SNDGAP lines, sound.csv (every mixer callback),
+#                      sound_out.raw (what was played: s16le 44100 Hz stereo)
+#   timing / threads   TIMELOG, THREADLOG, GILLOG=20 (lock holds > 20 ms), [timer]
+#   files              FILEOPLOG (opens/closes; loads between menus)
+#   GPU                PASSPROF every 120 frames -> passprof.csv, MATLOG, TEXUPSAY
+#   SESSION_LIGHT=1    PERFLOG only, as before
 #
 # The game starts with recording on (PERFLOG); play normally, quit the game when
 # done.  At the same time powermetrics writes CPU/GPU watts once a second (the
 # admin password is asked once; without it only the in-game recording is taken).
 # Recording: ~/nfs_sessions/<date>[_hd]   Analysis: python3 tools/session_report.py <dir>
 set -u
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-HD=0
-for a in "$@"; do case "$a" in hd) HD=1 ;; *) echo "unknown: $a"; exit 1 ;; esac; done
+HD=0; ALL=0
+for a in "$@"; do case "$a" in hd) HD=1 ;; all) ALL=1 ;; *) echo "unknown: $a"; exit 1 ;; esac; done
 # the recording directory is tagged with the version: always clear which version was played
 VERSION="$(tr -cd '0-9' < "$ROOT/VERSION" 2>/dev/null)"; VERSION="${VERSION:-0}"
 SUF="_v$VERSION"; ENG=original
 [ $HD = 1 ] && { SUF="${SUF}_hd"; ENG=hd; }
 # NFSU2.app holds both engines (launcher picks one); an older separate "NFSU2 HD.app"
 # is used only when NFSU2.app has no HD engine.
-pick(){ for d in "$ROOT/out/personal" "$ROOT/out"; do [ -d "$d/$1" ] && { echo "$d/$1"; return; }; done; }
+# the bundle with the NEWEST engine (an old out/personal copy must not win over a fresh ./pack.sh)
+pick(){ local best="" d
+  for d in "$ROOT/out/personal" "$ROOT/out"; do
+    [ -d "$d/$1" ] || continue
+    if [ -z "$best" ] || [ "$d/$1/Contents/MacOS/nfsu2-engine" -nt "$best/Contents/MacOS/nfsu2-engine" ]; then best="$d/$1"; fi
+  done; echo "$best"; }
 APP="$(pick NFSU2.app)"
 if [ $HD = 1 ] && { [ -z "$APP" ] || [ ! -x "$APP/Contents/MacOS/nfsu2-engine-hd" ]; }; then
   APP="$(pick "NFSU2 HD.app")"
@@ -51,8 +66,21 @@ echo "starting the game: play normally (~5 min), quit the game when done."
 { date; pmset -g batt; pmset -g | grep -i lowpowermode; } > "$DIR/battery_start.txt" 2>&1
 # DLINK=2: writes the real display refresh rate to the game's log every 5 s
 # NFSU2_SKIP_LAUNCHER: straight into the game, no launcher window
+EXTRA=()
+if [ "${SESSION_LIGHT:-0}" != 1 ]; then
+  for kv in GAMELOG=1 TIMELOG=1 THREADLOG=1 FILEOPLOG=1 GILLOG=20 SNDSTAT=1 SNDGAP=1 \
+            "SNDCSV=$DIR/sound.csv" "SNDDUMP=$DIR/sound_out.raw" \
+            PASSPROF=120 "PASSPROF_CSV=$DIR/passprof.csv" GPUWIN=1,2000000000 MATLOG=1 TEXUPSAY=1; do
+    EXTRA+=(--env "$kv"); done
+fi
+if [ $ALL = 1 ]; then
+  for kv in TINT=none CONSOLEGAMMA=1 EDGEAA=1 SHARPEN=50 \
+            NFSU2_REFLECT_SKY=1 NFSU2_REFLECT_LIGHTS=1 NFSU2_REFLECT_DETAIL=1; do
+    EXTRA+=(--env "$kv"); done
+fi
+printf '%s\n' ${EXTRA[@]+"${EXTRA[@]}"} | grep -v '^--env$' > "$DIR/session_env.txt"
 open -W -n "$APP" --env NFSU2_SKIP_LAUNCHER=1 --env NFSU2_ENGINE=$ENG \
-  --env PERFLOG="$DIR" --env DLINK=2 --stderr "$DIR/game.log"
+  --env PERFLOG="$DIR" --env DLINK=2 ${EXTRA[@]+"${EXTRA[@]}"} --stderr "$DIR/game.log"
 { date; pmset -g batt; pmset -g | grep -i lowpowermode; } > "$DIR/battery_end.txt" 2>&1
 LG=nfsu2; [ $HD = 1 ] && LG="$LG-hd"
 cp "$HOME/Library/Logs/NFSU2/$LG.log" "$DIR/game_full.log" 2>/dev/null