Mac: fix Metal HUD menu hide/show

dm/games/0100F43008C44000/README.md

@@ -66,6 +66,7 @@ Each item was found from a red line or a pass dump on the way through the langua
 
 ## Mac routes
 
+- **Resolved (2026-10-29):** the [Metal HUD Hide/Show menu](../../../docs/reference/rendering.md#metal-hud-stays-visible-after-hide-hud) works with `DM_METAL_HUD=1`. Update 2.0.2, M2 Max, macOS 26.6: the rebuilt host showed the HUD at language selection, Hide HUD removed it, and Show HUD restored it. This checked the frontend menu, not a new gameplay route.
 - A fresh save reaches play in Lumiose City with `DM_KBD=Taylor DM_KEYS="f450:A,f1200:LRight~1,f1600:A,f1900:Down,f2000:Down,f2100:A,f2400:A*80/90"`.
 - A save made there continues with `DM_KEYS="f300:A*3/150"` (play from about frame 600), and `LUp~12` then walks along the platform.
 - A 5-minute walk: GPU about 6 ms a frame, no crash.
@@ -74,6 +75,7 @@ Each item was found from a red line or a pass dump on the way through the langua
 
 General host changes first needed here; each applies to every game:
 
+- **Metal HUD menu visibility (resolved):** [Metal HUD stays visible after Hide HUD](../../../docs/reference/rendering.md#metal-hud-stays-visible-after-hide-hud).
 - **The pool enforced as on Horizon** (`mem_map_limit`, `hle_svc.c`): [the profile keys](../README.md#keys), [Maps past the application pool fail as on Horizon](../../../docs/reference/memory.md#maps-past-the-application-pool-fail-as-on-horizon).
 - **Trinity packs decoded with the game's own Oodle** (`trpfs_jobs` / `trinity_shaders`, `hle_oodle.c`, `DM_OODLE_HOST` / `DM_OODLE_MODULES`, set by the NSP script for any game with `ONEPACK` files): [BNSH in Trinity packs](../../../docs/reference/shaders.md#bnsh-in-trinity-packs), [01, Compressed RomFS content](../../../docs/agents/01-extract.md#compressed-romfs-content).
 - **SDK 19 calls:** csrng bytes, `GetAudioOutBufferCount` from the host queue, NVN state getters, `WaitForAddress` type 3, `OP_FENCE_SYNC`: [Cryptographically random bytes](../../../docs/reference/services.md#cryptographically-random-bytes), [AudioOut buffer count from the host queue](../../../docs/reference/audio.md#audioout-buffer-count-from-the-host-queue), [State read back through NVN getters](../../../docs/reference/nvn-objects.md#state-read-back-through-nvn-getters), [WaitForAddress type 3](../../../docs/reference/threads.md#waitforaddress-type-3-64-bit-wait-if-equal), [Fence syncs recorded in command buffers](../../../docs/reference/nvn-objects.md#fence-syncs-recorded-in-command-buffers).

dm/host/front_mac.m

@@ -1180,7 +1180,9 @@ void front_run(void (*guest)(void)) {
         g_layer.device = MTLCreateSystemDefaultDevice();
         g_layer.pixelFormat = MTLPixelFormatBGRA8Unorm;
         g_layer.contentsScale = win.backingScaleFactor;
-        if (getenv("DM_METAL_HUD") && atoi(getenv("DM_METAL_HUD"))) { g_layer.developerHUDProperties = @{@"mode": @"default"}; LOG("front end: Metal performance HUD on (DM_METAL_HUD)"); }   // Apple's HUD over the game: frame rate, frame and GPU time, memory
+        // front_hud_env enables Apple's HUD before the first device. Leave the layer's mode unset so its Metal HUD menu can hide/show it;
+        // developerHUDProperties mode=default forces this layer on even after the menu's Hide HUD action.
+        if (getenv("DM_METAL_HUD") && atoi(getenv("DM_METAL_HUD"))) LOG("front end: Metal performance HUD on (DM_METAL_HUD)");
         v.layer = g_layer; [(DmGameView *)v fitDrawable];
         [win center];
         [win makeKeyAndOrderFront:nil];

docs/agents/symptoms.md

@@ -425,6 +425,7 @@ One line per symptom in the [subsystem references](../reference/): what you see
 
 ## Rendering
 
+- with `DM_METAL_HUD=1`, Apple's Metal HUD menu changes from **Hide HUD** to **Show HUD**, but the overlay stays visible. → [Metal HUD stays visible after Hide HUD](../reference/rendering.md#metal-hud-stays-visible-after-hide-hud)
 - clang reports null dereferences in `nvnWindowInitialize` and `clear_tex`; clearing a null texture crashes with `DM_NVN_PASSDUMP=1`. → [Null textures in diagnostic logs](../reference/rendering.md#null-textures-in-diagnostic-logs)
 - Metal aborts on a texture descriptor with an absurd size (`height (1869367126) greater than … 16384`). → [Texture objects copied into command records](../reference/rendering.md#texture-objects-copied-into-command-records)
 - a decoded movie stays black even though its YUV textures contain the picture; disabling its depth test makes it visible. → [New textures start as zero](../reference/rendering.md#new-textures-start-as-zero)

docs/reference/rendering.md

@@ -2,6 +2,15 @@
 
 The replay on Metal (`dm/gfx/nvn/nvn_mtl.m`) and the Vulkan and OpenGL layers. Each entry: symptom, cause, fix, the games it was found on. The [symptom index](../agents/symptoms.md) lists every symptom.
 
+## Mac performance HUD
+
+### Metal HUD stays visible after Hide HUD
+
+- **Symptom:** with `DM_METAL_HUD=1`, Apple's Metal HUD menu changes from **Hide HUD** to **Show HUD**, but the overlay stays visible.
+- **Cause:** `front_mac.m` set the layer's `developerHUDProperties` to `mode=default`, forcing that layer's HUD on independently of the menu's visibility setting. `front_hud_env` already enables the HUD through `MTL_HUD_ENABLED` before the first Metal device is made.
+- **Fix:** leave the Mac layer's HUD properties unset and let Apple's menu control visibility. Keep the early environment setup; the iOS layer setup is unchanged.
+- **Found on:** a standalone AppKit/Metal reproducer on M2 Max, macOS 26.6: the same window with the layer override reproduced the failure; without it, Hide HUD removes the overlay and Show HUD restores it. The rebuilt host also passed both menu actions in [Pokémon Legends: Z-A](../../dm/games/0100F43008C44000/README.md#mac-routes).
+
 ## Textures and formats
 
 ### Null textures in diagnostic logs