Merge pull request #1 from CoderDayton/release/0.3.0

Release 0.3.0

CHANGELOG.md

@@ -6,6 +6,66 @@ GitHub are taken from the matching section here.
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-18
+
+### Added
+
+- Custom Discord presence. `integrations.discord_rpc.text.title` replaces the
+  name in "Playing Nightcap", and `integrations.discord_rpc.images` sets the
+  large and small icons and their hover text. Text and image fields accept
+  `{place_name}`, `{place_icon}`, and `{creator_name}`. A field that expands
+  an empty placeholder is left out, and `text.state: ""` hides the state line.
+- The default Discord card now matches Sober: the title is "Roblox", the
+  details line is "Playing <experience>", the state is "by <creator>", and
+  the Roblox badge sits inside the experience icon. The creator comes from the
+  same Roblox games request that already fetches the experience name. With
+  `show_place_name: false` the creator is hidden too, so the card shows only
+  the title and timer.
+- `--profile <file>` writes a Chrome-format trace of the Vulkan adapter's
+  work: presents, GPU waits, submits, ETC2 texture decode, and pipeline and
+  shader creation. Open it in ui.perfetto.dev. `docs/BENCHMARKING.md`
+  describes the benchmark runs, and `scripts/summarize_profile_trace.py`
+  turns traces into a before and after table.
+
+### Fixed
+
+- Texture uploads stalled the frame they were submitted on. ETC2 batches
+  decoded on worker threads but were then resampled one upload at a time on
+  the submitting thread, which at the default 4x upscale is sixteen times the
+  decoded texels. Resampling now runs on the same worker pool, in two passes so
+  mip level 0 still resolves before the mips built from it. In a 70k-part
+  place the worst `vkQueueSubmit` fell from 167ms to 92ms.
+- Most ETC2 batches decoded on a single thread. Workers were created and
+  joined per batch, so the parallel floor had to cover that cost and sat at a
+  1024x1024 image; batches under it ran on the caller, which was 54% of all
+  decode time in a 70k-part place. Decode workers are now a persistent pool,
+  and the floor drops to a 128x128 image. Mean decode time in that place fell
+  from 8.2ms to 4.7ms, and 11.8ms before both texture fixes.
+- On CPUs with a wide core-speed spread, Feral GameMode pinned the process to
+  the few fastest cores, concentrating Roblox's worker pool onto them instead
+  of spreading it. With `performance.gamemode: auto`, a request that narrows
+  the CPU affinity is now released again, which releases the pin. Set
+  `pin_cores=no` in `~/.config/gamemode.ini` to keep GameMode without the
+  pinning, or `performance.gamemode: on` to accept it. See
+  `docs/PERFORMANCE.md`.
+- With `show_place_name: false`, Discord no longer shows the experience
+  thumbnail or its name on hover.
+- The host main thread no longer spins on the engine's message pump, which
+  cost about half a core and 146,000 empty calls a second. It now rests 100 µs
+  between polls: sleeping when the governor is `performance`, parking the
+  core with TPAUSE on CPUs that have it, spinning otherwise. With GameMode
+  setting the governor, process CPU in a 60k-part place fell from 216% to
+  107% at the same 120 fps. `MOCKTAIL_ENGINE_PUMP_REST` forces a mode; see
+  `docs/PERFORMANCE.md`.
+- ETC2 uploads with a `bufferRowLength` or `bufferImageHeight` larger than
+  the image read the padded rows as packed data and decoded garbage.
+- ETC2 resampling created and joined worker threads on every batch. It now
+  runs on the persistent decode pool.
+- A failed trace write left the profile writer thread waking every 250 ms
+  for the rest of the session. It now exits.
+- The `--profile` trace gains a `pump` slice for the engine's main-thread
+  step.
+
 ## [0.2.0] - 2026-09-16
 
 ### Added
@@ -75,6 +135,7 @@ First Nightcap release, forked from komaruworld/mocktail.
 - The AppImage build no longer fails on stale checksums for the slimmed
   Arch packages.
 
-[Unreleased]: https://github.com/CoderDayton/nightcap/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/CoderDayton/nightcap/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/CoderDayton/nightcap/releases/tag/v0.3.0
 [0.2.0]: https://github.com/CoderDayton/nightcap/releases/tag/v0.2.0
 [0.1.0]: https://github.com/CoderDayton/nightcap/releases/tag/v0.1.0

CMakeLists.txt

@@ -266,6 +266,7 @@ add_library(mocktail_runtime STATIC
   src/runtime/crash_report_policy.cc
   src/runtime/discord_rpc.cc
   src/runtime/device_profile.cc
+  src/runtime/engine_pump_rest.cc
   src/runtime/environment.cc
   src/runtime/external_launch_broker.cc
   src/runtime/frame_rate_policy.cc

README.md

@@ -25,7 +25,8 @@ side by side.
   waiting in a queue.
 - **Sharper textures.** Small textures are upscaled 4x by default, and you
   can replace any texture with your own PNG in `~/.config/mocktail/textures`.
-  Set `MOCKTAIL_SMALL_TEXTURE_UPSCALE=1` to turn the upscale off.
+  A ready-made crosshair is in [`textures/`](textures/README.md). Set
+  `MOCKTAIL_SMALL_TEXTURE_UPSCALE=1` to turn the upscale off.
 - **ETC2 textures on any GPU.** Games that use compressed mobile textures now
   render correctly on desktop GPUs, without stutter.
 - **No more error 319 kicks.** Servers no longer drop you shortly after
@@ -36,8 +37,9 @@ side by side.
 
 Everything else works the same as upstream. See the
 [roadmap](docs/ROADMAP.md) for what is coming next, the
-[changelog](CHANGELOG.md) for what each release changed, and the
-[FAQ](FAQ.md) for Discord RPC, logs, and VR.
+[changelog](CHANGELOG.md) for what each release changed,
+[performance](docs/PERFORMANCE.md) for CPU load, heat and the knobs that change
+them, and the [FAQ](FAQ.md) for Discord RPC, logs, and VR.
 
 ## Install with Flatpak
 

config/mocktail.example.yaml

@@ -112,12 +112,24 @@ integrations:
       public_servers_only: true
       # button_label: Join Server
     # English defaults. Uncomment only the lines you want to customize.
+    # Text and image fields accept {place_name}, {place_icon}, and
+    # {creator_name}. A field that expands an empty placeholder is left out,
+    # and a "" title shows the app name.
+    # title, state, and the images fields may be "" to hide them.
     # text:
     #   browsing: Browsing experiences
     #   joining: Joining an experience
-    #   playing: "{place_name}"
-    #   state: Playing Roblox
+    #   playing: "Playing {place_name}"
+    #   state: "by {creator_name}"
     #   unknown_place: Unknown experience
+    #   title: Roblox
+    # Images take an https:// URL, or an asset key uploaded to application_id.
+    # large: "" hides both images; the small image needs a large one.
+    # images:
+    #   large: "{place_icon}"
+    #   large_text: "{place_name}"
+    #   small: roblox_small
+    #   small_text: Roblox
     # Advanced: overrides the application bundled by the package maintainer.
     # application_id: 123456789012345678
 

docs/BENCHMARKING.md

@@ -0,0 +1,98 @@
+# Benchmarking
+
+A pull request that claims a speedup shows before and after numbers taken
+the way this guide describes. Numbers from different machines are not
+compared with each other. Each run is compared with a run on the same
+machine.
+
+## Two layers, two tools
+
+Roblox measures its own work. Nightcap measures the layer between Roblox and
+your driver.
+
+| Layer | What it covers | Tool |
+| --- | --- | --- |
+| Roblox | Scripts, physics, rendering jobs, network | Roblox's stats overlays, Shift+F4 and Shift+F5 in game |
+| Nightcap | Vulkan adapter: present, swapchain and GPU waits, submits, ETC2 texture decode, pipeline and shader creation | `--profile` |
+
+A Nightcap change should move the `--profile` numbers. If it only moves the
+Roblox overlay numbers, say so in the pull request, since the cause is then
+less direct.
+
+## Recording a trace
+
+```sh
+mocktail --profile ~/nightcap-before.json
+```
+
+The Vulkan adapter writes a Chrome-format trace to that file, a few times a
+second. The file is valid JSON after every write, so a session that crashes
+or is killed still leaves a readable trace. Exit from the Roblox menu when you are done. Open the file
+in [ui.perfetto.dev](https://ui.perfetto.dev) or `chrome://tracing`.
+
+Expect about 130 bytes per event, around 15 MB per minute at 240 FPS.
+Profiling is off unless `--profile` is given, and `MOCKTAIL_PROFILE_TRACE`
+does the same thing as the flag.
+
+### What the trace contains
+
+Each slice is named after the call it times, on the thread that made it.
+
+| Category | Slices | Arguments |
+| --- | --- | --- |
+| `present` | `vkQueuePresentKHR`: the whole adapter present, including the text overlay | `result` |
+| `present` | `host present`: the host driver's present, nested inside the slice above | |
+| `wait` | `vkAcquireNextImageKHR`, `vkAcquireNextImage2KHR`, `vkWaitForFences`, `vkWaitSemaphores`, `vkWaitSemaphoresKHR`, `vkQueueWaitIdle`, `vkDeviceWaitIdle` | |
+| `submit` | `vkQueueSubmit`, `vkQueueSubmit2`, `vkQueueSubmit2KHR` | `submits` |
+| `texture` | `etc2 decode`: CPU decode of ETC2 textures before a submit | `uploads`, `compressed_bytes`, `decoded_bytes` |
+| `pipeline` | `vkCreateGraphicsPipelines`, `vkCreateComputePipelines` | `count`, `cache` (1 when a pipeline cache was passed), `result` |
+| `pipeline` | `vkCreateShaderModule` | `bytes`, `result` |
+| `pipeline` | `vkCreatePipelineCache` | `initial_bytes`, `result` |
+| `pump` | `nativeCallMessagesFromMainThread`: the engine's main-thread step, on the host main thread. Only calls of 20 µs or more are recorded; the empty polls between them are not. | |
+
+The `frame interval (ms)` counter is the time between successive adapter
+presents. `vkQueuePresentKHR` time minus `host present` time is the adapter's
+own cost per frame.
+
+## The benchmark runs
+
+Run every scenario before and after the change, on the same build type
+(`make build`), with the same `config.yaml`. Close other GPU-heavy apps.
+Record `graphics.frame_rate_limit` and `graphics.vsync` in the pull request,
+because a frame cap hides frame time gains.
+
+| Scenario | How to start | What to do | What it shows |
+| --- | --- | --- | --- |
+| Home screen, cold | `mocktail --profile home-cold.json` with an empty shader cache (below) | Wait 30 s on the home screen, exit | First-load stutter: `pipeline` and `texture` slices |
+| Tower of Hell | `mocktail --profile toh.json --launch-uri "roblox://experiences/start?placeId=1962086868"` | Stand still at spawn for 60 s, exit | Steady-state frame time on a light scene |
+| Murder Mystery 2 | `mocktail --profile mm2.json --launch-uri "roblox://experiences/start?placeId=142823291"` | Stay in the lobby for 60 s, exit | Frame time with many players and a busier scene |
+
+For the cold run, point the driver's shader cache at an empty directory, so
+your normal cache is left alone:
+
+```sh
+cache=$(mktemp -d)
+MESA_SHADER_CACHE_DIR="$cache" __GL_SHADER_DISK_CACHE_PATH="$cache" \
+  mocktail --profile home-cold.json
+```
+
+`MESA_SHADER_CACHE_DIR` applies to Mesa drivers (AMD, Intel) and
+`__GL_SHADER_DISK_CACHE_PATH` to the NVIDIA driver.
+
+Run each scenario three times and keep the median run, since one run can
+catch a background stall.
+
+## Comparing runs
+
+```sh
+scripts/summarize_profile_trace.py toh-before.json toh-after.json
+```
+
+This prints a Markdown table with one column per trace: frame count, frame
+interval mean, p50, p95, p99 and max, then count, total, mean, p99 and max
+for every slice name, largest total first. Paste the table into the pull
+request and attach both traces.
+
+For frame time, compare p95 and p99 as well as the mean. Stutter shows up in
+the tail first. For first-load work, compare the `total (ms)` rows of the
+`pipeline` and `texture` slices from the cold run.

docs/PERFORMANCE.md

@@ -0,0 +1,147 @@
+# Performance and CPU load
+
+What Nightcap does to your CPU and GPU, which knobs change it, and how to
+measure rather than guess.
+
+## GameMode core pinning
+
+Nightcap asks Feral GameMode for a performance session at startup
+(`performance.gamemode`, default `auto`). GameMode raises the CPU governor and
+the process priority, which helps.
+
+On a CPU with a wide spread of per-core maximum frequencies — Intel P-core and
+E-core parts, AMD parts with preferred cores — GameMode also pins the process
+to the fastest cores. On a 32-thread host that can mean 4 usable threads out of
+32. Roblox spreads its work across a worker pool, so the pin concentrates that
+pool onto a couple of physical cores instead of spreading it. Those cores sit
+near their boost ceiling and run hot while the rest of the chip idles.
+
+GameMode re-applies the pin roughly every 5 seconds, so widening the mask from
+inside the process does not hold. Releasing the request does release the pin.
+
+Under `auto`, Nightcap therefore checks its CPU affinity immediately after the
+request. If GameMode narrowed it, Nightcap ends the request and prints:
+
+```
+  [gamemode] released: it pinned this process to a subset of the CPUs, ...
+```
+
+The trade is that GameMode's governor and priority boost go with it. To keep
+those and lose only the pinning, turn pinning off for every game on the host:
+
+```ini
+# ~/.config/gamemode.ini
+[cpu]
+pin_cores=no
+park_cores=no
+```
+
+GameMode reads `$XDG_CONFIG_HOME`, `/usr/share/gamemode` and `/etc`, in that
+order. It does not read anything under Nightcap's own config directory, so this
+file has to live in one of those three places. The daemon reads it when it
+starts, so restart it after editing: `systemctl --user restart gamemoded`.
+
+The governor switch runs through polkit. Debian and Ubuntu only allow it for
+members of the `gamemode` group; without that, the daemon's journal shows
+`cpugovctl set performance: Not authorized` and the governor stays put while
+the session is otherwise active. Add yourself and log in again:
+
+```bash
+sudo usermod -aG gamemode "$USER"
+```
+
+Fedora and Arch allow any logged-in local user.
+
+Setting `performance.gamemode: on` accepts the pinning instead: `on` is an
+explicit request for GameMode, and Nightcap keeps the session whatever it does
+to the affinity. `off` never contacts the daemon.
+
+To see which CPUs the process may use:
+
+```bash
+taskset -pc $(pgrep -x mocktail)
+```
+
+## The main-thread pump
+
+Roblox posts its per-frame main-thread step at a time of its own choosing,
+and nothing signals the host when it does. The host main thread therefore
+polls `nativeCallMessagesFromMainThread`, and a post that waits more than a
+fraction of a millisecond costs a whole frame. Between polls the thread rests
+for 100 µs, and how it rests decides the CPU clock:
+
+| Mode | When | What it costs |
+| --- | --- | --- |
+| `sleep` | The governor is `performance`, which GameMode sets | The thread idles at about 3% of a core. The governor holds the clock. |
+| `tpause` | Otherwise, on a CPU with WAITPKG (Intel 12th gen and newer) | The core stays awake in a light C0 state. Frame rate holds; the OS books the time as busy, so the thread shows around 70% of a core, at lower power than a spin. |
+| `spin` | Otherwise | The core stays awake at full power. |
+
+Under a power-saving governor the CPU clocks a bursty core down unless some
+core stays awake, and Roblox's render thread then runs slower and drops
+frames. That is why `sleep` is not the default there. Startup prints the
+chosen mode:
+
+```
+  [main] engine pump rest: tpause (MOCKTAIL_ENGINE_PUMP_REST=sleep|tpause|spin)
+```
+
+`MOCKTAIL_ENGINE_PUMP_REST` forces a mode. `sleep` without the governor's help
+runs cooler for a few frames per second less; measure before keeping it.
+
+## Small texture upscaling
+
+`MOCKTAIL_SMALL_TEXTURE_UPSCALE` (default `4`) redraws ETC2 textures of 64px or
+smaller at N times their width and height. At the default that is 16 times the
+pixels per affected texture.
+
+The cost lands in two places. Decoding and resampling is CPU work on up to 8
+threads while textures load, which shows up as a burst rather than a steady
+load. The enlarged textures then stay in GPU memory for the session and cost
+extra sampling bandwidth on every frame that uses them.
+
+Set it to `1` to turn upscaling off:
+
+```bash
+MOCKTAIL_SMALL_TEXTURE_UPSCALE=1 mocktail
+```
+
+## Frame rate and present mode
+
+`graphics.frame_rate_limit` (default `-1`) leaves Roblox's own in-game
+framerate cap in charge; Nightcap sets no `DFIntTaskSchedulerTargetFps`
+override. A fixed value forwards that number to the scheduler.
+
+`graphics.vsync` (default `auto`) selects the presentation mode. `auto` and
+`on` both pick the lowest-latency synchronized mode the driver offers, in
+order: `FIFO_LATEST_READY`, `MAILBOX`, `FIFO_RELAXED`, `FIFO`. The first two do
+not block the render thread on the display refresh, so the frame rate is
+governed by the in-game cap rather than by presentation. `off` selects
+`IMMEDIATE` and does not synchronize at all.
+
+If the frame rate is higher than your refresh rate, the extra frames are work
+you cannot see. Lower the in-game cap to your refresh rate first.
+
+## Measuring
+
+Shift+F4 in game shows Roblox's own scheduler jobs, with a millisecond cost and
+a percentage for each. It does not show Nightcap's threads — the Vulkan
+adapter, the ETC2 decode workers, the libc shim — so it is a reading on the
+game, not on the process.
+
+For the whole process:
+
+```bash
+top -H -p $(pgrep -x mocktail)      # per-thread CPU, sorted
+ps -L -o psr=,pcpu=,comm= -p $(pgrep -x mocktail)   # which core each thread is on
+nvidia-smi --query-gpu=utilization.gpu,temperature.gpu,power.draw --format=csv
+```
+
+A thread pinned near 100% while the frame rate is steady is a busy-wait. The
+one exception is the host main thread in `tpause` mode, which the OS reports
+as busy while the core is parked (see above). Load spread across many
+`RBX Worker` threads is the game's own scheduler, and its cost tracks the
+place you are in — part count, moving parts and joints all show in the
+Shift+F4 World section.
+
+`--profile <file>` writes a Chrome trace of the Vulkan adapter's work for
+ui.perfetto.dev. See [BENCHMARKING.md](BENCHMARKING.md).

docs/ROADMAP.md

@@ -15,7 +15,8 @@ Goal: a small GTK4 settings window, reachable from the app menu and from a
 - Graphics tab: backend, frame rate limit, vsync, small texture upscale.
 - Input tab: the `input.raw_mouse` toggle and controller options.
 - Advanced tab: FFlag overrides with a plain text editor for `fflags.json`.
-- Discord tab: the `discord_rpc` block (see item 3).
+- Discord tab: every field in the `discord_rpc` block, so a friend can see
+  what you are playing and you can switch it all off in one click.
 - Changes apply on next launch. A restart button restarts Nightcap.
 
 Done when every option in `config/mocktail.example.yaml` that a player would
@@ -35,36 +36,16 @@ is left.
 
 Done when a plugged-in pad shows its own buttons.
 
-## 3. Discord Rich Presence
+## 3. First-load stutter
 
-Upstream ships Discord RPC. Nightcap turns it on by default; see the
-[FAQ](../FAQ.md) to switch it off. It shows the experience name, elapsed
-time, the experience icon, and a join button when the server is public.
+The `--profile` trace now shows shader compiles and pipeline creation, so
+the stutter on first entering an experience can be measured.
 
-- Custom presence: set the title, details line, state line, and large and
-  small icons from `config.yaml`, with placeholders like the experience name
-  and elapsed time.
-- A Discord tab in the settings window to toggle each field.
+- Cut the stutter the trace shows, and prove it with a before and after
+  trace per [BENCHMARKING.md](BENCHMARKING.md).
 
-Done when a friend can see what you are playing and join in one click, and
-you can switch it all off in one click.
-
-## 4. Performance profiling
-
-Every performance change should come with numbers. Today they come with a
-feeling.
-
-- A frame time overlay, toggled by a key and a config flag, showing CPU time,
-  GPU time, and present latency.
-- Shader compile and pipeline cache tracing, so first-load stutter can be
-  measured and cut.
-- A `--profile` flag that writes a Chrome-format trace file, readable in
-  `ui.perfetto.dev` and `chrome://tracing`.
-- A short benchmark guide in `docs/` with a fixed set of experiences, so
-  before and after numbers can be compared across machines.
-
-Done when a pull request that claims a speedup can show the trace that
-proves it.
+Done when entering a fresh experience no longer drops frames on shader
+compiles.
 
 ## Shipped
 
@@ -82,7 +63,21 @@ proves it.
 - No more error 319 kicks after joining a server.
 - Roblox sees the real host RAM and screen size.
 - Desktop launcher that works on Wayland and finds the installed binary.
-- Discord Rich Presence on by default.
+- Discord Rich Presence on by default, with the experience name, creator,
+  elapsed time, the experience icon with a Roblox badge, and a join button
+  when the server is public. See the [FAQ](../FAQ.md) to switch it off.
+- Custom Discord presence: title, details, state, and large and small icons
+  from `config.yaml`, with `{place_name}`, `{place_icon}`, and
+  `{creator_name}` placeholders.
+- `--profile` writes a Chrome-format trace of the Vulkan adapter's work,
+  including shader and pipeline creation, readable in `ui.perfetto.dev`.
+  [BENCHMARKING.md](BENCHMARKING.md) fixes the experiences to measure and
+  `scripts/summarize_profile_trace.py` builds the before and after table.
+- Texture uploads no longer stall the frame they land on: ETC2 decode and
+  resampling run on a persistent worker pool.
+- The host main thread rests between engine polls instead of spinning, and
+  GameMode's core pinning is released, so Roblox's workers spread across
+  every core. See [PERFORMANCE.md](PERFORMANCE.md).
 - Own app ID `io.github.CoderDayton.nightcap`, so Nightcap installs next to
   upstream.
 - AppImage and signed Flatpak releases on every `v*` tag, with the Flatpak

include/mocktail/graphics/chrome_trace_writer.h

@@ -0,0 +1,121 @@
+#ifndef MOCKTAIL_GRAPHICS_CHROME_TRACE_WRITER_H_
+#define MOCKTAIL_GRAPHICS_CHROME_TRACE_WRITER_H_
+
+#include <condition_variable>
+#include <cstdint>
+#include <cstdio>
+#include <filesystem>
+#include <initializer_list>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <thread>
+
+namespace mocktail {
+namespace graphics {
+
+// Environment variable naming the trace file the Vulkan adapter writes.
+inline constexpr char kProfileTraceEnvironment[] = "MOCKTAIL_PROFILE_TRACE";
+
+struct TraceArg {
+  const char* key;
+  std::int64_t value;
+};
+
+// CLOCK_MONOTONIC in nanoseconds.
+std::uint64_t TraceClockNanos();
+
+// Writes the Trace Event Format JSON array read by chrome://tracing and
+// ui.perfetto.dev. Recording threads only format into a shared buffer; a
+// background thread owns file writes, so disk stalls do not land inside the
+// measured calls. Events are written in arrival order. Each write ends the
+// file with the closing bracket, so a killed session leaves a loadable trace
+// holding everything written before it died.
+// Names, categories, and keys must outlive the call.
+class ChromeTraceWriter final {
+ public:
+  static std::unique_ptr<ChromeTraceWriter> Open(
+      const std::filesystem::path& path, std::string* error);
+
+  ~ChromeTraceWriter();
+  ChromeTraceWriter(const ChromeTraceWriter&) = delete;
+  ChromeTraceWriter& operator=(const ChromeTraceWriter&) = delete;
+
+  // A complete ("X") slice on the calling thread. Slices on one thread must
+  // nest, which scoped timing gives.
+  void Slice(const char* name, const char* category, std::uint64_t start_ns,
+             std::uint64_t end_ns, std::initializer_list<TraceArg> args = {});
+  void Slice(const char* name, const char* category, std::uint64_t start_ns,
+             std::uint64_t end_ns, const TraceArg* args,
+             std::size_t arg_count);
+  // A counter ("C") sample; each name becomes one counter track.
+  void Counter(const char* name, std::uint64_t timestamp_ns, double value);
+
+  // Returns once every event recorded before the call is on disk.
+  void Flush();
+  // Flushes, closes the file, and drops later events. Idempotent.
+  void Close();
+
+ private:
+  explicit ChromeTraceWriter(std::FILE* file);
+  void Append(const char* event, std::size_t size);
+  void WriterLoop();
+  void WritePending();
+
+  std::FILE* file_;
+  const int owner_pid_;
+  std::mutex file_mutex_;  // Guards file_ and spare_.
+  std::string spare_;
+  std::mutex mutex_;
+  std::condition_variable wake_;
+  std::string pending_;
+  bool first_event_ = true;
+  bool closed_ = false;
+  bool stopping_ = false;
+  std::thread writer_;
+};
+
+// The process trace named by MOCKTAIL_PROFILE_TRACE, opened on first use.
+// Null when profiling is off or the file could not be opened. The writer is
+// never destroyed; it is closed when the process exits normally.
+ChromeTraceWriter* ActiveProfileTrace();
+
+// Times its own lifetime as one slice. A null writer records nothing.
+class TraceScope final {
+ public:
+  TraceScope(ChromeTraceWriter* writer, const char* name,
+             const char* category)
+      : writer_(writer),
+        name_(name),
+        category_(category),
+        start_ns_(writer != nullptr ? TraceClockNanos() : 0) {}
+  ~TraceScope() {
+    if (writer_ != nullptr) {
+      writer_->Slice(name_, category_, start_ns_, TraceClockNanos(), args_,
+                     arg_count_);
+    }
+  }
+  TraceScope(const TraceScope&) = delete;
+  TraceScope& operator=(const TraceScope&) = delete;
+
+  // Keeps the first kMaxArgs arguments.
+  void Arg(const char* key, std::int64_t value) {
+    if (writer_ != nullptr && arg_count_ < kMaxArgs) {
+      args_[arg_count_++] = {key, value};
+    }
+  }
+
+ private:
+  static constexpr std::size_t kMaxArgs = 4;
+  ChromeTraceWriter* writer_;
+  const char* name_;
+  const char* category_;
+  std::uint64_t start_ns_;
+  TraceArg args_[kMaxArgs]{};
+  std::size_t arg_count_ = 0;
+};
+
+}  // namespace graphics
+}  // namespace mocktail
+
+#endif  // MOCKTAIL_GRAPHICS_CHROME_TRACE_WRITER_H_

include/mocktail/graphics/etc2_decoder.h

@@ -66,6 +66,14 @@ struct EtcDecodeJob {
 void DecodeEtcJobs(EtcDecodeJob* jobs, std::size_t count,
                    unsigned worker_count);
 
+// Calls run(context) worker_count times, once on the caller and the rest on
+// pooled decode workers that run alongside it, and returns when every call
+// has returned. `run` must be safe to call from several threads at once, so
+// it should drain a shared queue. When the pool is busy with another batch,
+// or no worker could be started, run is called on the caller alone.
+void RunOnDecodeWorkers(void (*run)(void*), void* context,
+                        unsigned worker_count);
+
 }  // namespace mocktail::graphics
 
 #endif  // MOCKTAIL_GRAPHICS_ETC2_DECODER_H_

include/runtime/command_line.h

@@ -33,6 +33,8 @@ struct CommandLineOptions {
   // Requests one explicit launch of the provider latest without promoting it
   // into the managed payload state.
   bool force_run_latest = false;
+  // Chrome trace file the Vulkan adapter writes; empty when not profiling.
+  std::string profile_trace_path;
 };
 
 struct CommandLineParseResult {

include/runtime/discord_rpc.h

@@ -13,11 +13,14 @@ namespace mocktail {
 namespace runtime {
 
 struct DiscordRpcActivity {
+  std::string name;
   std::string details;
   std::string state;
   std::optional<int64_t> start_timestamp;
   std::string large_image;
   std::string large_text;
+  std::string small_image;
+  std::string small_text;
   std::string button_label;
   std::string button_url;
 };
@@ -27,7 +30,8 @@ std::string BuildDiscordJoinUrl(const RobloxExperienceLaunchRequest& request);
 DiscordRpcActivity BuildDiscordRpcActivity(
     const DiscordRpcConfig& config, RobloxExperiencePresencePhase phase,
     const RobloxExperienceLaunchRequest* request, std::string place_name,
-    int64_t session_started_at, std::string place_icon_url = {});
+    int64_t session_started_at, std::string place_icon_url = {},
+    std::string creator_name = {});
 
 // Maintains a direct, unauthenticated Discord Desktop RPC connection. The
 // worker owns all network and IPC work; lifecycle notifications only replace

include/runtime/engine_pump_rest.h

@@ -0,0 +1,65 @@
+#ifndef MOCKTAIL_RUNTIME_ENGINE_PUMP_REST_H_
+#define MOCKTAIL_RUNTIME_ENGINE_PUMP_REST_H_
+
+#include <cstdint>
+
+namespace mocktail::runtime {
+
+// The engine posts its per-frame main-thread step at a time of its own
+// choosing, with no signal the host can block on, so the host main thread
+// polls nativeCallMessagesFromMainThread. An empty poll costs a few
+// microseconds; polled back to back it burns a core.
+//
+// Between polls the thread rests for kEnginePumpRestNs. A post is then picked
+// up at most kEnginePumpRestNs + timer slack + wake latency late, far under
+// the engine's sub-millisecond slack.
+//
+// How it rests decides the clock. Under a power-saving governor the CPU clocks
+// a bursty core down unless some core stays awake, and the engine's render
+// thread then runs slower and drops frames. So:
+//   kSleep   nanosleep. The core idles. Correct only when the governor holds
+//            the clock up on its own (performance, which GameMode sets).
+//   kTpause  TPAUSE in C0.2. The core stays awake at reduced power, the clock
+//            holds, and the OS books the time as busy. Needs WAITPKG.
+//   kSpin    No rest. The core stays awake at full power.
+inline constexpr uint64_t kEnginePumpRestNs = 100'000;
+// Timer slack the calling thread is set to; the kernel default of 50 us would
+// otherwise stretch every sleep.
+inline constexpr uint64_t kEnginePumpTimerSlackNs = 10'000;
+// Shallow C-state exit plus scheduler latency on the host, for the bound.
+inline constexpr uint64_t kShallowWakeNs = 50'000;
+
+enum class EnginePumpRestMode { kSleep, kTpause, kSpin };
+
+const char* EnginePumpRestModeName(EnginePumpRestMode mode);
+
+struct EnginePumpRestInputs {
+  bool governor_performance = false;
+  bool cpu_has_waitpkg = false;
+  // MOCKTAIL_ENGINE_PUMP_REST: "sleep", "tpause" or "spin". Null, empty or
+  // unknown defers to the policy; "tpause" without WAITPKG does too.
+  const char* override = nullptr;
+};
+
+EnginePumpRestMode ChooseEnginePumpRestMode(const EnginePumpRestInputs& inputs);
+
+// True when the file holds "performance". `path` is a cpufreq
+// scaling_governor file; cpu0's stands for the machine.
+bool CpuGovernorIsPerformance(const char* path);
+
+bool CpuHasWaitPkg();
+
+// The mode chosen from the host on first use.
+EnginePumpRestMode ActiveEnginePumpRestMode();
+
+// Rests the calling thread in the given mode and returns the rest length, 0
+// for kSpin. The first call lowers the thread's timer slack to
+// kEnginePumpTimerSlackNs.
+uint64_t RestAfterEnginePump(EnginePumpRestMode mode);
+inline uint64_t RestAfterEnginePump() {
+  return RestAfterEnginePump(ActiveEnginePumpRestMode());
+}
+
+}  // namespace mocktail::runtime
+
+#endif  // MOCKTAIL_RUNTIME_ENGINE_PUMP_REST_H_

include/runtime/game_mode.h

@@ -1,6 +1,8 @@
 #ifndef MOCKTAIL_RUNTIME_GAME_MODE_H_
 #define MOCKTAIL_RUNTIME_GAME_MODE_H_
 
+#include <sched.h>
+
 #include <string>
 #include <string_view>
 
@@ -22,6 +24,7 @@ enum class GameModeSessionState {
   kDisabled,
   kUnavailable,
   kRequestFailed,
+  kDeclinedCorePinning,
   kAlreadyActive,
   kActive,
   kStopped,
@@ -43,9 +46,37 @@ struct GameModeClientApi {
   ErrorFn error_string = nullptr;
 };
 
+// The CPU affinity calls, injectable so tests exercise the restore without
+// moving the threads they run on.
+struct CpuAffinityApi {
+  // Reads the calling thread's permitted CPUs. GameMode pins every thread
+  // alike, so one thread's mask is enough to detect the pin.
+  using GetFn = int (*)(cpu_set_t* mask);
+  // Applies `mask` to every thread of this process, not only the caller.
+  // Returns 0 when each live thread took it.
+  using SetFn = int (*)(const cpu_set_t* mask);
+
+  GetFn get = nullptr;
+  SetFn set = nullptr;
+};
+
+CpuAffinityApi HostCpuAffinityApi();
+
+// True when `after` permits a strict subset of the CPUs `before` permits.
+// An equal, wider or merely relocated set is not a narrowing.
+bool CpuAffinityNarrowed(const cpu_set_t& before, const cpu_set_t& after);
+
 // Owns at most one ref-counted GameMode request. Missing host support and
 // daemon rejection remain nonfatal because GameMode is an optimization, not a
 // correctness dependency.
+//
+// GameMode pins the calling process to the host's fastest cores when it sees a
+// wide core-speed spread. Roblox spreads its own work over a worker pool, so
+// that pin concentrates the load onto a couple of cores instead of helping,
+// and the daemon re-applies it every few seconds, so correcting the mask in
+// place does not hold. Under `auto`, a request that narrows the affinity is
+// released again: ending the request is what releases the pin. `on` is an
+// explicit choice and keeps the pinned session.
 class GameModeSession final {
  public:
   GameModeSession() = default;
@@ -59,6 +90,8 @@ class GameModeSession final {
   static GameModeSession Start(GameModePolicy policy);
   static GameModeSession StartWithClientForTesting(
       GameModePolicy policy, GameModeClientApi api);
+  static GameModeSession StartWithClientForTesting(
+      GameModePolicy policy, GameModeClientApi api, CpuAffinityApi affinity);
 
   GameModeSessionState state() const { return state_; }
   const std::string& detail() const { return detail_; }
@@ -73,6 +106,7 @@ class GameModeSession final {
  private:
   static GameModeSession StartBound(GameModePolicy policy,
                                     GameModeClientApi api,
+                                    CpuAffinityApi affinity,
                                     void* library_handle);
   void CloseLibrary();
 

include/runtime/roblox_input_router.h

@@ -223,6 +223,10 @@ class RobloxInputRouter final {
   Status DisconnectGamepadLocked(ActiveGamepad& gamepad);
   Status DisconnectGamepadsLocked();
   Status ReleasePressedInputsLocked();
+  // Keeps mouse_x_/mouse_y_ where they are for an event that carries no
+  // usable position, clamped to the current viewport. Before any absolute
+  // position has been seen, the held position is the viewport center.
+  void HoldPointerLocked(const platform::SurfaceCoordinateTransform& transform);
   int32_t AllocatePointerIdLocked() const;
   std::vector<ActiveTouch>::iterator FindTouchIteratorLocked(int64_t touch_id,
                                                              int64_t finger_id);
@@ -238,8 +242,13 @@ class RobloxInputRouter final {
   std::vector<ActiveTouch> active_touches_;
   std::vector<ActiveKey> active_keys_;
   std::vector<ActiveGamepad> gamepads_;
+  // Last known pointer position in guest units. Relative-mode motion, and
+  // wheel or button events with zero coordinates, do not move it: the pointer
+  // stays where it was captured while the deltas pass through.
   float mouse_x_ = 0.0f;
   float mouse_y_ = 0.0f;
+  // True once an absolute position has been received since Activate.
+  bool pointer_anchored_ = false;
   bool raw_mouse_ = false;
 };
 

include/runtime/runtime_config.h

@@ -51,14 +51,27 @@ struct NetworkProxyConfig {
   int port = 0;
 };
 
+// Text and image fields expand {place_name}, {place_icon}, and
+// {creator_name}. A field that expands an empty placeholder, or renders
+// empty, is left out of the activity.
 struct DiscordRpcTextConfig {
+  std::string title = "Roblox";
   std::string browsing = "Browsing experiences";
   std::string joining = "Joining an experience";
-  std::string playing = "{place_name}";
-  std::string state = "Playing Roblox";
+  std::string playing = "Playing {place_name}";
+  std::string state = "by {creator_name}";
   std::string unknown_place = "Unknown experience";
 };
 
+// Images are an https URL or a Discord application asset key. Discord shows
+// the small image only next to a large one.
+struct DiscordRpcImagesConfig {
+  std::string large = "{place_icon}";
+  std::string large_text = "{place_name}";
+  std::string small = "roblox_small";
+  std::string small_text = "Roblox";
+};
+
 struct DiscordRpcConfig {
   bool enabled = true;
   bool show_place_name = true;
@@ -68,6 +81,7 @@ struct DiscordRpcConfig {
   std::string join_button_label = "Join Server";
   std::string application_id;
   DiscordRpcTextConfig text;
+  DiscordRpcImagesConfig images;
 };
 
 std::optional<NetworkProxyConfig> ParseNetworkProxyConfig(

scripts/summarize_profile_trace.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+# Copyright 2026 Mocktail Project Authors
+# Licensed under the Apache License, Version 2.0.
+"""Summarizes `--profile` traces as a Markdown table for pull requests.
+
+Usage: summarize_profile_trace.py TRACE [TRACE ...]
+
+Each trace gets its own column, so `before.json after.json` compares them.
+Frame times come from the "frame interval (ms)" counter; every other row is
+a slice name recorded by the Vulkan adapter.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import math
+from pathlib import Path
+import sys
+from typing import Iterable
+
+FRAME_COUNTER = "frame interval (ms)"
+
+
+@dataclass(frozen=True)
+class Distribution:
+    count: int
+    total: float
+    mean: float
+    p50: float
+    p95: float
+    p99: float
+    max: float
+
+
+@dataclass(frozen=True)
+class Summary:
+    frames: Distribution | None
+    slices: dict[str, Distribution]
+
+
+def _nearest_rank(ordered: list[float], percent: float) -> float:
+    rank = max(1, math.ceil(percent / 100 * len(ordered)))
+    return ordered[rank - 1]
+
+
+def _distribution(values: list[float]) -> Distribution:
+    ordered = sorted(values)
+    total = sum(ordered)
+    return Distribution(count=len(ordered), total=total,
+                        mean=total / len(ordered),
+                        p50=_nearest_rank(ordered, 50),
+                        p95=_nearest_rank(ordered, 95),
+                        p99=_nearest_rank(ordered, 99), max=ordered[-1])
+
+
+def summarize(events: Iterable[dict]) -> Summary:
+    frames: list[float] = []
+    slices: dict[str, list[float]] = {}
+    for event in events:
+        phase = event.get("ph")
+        if phase == "C" and event.get("name") == FRAME_COUNTER:
+            frames.append(float(event["args"]["value"]))
+        elif phase == "X":
+            slices.setdefault(event["name"], []).append(event["dur"] / 1000)
+    return Summary(
+        frames=_distribution(frames) if frames else None,
+        slices={name: _distribution(values)
+                for name, values in slices.items()})
+
+
+def _row(label: str, cells: list[str]) -> str:
+    return "| " + " | ".join([label, *cells]) + " |"
+
+
+def _cell(distribution: Distribution | None, field: str) -> str:
+    if distribution is None:
+        return "-"
+    if field == "count":
+        return str(distribution.count)
+    return f"{getattr(distribution, field):.2f}"
+
+
+def _metric_row(label: str, distributions: list[Distribution | None],
+                field: str) -> str:
+    return _row(label, [_cell(item, field) for item in distributions])
+
+
+def to_markdown(traces: list[tuple[str, Summary]]) -> str:
+    summaries = [summary for _, summary in traces]
+    lines = [_row("metric", [name for name, _ in traces]),
+             _row("---", ["---:"] * len(traces))]
+
+    frames = [summary.frames for summary in summaries]
+    lines.append(_metric_row("frames", frames, "count"))
+    if any(frames):
+        lines += [_metric_row(f"frame interval {field} (ms)", frames, field)
+                  for field in ("mean", "p50", "p95", "p99", "max")]
+
+    # Largest total time first, taken from whichever trace spent the most.
+    totals: dict[str, float] = {}
+    for summary in summaries:
+        for name, distribution in summary.slices.items():
+            totals[name] = max(totals.get(name, 0.0), distribution.total)
+    for name in sorted(totals, key=lambda name: -totals[name]):
+        column = [summary.slices.get(name) for summary in summaries]
+        lines.append(_metric_row(f"{name} count", column, "count"))
+        lines += [_metric_row(f"{name} {field} (ms)", column, field)
+                  for field in ("total", "mean", "p99", "max")]
+    return "\n".join(lines)
+
+
+def main(arguments: list[str]) -> int:
+    if not arguments:
+        print(__doc__.strip(), file=sys.stderr)
+        return 2
+    traces = []
+    for argument in arguments:
+        path = Path(argument)
+        traces.append((path.name, summarize(json.loads(path.read_text()))))
+    print(to_markdown(traces))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

src/graphics/bionic_vulkan_loader_adapter.cc

@@ -17,6 +17,7 @@
 #include <vector>
 
 #include "mocktail/graphics/android_vulkan_wsi_adapter.h"
+#include "mocktail/graphics/chrome_trace_writer.h"
 #include "mocktail/graphics/present_mode_policy.h"
 #include "mocktail/graphics/vulkan_etc2_emulation.h"
 #include "mocktail/graphics/vulkan_text_overlay_compositor.h"
@@ -1011,7 +1012,8 @@ VkResult WaitForSemaphoresObserved(const char* call_name,
     }
     return VK_ERROR_INITIALIZATION_FAILED;
   }
-  static_cast<void>(call_name);
+  mocktail::graphics::TraceScope scope(mocktail::graphics::ActiveProfileTrace(),
+                                       call_name, "wait");
   const VkResult result = host_wait(device, wait_info, timeout);
   if (observation != nullptr) {
     observation->SetResult(result);
@@ -1130,7 +1132,12 @@ ObservedHostQueuePresent(VkQueue queue, const VkPresentInfoKHR* present_info) {
   }
   const bool fps_trace = FpsTraceEnabled();
   const std::uint64_t present_start_ns = fps_trace ? MonotonicNanos() : 0;
-  const VkResult result = host_present(queue, present_info);
+  VkResult result = VK_SUCCESS;
+  {
+    mocktail::graphics::TraceScope scope(
+        mocktail::graphics::ActiveProfileTrace(), "host present", "present");
+    result = host_present(queue, present_info);
+  }
   if (fps_trace) {
     PresentWaitTrace().Record(present_start_ns);
   }
@@ -1142,6 +1149,119 @@ ObservedHostQueuePresent(VkQueue queue, const VkPresentInfoKHR* present_info) {
   return result;
 }
 
+// Samples the time between successive adapter present calls.
+void RecordProfiledFrame(mocktail::graphics::ChromeTraceWriter* trace,
+                         std::uint64_t present_start_ns) {
+  static std::atomic<std::uint64_t> previous_start_ns{0};
+  const std::uint64_t previous =
+      previous_start_ns.exchange(present_start_ns, std::memory_order_relaxed);
+  if (previous != 0 && present_start_ns > previous) {
+    trace->Counter("frame interval (ms)", present_start_ns,
+                   static_cast<double>(present_start_ns - previous) / 1e6);
+  }
+}
+
+// Pipeline and shader creation is wrapped only while profiling, so a normal
+// session calls the host driver directly.
+VkResult VKAPI_CALL ProfiledCreateGraphicsPipelines(
+    VkDevice device, VkPipelineCache cache, std::uint32_t count,
+    const VkGraphicsPipelineCreateInfo* infos,
+    const VkAllocationCallbacks* allocator, VkPipeline* pipelines) {
+  const auto host = reinterpret_cast<PFN_vkCreateGraphicsPipelines>(
+      HostDeviceProc(device, "vkCreateGraphicsPipelines"));
+  if (host == nullptr) {
+    return VK_ERROR_INITIALIZATION_FAILED;
+  }
+  mocktail::graphics::TraceScope scope(mocktail::graphics::ActiveProfileTrace(),
+                                       "vkCreateGraphicsPipelines",
+                                       "pipeline");
+  const VkResult result =
+      host(device, cache, count, infos, allocator, pipelines);
+  scope.Arg("count", count);
+  scope.Arg("cache", cache != VK_NULL_HANDLE);
+  scope.Arg("result", result);
+  return result;
+}
+
+VkResult VKAPI_CALL ProfiledCreateComputePipelines(
+    VkDevice device, VkPipelineCache cache, std::uint32_t count,
+    const VkComputePipelineCreateInfo* infos,
+    const VkAllocationCallbacks* allocator, VkPipeline* pipelines) {
+  const auto host = reinterpret_cast<PFN_vkCreateComputePipelines>(
+      HostDeviceProc(device, "vkCreateComputePipelines"));
+  if (host == nullptr) {
+    return VK_ERROR_INITIALIZATION_FAILED;
+  }
+  mocktail::graphics::TraceScope scope(mocktail::graphics::ActiveProfileTrace(),
+                                       "vkCreateComputePipelines",
+                                       "pipeline");
+  const VkResult result =
+      host(device, cache, count, infos, allocator, pipelines);
+  scope.Arg("count", count);
+  scope.Arg("cache", cache != VK_NULL_HANDLE);
+  scope.Arg("result", result);
+  return result;
+}
+
+VkResult VKAPI_CALL ProfiledCreateShaderModule(
+    VkDevice device, const VkShaderModuleCreateInfo* create_info,
+    const VkAllocationCallbacks* allocator, VkShaderModule* shader_module) {
+  const auto host = reinterpret_cast<PFN_vkCreateShaderModule>(
+      HostDeviceProc(device, "vkCreateShaderModule"));
+  if (host == nullptr) {
+    return VK_ERROR_INITIALIZATION_FAILED;
+  }
+  mocktail::graphics::TraceScope scope(mocktail::graphics::ActiveProfileTrace(),
+                                       "vkCreateShaderModule", "pipeline");
+  const VkResult result = host(device, create_info, allocator, shader_module);
+  scope.Arg("bytes", create_info != nullptr
+                         ? static_cast<std::int64_t>(create_info->codeSize)
+                         : 0);
+  scope.Arg("result", result);
+  return result;
+}
+
+VkResult VKAPI_CALL ProfiledCreatePipelineCache(
+    VkDevice device, const VkPipelineCacheCreateInfo* create_info,
+    const VkAllocationCallbacks* allocator, VkPipelineCache* cache) {
+  const auto host = reinterpret_cast<PFN_vkCreatePipelineCache>(
+      HostDeviceProc(device, "vkCreatePipelineCache"));
+  if (host == nullptr) {
+    return VK_ERROR_INITIALIZATION_FAILED;
+  }
+  mocktail::graphics::TraceScope scope(mocktail::graphics::ActiveProfileTrace(),
+                                       "vkCreatePipelineCache", "pipeline");
+  const VkResult result = host(device, create_info, allocator, cache);
+  scope.Arg("initial_bytes",
+            create_info != nullptr
+                ? static_cast<std::int64_t>(create_info->initialDataSize)
+                : 0);
+  scope.Arg("result", result);
+  return result;
+}
+
+// Null unless profiling is on and `name` is a profiled device command.
+PFN_vkVoidFunction ProfileAdapterProc(const char* name) {
+  if (name == nullptr || mocktail::graphics::ActiveProfileTrace() == nullptr) {
+    return nullptr;
+  }
+  if (std::strcmp(name, "vkCreateGraphicsPipelines") == 0) {
+    return reinterpret_cast<PFN_vkVoidFunction>(
+        ProfiledCreateGraphicsPipelines);
+  }
+  if (std::strcmp(name, "vkCreateComputePipelines") == 0) {
+    return reinterpret_cast<PFN_vkVoidFunction>(
+        ProfiledCreateComputePipelines);
+  }
+  if (std::strcmp(name, "vkCreateShaderModule") == 0) {
+    return reinterpret_cast<PFN_vkVoidFunction>(ProfiledCreateShaderModule);
+  }
+  if (std::strcmp(name, "vkCreatePipelineCache") == 0) {
+    return reinterpret_cast<PFN_vkVoidFunction>(ProfiledCreatePipelineCache);
+  }
+  return nullptr;
+}
+
 template <typename Function>
 Function HostPhysicalDeviceProc(const char* name, const char* alias) {
   VkInstance instance = VK_NULL_HANDLE;
@@ -1397,6 +1517,10 @@ vkGetInstanceProcAddr(VkInstance instance, const char* name) {
                                  vkGetPhysicalDeviceSurfacePresentModesKHR)
                            : nullptr;
   }
+  if (const PFN_vkVoidFunction profiled = ProfileAdapterProc(name);
+      profiled != nullptr) {
+    return HostInstanceProc(instance, name) != nullptr ? profiled : nullptr;
+  }
   if (const PFN_vkVoidFunction adapter = AdapterProc(name);
       adapter != nullptr) {
     if ((IsDeviceAdapterProc(name) || IsEtc2PhysicalDeviceProc(name)) &&
@@ -1418,6 +1542,10 @@ VKAPI_ATTR PFN_vkVoidFunction VKAPI_CALL vkGetDeviceProcAddr(VkDevice device,
   const PFN_vkVoidFunction host = host_get_device_proc_addr != nullptr
                                       ? host_get_device_proc_addr(device, name)
                                       : nullptr;
+  if (const PFN_vkVoidFunction profiled = ProfileAdapterProc(name);
+      profiled != nullptr) {
+    return host != nullptr ? profiled : nullptr;
+  }
   if (!IsDeviceAdapterProc(name)) {
     return host;
   }
@@ -1599,6 +1727,10 @@ vkDestroyDevice(VkDevice device, const VkAllocationCallbacks* allocator) {
     host_destroy(device, allocator);
   }
   RemoveHostDeviceDispatch(device);
+  if (auto* trace = mocktail::graphics::ActiveProfileTrace();
+      trace != nullptr) {
+    trace->Flush();
+  }
 }
 
 VKAPI_ATTR void VKAPI_CALL vkGetDeviceQueue(VkDevice device,
@@ -1754,6 +1886,8 @@ VKAPI_ATTR VkResult VKAPI_CALL vkAcquireNextImageKHR(
     observation.SetResult(VK_ERROR_INITIALIZATION_FAILED);
     return VK_ERROR_INITIALIZATION_FAILED;
   }
+  mocktail::graphics::TraceScope scope(mocktail::graphics::ActiveProfileTrace(),
+                                       "vkAcquireNextImageKHR", "wait");
   const bool fps_trace = FpsTraceEnabled();
   const std::uint64_t acquire_start_ns = fps_trace ? MonotonicNanos() : 0;
   const VkResult host_result = host_acquire(
@@ -1783,6 +1917,8 @@ VKAPI_ATTR VkResult VKAPI_CALL vkAcquireNextImage2KHR(
     observation.SetResult(VK_ERROR_INITIALIZATION_FAILED);
     return VK_ERROR_INITIALIZATION_FAILED;
   }
+  mocktail::graphics::TraceScope scope(mocktail::graphics::ActiveProfileTrace(),
+                                       "vkAcquireNextImage2KHR", "wait");
   const VkResult host_result =
       host_acquire(device, acquire_info, image_index);
   const VkResult result = NormalizeSwapchainResult(host_result);
@@ -1807,6 +1943,8 @@ VKAPI_ATTR VkResult VKAPI_CALL vkWaitForFences(
     observation.SetResult(VK_ERROR_INITIALIZATION_FAILED);
     return VK_ERROR_INITIALIZATION_FAILED;
   }
+  mocktail::graphics::TraceScope scope(mocktail::graphics::ActiveProfileTrace(),
+                                       "vkWaitForFences", "wait");
   const bool fps_trace = FpsTraceEnabled();
   const std::uint64_t fence_start_ns = fps_trace ? MonotonicNanos() : 0;
   const VkResult result =
@@ -2002,6 +2140,9 @@ VKAPI_ATTR VkResult VKAPI_CALL vkQueueSubmit(
     observation.SetResult(VK_ERROR_INITIALIZATION_FAILED);
     return VK_ERROR_INITIALIZATION_FAILED;
   }
+  mocktail::graphics::TraceScope scope(mocktail::graphics::ActiveProfileTrace(),
+                                       "vkQueueSubmit", "submit");
+  scope.Arg("submits", submit_count);
   if (submits != nullptr) {
     for (std::uint32_t index = 0; index < submit_count; ++index) {
       State().etc2.PrepareSubmit(submits[index].pCommandBuffers,
@@ -2024,6 +2165,9 @@ VKAPI_ATTR VkResult VKAPI_CALL vkQueueSubmit2(
     observation.SetResult(VK_ERROR_INITIALIZATION_FAILED);
     return VK_ERROR_INITIALIZATION_FAILED;
   }
+  mocktail::graphics::TraceScope scope(mocktail::graphics::ActiveProfileTrace(),
+                                       "vkQueueSubmit2", "submit");
+  scope.Arg("submits", submit_count);
   PrepareEtc2Submit2(submit_count, submits);
   const VkResult result = State().text_overlay.QueueSubmit2(
       queue, submit_count, submits, fence, host_submit);
@@ -2041,6 +2185,9 @@ VKAPI_ATTR VkResult VKAPI_CALL vkQueueSubmit2KHR(
     observation.SetResult(VK_ERROR_INITIALIZATION_FAILED);
     return VK_ERROR_INITIALIZATION_FAILED;
   }
+  mocktail::graphics::TraceScope scope(mocktail::graphics::ActiveProfileTrace(),
+                                       "vkQueueSubmit2KHR", "submit");
+  scope.Arg("submits", submit_count);
   PrepareEtc2Submit2(submit_count, submits);
   const VkResult result = State().text_overlay.QueueSubmit2(
       queue, submit_count, submits, fence,
@@ -2073,6 +2220,8 @@ VKAPI_ATTR VkResult VKAPI_CALL vkQueueWaitIdle(VkQueue queue) {
     observation.SetResult(VK_ERROR_INITIALIZATION_FAILED);
     return VK_ERROR_INITIALIZATION_FAILED;
   }
+  mocktail::graphics::TraceScope scope(mocktail::graphics::ActiveProfileTrace(),
+                                       "vkQueueWaitIdle", "wait");
   const bool fps_trace = FpsTraceEnabled();
   const std::uint64_t idle_start_ns = fps_trace ? MonotonicNanos() : 0;
   const VkResult result =
@@ -2092,6 +2241,8 @@ VKAPI_ATTR VkResult VKAPI_CALL vkDeviceWaitIdle(VkDevice device) {
     observation.SetResult(VK_ERROR_INITIALIZATION_FAILED);
     return VK_ERROR_INITIALIZATION_FAILED;
   }
+  mocktail::graphics::TraceScope scope(mocktail::graphics::ActiveProfileTrace(),
+                                       "vkDeviceWaitIdle", "wait");
   const VkResult result =
       State().text_overlay.DeviceWaitIdle(device, host_wait);
   observation.SetResult(result);
@@ -2210,8 +2361,15 @@ vkQueuePresentKHR(VkQueue queue, const VkPresentInfoKHR* present_info) {
     observation.SetResult(VK_ERROR_INITIALIZATION_FAILED);
     return VK_ERROR_INITIALIZATION_FAILED;
   }
+  mocktail::graphics::ChromeTraceWriter* const trace =
+      mocktail::graphics::ActiveProfileTrace();
+  mocktail::graphics::TraceScope scope(trace, "vkQueuePresentKHR", "present");
+  if (trace != nullptr) {
+    RecordProfiledFrame(trace, mocktail::graphics::TraceClockNanos());
+  }
   const VkResult result = state.text_overlay.QueuePresent(
       queue, present_info, ObservedHostQueuePresent);
+  scope.Arg("result", result);
   const VkResult normalized_result = NormalizeSwapchainResult(result);
   if (normalized_result == VK_ERROR_OUT_OF_DATE_KHR) {
     const NoteSurfaceOutOfDateFn note_surface_out_of_date =

src/graphics/chrome_trace_writer.cc

@@ -0,0 +1,293 @@
+#include "mocktail/graphics/chrome_trace_writer.h"
+
+#include <sys/types.h>
+#include <time.h>
+#include <unistd.h>
+
+#include <cerrno>
+#include <charconv>
+#include <chrono>
+#include <cmath>
+#include <cstdlib>
+#include <cstring>
+
+namespace mocktail {
+namespace graphics {
+namespace {
+
+// Buffered bytes that wake the writer before its periodic tick.
+constexpr std::size_t kWakeBytes = 256 * 1024;
+constexpr std::chrono::milliseconds kWriteInterval{250};
+// Every write ends the file with this, and the next write starts over it.
+constexpr char kArrayEnd[] = "\n]\n";
+constexpr long kArrayEndBytes = sizeof(kArrayEnd) - 1;
+
+void AppendInteger(std::string* out, std::int64_t value) {
+  char digits[24];
+  const auto [end, error] =
+      std::to_chars(digits, digits + sizeof(digits), value);
+  if (error == std::errc()) {
+    out->append(digits, end);
+  } else {
+    // Appending nothing would leave "ts": with no value, which costs the
+    // whole trace rather than the one field.
+    out->push_back('0');
+  }
+}
+
+void AppendDouble(std::string* out, double value) {
+  // to_chars spells inf and nan without quotes, which no JSON reader accepts.
+  if (!std::isfinite(value)) {
+    out->push_back('0');
+    return;
+  }
+  char digits[32];
+  const auto [end, error] =
+      std::to_chars(digits, digits + sizeof(digits), value);
+  if (error == std::errc()) {
+    out->append(digits, end);
+  } else {
+    out->push_back('0');
+  }
+}
+
+void AppendString(std::string* out, const char* value) {
+  out->push_back('"');
+  for (const char* cursor = value != nullptr ? value : ""; *cursor != '\0';
+       ++cursor) {
+    const unsigned char byte = static_cast<unsigned char>(*cursor);
+    if (byte == '"' || byte == '\\') {
+      out->push_back('\\');
+      out->push_back(static_cast<char>(byte));
+    } else if (byte < 0x20) {
+      static constexpr char kHex[] = "0123456789abcdef";
+      out->append("\\u00");
+      out->push_back(kHex[byte >> 4]);
+      out->push_back(kHex[byte & 0xf]);
+    } else {
+      out->push_back(static_cast<char>(byte));
+    }
+  }
+  out->push_back('"');
+}
+
+void AppendHeader(std::string* out, const char* name, const char* category,
+                  char phase, std::uint64_t timestamp_ns) {
+  static const std::int64_t pid = getpid();
+  thread_local const std::int64_t tid = gettid();
+  out->append("{\"name\":");
+  AppendString(out, name);
+  if (category != nullptr) {
+    out->append(",\"cat\":");
+    AppendString(out, category);
+  }
+  out->append(",\"ph\":\"");
+  out->push_back(phase);
+  out->append("\",\"ts\":");
+  AppendInteger(out, static_cast<std::int64_t>(timestamp_ns / 1000));
+  out->append(",\"pid\":");
+  AppendInteger(out, pid);
+  out->append(",\"tid\":");
+  AppendInteger(out, tid);
+}
+
+std::string& ThreadScratch() {
+  thread_local std::string scratch;
+  scratch.clear();
+  return scratch;
+}
+
+}  // namespace
+
+std::uint64_t TraceClockNanos() {
+  timespec now{};
+  clock_gettime(CLOCK_MONOTONIC, &now);
+  return static_cast<std::uint64_t>(now.tv_sec) * 1'000'000'000ULL +
+         static_cast<std::uint64_t>(now.tv_nsec);
+}
+
+std::unique_ptr<ChromeTraceWriter> ChromeTraceWriter::Open(
+    const std::filesystem::path& path, std::string* error) {
+  std::FILE* file = std::fopen(path.c_str(), "wb");
+  if (file == nullptr || std::fputs("[", file) == EOF ||
+      std::fputs(kArrayEnd, file) == EOF || std::fflush(file) != 0) {
+    const int saved = errno;
+    if (file != nullptr) {
+      std::fclose(file);
+    }
+    if (error != nullptr) {
+      *error = "could not open profile trace " + path.string() + ": " +
+               std::strerror(saved);
+    }
+    return nullptr;
+  }
+  return std::unique_ptr<ChromeTraceWriter>(new ChromeTraceWriter(file));
+}
+
+ChromeTraceWriter::ChromeTraceWriter(std::FILE* file)
+    : file_(file), owner_pid_(getpid()) {
+  writer_ = std::thread([this] { WriterLoop(); });
+}
+
+ChromeTraceWriter::~ChromeTraceWriter() { Close(); }
+
+void ChromeTraceWriter::Slice(const char* name, const char* category,
+                              std::uint64_t start_ns, std::uint64_t end_ns,
+                              std::initializer_list<TraceArg> args) {
+  Slice(name, category, start_ns, end_ns, args.begin(), args.size());
+}
+
+void ChromeTraceWriter::Slice(const char* name, const char* category,
+                              std::uint64_t start_ns, std::uint64_t end_ns,
+                              const TraceArg* args, std::size_t arg_count) {
+  std::string& event = ThreadScratch();
+  AppendHeader(&event, name, category, 'X', start_ns);
+  event.append(",\"dur\":");
+  const std::uint64_t start_us = start_ns / 1000;
+  const std::uint64_t end_us = end_ns / 1000;
+  AppendInteger(&event, static_cast<std::int64_t>(
+                            end_us > start_us ? end_us - start_us : 0));
+  if (args != nullptr && arg_count != 0) {
+    event.append(",\"args\":{");
+    for (std::size_t index = 0; index < arg_count; ++index) {
+      if (index != 0) {
+        event.push_back(',');
+      }
+      AppendString(&event, args[index].key);
+      event.push_back(':');
+      AppendInteger(&event, args[index].value);
+    }
+    event.push_back('}');
+  }
+  event.push_back('}');
+  Append(event.data(), event.size());
+}
+
+void ChromeTraceWriter::Counter(const char* name, std::uint64_t timestamp_ns,
+                                double value) {
+  std::string& event = ThreadScratch();
+  AppendHeader(&event, name, nullptr, 'C', timestamp_ns);
+  event.append(",\"args\":{\"value\":");
+  AppendDouble(&event, value);
+  event.append("}}");
+  Append(event.data(), event.size());
+}
+
+void ChromeTraceWriter::Append(const char* event, std::size_t size) {
+  bool wake = false;
+  {
+    std::lock_guard<std::mutex> lock(mutex_);
+    if (closed_) {
+      return;
+    }
+    pending_.append(first_event_ ? "\n" : ",\n");
+    first_event_ = false;
+    pending_.append(event, size);
+    wake = pending_.size() >= kWakeBytes;
+  }
+  if (wake) {
+    wake_.notify_one();
+  }
+}
+
+void ChromeTraceWriter::WriterLoop() {
+  std::unique_lock<std::mutex> lock(mutex_);
+  while (!stopping_) {
+    wake_.wait_for(lock, kWriteInterval, [this] {
+      return stopping_ || pending_.size() >= kWakeBytes;
+    });
+    if (stopping_) {
+      break;
+    }
+    lock.unlock();
+    WritePending();
+    lock.lock();
+  }
+}
+
+// The file lock is taken before the buffer lock, so chunks reach the file in
+// the order they were buffered.
+void ChromeTraceWriter::WritePending() {
+  std::lock_guard<std::mutex> file_lock(file_mutex_);
+  spare_.clear();
+  {
+    std::lock_guard<std::mutex> lock(mutex_);
+    pending_.swap(spare_);
+  }
+  if (file_ == nullptr || spare_.empty()) {
+    return;
+  }
+  if (std::fseek(file_, -kArrayEndBytes, SEEK_END) != 0 ||
+      std::fwrite(spare_.data(), 1, spare_.size(), file_) != spare_.size() ||
+      std::fputs(kArrayEnd, file_) == EOF || std::fflush(file_) != 0) {
+    std::fprintf(stderr, "  [profile] trace write failed: %s\n",
+                 std::strerror(errno));
+    std::fclose(file_);
+    file_ = nullptr;
+    {
+      std::lock_guard<std::mutex> lock(mutex_);
+      closed_ = true;
+      // Nothing can reach the file now, so the writer thread exits instead of
+      // ticking for the rest of the process.
+      stopping_ = true;
+    }
+    wake_.notify_all();
+  }
+}
+
+void ChromeTraceWriter::Flush() { WritePending(); }
+
+void ChromeTraceWriter::Close() {
+  // A forked child shares the file but not the writer thread.
+  if (getpid() != owner_pid_) {
+    return;
+  }
+  // A write failure sets stopping_ without joining the thread, so the join
+  // below runs even when stopping_ is already set.
+  {
+    std::lock_guard<std::mutex> lock(mutex_);
+    stopping_ = true;
+  }
+  wake_.notify_all();
+  if (writer_.joinable() && writer_.get_id() != std::this_thread::get_id()) {
+    writer_.join();
+  }
+  WritePending();
+  std::lock_guard<std::mutex> file_lock(file_mutex_);
+  {
+    std::lock_guard<std::mutex> lock(mutex_);
+    closed_ = true;
+  }
+  if (file_ != nullptr) {
+    std::fclose(file_);
+    file_ = nullptr;
+  }
+}
+
+ChromeTraceWriter* ActiveProfileTrace() {
+  static ChromeTraceWriter* const trace = []() -> ChromeTraceWriter* {
+    const char* path = std::getenv(kProfileTraceEnvironment);
+    if (path == nullptr || path[0] == '\0') {
+      return nullptr;
+    }
+    std::string error;
+    std::unique_ptr<ChromeTraceWriter> writer =
+        ChromeTraceWriter::Open(path, &error);
+    if (writer == nullptr) {
+      std::fprintf(stderr, "  [profile] %s\n", error.c_str());
+      return nullptr;
+    }
+    std::fprintf(stderr, "  [profile] writing Chrome trace to %s\n", path);
+    // Leaked so threads still recording during exit never touch a destroyed
+    // writer; they find it closed instead.
+    static struct CloseAtExit {
+      ChromeTraceWriter* writer;
+      ~CloseAtExit() { writer->Close(); }
+    } close_at_exit{writer.get()};
+    return writer.release();
+  }();
+  return trace;
+}
+
+}  // namespace graphics
+}  // namespace mocktail

src/graphics/etc2_decoder.cc

@@ -5,7 +5,9 @@
 #include <pthread.h>
 
 #include <atomic>
+#include <condition_variable>
 #include <limits>
+#include <mutex>
 #include <vector>
 
 namespace mocktail::graphics {
@@ -213,10 +215,11 @@ std::size_t EtcDecodedTexelBytes(EtcFormat format) {
 
 namespace {
 
-// Blocks per band handed to one worker: about a 256x256 texel image.
-constexpr std::uint64_t kBlocksPerBand = 16384;
-// Batches smaller than a 1024x1024 texel image decode on the caller.
-constexpr std::uint64_t kParallelMinimumBlocks = 65536;
+// Blocks per band handed to one worker: about a 128x128 texel image.
+constexpr std::uint64_t kBlocksPerBand = 4096;
+// Batches smaller than a 128x128 texel image decode on the caller. Waking a
+// pooled worker costs microseconds, so the floor only has to cover that.
+constexpr std::uint64_t kParallelMinimumBlocks = 4096;
 
 bool ImageFits(EtcFormat format, const std::uint8_t* source,
                std::size_t source_bytes, std::uint32_t width,
@@ -274,10 +277,97 @@ struct DecodeBandQueue {
   }
 };
 
-void* RunDecodeBandQueue(void* queue) {
-  static_cast<DecodeBandQueue*>(queue)->Run();
-  return nullptr;
-}
+// Decode workers outlive the batches that use them: creating and joining a
+// thread per batch costs more than decoding a small one. The threads park on
+// a condition variable and are never joined, so the pool is leaked at exit.
+class DecodePool {
+ public:
+  static DecodePool& Instance() {
+    static DecodePool* pool = new DecodePool();
+    return *pool;
+  }
+
+  // Calls run(context) on the calling thread and on pooled workers, `workers`
+  // calls in all. Returns false without calling it when another batch
+  // already holds the pool or no worker could be started, leaving the whole
+  // batch to the caller.
+  bool Run(void (*run)(void*), void* context, std::size_t workers) {
+    if (workers < 2) {
+      return false;
+    }
+    std::unique_lock<std::mutex> batch(batch_mutex_, std::try_to_lock);
+    if (!batch.owns_lock()) {
+      return false;
+    }
+    const std::size_t helpers = Reserve(workers - 1);
+    if (helpers == 0) {
+      return false;
+    }
+    {
+      std::lock_guard<std::mutex> lock(mutex_);
+      run_ = run;
+      context_ = context;
+      unclaimed_ = helpers;
+      running_ = helpers;
+    }
+    ready_.notify_all();
+    run(context);
+    std::unique_lock<std::mutex> lock(mutex_);
+    done_.wait(lock, [this] { return running_ == 0; });
+    run_ = nullptr;
+    context_ = nullptr;
+    return true;
+  }
+
+ private:
+  DecodePool() = default;
+
+  // Grows the pool towards `wanted` and reports how many workers exist, so a
+  // pthread_create failure degrades instead of deadlocking the wait below.
+  std::size_t Reserve(std::size_t wanted) {
+    std::lock_guard<std::mutex> lock(mutex_);
+    while (threads_ < wanted) {
+      pthread_t worker;
+      if (pthread_create(&worker, nullptr, &DecodePool::RunWorker, this) != 0) {
+        break;
+      }
+      pthread_detach(worker);
+      ++threads_;
+    }
+    return std::min(threads_, wanted);
+  }
+
+  static void* RunWorker(void* pool) {
+    static_cast<DecodePool*>(pool)->WorkerLoop();
+    return nullptr;
+  }
+
+  void WorkerLoop() {
+    std::unique_lock<std::mutex> lock(mutex_);
+    for (;;) {
+      ready_.wait(lock, [this] { return unclaimed_ > 0; });
+      --unclaimed_;
+      void (*run)(void*) = run_;
+      void* context = context_;
+      lock.unlock();
+      run(context);
+      lock.lock();
+      if (--running_ == 0) {
+        done_.notify_all();
+      }
+    }
+  }
+
+  std::mutex batch_mutex_;
+  std::mutex mutex_;
+  std::condition_variable ready_;
+  std::condition_variable done_;
+  void (*run_)(void*) = nullptr;
+  void* context_ = nullptr;
+  std::size_t unclaimed_ = 0;
+  std::size_t running_ = 0;
+  std::size_t threads_ = 0;
+};
 
 }  // namespace
 
@@ -311,19 +401,20 @@ void DecodeEtcJobs(EtcDecodeJob* jobs, std::size_t count,
       total_blocks < kParallelMinimumBlocks
           ? 1
           : std::min<std::size_t>(std::max(worker_count, 1U), bands.size());
-  std::vector<pthread_t> workers;
-  workers.reserve(threads > 0 ? threads - 1 : 0);
-  for (std::size_t index = 1; index < threads; ++index) {
-    pthread_t worker;
-    // The caller decodes whatever workers that failed to start leave behind.
-    if (pthread_create(&worker, nullptr, RunDecodeBandQueue, &queue) != 0) {
-      break;
-    }
-    workers.push_back(worker);
+  RunOnDecodeWorkers(
+      [](void* context) { static_cast<DecodeBandQueue*>(context)->Run(); },
+      &queue, static_cast<unsigned>(threads));
+}
+
+void RunOnDecodeWorkers(void (*run)(void*), void* context,
+                        unsigned worker_count) {
+  if (run == nullptr) {
+    return;
   }
-  queue.Run();
-  for (pthread_t worker : workers) {
-    pthread_join(worker, nullptr);
+  // The pool declines when it is already busy; the caller drains the whole
+  // batch itself then, exactly as a single-threaded batch does.
+  if (!DecodePool::Instance().Run(run, context, worker_count)) {
+    run(context);
   }
 }
 

src/graphics/texture_override.cc

@@ -2,6 +2,7 @@
 
 #include <png.h>
 
+#include <algorithm>
 #include <cstdio>
 #include <cstdlib>
 #include <cstring>
@@ -82,6 +83,23 @@ void ResampleRgba(const std::uint8_t* source, std::uint32_t source_width,
       height == 0 || source_width == 0 || source_height == 0) {
     return;
   }
+  // Source box of destination column x is [columns[2x], columns[2x + 1]).
+  thread_local std::vector<std::uint32_t> columns;
+  columns.resize(static_cast<std::size_t>(width) * 2);
+  bool one_texel_columns = true;
+  for (std::uint32_t x = 0; x < width; ++x) {
+    const std::uint32_t x0 = static_cast<std::uint32_t>(
+        static_cast<std::uint64_t>(x) * source_width / width);
+    const std::uint32_t x1 = std::max<std::uint32_t>(
+        x0 + 1, static_cast<std::uint32_t>(
+                    (static_cast<std::uint64_t>(x) + 1) * source_width / width));
+    columns[2 * static_cast<std::size_t>(x)] = x0;
+    columns[2 * static_cast<std::size_t>(x) + 1] = x1;
+    one_texel_columns = one_texel_columns && x1 == x0 + 1;
+  }
+  const std::size_t row_bytes = static_cast<std::size_t>(width) * 4;
+  std::uint64_t previous_y0 = 0;
+  std::uint64_t previous_y1 = 0;
   for (std::uint32_t y = 0; y < height; ++y) {
     const std::uint64_t y0 = static_cast<std::uint64_t>(y) * source_height / height;
     std::uint64_t y1 =
@@ -89,13 +107,25 @@ void ResampleRgba(const std::uint8_t* source, std::uint32_t source_width,
     if (y1 <= y0) {
       y1 = y0 + 1;
     }
-    for (std::uint32_t x = 0; x < width; ++x) {
-      const std::uint64_t x0 = static_cast<std::uint64_t>(x) * source_width / width;
-      std::uint64_t x1 =
-          (static_cast<std::uint64_t>(x) + 1) * source_width / width;
-      if (x1 <= x0) {
-        x1 = x0 + 1;
+    std::uint8_t* out_row = destination + y * row_bytes;
+    if (y > 0 && y0 == previous_y0 && y1 == previous_y1) {
+      std::memcpy(out_row, out_row - row_bytes, row_bytes);
+      continue;
+    }
+    previous_y0 = y0;
+    previous_y1 = y1;
+    if (one_texel_columns && y1 == y0 + 1) {
+      const std::uint8_t* source_row = source + y0 * source_width * 4;
+      for (std::uint32_t x = 0; x < width; ++x) {
+        std::memcpy(out_row + static_cast<std::size_t>(x) * 4,
+                    source_row + columns[2 * static_cast<std::size_t>(x)] * 4,
+                    4);
       }
+      continue;
+    }
+    for (std::uint32_t x = 0; x < width; ++x) {
+      const std::uint64_t x0 = columns[2 * static_cast<std::size_t>(x)];
+      const std::uint64_t x1 = columns[2 * static_cast<std::size_t>(x) + 1];
       std::uint64_t sum[4] = {0, 0, 0, 0};
       for (std::uint64_t sy = y0; sy < y1; ++sy) {
         for (std::uint64_t sx = x0; sx < x1; ++sx) {

src/graphics/vulkan_etc2_emulation.cc

@@ -1,8 +1,10 @@
 #include "mocktail/graphics/vulkan_etc2_emulation.h"
 
+#include "mocktail/graphics/chrome_trace_writer.h"
 #include "mocktail/graphics/texture_override.h"
 
 #include <algorithm>
+
 #include <atomic>
 #include <cstdio>
 #include <cstdlib>
@@ -199,18 +201,36 @@ bool IsColorFormat(EtcFormat format) {
          format == EtcFormat::kEtc2Rgba8;
 }
 
+// A host-visible transfer buffer that stays mapped for its whole life.
 struct Staging {
   VkDevice device = VK_NULL_HANDLE;
   VkBuffer buffer = VK_NULL_HANDLE;
   VkDeviceMemory memory = VK_NULL_HANDLE;
+  VkDeviceSize capacity = 0;
+  std::uint8_t* mapped = nullptr;
 };
 
+// Idle staging buffers kept for reuse. Creating, allocating, binding and
+// mapping one costs hundreds of microseconds in the driver, so a burst of
+// texture uploads would otherwise stall the frame that records it.
+constexpr VkDeviceSize kMaxIdleStagingBytes = 64 * 1024 * 1024;
+constexpr std::size_t kMaxIdleStagingBuffers = 64;
+// A request may take an idle buffer up to this size, or up to 4x its own
+// size when larger, so small uploads share buffers without pinning big ones.
+constexpr VkDeviceSize kStagingReuseSlack = 64 * 1024;
+
 struct PendingUpload {
   VkDevice device = VK_NULL_HANDLE;
   VkBuffer source = VK_NULL_HANDLE;
   VkDeviceSize source_offset = 0;
   VkDeviceSize compressed = 0;
   VkDeviceSize decoded = 0;
+  // Source pitch in bytes from bufferRowLength/bufferImageHeight, and the
+  // bytes the region spans from `source_offset` including that padding.
+  // `compressed` stays the packed size the decoder consumes.
+  VkDeviceSize source_row_stride = 0;
+  VkDeviceSize source_layer_stride = 0;
+  VkDeviceSize source_span = 0;
   VkDeviceSize target_offset = 0;
   EtcFormat format = EtcFormat::kEtc2Rgb8;
   VkImage image = VK_NULL_HANDLE;
@@ -251,6 +271,7 @@ void LogFailure(const char* message) {
 
 bool CreateStaging(const HostDevice& dev, VkDeviceSize size, Staging* staging,
                    std::uint8_t** mapped) {
+  *mapped = nullptr;
   if (dev.create_buffer == nullptr || dev.allocate_memory == nullptr ||
       dev.get_buffer_memory_requirements == nullptr ||
       dev.bind_buffer_memory == nullptr || dev.map_memory == nullptr ||
@@ -300,8 +321,8 @@ bool CreateStaging(const HostDevice& dev, VkDeviceSize size, Staging* staging,
     dev.free_memory(dev.device, memory, nullptr);
     return false;
   }
-  *staging = {dev.device, buffer, memory};
   *mapped = static_cast<std::uint8_t*>(data);
+  *staging = {dev.device, buffer, memory, size, *mapped};
   return true;
 }
 
@@ -408,6 +429,25 @@ bool PlanRegions(const ImageRecord& record, VkDevice device, VkBuffer source,
     upload.target_width = upload.width;
     upload.target_height = upload.height;
     upload.target_bytes = upload.decoded;
+    const VkDeviceSize row_texels =
+        region.bufferRowLength != 0 ? region.bufferRowLength : upload.width;
+    const VkDeviceSize layer_rows =
+        region.bufferImageHeight != 0 ? region.bufferImageHeight
+                                      : upload.height;
+    if (row_texels < upload.width || layer_rows < upload.height) {
+      return false;
+    }
+    const VkDeviceSize block_bytes = EtcBlockBytes(record.format.etc_format);
+    const VkDeviceSize block_rows =
+        (static_cast<VkDeviceSize>(upload.height) + 3) / 4;
+    const VkDeviceSize packed_row =
+        ((static_cast<VkDeviceSize>(upload.width) + 3) / 4) * block_bytes;
+    upload.source_row_stride = ((row_texels + 3) / 4) * block_bytes;
+    upload.source_layer_stride =
+        upload.source_row_stride * ((layer_rows + 3) / 4);
+    upload.source_span = (upload.layers - 1) * upload.source_layer_stride +
+                         (block_rows - 1) * upload.source_row_stride +
+                         packed_row;
     Region copy = region;
     copy.bufferOffset = *total;
     copy.bufferRowLength = 0;
@@ -465,6 +505,8 @@ struct VulkanEtc2Emulation::State {
   std::unordered_map<VkDeviceMemory, Mapping> mappings;
   std::unordered_map<VkCommandBuffer, CommandRecord> commands;
   std::atomic<bool> has_commands{false};
+  std::vector<Staging> idle_staging;
+  VkDeviceSize idle_staging_bytes = 0;
   // Heap buffers reused across submits; they only grow.
   std::mutex scratch_mutex;
   std::vector<std::uint8_t> scratch_source;
@@ -562,6 +604,109 @@ struct VulkanEtc2Emulation::State {
     }
   }
 
+  struct EmitJob {
+    const PendingUpload* upload = nullptr;
+    const std::uint8_t* compressed = nullptr;
+    const std::uint8_t* decoded = nullptr;
+  };
+
+  struct EmitQueue {
+    State* state = nullptr;
+    std::vector<EmitJob> jobs;
+    std::atomic<std::size_t> next{0};
+
+    void Run() {
+      for (;;) {
+        const std::size_t index = next.fetch_add(1, std::memory_order_relaxed);
+        if (index >= jobs.size()) {
+          return;
+        }
+        const EmitJob& job = jobs[index];
+        state->EmitUpload(*job.upload, job.compressed, job.decoded);
+      }
+    }
+  };
+
+  // Resampling a batch costs sixteen times the decoded texels at the default
+  // upscale, so uploads are emitted across the decode worker pool. They write
+  // disjoint staging ranges, and level 0 is emitted before the rest because it
+  // publishes the texels the other mips resample from.
+  void EmitBatch(std::vector<EmitJob> jobs, unsigned worker_count) {
+    if (jobs.empty()) {
+      return;
+    }
+    std::vector<EmitJob> level_zero;
+    std::vector<EmitJob> rest;
+    for (const EmitJob& job : jobs) {
+      (job.upload->mip_level == 0 ? level_zero : rest).push_back(job);
+    }
+    EmitPass(std::move(level_zero), worker_count);
+    EmitPass(std::move(rest), worker_count);
+  }
+
+  void EmitPass(std::vector<EmitJob> jobs, unsigned worker_count) {
+    if (jobs.empty()) {
+      return;
+    }
+    EmitQueue queue;
+    queue.state = this;
+    queue.jobs = std::move(jobs);
+    const std::size_t threads =
+        std::min<std::size_t>(std::max(worker_count, 1U), queue.jobs.size());
+    RunOnDecodeWorkers(
+        [](void* context) { static_cast<EmitQueue*>(context)->Run(); }, &queue,
+        static_cast<unsigned>(threads));
+  }
+
+  // Takes the smallest idle buffer that fits, or creates one.
+  bool AcquireStaging(const HostDevice& dev, VkDeviceSize size,
+                      Staging* staging) {
+    {
+      std::lock_guard<std::mutex> lock(mutex);
+      const VkDeviceSize limit = std::max(size * 4, kStagingReuseSlack);
+      auto best = idle_staging.end();
+      for (auto it = idle_staging.begin(); it != idle_staging.end(); ++it) {
+        if (it->device == dev.device && it->capacity >= size &&
+            it->capacity <= limit &&
+            (best == idle_staging.end() || it->capacity < best->capacity)) {
+          best = it;
+        }
+      }
+      if (best != idle_staging.end()) {
+        *staging = *best;
+        idle_staging_bytes -= best->capacity;
+        *best = idle_staging.back();
+        idle_staging.pop_back();
+        return true;
+      }
+    }
+    std::uint8_t* mapped = nullptr;
+    return CreateStaging(dev, size, staging, &mapped);
+  }
+
+  // Keeps released buffers for reuse up to the idle limits and destroys
+  // the rest.
+  void ReleaseStaging(std::vector<Staging> released) {
+    std::vector<Staging> doomed;
+    {
+      std::lock_guard<std::mutex> lock(mutex);
+      for (const Staging& staging : released) {
+        if (idle_staging.size() < kMaxIdleStagingBuffers &&
+            idle_staging_bytes + staging.capacity <= kMaxIdleStagingBytes) {
+          idle_staging.push_back(staging);
+          idle_staging_bytes += staging.capacity;
+        } else {
+          doomed.push_back(staging);
+        }
+      }
+    }
+    for (const Staging& staging : doomed) {
+      if (const HostDevice* dev = Find(staging.device); dev != nullptr) {
+        DestroyStaging(*dev, staging);
+      }
+    }
+  }
+
   const HostDevice* Find(VkDevice device) {
     std::lock_guard<std::mutex> lock(devices_mutex);
     for (const auto& candidate : devices) {
@@ -707,6 +852,16 @@ void VulkanEtc2Emulation::DestroyDevice(VkDevice device) {
         ++it;
       }
     }
+    for (auto it = state_->idle_staging.begin();
+         it != state_->idle_staging.end();) {
+      if (it->device == device) {
+        state_->idle_staging_bytes -= it->capacity;
+        doomed.push_back(*it);
+        it = state_->idle_staging.erase(it);
+      } else {
+        ++it;
+      }
+    }
     for (auto it = state_->images.begin(); it != state_->images.end();) {
       it = it->second.device == device ? state_->images.erase(it) : std::next(it);
     }
@@ -943,18 +1098,17 @@ void VulkanEtc2Emulation::CmdCopyBufferToImage(
   std::vector<PendingUpload> uploads;
   VkDeviceSize total = 0;
   Staging staging;
-  std::uint8_t* mapped = nullptr;
   if (!PlanRegions(record, device, source, destination, region_count, regions,
                    &rewritten, &uploads, &total)) {
     LogFailure("skipped an upload with an unsupported region");
     return;
   }
-  if (!CreateStaging(*dev, total, &staging, &mapped)) {
+  if (!state_->AcquireStaging(*dev, total, &staging)) {
     LogFailure("could not allocate a host-visible staging buffer");
     return;
   }
   for (PendingUpload& upload : uploads) {
-    upload.target = mapped + upload.target_offset;
+    upload.target = staging.mapped + upload.target_offset;
   }
   state_->Record(command_buffer, std::move(uploads), staging);
   dev->copy_buffer_to_image(command_buffer, staging.buffer, destination,
@@ -978,19 +1132,18 @@ void VulkanEtc2Emulation::CmdCopyBufferToImage2(
   std::vector<PendingUpload> uploads;
   VkDeviceSize total = 0;
   Staging staging;
-  std::uint8_t* mapped = nullptr;
   if (!PlanRegions(record, device, info->srcBuffer, info->dstImage,
                    info->regionCount, info->pRegions, &rewritten, &uploads,
                    &total)) {
     LogFailure("skipped an upload with an unsupported region");
     return;
   }
-  if (!CreateStaging(*dev, total, &staging, &mapped)) {
+  if (!state_->AcquireStaging(*dev, total, &staging)) {
     LogFailure("could not allocate a host-visible staging buffer");
     return;
   }
   for (PendingUpload& upload : uploads) {
-    upload.target = mapped + upload.target_offset;
+    upload.target = staging.mapped + upload.target_offset;
   }
   state_->Record(command_buffer, std::move(uploads), staging);
   VkCopyBufferToImageInfo2 host_info = *info;
@@ -1146,9 +1299,9 @@ void VulkanEtc2Emulation::PrepareSubmit(const VkCommandBuffer* command_buffers,
                    (mapping->second.size == VK_WHOLE_SIZE ||
                     (absolute - mapping->second.offset <=
                          mapping->second.size &&
-                     upload.compressed <= mapping->second.size -
-                                              (absolute -
-                                               mapping->second.offset)))) {
+                     upload.source_span <= mapping->second.size -
+                                               (absolute -
+                                                mapping->second.offset)))) {
           item.source = static_cast<std::uint8_t*>(mapping->second.data) +
                         (absolute - mapping->second.offset);
         } else {
@@ -1170,6 +1323,8 @@ void VulkanEtc2Emulation::PrepareSubmit(const VkCommandBuffer* command_buffers,
       }
     }
   }
+  TraceScope trace_scope(work.empty() ? nullptr : ActiveProfileTrace(),
+                         "etc2 decode", "texture");
   // Mapped Vulkan memory is uncached or write-combined, which makes the
   // decoder's scattered byte reads and writes tens of times slower than on
   // heap memory. Compressed bytes are streamed into a heap scratch buffer,
@@ -1217,6 +1372,10 @@ void VulkanEtc2Emulation::PrepareSubmit(const VkCommandBuffer* command_buffers,
     compressed_total += upload.compressed;
     decoded_total += upload.decoded;
   }
+  trace_scope.Arg("uploads", static_cast<std::int64_t>(copies.size()));
+  trace_scope.Arg("compressed_bytes",
+                  static_cast<std::int64_t>(compressed_total));
+  trace_scope.Arg("decoded_bytes", static_cast<std::int64_t>(decoded_total));
 
   std::lock_guard<std::mutex> scratch_lock(state_->scratch_mutex);
   std::vector<std::uint8_t>& scratch_source = state_->scratch_source;
@@ -1235,8 +1394,24 @@ void VulkanEtc2Emulation::PrepareSubmit(const VkCommandBuffer* command_buffers,
     const PendingUpload& upload = *copied_uploads[index];
     std::uint8_t* source = scratch_source.data() + compressed_offset;
     std::uint8_t* decoded = scratch_decoded.data() + decoded_offset;
-    std::memcpy(source, copy.source, copy.compressed);
     const VkDeviceSize compressed_layer = upload.compressed / upload.layers;
+    if (upload.source_span == copy.compressed) {
+      std::memcpy(source, copy.source, copy.compressed);
+    } else {
+      // Padded rows: gather the covered blocks into the packed layout the
+      // decoder expects.
+      const VkDeviceSize block_rows =
+          (static_cast<VkDeviceSize>(upload.height) + 3) / 4;
+      const VkDeviceSize packed_row = compressed_layer / block_rows;
+      for (std::uint32_t layer = 0; layer < upload.layers; ++layer) {
+        for (VkDeviceSize row = 0; row < block_rows; ++row) {
+          std::memcpy(source + layer * compressed_layer + row * packed_row,
+                      copy.source + layer * upload.source_layer_stride +
+                          row * upload.source_row_stride,
+                      packed_row);
+        }
+      }
+    }
     const VkDeviceSize decoded_layer = upload.decoded / upload.layers;
     for (std::uint32_t layer = 0; layer < upload.layers; ++layer) {
       EtcDecodeJob job;
@@ -1270,12 +1445,15 @@ void VulkanEtc2Emulation::PrepareSubmit(const VkCommandBuffer* command_buffers,
   }
   compressed_offset = 0;
   decoded_offset = 0;
+  std::vector<State::EmitJob> emit_jobs;
+  emit_jobs.reserve(copied_uploads.size());
   for (const PendingUpload* upload : copied_uploads) {
-    state_->EmitUpload(*upload, scratch_source.data() + compressed_offset,
-                       scratch_decoded.data() + decoded_offset);
+    emit_jobs.push_back({upload, scratch_source.data() + compressed_offset,
+                         scratch_decoded.data() + decoded_offset});
     compressed_offset += upload->compressed;
     decoded_offset += upload->decoded;
   }
+  state_->EmitBatch(std::move(emit_jobs), DecodeWorkerCount());
 }
 
 void VulkanEtc2Emulation::ReleaseCommandBuffer(VkCommandBuffer command_buffer) {
@@ -1294,11 +1472,7 @@ void VulkanEtc2Emulation::ReleaseCommandBuffer(VkCommandBuffer command_buffer) {
     state_->has_commands.store(!state_->commands.empty(),
                                std::memory_order_release);
   }
-  for (const Staging& staging : doomed) {
-    if (const HostDevice* dev = state_->Find(staging.device); dev != nullptr) {
-      DestroyStaging(*dev, staging);
-    }
-  }
+  state_->ReleaseStaging(std::move(doomed));
 }
 
 }  // namespace mocktail::graphics

src/jnivm/jnivm.cc

@@ -62,7 +62,10 @@ thread_local JNIEnv* g_thread_local_env = nullptr;
 thread_local JNIEnv g_thread_env_storage = {};
 thread_local VM* g_thread_vm_instance = nullptr;
 thread_local mocktail::audio::FmodThreadFloatingPointMode g_thread_audio_fp_mode;
-thread_local std::vector<std::vector<jobject>> g_local_frames;
+// Each frame counts how many local references it holds per handle, so
+// DeleteLocalRef costs one hash lookup per open frame.
+using LocalFrame = std::unordered_map<jobject, uint32_t>;
+thread_local std::vector<LocalFrame> g_local_frames;
 
 std::recursive_mutex g_jni_state_mutex;
 // Authentication preflight can briefly own a second VM. Keep every live
@@ -289,6 +292,10 @@ constexpr uint32_t kJniHandleShift = 16;
 std::shared_ptr<void> g_segment_owners[kJniSegmentCapacity];
 std::unordered_set<jclass> g_known_classes;
 std::unordered_map<std::string, jobject> g_singleton_objects;
+std::unordered_set<jobject> g_singleton_handles;
+// One handle per Class. Class slots are never freed, so the table holds at
+// most one slot per distinct class.
+std::unordered_map<const Class*, jclass> g_class_handles;
 std::unordered_map<std::string, std::shared_ptr<Class>> g_fallback_classes;
 std::unordered_set<jstring> g_known_strings;
 std::list<std::string> g_method_name_storage;
@@ -339,7 +346,7 @@ void RegisterLocalRef(jobject obj) {
     return;
   }
   EnsureLocalFrame();
-  g_local_frames.back().push_back(obj);
+  ++g_local_frames.back()[obj];
 }
 
 void UnregisterLocalRef(jobject obj) {
@@ -348,10 +355,27 @@ void UnregisterLocalRef(jobject obj) {
   }
   for (auto frame = g_local_frames.rbegin(); frame != g_local_frames.rend();
        ++frame) {
-    for (auto it = frame->rbegin(); it != frame->rend(); ++it) {
-      if (*it == obj) {
-        frame->erase(std::next(it).base());
-        return;
+    auto it = frame->find(obj);
+    if (it != frame->end()) {
+      if (--it->second == 0) {
+        frame->erase(it);
+      }
+      return;
+    }
+  }
+}
+
+void ReleaseJniReference(jobject obj);
+
+// A detached thread can no longer use its local references, so they go the
+// way ART drops them on detach.
+void ReleaseThreadLocalRefs() {
+  std::vector<LocalFrame> frames = std::move(g_local_frames);
+  g_local_frames.clear();
+  for (const LocalFrame& frame : frames) {
+    for (const auto& [obj, count] : frame) {
+      for (uint32_t i = 0; i < count; ++i) {
+        ReleaseJniReference(obj);
       }
     }
   }
@@ -370,6 +394,8 @@ void RetainJniReference(jobject obj) {
   }
 }
 
+void ReportHandleTableFull();
+
 int AllocateSegmentSlot(void* value, std::shared_ptr<void> owner = nullptr,
                         SegmentType type = SegmentType::kObject) {
   std::lock_guard<std::recursive_mutex> lock(g_jni_state_mutex);
@@ -381,6 +407,7 @@ int AllocateSegmentSlot(void* value, std::shared_ptr<void> owner = nullptr,
              static_cast<uint32_t>(g_jni_ref_index) < kJniSegmentCapacity) {
     index = g_jni_ref_index++;
   } else {
+    ReportHandleTableFull();
     return 0;
   }
   my_segment[index] = value;
@@ -739,6 +766,13 @@ std::shared_ptr<Class> ClassFromJClass(jclass clazz) {
 static jclass StoreClass(std::shared_ptr<Class> cls) {
   std::lock_guard<std::recursive_mutex> lock(g_jni_state_mutex);
   Class* raw_ptr = cls.get();
+  if (raw_ptr == nullptr) {
+    return nullptr;
+  }
+  auto cached = g_class_handles.find(raw_ptr);
+  if (cached != g_class_handles.end()) {
+    return cached->second;
+  }
   int index = AllocateSegmentSlot(raw_ptr, cls, SegmentType::kClass);
   if (index <= 0) {
     return nullptr;
@@ -746,6 +780,7 @@ static jclass StoreClass(std::shared_ptr<Class> cls) {
   jclass handle =
       reinterpret_cast<jclass>(JniHandleFromIndex(static_cast<uint32_t>(index)));
   g_known_classes.insert(handle);
+  g_class_handles.emplace(raw_ptr, handle);
   return handle;
 }
 
@@ -790,10 +825,8 @@ void ReleaseJniReference(jobject obj) {
       g_known_classes.end()) {
     return;
   }
-  for (const auto& pair : g_singleton_objects) {
-    if (pair.second == obj) {
-      return;
-    }
+  if (g_singleton_handles.count(obj) != 0) {
+    return;
   }
   const uint32_t index = JniIndexFromHandle(obj);
   if (index > 0 && index < kJniSegmentCapacity) {
@@ -850,6 +883,7 @@ jobject SingletonObject(const std::string& class_name) {
   }
   jobject object = MakeObjectForClass(class_name);
   g_singleton_objects[class_name] = object;
+  g_singleton_handles.insert(object);
   return object;
 }
 
@@ -861,6 +895,38 @@ std::string_view ObjectClassName(jobject obj) {
   return pseudo_object->GetClass()->GetName();
 }
 
+// Logs once per process which classes hold the live handles, so the leak
+// behind a later null FindClass or NewStringUTF can be named.
+void ReportHandleTableFull() {
+  std::lock_guard<std::recursive_mutex> lock(g_jni_state_mutex);
+  static bool reported = false;
+  if (reported) {
+    return;
+  }
+  reported = true;
+  std::unordered_map<std::string_view, std::size_t> live_by_class;
+  for (const auto& entry : g_object_storage) {
+    std::string_view name = ObjectClassName(entry.first);
+    ++live_by_class[name.empty() ? std::string_view("<unknown>") : name];
+  }
+  std::vector<std::pair<std::string_view, std::size_t>> ranked(
+      live_by_class.begin(), live_by_class.end());
+  const std::size_t shown = std::min<std::size_t>(ranked.size(), 10);
+  std::partial_sort(ranked.begin(), ranked.begin() + shown, ranked.end(),
+                    [](const auto& a, const auto& b) {
+                      return a.second > b.second;
+                    });
+  fprintf(stderr,
+          "[JNI] handle table full (%u slots): %zu objects, %zu classes, "
+          "%zu arrays live; new objects return null\n",
+          kJniSegmentCapacity, g_object_storage.size(),
+          g_class_handles.size(), g_array_storage.size());
+  for (std::size_t i = 0; i < shown; ++i) {
+    fprintf(stderr, "[JNI]   %zu x %.*s\n", ranked[i].second,
+            static_cast<int>(ranked[i].first.size()), ranked[i].first.data());
+  }
+}
+
 jobject ExactMessageBusStaticObject(jclass clazz, jmethodID method_id) {
   const std::shared_ptr<Class> object_class = ClassFromJClass(clazz);
   if (object_class == nullptr ||
@@ -881,6 +947,8 @@ jobject EngineJavaCallbackObject() {
   }
   g_engine_java_callback =
       MakeObjectForClass("com/roblox/engine/jni/EngineJavaCallback2");
+  // VM-owned like a singleton, so detaching the creating thread keeps it.
+  g_singleton_handles.insert(g_engine_java_callback);
   g_static_object_fields["sImplementation"] = g_engine_java_callback;
   return g_engine_java_callback;
 }
@@ -1149,7 +1217,7 @@ static inline bool IsRawStringPointer(jstring str) {
   if (val < 0x10000) {
     return false;
   }
-  if (val < 0x10000000ULL && (val & 0xffff) == 0) {
+  if ((val & 0xffff) == 0 && (val >> kJniHandleShift) < kJniSegmentCapacity) {
     return false;
   }
   return true;
@@ -2230,10 +2298,9 @@ bool HandleRobloxCookieSetVoidMethodA(jobject obj, jmethodID method_id,
 
 jobject MakeFileObject(const char* path) {
   jobject file = MakeObjectForClass("java/io/File");
-  auto* pseudo_object = PseudoObjectFromRef(file);
-  if (pseudo_object) {
-    pseudo_object->object_fields["path"] = MakeString(path);
-  }
+  // The field owns a reference, so the calling thread's local ref can be
+  // released on detach without freeing the value.
+  SetStringFieldRaw(file, "path", path);
   return file;
 }
 
@@ -2270,25 +2337,26 @@ jobject MakeDeviceStaticParamsObject() {
   auto* pseudo_object = PseudoObjectFromRef(object);
   if (pseudo_object) {
     const PlatformIdentity identity = CurrentPlatformIdentity();
-    pseudo_object->object_fields["osVersion"] = MakeString("Android 13");
-    pseudo_object->object_fields["deviceName"] =
-        MakeString(identity.device_name.c_str());
+    // The field owns a reference, so the calling thread's local ref can be
+    // released on detach without freeing the value.
+    const auto set_string = [pseudo_object](const char* field,
+                                            const char* value) {
+      jobject text = MakeString(value);
+      RetainJniReference(text);
+      pseudo_object->object_fields[field] = text;
+    };
+    set_string("osVersion", "Android 13");
+    set_string("deviceName", identity.device_name.c_str());
     const char* app_version = std::getenv("MOCKTAIL_ROBLOX_VERSION");
-    pseudo_object->object_fields["appVersion"] =
-        MakeString(app_version != nullptr ? app_version : "unknown");
-    pseudo_object->object_fields["manufacturer"] =
-        MakeString(identity.manufacturer.c_str());
-    pseudo_object->object_fields["model"] = MakeString(identity.model.c_str());
-    pseudo_object->object_fields["brand"] = MakeString(identity.brand.c_str());
-    pseudo_object->object_fields["device"] =
-        MakeString(identity.device_code.c_str());
-    pseudo_object->object_fields["deviceSku"] =
-        MakeString(identity.device_sku.c_str());
-    pseudo_object->object_fields["appBuildVariant"] = MakeString("headless");
-    pseudo_object->object_fields["socModel"] =
-        MakeString(identity.soc_model.c_str());
-    pseudo_object->object_fields["soc_model"] =
-        MakeString(identity.soc_model.c_str());
+    set_string("appVersion", app_version != nullptr ? app_version : "unknown");
+    set_string("manufacturer", identity.manufacturer.c_str());
+    set_string("model", identity.model.c_str());
+    set_string("brand", identity.brand.c_str());
+    set_string("device", identity.device_code.c_str());
+    set_string("deviceSku", identity.device_sku.c_str());
+    set_string("appBuildVariant", "headless");
+    set_string("socModel", identity.soc_model.c_str());
+    set_string("soc_model", identity.soc_model.c_str());
     pseudo_object->boolean_fields["cpu64Bit"] = JNI_TRUE;
     const mocktail::runtime::DisplaySize host_display =
         mocktail::runtime::ParseDisplaySize(
@@ -6486,6 +6554,7 @@ void VM::InitJNIFunctionTables() {
     if (g_thread_vm_instance != owner || !IsThreadLocalEnvValid()) {
       return JNI_EDETACHED;
     }
+    ReleaseThreadLocalRefs();
     g_thread_audio_fp_mode.Restore();
     g_thread_local_env = nullptr;
     g_thread_vm_instance = nullptr;
@@ -6615,17 +6684,26 @@ void VM::InitJNIFunctionTables() {
   native_interface_.PopLocalFrame =
       [](JNIEnv* /*env*/, jobject result) -> jobject {
     EnsureLocalFrame();
-    std::vector<jobject> frame = std::move(g_local_frames.back());
+    LocalFrame frame = std::move(g_local_frames.back());
     if (g_local_frames.size() > 1) {
       g_local_frames.pop_back();
     } else {
       g_local_frames.back().clear();
     }
-    for (jobject obj : frame) {
-      if (obj != result) {
+    bool result_kept = false;
+    for (const auto& [obj, count] : frame) {
+      uint32_t releases = count;
+      if (obj == result) {
+        --releases;
+        result_kept = true;
+      }
+      for (uint32_t i = 0; i < releases; ++i) {
         ReleaseJniReference(obj);
       }
     }
+    if (result != nullptr && !result_kept) {
+      RetainJniReference(result);
+    }
     RegisterLocalRef(result);
     return result;
   };

src/legacy/legacy_runtime.cc

@@ -58,6 +58,8 @@
 #include "libc_shim/libc_shim.h"
 #include "linker/linker.h"
 #include "mocktail/graphics/bionic_egl_bridge.h"
+#include "mocktail/graphics/chrome_trace_writer.h"
+#include "runtime/engine_pump_rest.h"
 #include "runtime/device_memory_profile.h"
 #include "runtime/display_size.h"
 #include "runtime/environment.h"
@@ -762,7 +764,12 @@ uint64_t MonotonicNanos() {
          static_cast<uint64_t>(ts.tv_nsec);
 }
 
-JNIEnv* AttachMainThreadJniEnv() {
+// `attached` reports whether AttachCurrentThread itself succeeded, so a caller
+// that caches the env can tell a real attach from the GetJNIEnv fallback.
+JNIEnv* AttachMainThreadJniEnv(bool* attached = nullptr) {
+  if (attached != nullptr) {
+    *attached = false;
+  }
   if (g_vm_for_main_thread_pump == nullptr) {
     return nullptr;
   }
@@ -773,6 +780,9 @@ JNIEnv* AttachMainThreadJniEnv() {
     jint attach_result = java_vm->AttachCurrentThread(&raw_env, nullptr);
     if (attach_result == JNI_OK && raw_env != nullptr) {
       env = static_cast<JNIEnv*>(raw_env);
+      if (attached != nullptr) {
+        *attached = true;
+      }
     } else if (IsEnabled("MOCKTAIL_TRACE_MAIN_THREAD_PUMP")) {
       std::cerr << "  [main] AttachCurrentThread failed in pump: "
                 << attach_result << '\n'
@@ -787,6 +797,35 @@ JNIEnv* AttachMainThreadJniEnv() {
   return env;
 }
 
+// The pseudo-VM attach is idempotent: once this thread holds a live env for
+// the VM, re-attaching hands back the same thread-local pointer. Only the
+// main thread calls this, so the cache needs no synchronization. The game
+// session installs RestoreGameSessionJniEnvironment, which restores the JNI
+// function tables when a guest JNI_OnLoad replaces them.
+JNIEnv* MainThreadPumpJniEnv() {
+  static JNIEnv* cached_env = nullptr;
+  static const jnivm::VM* cached_vm = nullptr;
+  if (cached_env != nullptr && cached_vm == g_vm_for_main_thread_pump) {
+    // Only the attach is cached. The table restore and the env publish run on
+    // every tick: a guest JNI_OnLoad can replace the function tables, and any
+    // other thread that publishes its own env overwrites the single global
+    // slot this one shares.
+    g_vm_for_main_thread_pump->RestoreFunctions();
+    PublishCurrentJniEnv(cached_env);
+    return cached_env;
+  }
+  // Only a real attach is worth caching. The GetJNIEnv fallback means this
+  // thread is not attached to the VM, and the next tick has to retry: a VM
+  // swap can make AttachCurrentThread fail for one tick and succeed after.
+  bool attached = false;
+  JNIEnv* env = AttachMainThreadJniEnv(&attached);
+  if (env != nullptr && attached) {
+    cached_env = env;
+    cached_vm = g_vm_for_main_thread_pump;
+  }
+  return env;
+}
+
 bool InvokeTaskSchedulerForeground(
     JNIEnv* env, jclass native_gl_class,
     NativeSetTaskSchedulerBackgroundModeFn native_set_task_scheduler_background_mode,
@@ -905,6 +944,43 @@ bool RunTaskSchedulerForegroundOnMainThread(
   }
 }
 
+// The profile trace writer is compiled into the Vulkan adapter, which the host
+// dlopens RTLD_GLOBAL, so the pump slice goes through symbols resolved from it.
+// Until the adapter is loaded there is no writer and nothing is recorded.
+struct PumpTraceHooks {
+  using ActiveFn = mocktail::graphics::ChromeTraceWriter* (*)();
+  using ClockFn = std::uint64_t (*)();
+  using SliceFn = void (*)(mocktail::graphics::ChromeTraceWriter*, const char*,
+                           const char*, std::uint64_t, std::uint64_t,
+                           const mocktail::graphics::TraceArg*, std::size_t);
+  ActiveFn active = nullptr;
+  ClockFn clock = nullptr;
+  SliceFn slice = nullptr;
+};
+
+const PumpTraceHooks& PumpTrace() {
+  static PumpTraceHooks hooks;
+  // The adapter loads during startup, so a few hundred ticks cover it. After
+  // that the lookups stop and the pump stays untraced.
+  static int attempts = 0;
+  if (hooks.active == nullptr && attempts++ < 1000) {
+    PumpTraceHooks resolved;
+    resolved.active = reinterpret_cast<PumpTraceHooks::ActiveFn>(
+        ::dlsym(RTLD_DEFAULT, "_ZN8mocktail8graphics18ActiveProfileTraceEv"));
+    resolved.clock = reinterpret_cast<PumpTraceHooks::ClockFn>(
+        ::dlsym(RTLD_DEFAULT, "_ZN8mocktail8graphics15TraceClockNanosEv"));
+    resolved.slice = reinterpret_cast<PumpTraceHooks::SliceFn>(::dlsym(
+        RTLD_DEFAULT,
+        "_ZN8mocktail8graphics17ChromeTraceWriter5SliceEPKcS3_mmPKNS0_"
+        "8TraceArgEm"));
+    if (resolved.active != nullptr && resolved.clock != nullptr &&
+        resolved.slice != nullptr) {
+      hooks = resolved;
+    }
+  }
+  return hooks;
+}
+
 void PumpRobloxMainThreadMessagesOnce() {
   static const bool force_early =
       IsEnabled("MOCKTAIL_FORCE_EARLY_MAIN_THREAD_MESSAGE_PUMP");
@@ -944,7 +1020,7 @@ void PumpRobloxMainThreadMessagesOnce() {
     return;
   }
 
-  JNIEnv* env = AttachMainThreadJniEnv();
+  JNIEnv* env = MainThreadPumpJniEnv();
   if (env == nullptr) {
     static bool logged_missing_env = false;
     if (!logged_missing_env && trace_pump) {
@@ -966,8 +1042,21 @@ void PumpRobloxMainThreadMessagesOnce() {
                 << std::flush;
     }
   }
+  const PumpTraceHooks& hooks = PumpTrace();
+  mocktail::graphics::ChromeTraceWriter* trace =
+      hooks.active != nullptr ? hooks.active() : nullptr;
+  const std::uint64_t pump_start_ns = trace != nullptr ? hooks.clock() : 0;
   g_native_call_messages_from_main_thread(
       env, g_native_gl_class_for_main_thread);
+  if (trace != nullptr) {
+    // Empty polls run at kilohertz rates and would swamp the trace, so only
+    // calls that ran a message are recorded.
+    const std::uint64_t pump_end_ns = hooks.clock();
+    if (pump_end_ns - pump_start_ns >= 20'000) {
+      hooks.slice(trace, "nativeCallMessagesFromMainThread", "pump",
+                  pump_start_ns, pump_end_ns, nullptr, 0);
+    }
+  }
   if (__builtin_expect(trace_pump, 0)) {
     if (pump_count <= 10 || pump_count % 100 == 0) {
       std::cerr << "  [main] nativeCallMessagesFromMainThread returned #"
@@ -1414,8 +1503,11 @@ void JniOnLoadTimeoutAlarm(int, siginfo_t* info, void* context) {
 
 void PublishCurrentJniEnv(JNIEnv* env) {
   using SetCurrentJniEnvFn = void (*)(void*);
-  auto* set_current_jni_env = reinterpret_cast<SetCurrentJniEnvFn>(
-      ::dlsym(RTLD_DEFAULT, "mocktail_set_current_jni_env"));
+  // RTLD_DEFAULT resolves this to the runtime's own exported setter, so the
+  // address is fixed for the life of the process.
+  static SetCurrentJniEnvFn set_current_jni_env =
+      reinterpret_cast<SetCurrentJniEnvFn>(
+          ::dlsym(RTLD_DEFAULT, "mocktail_set_current_jni_env"));
   if (set_current_jni_env) {
     set_current_jni_env(env);
   }
@@ -6831,6 +6923,10 @@ int mocktail::legacy::Run(const runtime::CommandLineOptions& options,
   bool input_shutdown_completed = window_input_runtime == nullptr;
   bool resize_readiness_completed = true;
   if (mocktail::window::IsInitialised()) {
+    std::cout << "  [main] engine pump rest: "
+              << mocktail::runtime::EnginePumpRestModeName(
+                     mocktail::runtime::ActiveEnginePumpRestMode())
+              << " (MOCKTAIL_ENGINE_PUMP_REST=sleep|tpause|spin)\n";
     std::cout << "  [main] entering SDL event loop (close the window to quit)\n"
               << std::flush;
     std::unique_ptr<mocktail::window::WindowGameSurfaceBridge> surface_bridge;
@@ -6946,7 +7042,14 @@ int mocktail::legacy::Run(const runtime::CommandLineOptions& options,
         }
       }
       const uint64_t fps_after_launch_ns = fps_trace ? MonotonicNanos() : 0;
-      const uint64_t fps_pace_ns = mocktail::window::PaceInputPump();
+      // The pacer sleeps only under throttled presentation. Unthrottled, the
+      // engine pump above is a poll, and the rest between polls is what keeps
+      // it from spinning.
+      uint64_t fps_pace_ns = mocktail::window::PaceInputPump();
+      if (fps_pace_ns == 0 &&
+          mocktail::window::UnthrottledPresentationRequested()) {
+        fps_pace_ns = mocktail::runtime::RestAfterEnginePump();
+      }
       if (fps_trace) {
         const uint64_t fps_tick_end_ns = MonotonicNanos();
         ++fps_samples;

src/libc_shim/libc_shim.cc

@@ -11,6 +11,8 @@
 #include <filesystem>
 #include <iostream>
 #include <limits.h>
+#include <algorithm>
+#include <string_view>
 #include <unordered_map>
 #include <unistd.h>
 #include <vector>
@@ -20,8 +22,19 @@ namespace libc_shim {
 namespace {
 
 std::unordered_map<std::string, std::string> g_path_mappings;
+// g_path_mappings ordered longest Android prefix first, so the first match
+// is the most specific one. Rebuilt whenever the mappings change.
+std::vector<std::pair<std::string, std::string>> g_ordered_mappings;
 std::vector<std::string> g_ca_bundle_aliases;
 
+void RebuildOrderedMappings() {
+  g_ordered_mappings.assign(g_path_mappings.begin(), g_path_mappings.end());
+  std::stable_sort(g_ordered_mappings.begin(), g_ordered_mappings.end(),
+                   [](const auto& a, const auto& b) {
+                     return a.first.size() > b.first.size();
+                   });
+}
+
 bool g_installed = false;
 std::atomic<GuestAllocator> g_guest_allocator{nullptr};
 
@@ -72,11 +85,9 @@ std::string DefaultDataRoot() {
   return RuntimeRoot() + "/data";
 }
 
-bool PrefixMatchesPath(const std::string& path, const std::string& prefix) {
-  if (path.size() < prefix.size()) {
-    return false;
-  }
-  if (path.compare(0, prefix.size(), prefix) != 0) {
+bool PrefixMatchesPath(std::string_view path, std::string_view prefix) {
+  if (path.size() < prefix.size() ||
+      std::memcmp(path.data(), prefix.data(), prefix.size()) != 0) {
     return false;
   }
   return path.size() == prefix.size() || path[prefix.size()] == '/';
@@ -202,6 +213,7 @@ HostCaBundleResolution ResolveHostCaBundle() {
 
 HostCaBundleResolution ConfigureHostCaBundlePathMappings() {
   for (const auto& alias : g_ca_bundle_aliases) g_path_mappings.erase(alias);
+  RebuildOrderedMappings();
   g_ca_bundle_aliases.assign(kAndroidCaBundlePaths.begin(), kAndroidCaBundlePaths.end());
   if (const char* content = GetEnvNonEmpty("MOCKTAIL_ASSET_PATH")) {
     auto root = std::filesystem::path(content).lexically_normal();
@@ -297,31 +309,33 @@ void Install() {
             << g_path_mappings.size() << " prefix mappings)\n";
 }
 
-std::string TranslatePath(const std::string& android_path) {
-  const std::string* best_android_prefix = nullptr;
-  const std::string* best_host_prefix = nullptr;
-  for (const auto& [android_prefix, host_prefix] : g_path_mappings) {
-    if (PrefixMatchesPath(android_path, android_prefix) &&
-        (best_android_prefix == nullptr ||
-         android_prefix.size() > best_android_prefix->size())) {
-      best_android_prefix = &android_prefix;
-      best_host_prefix = &host_prefix;
+bool TranslatePathInto(std::string_view android_path, std::string* host_path) {
+  for (const auto& [android_prefix, host_prefix] : g_ordered_mappings) {
+    if (PrefixMatchesPath(android_path, android_prefix)) {
+      const std::string_view rest = android_path.substr(android_prefix.size());
+      host_path->reserve(host_prefix.size() + rest.size());
+      host_path->assign(host_prefix);
+      host_path->append(rest);
+      return true;
     }
   }
-  if (best_android_prefix != nullptr && best_host_prefix != nullptr) {
-    return *best_host_prefix +
-           android_path.substr(best_android_prefix->size());
-  }
-  return android_path;
+  return false;
+}
+
+std::string TranslatePath(const std::string& android_path) {
+  std::string host_path;
+  return TranslatePathInto(android_path, &host_path) ? host_path : android_path;
 }
 
 void RegisterPathMapping(const std::string& android_prefix,
                          const std::string& host_prefix) {
   g_path_mappings[android_prefix] = host_prefix;
+  RebuildOrderedMappings();
 }
 
 void ClearPathMappings() {
   g_path_mappings.clear();
+  g_ordered_mappings.clear();
   g_ca_bundle_aliases.clear();
 }
 
@@ -333,13 +347,16 @@ const char* HostPath(const char* path, std::string* storage) {
   if (path == nullptr) {
     return nullptr;
   }
-  *storage = libc_shim::TranslatePath(path);
-  return storage->c_str();
+  return libc_shim::TranslatePathInto(path, storage) ? storage->c_str() : path;
 }
 
+// Read once: the guest calls these shims on every file operation.
 bool PathTraceEnabled() {
-  const char* value = std::getenv("MOCKTAIL_PATH_TRACE");
-  return value != nullptr && value[0] != '\0' && value[0] != '0';
+  static const bool enabled = [] {
+    const char* value = std::getenv("MOCKTAIL_PATH_TRACE");
+    return value != nullptr && value[0] != '\0' && value[0] != '0';
+  }();
+  return enabled;
 }
 
 void TracePathCall(const char* name, const char* path, const char* host_path,

src/main.cc

@@ -552,6 +552,12 @@ int main(int argc, char* argv[]) {
     case mocktail::runtime::GameModeSessionState::kActive:
       std::cout << "  [gamemode] performance request active\n";
       break;
+    case mocktail::runtime::GameModeSessionState::kDeclinedCorePinning:
+      std::cout << "  [gamemode] released: it pinned this process to a subset "
+                   "of the CPUs, which concentrates the worker pool. Set "
+                   "pin_cores=no in ~/.config/gamemode.ini to keep GameMode, "
+                   "or performance.gamemode: on to accept the pinning\n";
+      break;
     case mocktail::runtime::GameModeSessionState::kAlreadyActive:
       std::cout << "  [gamemode] already active for this process\n";
       break;

src/runtime/command_line.cc

@@ -1,6 +1,7 @@
 #include "runtime/command_line.h"
 
 #include <cstdlib>
+#include <filesystem>
 #include <sstream>
 #include <string>
 #include <string_view>
@@ -78,6 +79,12 @@ CommandLineParseResult ParseCommandLine(int argc, const char* const argv[]) {
       result.options.allow_unverified_build = true;
     } else if (argument == "--force-run-latest") {
       result.options.force_run_latest = true;
+    } else if (argument == "--profile") {
+      if (!ReadOptionValue(argc, argv, &index, argument,
+                           &result.options.profile_trace_path,
+                           &result.error)) {
+        return result;
+      }
     } else if (argument == "--launch-uri") {
       if (!result.options.launch_request_json.empty()) {
         result.error = "duplicate option: --launch-uri";
@@ -227,6 +234,20 @@ bool ApplyCommandLineEnvironment(const CommandLineOptions& options,
                       error)) {
     return false;
   }
+  if (!options.profile_trace_path.empty()) {
+    // Absolute, so a later working-directory change cannot move the trace.
+    std::error_code absolute_error;
+    const std::filesystem::path trace_path =
+        std::filesystem::absolute(options.profile_trace_path, absolute_error);
+    if (absolute_error ||
+        !SetEnvironment("MOCKTAIL_PROFILE_TRACE", trace_path.string(),
+                        error)) {
+      if (error != nullptr && absolute_error) {
+        *error = "could not resolve --profile path";
+      }
+      return false;
+    }
+  }
   if (options.window_mode == WindowMode::kHeadless) {
     return SetEnvironment("MOCKTAIL_HEADLESS", "1", error);
   }
@@ -256,6 +277,8 @@ std::string CommandLineUsage(const std::string& program_name) {
          "without approval; it is not activated\n"
       << "  --launch-uri <uri>       Join from a roblox: or roblox-player: "
          "website link\n"
+      << "  --profile <file>         Write a Chrome trace of Vulkan adapter "
+         "work for ui.perfetto.dev\n"
       << "  --help, -h               Show this help\n\n"
       << "Auth:\n"
       << "  When no saved Roblox session is found, Roblox's welcome screen "

src/runtime/discord_rpc.cc

@@ -84,14 +84,50 @@ std::string DumpJson(const Json& value) {
   return value.dump(-1, ' ', false, Json::error_handler_t::replace);
 }
 
-std::string RenderPlaceTemplate(std::string text, std::string_view place_name) {
-  constexpr std::string_view placeholder = "{place_name}";
+// Expands in one pass, so placeholder text inside a place name stays literal.
+// A template that expands an empty placeholder renders empty, so "by
+// {creator_name}" never shows a dangling "by".
+std::string RenderPresenceTemplate(std::string_view text,
+                                   std::string_view place_name,
+                                   std::string_view place_icon,
+                                   std::string_view creator_name) {
+  constexpr std::string_view kPlaceName = "{place_name}";
+  constexpr std::string_view kPlaceIcon = "{place_icon}";
+  constexpr std::string_view kCreatorName = "{creator_name}";
+  std::string rendered;
+  rendered.reserve(text.size());
   std::size_t offset = 0;
-  while ((offset = text.find(placeholder, offset)) != std::string::npos) {
-    text.replace(offset, placeholder.size(), place_name);
-    offset += place_name.size();
+  const auto expand = [&](std::string_view token, std::string_view value) {
+    if (value.empty()) {
+      return false;
+    }
+    rendered += value;
+    offset += token.size();
+    return true;
+  };
+  while (offset < text.size()) {
+    const std::string_view rest = text.substr(offset);
+    if (rest.substr(0, kPlaceName.size()) == kPlaceName) {
+      if (!expand(kPlaceName, place_name)) return {};
+    } else if (rest.substr(0, kPlaceIcon.size()) == kPlaceIcon) {
+      if (!expand(kPlaceIcon, place_icon)) return {};
+    } else if (rest.substr(0, kCreatorName.size()) == kCreatorName) {
+      if (!expand(kCreatorName, creator_name)) return {};
+    } else {
+      rendered.push_back(text[offset]);
+      ++offset;
+    }
   }
-  return TruncateUtf8(std::move(text), 128);
+  return rendered;
+}
+
+bool IsDiscordAssetKey(std::string_view key) {
+  return !key.empty() && key.size() <= 32 &&
+         std::all_of(key.begin(), key.end(), [](unsigned char byte) {
+           return (byte >= 'a' && byte <= 'z') ||
+                  (byte >= 'A' && byte <= 'Z') ||
+                  (byte >= '0' && byte <= '9') || byte == '_' || byte == '-';
+         });
 }
 
 std::string PercentEncode(std::string_view value) {
@@ -329,8 +365,14 @@ bool HandshakeDiscord(int descriptor, std::string_view application_id) {
 }
 
 Json ActivityJson(const DiscordRpcActivity& activity) {
-  Json result = {
-      {"type", 0}, {"details", activity.details}, {"instance", true}};
+  // Discord rejects the whole activity when a text field is an empty string.
+  Json result = {{"type", 0}, {"instance", true}};
+  if (!activity.details.empty()) {
+    result["details"] = activity.details;
+  }
+  if (!activity.name.empty()) {
+    result["name"] = activity.name;
+  }
   if (!activity.state.empty()) {
     result["state"] = activity.state;
   }
@@ -342,6 +384,12 @@ Json ActivityJson(const DiscordRpcActivity& activity) {
     if (!activity.large_text.empty()) {
       result["assets"]["large_text"] = activity.large_text;
     }
+    if (!activity.small_image.empty()) {
+      result["assets"]["small_image"] = activity.small_image;
+      if (!activity.small_text.empty()) {
+        result["assets"]["small_text"] = activity.small_text;
+      }
+    }
   }
   if (!activity.button_label.empty() && !activity.button_url.empty()) {
     result["buttons"] = Json::array(
@@ -446,6 +494,7 @@ std::optional<Json> GetRobloxJson(std::string url) {
 
 struct ResolvedPlaceMetadata {
   std::string name;
+  std::string creator_name;
   std::string icon_url;
 };
 
@@ -494,6 +543,13 @@ ResolvedPlaceMetadata ResolvePlaceMetadata(int64_t place_id) {
       metadata.name =
           TruncateUtf8(first["name"].get<std::string>(), 128);
     }
+    if (first.contains("creator") && first["creator"].is_object()) {
+      const Json& creator = first["creator"];
+      if (creator.contains("name") && creator["name"].is_string()) {
+        metadata.creator_name =
+            TruncateUtf8(creator["name"].get<std::string>(), 128);
+      }
+    }
   }
 
   const std::optional<Json> thumbnail = GetRobloxJson(
@@ -542,46 +598,74 @@ std::string BuildDiscordJoinUrl(const RobloxExperienceLaunchRequest& request) {
 DiscordRpcActivity BuildDiscordRpcActivity(
     const DiscordRpcConfig& config, RobloxExperiencePresencePhase phase,
     const RobloxExperienceLaunchRequest* request, std::string place_name,
-    int64_t session_started_at, std::string place_icon_url) {
+    int64_t session_started_at, std::string place_icon_url,
+    std::string creator_name) {
+  const bool browsing = phase == RobloxExperiencePresencePhase::kBrowsing;
+  const bool joining_without_place =
+      phase == RobloxExperiencePresencePhase::kJoining && place_name.empty();
+  if (!browsing && place_name.empty()) {
+    place_name = config.text.unknown_place;
+  }
+  // Hidden or absent places expose nothing to any template, icons included.
+  const bool show_place =
+      !browsing && !joining_without_place && config.show_place_name;
+  const std::string_view shown_name =
+      show_place ? std::string_view(place_name) : std::string_view();
+  const std::string_view shown_icon =
+      show_place && IsSafeExternalImageUrl(place_icon_url)
+          ? std::string_view(place_icon_url)
+          : std::string_view();
+  const std::string_view shown_creator =
+      show_place ? std::string_view(creator_name) : std::string_view();
+  const auto render = [&](std::string_view text) {
+    return RenderPresenceTemplate(text, shown_name, shown_icon,
+                                  shown_creator);
+  };
+  const auto render_text = [&](std::string_view text) {
+    return TruncateUtf8(render(text), 128);
+  };
+  const auto is_image = [](std::string_view image) {
+    return IsSafeExternalImageUrl(image) || IsDiscordAssetKey(image);
+  };
+
   DiscordRpcActivity activity;
-  activity.state = TruncateUtf8(config.text.state, 128);
-  switch (phase) {
-    case RobloxExperiencePresencePhase::kBrowsing:
-      activity.details = TruncateUtf8(config.text.browsing, 128);
-      break;
-    case RobloxExperiencePresencePhase::kJoining:
-    case RobloxExperiencePresencePhase::kPlaying: {
-      if (place_name.empty()) {
-        if (phase == RobloxExperiencePresencePhase::kJoining) {
-          activity.details = TruncateUtf8(config.text.joining, 128);
-          break;
-        }
-        place_name = config.text.unknown_place;
-      }
-      if (config.show_place_name) {
-        activity.details = RenderPlaceTemplate(config.text.playing, place_name);
-      } else {
-        activity.details = activity.state;
-        activity.state.clear();
-      }
-      if (phase == RobloxExperiencePresencePhase::kPlaying &&
-          config.show_elapsed_time && session_started_at > 0) {
-        activity.start_timestamp = session_started_at;
-      }
-      if (IsSafeExternalImageUrl(place_icon_url)) {
-        activity.large_image = std::move(place_icon_url);
-        activity.large_text = TruncateUtf8(place_name, 128);
-      }
-      if (phase == RobloxExperiencePresencePhase::kPlaying &&
-          config.join_enabled && request != nullptr &&
-          (!config.public_servers_only || IsPublicDiscordJoin(*request))) {
-        activity.button_url = BuildDiscordJoinUrl(*request);
-        if (!activity.button_url.empty()) {
-          activity.button_label = config.join_button_label;
-        }
-      }
-      break;
+  activity.name = render_text(config.text.title);
+  activity.state = render_text(config.text.state);
+  if (browsing) {
+    activity.details = render_text(config.text.browsing);
+  } else if (joining_without_place) {
+    activity.details = render_text(config.text.joining);
+  } else {
+    if (config.show_place_name) {
+      activity.details = render_text(config.text.playing);
+    } else {
+      activity.details = std::move(activity.state);
+      activity.state.clear();
     }
+    if (phase == RobloxExperiencePresencePhase::kPlaying &&
+        config.show_elapsed_time && session_started_at > 0) {
+      activity.start_timestamp = session_started_at;
+    }
+    if (phase == RobloxExperiencePresencePhase::kPlaying &&
+        config.join_enabled && request != nullptr &&
+        (!config.public_servers_only || IsPublicDiscordJoin(*request))) {
+      activity.button_url = BuildDiscordJoinUrl(*request);
+      if (!activity.button_url.empty()) {
+        activity.button_label = config.join_button_label;
+      }
+    }
+  }
+  activity.large_image = render(config.images.large);
+  if (!is_image(activity.large_image)) {
+    activity.large_image.clear();
+    return activity;
+  }
+  activity.large_text = render_text(config.images.large_text);
+  activity.small_image = render(config.images.small);
+  if (is_image(activity.small_image)) {
+    activity.small_text = render_text(config.images.small_text);
+  } else {
+    activity.small_image.clear();
   }
   return activity;
 }
@@ -697,6 +781,7 @@ class DiscordRpcSession::Impl final {
 
   struct CachedPlaceMetadata {
     std::string name;
+    std::string creator_name;
     std::string icon_url;
     std::chrono::steady_clock::time_point next_attempt{};
     unsigned failures = 0;
@@ -734,6 +819,7 @@ class DiscordRpcSession::Impl final {
       Desired desired = Snapshot();
       std::string place_name;
       std::string place_icon_url;
+      std::string creator_name;
       bool resolve_metadata_after_publish = false;
       if ((desired.phase == RobloxExperiencePresencePhase::kJoining ||
            desired.phase == RobloxExperiencePresencePhase::kPlaying) &&
@@ -742,6 +828,7 @@ class DiscordRpcSession::Impl final {
             place_metadata_[desired.request.place_id];
         place_name = cached.name;
         place_icon_url = cached.icon_url;
+        creator_name = cached.creator_name;
         if ((cached.name.empty() || cached.icon_url.empty()) &&
             std::chrono::steady_clock::now() >= cached.next_attempt) {
           resolve_metadata_after_publish = true;
@@ -787,7 +874,7 @@ class DiscordRpcSession::Impl final {
                 ? nullptr
                 : &desired.request,
             std::move(place_name), desired.started_at,
-            std::move(place_icon_url));
+            std::move(place_icon_url), std::move(creator_name));
         if (!SetDiscordActivity(descriptor, &activity, nonce++)) {
           (void)close(descriptor);
           descriptor = -1;
@@ -811,6 +898,11 @@ class DiscordRpcSession::Impl final {
           cached.name = resolved.name;
           changed = true;
         }
+        if (!resolved.creator_name.empty() &&
+            resolved.creator_name != cached.creator_name) {
+          cached.creator_name = resolved.creator_name;
+          changed = true;
+        }
         if (!resolved.icon_url.empty() &&
             resolved.icon_url != cached.icon_url) {
           cached.icon_url = resolved.icon_url;

src/runtime/engine_pump_rest.cc

@@ -0,0 +1,130 @@
+#include "runtime/engine_pump_rest.h"
+
+#include <cpuid.h>
+#include <immintrin.h>
+#include <sys/prctl.h>
+#include <time.h>
+#include <x86intrin.h>
+
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+
+namespace mocktail::runtime {
+namespace {
+
+uint64_t NowNs() {
+  timespec now{};
+  clock_gettime(CLOCK_MONOTONIC, &now);
+  return static_cast<uint64_t>(now.tv_sec) * 1'000'000'000ULL +
+         static_cast<uint64_t>(now.tv_nsec);
+}
+
+// The kernel caps one TPAUSE at umwait_control/max_time TSC cycles (100000 by
+// default), so the wait is a loop of short pauses up to the deadline. Control
+// bit 0 clear selects C0.2, the deeper of the two light states.
+__attribute__((target("waitpkg"))) void TpauseUntil(uint64_t deadline_ns) {
+  while (NowNs() < deadline_ns) {
+    _tpause(0, __rdtsc() + 100000ULL);
+  }
+}
+
+void LowerTimerSlackOnce() {
+  // Only the main thread rests, so the slack is set once per process.
+  static const bool slack_set = [] {
+    return prctl(PR_SET_TIMERSLACK, kEnginePumpTimerSlackNs) == 0;
+  }();
+  (void)slack_set;
+}
+
+}  // namespace
+
+const char* EnginePumpRestModeName(EnginePumpRestMode mode) {
+  switch (mode) {
+    case EnginePumpRestMode::kSleep:
+      return "sleep";
+    case EnginePumpRestMode::kTpause:
+      return "tpause";
+    case EnginePumpRestMode::kSpin:
+      return "spin";
+  }
+  return "spin";
+}
+
+EnginePumpRestMode ChooseEnginePumpRestMode(
+    const EnginePumpRestInputs& inputs) {
+  if (inputs.override != nullptr) {
+    if (std::strcmp(inputs.override, "sleep") == 0) {
+      return EnginePumpRestMode::kSleep;
+    }
+    if (std::strcmp(inputs.override, "spin") == 0) {
+      return EnginePumpRestMode::kSpin;
+    }
+    if (std::strcmp(inputs.override, "tpause") == 0 &&
+        inputs.cpu_has_waitpkg) {
+      return EnginePumpRestMode::kTpause;
+    }
+  }
+  if (inputs.governor_performance) {
+    return EnginePumpRestMode::kSleep;
+  }
+  return inputs.cpu_has_waitpkg ? EnginePumpRestMode::kTpause
+                                : EnginePumpRestMode::kSpin;
+}
+
+bool CpuGovernorIsPerformance(const char* path) {
+  std::FILE* file = std::fopen(path, "r");
+  if (file == nullptr) {
+    return false;
+  }
+  char governor[32] = {};
+  const bool read = std::fgets(governor, sizeof(governor), file) != nullptr;
+  std::fclose(file);
+  if (!read) {
+    return false;
+  }
+  governor[std::strcspn(governor, "\r\n")] = '\0';
+  return std::strcmp(governor, "performance") == 0;
+}
+
+bool CpuHasWaitPkg() {
+  unsigned eax = 0, ebx = 0, ecx = 0, edx = 0;
+  if (__get_cpuid_count(7, 0, &eax, &ebx, &ecx, &edx) == 0) {
+    return false;
+  }
+  return (ecx & (1u << 5)) != 0;
+}
+
+EnginePumpRestMode ActiveEnginePumpRestMode() {
+  static const EnginePumpRestMode mode = [] {
+    EnginePumpRestInputs inputs;
+    inputs.governor_performance = CpuGovernorIsPerformance(
+        "/sys/devices/system/cpu/cpu0/cpufreq/scaling_governor");
+    inputs.cpu_has_waitpkg = CpuHasWaitPkg();
+    inputs.override = std::getenv("MOCKTAIL_ENGINE_PUMP_REST");
+    return ChooseEnginePumpRestMode(inputs);
+  }();
+  return mode;
+}
+
+uint64_t RestAfterEnginePump(EnginePumpRestMode mode) {
+  LowerTimerSlackOnce();
+  switch (mode) {
+    case EnginePumpRestMode::kSpin:
+      return 0;
+    case EnginePumpRestMode::kTpause:
+      TpauseUntil(NowNs() + kEnginePumpRestNs);
+      return kEnginePumpRestNs;
+    case EnginePumpRestMode::kSleep:
+      break;
+  }
+  timespec rest{};
+  rest.tv_sec = 0;
+  rest.tv_nsec = static_cast<long>(kEnginePumpRestNs);
+  // A signal may cut the rest short. The remainder is not slept again: an
+  // early poll only costs a few microseconds.
+  (void)clock_nanosleep(CLOCK_MONOTONIC, 0, &rest, nullptr);
+  return kEnginePumpRestNs;
+}
+
+}  // namespace mocktail::runtime

src/runtime/external_launch_broker.cc

@@ -349,6 +349,7 @@ class ExternalLaunchBroker::Impl final {
       Status initial_status = NormalizeRequest(*initial_request, &normalized);
       if (!initial_status.ok()) return initial_status;
       pending_.push_back(std::move(normalized));
+      PublishPendingCount();
     }
     socket_path_ = options_.socket_path;
     Status status = socket_path_.empty()
@@ -426,6 +427,14 @@ class ExternalLaunchBroker::Impl final {
     if (!sink.valid()) {
       return Invalid("external-launch sink is incomplete");
     }
+    // The host main loop drains on every tick and the queue is almost always
+    // empty. Observe that without either lock, so an idle tick never waits
+    // behind a dispatch already in flight. A request queued just after this
+    // load is delivered on the next tick.
+    if (pending_count_.load(std::memory_order_acquire) == 0 &&
+        !stopping_.load(std::memory_order_acquire)) {
+      return Status::Ok();
+    }
     std::lock_guard<std::mutex> drain_lock(drain_mutex_);
     if (stopping_.load(std::memory_order_acquire)) {
       return Failed("external-launch broker is stopping");
@@ -437,11 +446,13 @@ class ExternalLaunchBroker::Impl final {
         if (pending_.empty()) break;
         request = std::move(pending_.front());
         pending_.pop_front();
+        PublishPendingCount();
       }
       Status status = sink.dispatch(sink.context, request);
       if (!status.ok()) {
         std::lock_guard<std::mutex> lock(queue_mutex_);
         pending_.push_front(std::move(request));
+        PublishPendingCount();
         return status;
       }
     }
@@ -482,6 +493,7 @@ class ExternalLaunchBroker::Impl final {
     {
       std::lock_guard<std::mutex> lock(queue_mutex_);
       pending_.clear();
+      PublishPendingCount();
     }
     started_ = false;
     return Status::Ok();
@@ -577,9 +589,16 @@ class ExternalLaunchBroker::Impl final {
       return Unavailable("external-launch queue is full");
     }
     pending_.push_back(std::move(request));
+    PublishPendingCount();
     return Status::Ok();
   }
 
+  // Mirrors pending_.size() for Drain's lock-free idle check. Every caller
+  // holds queue_mutex_, except Start, which runs before the worker exists.
+  void PublishPendingCount() {
+    pending_count_.store(pending_.size(), std::memory_order_release);
+  }
+
   void CleanupEndpoint() {
     CloseDescriptor(&stop_event_);
     CloseDescriptor(&listener_);
@@ -607,6 +626,7 @@ class ExternalLaunchBroker::Impl final {
   std::mutex drain_mutex_;
   std::mutex lifecycle_mutex_;
   std::deque<RobloxExperienceLaunchRequest> pending_;
+  std::atomic<std::size_t> pending_count_{0};
   OwnedPthread worker_;
   std::atomic<bool> stopping_{true};
   int listener_ = -1;

src/runtime/game_mode.cc

@@ -1,10 +1,13 @@
 #include "runtime/game_mode.h"
 
+#include <dirent.h>
 #include <dlfcn.h>
 #if defined(__GLIBC__)
 #include <link.h>
 #endif
 
+#include <cerrno>
+#include <cstdlib>
 #include <cstring>
 #include <string>
 #include <utility>
@@ -56,8 +59,63 @@ void* OpenClientLibrary(const char* name) {
 #endif
 }
 
+int GetThreadAffinity(cpu_set_t* mask) {
+  return sched_getaffinity(0, sizeof(*mask), mask);
+}
+
+// sched_setaffinity binds one thread, and GameMode pins every thread it finds,
+// so restoring the mask means walking the task list. Threads that exit while
+// the directory is being read are skipped, not treated as failures.
+int SetAffinityOfEveryThread(const cpu_set_t* mask) {
+  DIR* tasks = opendir("/proc/self/task");
+  if (tasks == nullptr) {
+    return sched_setaffinity(0, sizeof(*mask), mask);
+  }
+  int result = 0;
+  for (;;) {
+    // readdir() reports both end-of-directory and failure with a null return,
+    // so a read that dies partway must not pass for a completed walk.
+    errno = 0;
+    const dirent* entry = readdir(tasks);
+    if (entry == nullptr) {
+      if (errno != 0) {
+        result = -1;
+      }
+      break;
+    }
+    const long tid = std::strtol(entry->d_name, nullptr, 10);
+    if (tid <= 0) {
+      continue;
+    }
+    if (sched_setaffinity(static_cast<pid_t>(tid), sizeof(*mask), mask) != 0 &&
+        errno != ESRCH) {
+      result = -1;
+    }
+  }
+  closedir(tasks);
+  return result;
+}
+
 }  // namespace
 
+CpuAffinityApi HostCpuAffinityApi() {
+  return CpuAffinityApi{&GetThreadAffinity, &SetAffinityOfEveryThread};
+}
+
+bool CpuAffinityNarrowed(const cpu_set_t& before, const cpu_set_t& after) {
+  if (CPU_COUNT(&after) >= CPU_COUNT(&before)) {
+    return false;
+  }
+  // A smaller set that escapes `before` is a move, not a narrowing, and the
+  // daemon's choice of CPUs is then the only one known to be permitted.
+  for (int cpu = 0; cpu < CPU_SETSIZE; ++cpu) {
+    if (CPU_ISSET(cpu, &after) && !CPU_ISSET(cpu, &before)) {
+      return false;
+    }
+  }
+  return true;
+}
+
 bool ParseGameModePolicy(std::string_view value, GameModePolicy* policy) {
   if (policy == nullptr) {
     return false;
@@ -97,6 +155,8 @@ const char* GameModeSessionStateName(GameModeSessionState state) {
       return "unavailable";
     case GameModeSessionState::kRequestFailed:
       return "request-failed";
+    case GameModeSessionState::kDeclinedCorePinning:
+      return "declined-core-pinning";
     case GameModeSessionState::kAlreadyActive:
       return "already-active";
     case GameModeSessionState::kActive:
@@ -123,7 +183,7 @@ GameModeSession::GameModeSession(GameModeSession&& other) noexcept
 
 GameModeSession GameModeSession::Start(GameModePolicy policy) {
   if (policy == GameModePolicy::kOff) {
-    return StartBound(policy, {}, nullptr);
+    return StartBound(policy, {}, {}, nullptr);
   }
 
   void* library = OpenClientLibrary("libgamemode.so.0");
@@ -155,7 +215,8 @@ GameModeSession GameModeSession::Start(GameModePolicy policy) {
   (void)ResolveFunction(library, "real_gamemode_query_status",
                         &api.query_status, nullptr);
 
-  GameModeSession session = StartBound(policy, api, library);
+  GameModeSession session =
+      StartBound(policy, api, HostCpuAffinityApi(), library);
   if (!session.owns_request_) {
     session.CloseLibrary();
   }
@@ -164,11 +225,17 @@ GameModeSession GameModeSession::Start(GameModePolicy policy) {
 
 GameModeSession GameModeSession::StartWithClientForTesting(
     GameModePolicy policy, GameModeClientApi api) {
-  return StartBound(policy, api, nullptr);
+  return StartBound(policy, api, {}, nullptr);
+}
+
+GameModeSession GameModeSession::StartWithClientForTesting(
+    GameModePolicy policy, GameModeClientApi api, CpuAffinityApi affinity) {
+  return StartBound(policy, api, affinity, nullptr);
 }
 
 GameModeSession GameModeSession::StartBound(GameModePolicy policy,
                                             GameModeClientApi api,
+                                            CpuAffinityApi affinity,
                                             void* library_handle) {
   GameModeSession session;
   if (policy == GameModePolicy::kOff) {
@@ -185,6 +252,11 @@ GameModeSession GameModeSession::StartBound(GameModePolicy policy,
     session.state_ = GameModeSessionState::kAlreadyActive;
     return session;
   }
+  cpu_set_t before;
+  CPU_ZERO(&before);
+  const bool affinity_readable =
+      policy != GameModePolicy::kOn && affinity.get != nullptr &&
+      affinity.set != nullptr && affinity.get(&before) == 0;
   if (api.request_start() != 0) {
     session.state_ = GameModeSessionState::kRequestFailed;
     session.detail_ = ClientError(api, "GameMode request was rejected");
@@ -192,6 +264,21 @@ GameModeSession GameModeSession::StartBound(GameModePolicy policy,
   }
   session.state_ = GameModeSessionState::kActive;
   session.owns_request_ = true;
+  // The daemon pins before the request call returns, and re-pins every few
+  // seconds afterwards. Ending the request is what releases the pin.
+  cpu_set_t after;
+  CPU_ZERO(&after);
+  if (affinity_readable && affinity.get(&after) == 0 &&
+      CpuAffinityNarrowed(before, after)) {
+    session.state_ = GameModeSessionState::kDeclinedCorePinning;
+    session.detail_ = "GameMode pinned the process to a subset of its CPUs";
+    // A release that fails leaves the daemon holding the request, so keep
+    // owning it and let Stop() retry rather than reporting it released.
+    if (api.request_end() == 0) {
+      session.owns_request_ = false;
+    }
+    (void)affinity.set(&before);
+  }
   return session;
 }
 

src/runtime/roblox_input_router.cc

@@ -316,6 +316,7 @@ Status RobloxInputRouter::Activate(RobloxInputViewport viewport,
   gamepads_.clear();
   mouse_x_ = 0.0f;
   mouse_y_ = 0.0f;
+  pointer_anchored_ = false;
   return Status::Ok();
 }
 
@@ -549,20 +550,20 @@ RobloxInputDispatchResult RobloxInputRouter::HandleMouseMotionLocked(
   const float delta_x = transform.HostLogicalToGuestX(event.delta_x);
   const float delta_y = transform.HostLogicalToGuestY(event.delta_y);
 
-  const float max_x = std::max(0.0F, transform.guest_width() - 1.0F);
-  const float max_y = std::max(0.0F, transform.guest_height() - 1.0F);
-
-  // mouse_x_/mouse_y_ stay inside the viewport. Relative-mode motion reports
-  // zero absolute coordinates, so the accumulated position is the only
-  // position there; letting it drift past the edge would swallow every
-  // reversal until the pointer walked all the way back.
+  // Relative-mode motion reports zero absolute coordinates and a delta. The
+  // pointer holds its captured position while the delta passes through, so a
+  // long camera turn neither parks the reported position at the viewport edge
+  // nor swallows the reversal. Roblox draws its cursor at the held position
+  // when the capture ends, which matches where the host pointer is warped.
   if (event.x == 0.0f && event.y == 0.0f &&
       (delta_x != 0.0f || delta_y != 0.0f)) {
-    mouse_x_ = std::clamp(mouse_x_ + delta_x, 0.0f, max_x);
-    mouse_y_ = std::clamp(mouse_y_ + delta_y, 0.0f, max_y);
+    HoldPointerLocked(transform);
   } else {
+    const float max_x = std::max(0.0F, transform.guest_width() - 1.0F);
+    const float max_y = std::max(0.0F, transform.guest_height() - 1.0F);
     mouse_x_ = std::clamp(transform.HostLogicalToGuestX(event.x), 0.0f, max_x);
     mouse_y_ = std::clamp(transform.HostLogicalToGuestY(event.y), 0.0f, max_y);
+    pointer_anchored_ = true;
   }
 
   // Raw mouse reports the host's own delta, skipping the guest-surface scale
@@ -590,19 +591,21 @@ RobloxInputDispatchResult RobloxInputRouter::HandleMouseButtonLocked(
                   RobloxInputEventKind::kMouseButton,
                   Unsupported("SDL mouse button has no Android mapping"));
   }
-  if (event.x > 0.0f || event.y > 0.0f ||
-      (mouse_x_ == 0.0f && mouse_y_ == 0.0f)) {
-    const platform::SurfaceCoordinateTransform transform =
-        CoordinateTransform(snapshot_.viewport);
-    mouse_x_ = transform.HostLogicalToGuestX(event.x);
-    mouse_y_ = transform.HostLogicalToGuestY(event.y);
-  }
   const platform::SurfaceCoordinateTransform transform =
       CoordinateTransform(snapshot_.viewport);
   const float max_x = std::max(0.0F, transform.guest_width() - 1.0F);
   const float max_y = std::max(0.0F, transform.guest_height() - 1.0F);
-  const float clamped_x = std::clamp(mouse_x_, 0.0f, max_x);
-  const float clamped_y = std::clamp(mouse_y_, 0.0f, max_y);
+  // Button events during pointer capture carry zero coordinates and must not
+  // move the held position.
+  if (event.x > 0.0f || event.y > 0.0f) {
+    mouse_x_ = std::clamp(transform.HostLogicalToGuestX(event.x), 0.0f, max_x);
+    mouse_y_ = std::clamp(transform.HostLogicalToGuestY(event.y), 0.0f, max_y);
+    pointer_anchored_ = true;
+  } else {
+    HoldPointerLocked(transform);
+  }
+  const float clamped_x = mouse_x_;
+  const float clamped_y = mouse_y_;
   if (event.pressed) {
     const RobloxTextEditorSnapshot text = text_editor_.Snapshot();
     if (text.focused) {
@@ -635,13 +638,38 @@ RobloxInputDispatchResult RobloxInputRouter::HandleMouseWheelLocked(
   }
   const platform::SurfaceCoordinateTransform transform =
       CoordinateTransform(snapshot_.viewport);
-  mouse_x_ = transform.HostLogicalToGuestX(std::max(0.0f, event.mouse_x));
-  mouse_y_ = transform.HostLogicalToGuestY(std::max(0.0f, event.mouse_y));
+  // Wheel events during pointer capture carry zero coordinates and must not
+  // move the held position.
+  if (event.mouse_x > 0.0f || event.mouse_y > 0.0f) {
+    const float max_x = std::max(0.0F, transform.guest_width() - 1.0F);
+    const float max_y = std::max(0.0F, transform.guest_height() - 1.0F);
+    mouse_x_ = std::clamp(transform.HostLogicalToGuestX(event.mouse_x), 0.0f,
+                          max_x);
+    mouse_y_ = std::clamp(transform.HostLogicalToGuestY(event.mouse_y), 0.0f,
+                          max_y);
+    pointer_anchored_ = true;
+  } else {
+    HoldPointerLocked(transform);
+  }
   return NativeResultLocked(
       sink_.mouse_wheel(sink_.context, mouse_x_, mouse_y_, event.delta_y),
       RobloxInputEventKind::kMouseWheel);
 }
 
+void RobloxInputRouter::HoldPointerLocked(
+    const platform::SurfaceCoordinateTransform& transform) {
+  const float max_x = std::max(0.0F, transform.guest_width() - 1.0F);
+  const float max_y = std::max(0.0F, transform.guest_height() - 1.0F);
+  if (!pointer_anchored_) {
+    mouse_x_ = max_x / 2.0f;
+    mouse_y_ = max_y / 2.0f;
+    pointer_anchored_ = true;
+    return;
+  }
+  mouse_x_ = std::clamp(mouse_x_, 0.0f, max_x);
+  mouse_y_ = std::clamp(mouse_y_, 0.0f, max_y);
+}
+
 RobloxInputDispatchResult RobloxInputRouter::HandleTouchLocked(
     const platform::TouchEvent& event) {
   if (sink_.touch == nullptr) {

src/runtime/runtime_config.cc

@@ -8,6 +8,7 @@
 #include <climits>
 #include <cstdlib>
 #include <optional>
+#include <tuple>
 
 #ifndef MOCKTAIL_DISCORD_APPLICATION_ID
 #define MOCKTAIL_DISCORD_APPLICATION_ID ""
@@ -40,13 +41,17 @@ bool IsDiscordApplicationId(std::string_view value) {
           }));
 }
 
-bool IsDiscordText(std::string_view value, std::size_t maximum) {
-  return !value.empty() && value.size() <= maximum &&
+bool IsDiscordOptionalText(std::string_view value, std::size_t maximum) {
+  return value.size() <= maximum &&
          std::none_of(value.begin(), value.end(), [](unsigned char byte) {
            return byte < 0x20 || byte == 0x7f;
          });
 }
 
+bool IsDiscordText(std::string_view value, std::size_t maximum) {
+  return !value.empty() && IsDiscordOptionalText(value, maximum);
+}
+
 bool ReadBoolean(const Environment& environment, std::string_view name,
                  bool default_value, bool* valid) {
   const std::optional<std::string> value = environment.Get(name);
@@ -357,18 +362,40 @@ RuntimeConfig RuntimeConfig::FromEnvironment(const Environment& environment) {
       "MOCKTAIL_DISCORD_RPC_TEXT_JOINING", config.discord_rpc_.text.joining);
   config.discord_rpc_.text.playing = environment.GetOr(
       "MOCKTAIL_DISCORD_RPC_TEXT_PLAYING", config.discord_rpc_.text.playing);
-  config.discord_rpc_.text.state = environment.GetOr(
-      "MOCKTAIL_DISCORD_RPC_TEXT_STATE", config.discord_rpc_.text.state);
   config.discord_rpc_.text.unknown_place = environment.GetOr(
       "MOCKTAIL_DISCORD_RPC_TEXT_UNKNOWN_PLACE",
       config.discord_rpc_.text.unknown_place);
-  config.discord_rpc_valid_ = discord_booleans_valid &&
+  // An empty presence field hides it, so only an unset variable keeps the
+  // default.
+  bool discord_presence_valid = true;
+  for (const auto& [variable, field, maximum] : {
+           std::tuple<std::string_view, std::string*, std::size_t>(
+               "MOCKTAIL_DISCORD_RPC_TEXT_TITLE",
+               &config.discord_rpc_.text.title, 128),
+           {"MOCKTAIL_DISCORD_RPC_TEXT_STATE",
+            &config.discord_rpc_.text.state, 128},
+           {"MOCKTAIL_DISCORD_RPC_IMAGE_LARGE",
+            &config.discord_rpc_.images.large, 512},
+           {"MOCKTAIL_DISCORD_RPC_IMAGE_LARGE_TEXT",
+            &config.discord_rpc_.images.large_text, 128},
+           {"MOCKTAIL_DISCORD_RPC_IMAGE_SMALL",
+            &config.discord_rpc_.images.small, 512},
+           {"MOCKTAIL_DISCORD_RPC_IMAGE_SMALL_TEXT",
+            &config.discord_rpc_.images.small_text, 128},
+       }) {
+    if (std::optional<std::string> value = environment.Get(variable)) {
+      *field = std::move(*value);
+    }
+    discord_presence_valid =
+        discord_presence_valid && IsDiscordOptionalText(*field, maximum);
+  }
+  config.discord_rpc_valid_ =
+      discord_booleans_valid && discord_presence_valid &&
       IsDiscordApplicationId(config.discord_rpc_.application_id) &&
       IsDiscordText(config.discord_rpc_.join_button_label, 32) &&
       IsDiscordText(config.discord_rpc_.text.browsing, 128) &&
       IsDiscordText(config.discord_rpc_.text.joining, 128) &&
       IsDiscordText(config.discord_rpc_.text.playing, 128) &&
-      IsDiscordText(config.discord_rpc_.text.state, 128) &&
       IsDiscordText(config.discord_rpc_.text.unknown_place, 128);
   for (const std::string_view name : kUnsafeDetachedThreadOverrides) {
     if (LegacyEnabled(environment, name)) {

src/runtime/runtime_config_bootstrap.cc

@@ -131,12 +131,24 @@ integrations:
       public_servers_only: true
       # button_label: Join Server
     # English defaults. Uncomment only the lines you want to customize.
+    # Text and image fields accept {place_name}, {place_icon}, and
+    # {creator_name}. A field that expands an empty placeholder is left out,
+    # and a "" title shows the app name.
+    # title, state, and the images fields may be "" to hide them.
     # text:
     #   browsing: Browsing experiences
     #   joining: Joining an experience
-    #   playing: "{place_name}"
-    #   state: Playing Roblox
+    #   playing: "Playing {place_name}"
+    #   state: "by {creator_name}"
     #   unknown_place: Unknown experience
+    #   title: Roblox
+    # Images take an https:// URL, or an asset key uploaded to application_id.
+    # large: "" hides both images; the small image needs a large one.
+    # images:
+    #   large: "{place_icon}"
+    #   large_text: "{place_name}"
+    #   small: roblox_small
+    #   small_text: Roblox
     # Advanced: overrides the application bundled by the package maintainer.
     # application_id: 123456789012345678
 

src/runtime/runtime_config_file.cc

@@ -205,6 +205,11 @@ bool ValidateAndMap(const ValueMap& yaml, ValueMap* environment,
       "integrations.discord_rpc.text.playing",
       "integrations.discord_rpc.text.state",
       "integrations.discord_rpc.text.unknown_place",
+      "integrations.discord_rpc.text.title",
+      "integrations.discord_rpc.images.large",
+      "integrations.discord_rpc.images.large_text",
+      "integrations.discord_rpc.images.small",
+      "integrations.discord_rpc.images.small_text",
   };
   for (const auto& [key, ignored] : yaml) {
     if (supported.find(key) == supported.end()) {
@@ -554,8 +559,6 @@ bool ValidateAndMap(const ValueMap& yaml, ValueMap* environment,
             "MOCKTAIL_DISCORD_RPC_TEXT_JOINING", 128},
            {"integrations.discord_rpc.text.playing",
             "MOCKTAIL_DISCORD_RPC_TEXT_PLAYING", 128},
-           {"integrations.discord_rpc.text.state",
-            "MOCKTAIL_DISCORD_RPC_TEXT_STATE", 128},
            {"integrations.discord_rpc.text.unknown_place",
             "MOCKTAIL_DISCORD_RPC_TEXT_UNKNOWN_PLACE", 128},
        }) {
@@ -574,6 +577,36 @@ bool ValidateAndMap(const ValueMap& yaml, ValueMap* environment,
     }
     (*environment)[std::string(field.variable)] = *configured;
   }
+  // Presence fields may be empty: an empty value hides that field.
+  for (const DiscordStringField& field : {
+           DiscordStringField{"integrations.discord_rpc.text.title",
+                              "MOCKTAIL_DISCORD_RPC_TEXT_TITLE", 128},
+           {"integrations.discord_rpc.text.state",
+            "MOCKTAIL_DISCORD_RPC_TEXT_STATE", 128},
+           {"integrations.discord_rpc.images.large",
+            "MOCKTAIL_DISCORD_RPC_IMAGE_LARGE", 512},
+           {"integrations.discord_rpc.images.large_text",
+            "MOCKTAIL_DISCORD_RPC_IMAGE_LARGE_TEXT", 128},
+           {"integrations.discord_rpc.images.small",
+            "MOCKTAIL_DISCORD_RPC_IMAGE_SMALL", 512},
+           {"integrations.discord_rpc.images.small_text",
+            "MOCKTAIL_DISCORD_RPC_IMAGE_SMALL_TEXT", 128},
+       }) {
+    const std::optional<std::string> configured = value(field.yaml);
+    if (!configured.has_value()) {
+      continue;
+    }
+    if (configured->size() > field.maximum ||
+        std::any_of(configured->begin(), configured->end(),
+                    [](unsigned char byte) {
+                      return byte < 0x20 || byte == 0x7f;
+                    })) {
+      *error = std::string(field.yaml) +
+               " must be bounded and contain no control bytes";
+      return false;
+    }
+    (*environment)[std::string(field.variable)] = *configured;
+  }
   return true;
 }
 
@@ -940,7 +973,17 @@ bool ExportRuntimeConfigEnvironment(const RuntimeConfig& config,
       SetEnvironmentValue("MOCKTAIL_DISCORD_RPC_TEXT_STATE",
                           config.discord_rpc().text.state, error) &&
       SetEnvironmentValue("MOCKTAIL_DISCORD_RPC_TEXT_UNKNOWN_PLACE",
-                          config.discord_rpc().text.unknown_place, error);
+                          config.discord_rpc().text.unknown_place, error) &&
+      SetEnvironmentValue("MOCKTAIL_DISCORD_RPC_TEXT_TITLE",
+                          config.discord_rpc().text.title, error) &&
+      SetEnvironmentValue("MOCKTAIL_DISCORD_RPC_IMAGE_LARGE",
+                          config.discord_rpc().images.large, error) &&
+      SetEnvironmentValue("MOCKTAIL_DISCORD_RPC_IMAGE_LARGE_TEXT",
+                          config.discord_rpc().images.large_text, error) &&
+      SetEnvironmentValue("MOCKTAIL_DISCORD_RPC_IMAGE_SMALL",
+                          config.discord_rpc().images.small, error) &&
+      SetEnvironmentValue("MOCKTAIL_DISCORD_RPC_IMAGE_SMALL_TEXT",
+                          config.discord_rpc().images.small_text, error);
   if (!base_exported) {
     return false;
   }

stubs/CMakeLists.txt

@@ -106,6 +106,7 @@ target_link_libraries(stub_glesv2 PRIVATE dl)
 # The host Vulkan loader owns device commands; this target adapts Android WSI.
 add_library(stub_vulkan SHARED
   ${CMAKE_SOURCE_DIR}/src/graphics/bionic_vulkan_loader_adapter.cc
+  ${CMAKE_SOURCE_DIR}/src/graphics/chrome_trace_writer.cc
   ${CMAKE_SOURCE_DIR}/src/graphics/vulkan_text_overlay_compositor.cc
   ${CMAKE_SOURCE_DIR}/src/graphics/vulkan_etc2_emulation.cc
   ${CMAKE_SOURCE_DIR}/src/graphics/etc2_decoder.cc

tests/CMakeLists.txt

@@ -208,6 +208,13 @@ target_link_libraries(external_launch_broker_test PRIVATE
 )
 mocktail_apply_compile_options(external_launch_broker_test)
 
+add_executable(engine_pump_rest_test engine_pump_rest_test.cc)
+target_link_libraries(engine_pump_rest_test PRIVATE
+  Mocktail::Runtime
+  GTest::gtest_main
+)
+mocktail_apply_compile_options(engine_pump_rest_test)
+
 add_executable(supported_launch_policy_test supported_launch_policy_test.cc)
 target_link_libraries(supported_launch_policy_test PRIVATE
   Mocktail::Runtime
@@ -454,6 +461,16 @@ target_link_libraries(input_pump_pacer_test PRIVATE
 )
 mocktail_apply_compile_options(input_pump_pacer_test)
 
+add_executable(input_pump_pacing_runtime_test
+  input_pump_pacing_runtime_test.cc
+)
+target_link_libraries(input_pump_pacing_runtime_test PRIVATE
+  mocktail_window
+  GTest::gtest_main
+  Threads::Threads
+)
+mocktail_apply_compile_options(input_pump_pacing_runtime_test)
+
 add_executable(vulkan_surface_recovery_gate_test
   vulkan_surface_recovery_gate_test.cc
 )
@@ -513,9 +530,21 @@ target_link_libraries(texture_override_test PRIVATE GTest::gtest_main
   PkgConfig::LIBPNG)
 mocktail_apply_compile_options(texture_override_test)
 
+add_executable(chrome_trace_writer_test
+  chrome_trace_writer_test.cc
+  ${PROJECT_SOURCE_DIR}/src/graphics/chrome_trace_writer.cc
+)
+target_include_directories(chrome_trace_writer_test PRIVATE
+  ${PROJECT_SOURCE_DIR}/include
+)
+target_link_libraries(chrome_trace_writer_test PRIVATE GTest::gtest_main
+  Threads::Threads nlohmann_json::nlohmann_json)
+mocktail_apply_compile_options(chrome_trace_writer_test)
+
 add_executable(vulkan_etc2_emulation_test
   vulkan_etc2_emulation_test.cc
   ${PROJECT_SOURCE_DIR}/src/graphics/vulkan_etc2_emulation.cc
+  ${PROJECT_SOURCE_DIR}/src/graphics/chrome_trace_writer.cc
   ${PROJECT_SOURCE_DIR}/src/graphics/etc2_decoder.cc
   ${PROJECT_SOURCE_DIR}/src/graphics/texture_override.cc
 )
@@ -964,6 +993,7 @@ gtest_discover_tests(browser_tracker_service_test)
 gtest_discover_tests(command_line_test)
 gtest_discover_tests(roblox_launch_uri_test)
 gtest_discover_tests(external_launch_broker_test)
+gtest_discover_tests(engine_pump_rest_test)
 gtest_discover_tests(webview_helper_launcher_test)
 gtest_discover_tests(webview_helper_policy_test)
 gtest_discover_tests(webview_roblox_cookie_test)
@@ -985,10 +1015,12 @@ gtest_discover_tests(jnivm_native_text_box_info_test)
 gtest_discover_tests(jnivm_webrtc_audio_manager_test)
 gtest_discover_tests(vulkan_present_observer_test)
 gtest_discover_tests(input_pump_pacer_test)
+gtest_discover_tests(input_pump_pacing_runtime_test)
 gtest_discover_tests(vulkan_surface_recovery_gate_test)
 gtest_discover_tests(vulkan_present_progress_gate_test)
 gtest_discover_tests(vulkan_text_overlay_compositor_test)
 gtest_discover_tests(etc2_decoder_test)
+gtest_discover_tests(chrome_trace_writer_test)
 gtest_discover_tests(vulkan_etc2_emulation_test)
 gtest_discover_tests(video_driver_policy_test)
 gtest_discover_tests(window_surface_lifecycle_test)

tests/chrome_trace_writer_test.cc

@@ -0,0 +1,317 @@
+#include "mocktail/graphics/chrome_trace_writer.h"
+
+#include <gtest/gtest.h>
+#include <signal.h>
+#include <sys/resource.h>
+#include <unistd.h>
+
+#include <chrono>
+#include <cstdlib>
+#include <filesystem>
+#include <fstream>
+#include <nlohmann/json.hpp>
+#include <set>
+#include <sstream>
+#include <string>
+#include <thread>
+#include <vector>
+
+namespace mocktail {
+namespace graphics {
+namespace {
+
+class TemporaryDirectory final {
+ public:
+  TemporaryDirectory() {
+    char pattern[] = "/tmp/mocktail_chrome_trace_XXXXXX";
+    const char* created = mkdtemp(pattern);
+    if (created != nullptr) root_ = created;
+  }
+
+  ~TemporaryDirectory() {
+    std::error_code error;
+    std::filesystem::remove_all(root_, error);
+  }
+
+  const std::filesystem::path& root() const { return root_; }
+
+ private:
+  std::filesystem::path root_;
+};
+
+std::string ReadFile(const std::filesystem::path& path) {
+  std::ifstream input(path, std::ios::binary);
+  std::ostringstream content;
+  content << input.rdbuf();
+  return content.str();
+}
+
+nlohmann::json ParseTrace(const std::filesystem::path& path) {
+  return nlohmann::json::parse(ReadFile(path));
+}
+
+std::unique_ptr<ChromeTraceWriter> OpenOrFail(
+    const std::filesystem::path& path) {
+  std::string error;
+  auto writer = ChromeTraceWriter::Open(path, &error);
+  EXPECT_NE(writer, nullptr) << error;
+  return writer;
+}
+
+TEST(ChromeTraceWriterTest, WritesSliceAsCompleteEventInMicroseconds) {
+  TemporaryDirectory directory;
+  const auto path = directory.root() / "trace.json";
+  auto writer = OpenOrFail(path);
+  ASSERT_NE(writer, nullptr);
+
+  writer->Slice("vkQueuePresentKHR", "present", 5'000'123'456ULL,
+                5'002'623'456ULL, {{"frame", 7}, {"result", -4}});
+  writer->Close();
+
+  const nlohmann::json trace = ParseTrace(path);
+  ASSERT_TRUE(trace.is_array());
+  ASSERT_EQ(trace.size(), 1u);
+  const nlohmann::json& event = trace[0];
+  EXPECT_EQ(event["name"], "vkQueuePresentKHR");
+  EXPECT_EQ(event["cat"], "present");
+  EXPECT_EQ(event["ph"], "X");
+  EXPECT_EQ(event["ts"], 5'000'123);
+  EXPECT_EQ(event["dur"], 2'500);
+  EXPECT_EQ(event["pid"], static_cast<int>(getpid()));
+  EXPECT_EQ(event["tid"], static_cast<int>(gettid()));
+  EXPECT_EQ(event["args"]["frame"], 7);
+  EXPECT_EQ(event["args"]["result"], -4);
+}
+
+TEST(ChromeTraceWriterTest, WritesCounterSample) {
+  TemporaryDirectory directory;
+  const auto path = directory.root() / "trace.json";
+  auto writer = OpenOrFail(path);
+  ASSERT_NE(writer, nullptr);
+
+  writer->Counter("frame interval (ms)", 9'000'000ULL, 16.5);
+  writer->Close();
+
+  const nlohmann::json trace = ParseTrace(path);
+  ASSERT_EQ(trace.size(), 1u);
+  EXPECT_EQ(trace[0]["name"], "frame interval (ms)");
+  EXPECT_EQ(trace[0]["ph"], "C");
+  EXPECT_EQ(trace[0]["ts"], 9'000);
+  EXPECT_DOUBLE_EQ(trace[0]["args"]["value"].get<double>(), 16.5);
+}
+
+TEST(ChromeTraceWriterTest, EmptyTraceIsAnEmptyArray) {
+  TemporaryDirectory directory;
+  const auto path = directory.root() / "trace.json";
+  auto writer = OpenOrFail(path);
+  ASSERT_NE(writer, nullptr);
+
+  writer->Close();
+
+  EXPECT_EQ(ParseTrace(path), nlohmann::json::array());
+}
+
+TEST(ChromeTraceWriterTest, EscapesNames) {
+  TemporaryDirectory directory;
+  const auto path = directory.root() / "trace.json";
+  auto writer = OpenOrFail(path);
+  ASSERT_NE(writer, nullptr);
+
+  writer->Slice("say \"hi\"\\now", "c\ta", 0, 1000);
+  writer->Close();
+
+  const nlohmann::json trace = ParseTrace(path);
+  ASSERT_EQ(trace.size(), 1u);
+  EXPECT_EQ(trace[0]["name"], "say \"hi\"\\now");
+  EXPECT_EQ(trace[0]["cat"], "c\ta");
+}
+
+TEST(ChromeTraceWriterTest, FileIsValidJsonBetweenWrites) {
+  TemporaryDirectory directory;
+  const auto path = directory.root() / "trace.json";
+  auto writer = OpenOrFail(path);
+  ASSERT_NE(writer, nullptr);
+
+  // A session killed at any of these points leaves a loadable trace.
+  EXPECT_EQ(ParseTrace(path), nlohmann::json::array());
+  writer->Slice("first", "test", 1000, 2000);
+  writer->Flush();
+  EXPECT_EQ(ParseTrace(path).size(), 1u);
+  writer->Slice("second", "test", 3000, 4000);
+  writer->Flush();
+
+  const nlohmann::json trace = ParseTrace(path);
+  ASSERT_EQ(trace.size(), 2u);
+  EXPECT_EQ(trace[0]["name"], "first");
+  EXPECT_EQ(trace[1]["name"], "second");
+  writer->Close();
+  EXPECT_EQ(ParseTrace(path), trace);
+}
+
+TEST(ChromeTraceWriterTest, DropsEventsAfterClose) {
+  TemporaryDirectory directory;
+  const auto path = directory.root() / "trace.json";
+  auto writer = OpenOrFail(path);
+  ASSERT_NE(writer, nullptr);
+
+  writer->Slice("kept", "test", 0, 1);
+  writer->Close();
+  writer->Slice("dropped", "test", 2, 3);
+  writer->Counter("dropped", 4, 1.0);
+  writer->Flush();
+  writer->Close();
+
+  const nlohmann::json trace = ParseTrace(path);
+  ASSERT_EQ(trace.size(), 1u);
+  EXPECT_EQ(trace[0]["name"], "kept");
+}
+
+TEST(ChromeTraceWriterTest, KeepsEveryEventFromConcurrentThreads) {
+  TemporaryDirectory directory;
+  const auto path = directory.root() / "trace.json";
+  auto writer = OpenOrFail(path);
+  ASSERT_NE(writer, nullptr);
+
+  constexpr int kThreads = 8;
+  constexpr int kEventsPerThread = 20'000;
+  std::vector<std::thread> threads;
+  for (int thread = 0; thread < kThreads; ++thread) {
+    threads.emplace_back([&writer, thread] {
+      for (int event = 0; event < kEventsPerThread; ++event) {
+        writer->Slice("work", "test", 1000, 2000,
+                      {{"thread", thread}, {"event", event}});
+      }
+    });
+  }
+  for (std::thread& thread : threads) {
+    thread.join();
+  }
+  writer->Close();
+
+  const nlohmann::json trace = ParseTrace(path);
+  ASSERT_EQ(trace.size(), static_cast<std::size_t>(kThreads) *
+                              kEventsPerThread);
+  std::set<std::pair<int, int>> seen;
+  std::set<int> tids;
+  for (const nlohmann::json& event : trace) {
+    seen.emplace(event["args"]["thread"].get<int>(),
+                 event["args"]["event"].get<int>());
+    tids.insert(event["tid"].get<int>());
+  }
+  EXPECT_EQ(seen.size(), trace.size());
+  EXPECT_EQ(tids.size(), static_cast<std::size_t>(kThreads));
+}
+
+TEST(ChromeTraceWriterTest, DestructorClosesTheArray) {
+  TemporaryDirectory directory;
+  const auto path = directory.root() / "trace.json";
+  {
+    auto writer = OpenOrFail(path);
+    ASSERT_NE(writer, nullptr);
+    writer->Slice("only", "test", 0, 1000);
+  }
+  EXPECT_EQ(ParseTrace(path).size(), 1u);
+}
+
+TEST(ChromeTraceWriterTest, OpenReportsUnwritablePath) {
+  TemporaryDirectory directory;
+  std::string error;
+
+  const auto writer = ChromeTraceWriter::Open(
+      directory.root() / "missing" / "trace.json", &error);
+
+  EXPECT_EQ(writer, nullptr);
+  EXPECT_NE(error.find("missing"), std::string::npos) << error;
+}
+
+TEST(ChromeTraceWriterTest, OpenCreatesOrTruncatesTheFile) {
+  TemporaryDirectory directory;
+  const auto path = directory.root() / "trace.json";
+  std::ofstream(path) << "stale content that is not json";
+
+  auto writer = OpenOrFail(path);
+  ASSERT_NE(writer, nullptr);
+  writer->Close();
+
+  EXPECT_EQ(ParseTrace(path), nlohmann::json::array());
+}
+
+TEST(ChromeTraceWriterTest, ScopeRecordsItsLifetimeAndArgs) {
+  TemporaryDirectory directory;
+  const auto path = directory.root() / "trace.json";
+  auto writer = OpenOrFail(path);
+  ASSERT_NE(writer, nullptr);
+
+  const std::uint64_t before = TraceClockNanos();
+  {
+    TraceScope scope(writer.get(), "scoped", "test");
+    scope.Arg("count", 3);
+    std::this_thread::sleep_for(std::chrono::milliseconds(2));
+  }
+  const std::uint64_t after = TraceClockNanos();
+  writer->Close();
+
+  const nlohmann::json trace = ParseTrace(path);
+  ASSERT_EQ(trace.size(), 1u);
+  const auto ts = trace[0]["ts"].get<std::uint64_t>();
+  const auto dur = trace[0]["dur"].get<std::uint64_t>();
+  EXPECT_GE(ts, before / 1000);
+  EXPECT_GE(dur, 2'000u);
+  EXPECT_LE(ts + dur, after / 1000 + 1);
+  EXPECT_EQ(trace[0]["args"]["count"], 3);
+}
+
+TEST(ChromeTraceWriterTest, ScopeWithoutWriterRecordsNothing) {
+  TraceScope scope(nullptr, "unused", "test");
+  scope.Arg("ignored", 1);
+}
+
+std::size_t ThreadCount() {
+  return static_cast<std::size_t>(
+      std::distance(std::filesystem::directory_iterator("/proc/self/task"),
+                    std::filesystem::directory_iterator()));
+}
+
+// A failed write closes the trace, so the writer thread has nothing left to
+// do and exits instead of ticking for the rest of the process.
+TEST(ChromeTraceWriterTest, WriterThreadExitsAfterAWriteFailure) {
+  TemporaryDirectory directory;
+  const auto path = directory.root() / "trace.json";
+  const std::size_t idle_threads = ThreadCount();
+  auto writer = OpenOrFail(path);
+  ASSERT_NE(writer, nullptr);
+  ASSERT_EQ(ThreadCount(), idle_threads + 1);
+
+  // With SIGXFSZ ignored, a write past RLIMIT_FSIZE fails with EFBIG.
+  struct sigaction ignore {};
+  ignore.sa_handler = SIG_IGN;
+  struct sigaction saved_action {};
+  ASSERT_EQ(sigaction(SIGXFSZ, &ignore, &saved_action), 0);
+  rlimit saved_limit{};
+  ASSERT_EQ(getrlimit(RLIMIT_FSIZE, &saved_limit), 0);
+  rlimit no_growth = saved_limit;
+  no_growth.rlim_cur = 0;
+  ASSERT_EQ(setrlimit(RLIMIT_FSIZE, &no_growth), 0);
+  writer->Slice("lost", "test", 0, 1);
+  writer->Flush();
+  EXPECT_EQ(setrlimit(RLIMIT_FSIZE, &saved_limit), 0);
+  EXPECT_EQ(sigaction(SIGXFSZ, &saved_action, nullptr), 0);
+
+  const auto deadline =
+      std::chrono::steady_clock::now() + std::chrono::seconds(2);
+  while (ThreadCount() != idle_threads &&
+         std::chrono::steady_clock::now() < deadline) {
+    std::this_thread::sleep_for(std::chrono::milliseconds(5));
+  }
+  EXPECT_EQ(ThreadCount(), idle_threads);
+  writer->Close();
+}
+
+TEST(ChromeTraceWriterTest, ActiveProfileTraceIsOffWithoutEnvironment) {
+  ASSERT_EQ(std::getenv(kProfileTraceEnvironment), nullptr);
+  EXPECT_EQ(ActiveProfileTrace(), nullptr);
+}
+
+}  // namespace
+}  // namespace graphics
+}  // namespace mocktail

tests/command_line_test.cc

@@ -4,6 +4,8 @@
 
 #include <algorithm>
 #include <array>
+#include <cstdlib>
+#include <filesystem>
 #include <string>
 #include <vector>
 
@@ -160,6 +162,42 @@ TEST(CommandLineTest, ScrubsInternalLaunchDocumentFromOwnedAndProcessArgv) {
                           [](char byte) { return byte == '\0'; }));
 }
 
+TEST(CommandLineTest, ParsesProfileTracePath) {
+  const std::array<const char*, 3> arguments = {"mocktail", "--profile",
+                                                "/traces/session.json"};
+
+  const CommandLineParseResult result =
+      ParseCommandLine(arguments.size(), arguments.data());
+
+  ASSERT_TRUE(result) << result.error;
+  EXPECT_EQ(result.options.profile_trace_path, "/traces/session.json");
+}
+
+TEST(CommandLineTest, AppliesProfileTraceAsAbsolutePath) {
+  unsetenv("MOCKTAIL_PROFILE_TRACE");
+  CommandLineOptions options;
+  options.profile_trace_path = "session.json";
+  std::string error;
+
+  ASSERT_TRUE(ApplyCommandLineEnvironment(options, &error)) << error;
+
+  const char* applied = std::getenv("MOCKTAIL_PROFILE_TRACE");
+  ASSERT_NE(applied, nullptr);
+  EXPECT_EQ(std::string(applied),
+            (std::filesystem::current_path() / "session.json").string());
+  unsetenv("MOCKTAIL_PROFILE_TRACE");
+}
+
+TEST(CommandLineTest, LeavesProfileTraceUnsetWithoutOption) {
+  unsetenv("MOCKTAIL_PROFILE_TRACE");
+  std::string error;
+
+  ASSERT_TRUE(ApplyCommandLineEnvironment(CommandLineOptions{}, &error))
+      << error;
+
+  EXPECT_EQ(std::getenv("MOCKTAIL_PROFILE_TRACE"), nullptr);
+}
+
 TEST(CommandLineTest, RejectsUnsupportedPositionalArgument) {
   const std::array<const char*, 2> arguments = {"mocktail", "/tmp/payload"};
 
@@ -182,7 +220,7 @@ TEST(CommandLineTest, RejectsUnknownOptionBeforeRuntimeWork) {
 
 TEST(CommandLineTest, RejectsEveryMissingValue) {
   for (const char* option :
-       {"--roblox-lib", "--graphics", "--launch-uri"}) {
+       {"--roblox-lib", "--graphics", "--launch-uri", "--profile"}) {
     const std::array<const char*, 2> arguments = {"mocktail", option};
     const CommandLineParseResult result =
         ParseCommandLine(arguments.size(), arguments.data());
@@ -268,7 +306,7 @@ TEST(CommandLineTest, UsageContainsEverySupportedOption) {
   for (const char* option :
        {"--roblox-lib", "--headless", "--windowed", "--graphics",
         "--allow-unverified-build", "--force-run-latest", "--launch-uri",
-        "--help"}) {
+        "--profile", "--help"}) {
     EXPECT_NE(usage.find(option), std::string::npos) << option;
   }
   EXPECT_EQ(usage.find("--login"), std::string::npos);

tests/discord_rpc_test.cc

@@ -79,8 +79,9 @@ TEST(DiscordRpcTest, BuildsEnglishBrowsingAndJoiningActivities) {
 
   const DiscordRpcActivity browsing = BuildDiscordRpcActivity(
       config, RobloxExperiencePresencePhase::kBrowsing, nullptr, {}, 0);
+  EXPECT_EQ(browsing.name, "Roblox");
   EXPECT_EQ(browsing.details, "Browsing experiences");
-  EXPECT_EQ(browsing.state, "Playing Roblox");
+  EXPECT_TRUE(browsing.state.empty());
   EXPECT_FALSE(browsing.start_timestamp.has_value());
   EXPECT_TRUE(browsing.button_url.empty());
 
@@ -88,7 +89,7 @@ TEST(DiscordRpcTest, BuildsEnglishBrowsingAndJoiningActivities) {
   const DiscordRpcActivity joining = BuildDiscordRpcActivity(
       config, RobloxExperiencePresencePhase::kJoining, &request, {}, 0);
   EXPECT_EQ(joining.details, "Joining an experience");
-  EXPECT_EQ(joining.state, "Playing Roblox");
+  EXPECT_TRUE(joining.state.empty());
   EXPECT_TRUE(joining.button_url.empty());
 }
 
@@ -107,10 +108,11 @@ TEST(DiscordRpcTest, ShowsPlaceTimerAndPublicJoinWhenPlaying) {
 
   const DiscordRpcActivity activity = BuildDiscordRpcActivity(
       config, RobloxExperiencePresencePhase::kPlaying, &request,
-      "Natural Disaster Survival", 1770000000);
+      "Natural Disaster Survival", 1770000000, {}, "Stickmasterluke");
 
-  EXPECT_EQ(activity.details, "Natural Disaster Survival");
-  EXPECT_EQ(activity.state, "Playing Roblox");
+  EXPECT_EQ(activity.name, "Roblox");
+  EXPECT_EQ(activity.details, "Playing Natural Disaster Survival");
+  EXPECT_EQ(activity.state, "by Stickmasterluke");
   ASSERT_TRUE(activity.start_timestamp.has_value());
   EXPECT_EQ(*activity.start_timestamp, 1770000000);
   EXPECT_EQ(activity.button_label, "Join Server");
@@ -119,6 +121,30 @@ TEST(DiscordRpcTest, ShowsPlaceTimerAndPublicJoinWhenPlaying) {
             "189707&gameInstanceId=job%2Fa%2Bb");
 }
 
+TEST(DiscordRpcTest, LeavesOutTextThatExpandsAnEmptyCreator) {
+  const RobloxExperienceLaunchRequest request = PublicServer();
+
+  const DiscordRpcActivity unknown_creator = BuildDiscordRpcActivity(
+      DiscordRpcConfig(), RobloxExperiencePresencePhase::kPlaying, &request,
+      "Natural Disaster Survival", 1);
+  EXPECT_EQ(unknown_creator.details, "Playing Natural Disaster Survival");
+  EXPECT_TRUE(unknown_creator.state.empty());
+
+  DiscordRpcConfig custom;
+  custom.text.state = "by {creator_name} on Linux";
+  EXPECT_TRUE(BuildDiscordRpcActivity(custom,
+                                      RobloxExperiencePresencePhase::kPlaying,
+                                      &request, "Natural Disaster Survival",
+                                      1)
+                  .state.empty());
+  EXPECT_EQ(BuildDiscordRpcActivity(custom,
+                                    RobloxExperiencePresencePhase::kPlaying,
+                                    &request, "Natural Disaster Survival", 1,
+                                    {}, "Stickmasterluke")
+                .state,
+            "by Stickmasterluke on Linux");
+}
+
 TEST(DiscordRpcTest, ShowsExternalPlaceThumbnailWhenAvailable) {
   const DiscordRpcConfig config;
   const RobloxExperienceLaunchRequest request = PublicServer();
@@ -130,6 +156,8 @@ TEST(DiscordRpcTest, ShowsExternalPlaceThumbnailWhenAvailable) {
   EXPECT_EQ(activity.large_image,
             "https://tr.rbxcdn.com/example/512/512/Image/Png");
   EXPECT_EQ(activity.large_text, "Natural Disaster Survival");
+  EXPECT_EQ(activity.small_image, "roblox_small");
+  EXPECT_EQ(activity.small_text, "Roblox");
 }
 
 TEST(DiscordRpcTest, ShowsPlaceJoinWhenServerIdIsUnavailable) {
@@ -191,12 +219,20 @@ TEST(DiscordRpcTest, HidesPlaceNameAndElapsedTimeByPolicy) {
   config.join_enabled = false;
 
   const RobloxExperienceLaunchRequest request = PublicServer();
-  const DiscordRpcActivity activity =
-      BuildDiscordRpcActivity(config, RobloxExperiencePresencePhase::kPlaying,
-                              &request, "Secret place name", 1770000000);
+  const DiscordRpcActivity activity = BuildDiscordRpcActivity(
+      config, RobloxExperiencePresencePhase::kPlaying, &request,
+      "Secret place name", 1770000000, {}, "Secret creator");
 
-  EXPECT_EQ(activity.details, "Playing Roblox");
+  // The creator hides with the place, so the default state renders empty.
+  EXPECT_TRUE(activity.details.empty());
   EXPECT_TRUE(activity.state.empty());
+
+  config.text.state = "Playing Roblox";
+  const DiscordRpcActivity fixed_state = BuildDiscordRpcActivity(
+      config, RobloxExperiencePresencePhase::kPlaying, &request,
+      "Secret place name", 1770000000, {}, "Secret creator");
+  EXPECT_EQ(fixed_state.details, "Playing Roblox");
+  EXPECT_TRUE(fixed_state.state.empty());
   EXPECT_FALSE(activity.start_timestamp.has_value());
   EXPECT_TRUE(activity.button_url.empty());
 }
@@ -219,6 +255,99 @@ TEST(DiscordRpcTest, ExpandsCustomPlaceTemplateAndUsesFallback) {
       "Playing Unknown world with Mocktail");
 }
 
+TEST(DiscordRpcTest, RendersCustomTitleAndStateTemplates) {
+  DiscordRpcConfig config;
+  config.text.title = "{place_name}";
+  config.text.state = "In {place_name}";
+  const RobloxExperienceLaunchRequest request = PublicServer();
+
+  const DiscordRpcActivity playing =
+      BuildDiscordRpcActivity(config, RobloxExperiencePresencePhase::kPlaying,
+                              &request, "Natural Disaster Survival", 1);
+  EXPECT_EQ(playing.name, "Natural Disaster Survival");
+  EXPECT_EQ(playing.state, "In Natural Disaster Survival");
+
+  const DiscordRpcActivity browsing = BuildDiscordRpcActivity(
+      config, RobloxExperiencePresencePhase::kBrowsing, nullptr, {}, 0);
+  EXPECT_TRUE(browsing.name.empty());
+}
+
+TEST(DiscordRpcTest, RendersCustomImagesWithPlaceholders) {
+  DiscordRpcConfig config;
+  config.images.large = "nightcap_logo";
+  config.images.large_text = "Nightcap";
+  config.images.small = "{place_icon}";
+  config.images.small_text = "{place_name}";
+  const RobloxExperienceLaunchRequest request = PublicServer();
+
+  const DiscordRpcActivity activity = BuildDiscordRpcActivity(
+      config, RobloxExperiencePresencePhase::kPlaying, &request,
+      "Natural Disaster Survival", 1,
+      "https://tr.rbxcdn.com/example/512/512/Image/Png");
+
+  EXPECT_EQ(activity.large_image, "nightcap_logo");
+  EXPECT_EQ(activity.large_text, "Nightcap");
+  EXPECT_EQ(activity.small_image,
+            "https://tr.rbxcdn.com/example/512/512/Image/Png");
+  EXPECT_EQ(activity.small_text, "Natural Disaster Survival");
+}
+
+TEST(DiscordRpcTest, EmptyLargeImageHidesBothImages) {
+  DiscordRpcConfig config;
+  config.images.large = "";
+  config.images.small = "nightcap_logo";
+  config.images.small_text = "Nightcap";
+  const RobloxExperienceLaunchRequest request = PublicServer();
+
+  const DiscordRpcActivity activity = BuildDiscordRpcActivity(
+      config, RobloxExperiencePresencePhase::kPlaying, &request,
+      "Natural Disaster Survival", 1,
+      "https://tr.rbxcdn.com/example/512/512/Image/Png");
+
+  EXPECT_TRUE(activity.large_image.empty());
+  EXPECT_TRUE(activity.large_text.empty());
+  EXPECT_TRUE(activity.small_image.empty());
+  EXPECT_TRUE(activity.small_text.empty());
+}
+
+TEST(DiscordRpcTest, DropsUnsafeCustomImages) {
+  const RobloxExperienceLaunchRequest request = PublicServer();
+  for (const char* unsafe :
+       {"file:///etc/passwd", "http://example.test/a.png", "not a key",
+        "{place_name}"}) {
+    DiscordRpcConfig config;
+    config.images.large = "nightcap_logo";
+    config.images.small = unsafe;
+    const DiscordRpcActivity small = BuildDiscordRpcActivity(
+        config, RobloxExperiencePresencePhase::kPlaying, &request,
+        "Natural Disaster Survival", 1);
+    EXPECT_TRUE(small.small_image.empty()) << unsafe;
+
+    config.images.large = unsafe;
+    const DiscordRpcActivity large = BuildDiscordRpcActivity(
+        config, RobloxExperiencePresencePhase::kPlaying, &request,
+        "Natural Disaster Survival", 1);
+    EXPECT_TRUE(large.large_image.empty()) << unsafe;
+    EXPECT_TRUE(large.large_text.empty()) << unsafe;
+  }
+}
+
+TEST(DiscordRpcTest, HiddenPlaceNameAlsoHidesPlaceImagesAndTitle) {
+  DiscordRpcConfig config;
+  config.show_place_name = false;
+  config.text.title = "{place_name}";
+  const RobloxExperienceLaunchRequest request = PublicServer();
+
+  const DiscordRpcActivity activity = BuildDiscordRpcActivity(
+      config, RobloxExperiencePresencePhase::kPlaying, &request,
+      "Secret place name", 1,
+      "https://tr.rbxcdn.com/example/512/512/Image/Png");
+
+  EXPECT_TRUE(activity.name.empty());
+  EXPECT_TRUE(activity.large_image.empty());
+  EXPECT_TRUE(activity.large_text.empty());
+}
+
 TEST(DiscordRpcTest, PublishesLifecycleActivitiesOverDiscordIpc) {
   char directory_pattern[] = "/tmp/mocktail_discord_rpc_XXXXXX";
   char* directory = mkdtemp(directory_pattern);
@@ -280,6 +409,13 @@ TEST(DiscordRpcTest, PublishesLifecycleActivitiesOverDiscordIpc) {
   config.application_id = "123456789012345678";
   config.show_place_name = false;
   config.join_enabled = false;
+  config.text.title = "Nightcap Test";
+  config.text.state = "Playing Roblox";
+  // Joining has no place yet, so this renders empty and must be left out.
+  config.text.joining = "{place_name}";
+  config.images.large = "nightcap_logo";
+  config.images.small = "linux";
+  config.images.small_text = "On Linux";
   DiscordRpcSession session(std::move(config));
   std::string detail;
   ASSERT_TRUE(session.Start(&detail)) << detail;
@@ -320,8 +456,15 @@ TEST(DiscordRpcTest, PublishesLifecycleActivitiesOverDiscordIpc) {
   EXPECT_NE(activity_payloads[0].find("SET_ACTIVITY"), std::string::npos);
   EXPECT_NE(activity_payloads[0].find("Browsing experiences"),
             std::string::npos);
-  EXPECT_NE(activity_payloads[1].find("Joining an experience"),
+  EXPECT_NE(activity_payloads[0].find("\"name\":\"Nightcap Test\""),
             std::string::npos);
+  EXPECT_NE(activity_payloads[0].find("\"large_image\":\"nightcap_logo\""),
+            std::string::npos);
+  EXPECT_NE(activity_payloads[0].find("\"small_image\":\"linux\""),
+            std::string::npos);
+  EXPECT_NE(activity_payloads[0].find("\"small_text\":\"On Linux\""),
+            std::string::npos);
+  EXPECT_EQ(activity_payloads[1].find("\"details\""), std::string::npos);
   EXPECT_NE(activity_payloads[2].find("Playing Roblox"), std::string::npos);
   EXPECT_NE(activity_payloads[2].find("timestamps"), std::string::npos);
 

tests/engine_pump_rest_test.cc

@@ -0,0 +1,131 @@
+#include "runtime/engine_pump_rest.h"
+
+#include <gtest/gtest.h>
+#include <sys/prctl.h>
+#include <unistd.h>
+
+#include <cstdio>
+#include <ctime>
+#include <filesystem>
+#include <fstream>
+#include <string>
+
+namespace mocktail::runtime {
+namespace {
+
+uint64_t NowNs() {
+  timespec now{};
+  clock_gettime(CLOCK_MONOTONIC, &now);
+  return static_cast<uint64_t>(now.tv_sec) * 1'000'000'000ULL +
+         static_cast<uint64_t>(now.tv_nsec);
+}
+
+class GovernorFile final {
+ public:
+  explicit GovernorFile(const char* content) {
+    char pattern[] = "/tmp/mocktail_governor_XXXXXX";
+    const int fd = mkstemp(pattern);
+    if (fd >= 0) {
+      close(fd);
+      path_ = pattern;
+      std::ofstream(path_) << content;
+    }
+  }
+  ~GovernorFile() {
+    std::error_code error;
+    std::filesystem::remove(path_, error);
+  }
+  const char* path() const { return path_.c_str(); }
+
+ private:
+  std::string path_;
+};
+
+// A performance governor holds the clock up on its own, so the thread can
+// sleep. Without it, only a core that stays awake keeps the clock up: tpause
+// where the CPU has it, a spin otherwise.
+TEST(EnginePumpRestTest, PolicyFollowsGovernorThenCpuFeature) {
+  EXPECT_EQ(ChooseEnginePumpRestMode({true, true, nullptr}),
+            EnginePumpRestMode::kSleep);
+  EXPECT_EQ(ChooseEnginePumpRestMode({true, false, nullptr}),
+            EnginePumpRestMode::kSleep);
+  EXPECT_EQ(ChooseEnginePumpRestMode({false, true, nullptr}),
+            EnginePumpRestMode::kTpause);
+  EXPECT_EQ(ChooseEnginePumpRestMode({false, false, nullptr}),
+            EnginePumpRestMode::kSpin);
+}
+
+TEST(EnginePumpRestTest, OverrideWinsWhenTheCpuCanHonorIt) {
+  EXPECT_EQ(ChooseEnginePumpRestMode({false, true, "sleep"}),
+            EnginePumpRestMode::kSleep);
+  EXPECT_EQ(ChooseEnginePumpRestMode({true, true, "spin"}),
+            EnginePumpRestMode::kSpin);
+  EXPECT_EQ(ChooseEnginePumpRestMode({true, true, "tpause"}),
+            EnginePumpRestMode::kTpause);
+  // tpause needs the instruction; without it the policy decides.
+  EXPECT_EQ(ChooseEnginePumpRestMode({false, false, "tpause"}),
+            EnginePumpRestMode::kSpin);
+  EXPECT_EQ(ChooseEnginePumpRestMode({false, true, "bogus"}),
+            EnginePumpRestMode::kTpause);
+  EXPECT_EQ(ChooseEnginePumpRestMode({false, true, ""}),
+            EnginePumpRestMode::kTpause);
+}
+
+TEST(EnginePumpRestTest, ReadsThePerformanceGovernorFromSysfs) {
+  GovernorFile performance("performance\n");
+  GovernorFile powersave("powersave\n");
+  EXPECT_TRUE(CpuGovernorIsPerformance(performance.path()));
+  EXPECT_FALSE(CpuGovernorIsPerformance(powersave.path()));
+  EXPECT_FALSE(CpuGovernorIsPerformance("/nonexistent/scaling_governor"));
+}
+
+TEST(EnginePumpRestTest, ModeNamesAreStable) {
+  EXPECT_STREQ(EnginePumpRestModeName(EnginePumpRestMode::kSleep), "sleep");
+  EXPECT_STREQ(EnginePumpRestModeName(EnginePumpRestMode::kTpause), "tpause");
+  EXPECT_STREQ(EnginePumpRestModeName(EnginePumpRestMode::kSpin), "spin");
+}
+
+// The rest bounds how late an engine post is picked up. With the thread's
+// timer slack lowered and a shallow C-state exit, the bound sits far under
+// the engine's sub-millisecond slack.
+TEST(EnginePumpRestTest, BoundStaysUnderTheEngineSlack) {
+  EXPECT_LE(kEnginePumpRestNs + kEnginePumpTimerSlackNs + kShallowWakeNs,
+            300'000ULL);
+}
+
+TEST(EnginePumpRestTest, LowersTheCallingThreadTimerSlackOnce) {
+  (void)RestAfterEnginePump(EnginePumpRestMode::kSleep);
+  EXPECT_EQ(prctl(PR_GET_TIMERSLACK), static_cast<int>(kEnginePumpTimerSlackNs));
+}
+
+// A real sleep, not a spin: the call takes at least the rest, and on an idle
+// core not much more. The upper bound is loose so a loaded box does not flake.
+TEST(EnginePumpRestTest, SleepModeSleepsForTheRestInterval) {
+  const uint64_t start = NowNs();
+  const uint64_t reported = RestAfterEnginePump(EnginePumpRestMode::kSleep);
+  const uint64_t elapsed = NowNs() - start;
+  EXPECT_EQ(reported, kEnginePumpRestNs);
+  EXPECT_GE(elapsed, kEnginePumpRestNs);
+  EXPECT_LT(elapsed, 2'000'000ULL) << "rest overshot by " << elapsed << " ns";
+}
+
+TEST(EnginePumpRestTest, TpauseModeWaitsForTheRestInterval) {
+  if (!CpuHasWaitPkg()) {
+    GTEST_SKIP() << "CPU has no WAITPKG";
+  }
+  const uint64_t start = NowNs();
+  const uint64_t reported = RestAfterEnginePump(EnginePumpRestMode::kTpause);
+  const uint64_t elapsed = NowNs() - start;
+  EXPECT_EQ(reported, kEnginePumpRestNs);
+  EXPECT_GE(elapsed, kEnginePumpRestNs);
+  EXPECT_LT(elapsed, 2'000'000ULL) << "rest overshot by " << elapsed << " ns";
+}
+
+TEST(EnginePumpRestTest, SpinModeDoesNotRest) {
+  const uint64_t start = NowNs();
+  EXPECT_EQ(RestAfterEnginePump(EnginePumpRestMode::kSpin), 0U);
+  EXPECT_LT(NowNs() - start, kEnginePumpRestNs);
+}
+
+}  // namespace
+}  // namespace mocktail::runtime

tests/etc2_decoder_test.cc

@@ -3,9 +3,14 @@
 #include <gtest/gtest.h>
 
 #include <array>
+#include <atomic>
 #include <cstdint>
+#include <filesystem>
 #include <iterator>
+#include <mutex>
 #include <random>
+#include <set>
+#include <thread>
 #include <vector>
 
 namespace mocktail::graphics {
@@ -252,6 +257,94 @@ TEST(Etc2DecoderTest, DecodesJobsOnWorkersLikeSerialDecode) {
   EXPECT_EQ(short_output, std::vector<std::uint8_t>(4 * 4 * 4 - 1, 0xAB));
 }
 
+// Batches of small textures stay under the old parallel floor; the pool has
+// to decode them exactly as the caller would.
+TEST(Etc2DecoderTest, DecodesManySmallJobsLikeSerialDecode) {
+  constexpr std::size_t kJobs = 24;
+  constexpr std::uint32_t kWidth = 64;
+  constexpr std::uint32_t kHeight = 64;
+  std::vector<std::vector<std::uint8_t>> sources;
+  std::vector<std::vector<std::uint8_t>> expected;
+  std::vector<std::vector<std::uint8_t>> outputs;
+  for (std::size_t index = 0; index < kJobs; ++index) {
+    sources.push_back(RandomBlocks(EtcFormat::kEtc2Rgb8, kWidth, kHeight,
+                                   static_cast<std::uint32_t>(index + 11)));
+    expected.push_back(
+        Decode(EtcFormat::kEtc2Rgb8, sources.back(), kWidth, kHeight));
+    outputs.emplace_back(expected.back().size(), 0xAB);
+  }
+  std::vector<EtcDecodeJob> jobs;
+  for (std::size_t index = 0; index < kJobs; ++index) {
+    jobs.push_back({EtcFormat::kEtc2Rgb8, sources[index].data(),
+                    sources[index].size(), kWidth, kHeight,
+                    outputs[index].data(), outputs[index].size()});
+  }
+
+  DecodeEtcJobs(jobs.data(), jobs.size(), 8);
+
+  for (std::size_t index = 0; index < kJobs; ++index) {
+    EXPECT_TRUE(jobs[index].ok) << index;
+    EXPECT_EQ(outputs[index], expected[index]) << index;
+  }
+}
+
+// The workers outlive each batch, so a later batch must find them idle.
+TEST(Etc2DecoderTest, DecodesCorrectlyAcrossRepeatedBatches) {
+  constexpr std::uint32_t kWidth = 260;
+  constexpr std::uint32_t kHeight = 132;
+  const std::vector<std::uint8_t> source =
+      RandomBlocks(EtcFormat::kEtc2Rgba8, kWidth, kHeight, 7);
+  const std::vector<std::uint8_t> expected =
+      Decode(EtcFormat::kEtc2Rgba8, source, kWidth, kHeight);
+
+  for (int round = 0; round < 40; ++round) {
+    std::vector<std::uint8_t> output(expected.size(), 0xAB);
+    EtcDecodeJob job{EtcFormat::kEtc2Rgba8, source.data(), source.size(),
+                     kWidth,                kHeight,      output.data(),
+                     output.size()};
+    DecodeEtcJobs(&job, 1, 8);
+    ASSERT_TRUE(job.ok) << round;
+    ASSERT_EQ(output, expected) << round;
+  }
+}
+
+std::size_t ThreadCount() {
+  return static_cast<std::size_t>(
+      std::distance(std::filesystem::directory_iterator("/proc/self/task"),
+                    std::filesystem::directory_iterator()));
+}
+
+// Other batch work (ETC2 emit) drains its own queue across the decode
+// workers. The function runs worker_count times, once of them on the caller,
+// and a second batch reuses the threads the first one started.
+TEST(Etc2DecoderTest, RunsAFunctionAcrossPooledWorkersWithoutNewThreads) {
+  struct Probe {
+    std::mutex mutex;
+    std::set<std::thread::id> threads;
+    std::atomic<int> calls{0};
+  };
+  const auto run = [](void* context) {
+    auto* probe = static_cast<Probe*>(context);
+    probe->calls.fetch_add(1, std::memory_order_relaxed);
+    std::lock_guard<std::mutex> lock(probe->mutex);
+    probe->threads.insert(std::this_thread::get_id());
+  };
+
+  Probe first;
+  RunOnDecodeWorkers(run, &first, 3);
+  EXPECT_EQ(first.calls.load(), 3);
+  // An idle worker may claim two of the slots.
+  EXPECT_GE(first.threads.size(), 2u);
+  EXPECT_LE(first.threads.size(), 3u);
+  EXPECT_EQ(first.threads.count(std::this_thread::get_id()), 1u);
+
+  const std::size_t pooled = ThreadCount();
+  Probe second;
+  RunOnDecodeWorkers(run, &second, 3);
+  EXPECT_EQ(second.calls.load(), 3);
+  EXPECT_EQ(ThreadCount(), pooled);
+}
+
 TEST(Etc2DecoderTest, RejectsShortBuffers) {
   const std::vector<std::uint8_t> source(8, 0);
   std::vector<std::uint8_t> output(4 * 4 * 4, 0);

tests/external_launch_broker_test.cc

@@ -9,13 +9,16 @@
 #include <unistd.h>
 
 #include <array>
+#include <atomic>
 #include <chrono>
+#include <condition_variable>
 #include <cstddef>
 #include <cstdlib>
 #include <cstring>
 #include <filesystem>
 #include <fstream>
 #include <memory>
+#include <mutex>
 #include <string>
 #include <thread>
 #include <utility>
@@ -288,6 +291,121 @@ TEST_F(ExternalLaunchBrokerTest, GlobalAttachmentDrainsAndRequiresOneOwner) {
   EXPECT_EQ(GetActiveExternalLaunchBroker(), nullptr);
 }
 
+// The host main loop drains the broker on every tick and is almost always
+// idle. An idle drain must observe the empty queue without waiting for a
+// dispatch already in flight, or one slow launch stalls the whole loop.
+TEST_F(ExternalLaunchBrokerTest, IdleDrainDoesNotWaitForAnInFlightDispatch) {
+  Start();
+  ASSERT_TRUE(broker_->QueueInitialRequest(Request(7001)).ok());
+
+  std::mutex gate_mutex;
+  std::condition_variable gate;
+  bool released = false;
+  std::atomic<bool> dispatching{false};
+
+  struct BlockingProbe {
+    std::mutex* gate_mutex;
+    std::condition_variable* gate;
+    bool* released;
+    std::atomic<bool>* dispatching;
+  } blocking{&gate_mutex, &gate, &released, &dispatching};
+
+  const ExternalLaunchSink blocking_sink{
+      &blocking,
+      [](void* context, const RobloxExperienceLaunchRequest&) -> Status {
+        auto* probe = static_cast<BlockingProbe*>(context);
+        probe->dispatching->store(true, std::memory_order_release);
+        std::unique_lock<std::mutex> lock(*probe->gate_mutex);
+        probe->gate->wait(lock, [probe] { return *probe->released; });
+        return Status::Ok();
+      }};
+
+  std::thread holder([&] {
+    EXPECT_TRUE(broker_->Drain(blocking_sink, 1).ok());
+  });
+  while (!dispatching.load(std::memory_order_acquire)) {
+    std::this_thread::sleep_for(std::chrono::milliseconds(1));
+  }
+
+  // Release on a timer, so a drain that does block behind the dispatch
+  // reports a slow elapsed time instead of deadlocking the test.
+  std::thread releaser([&] {
+    std::this_thread::sleep_for(std::chrono::seconds(2));
+    {
+      std::lock_guard<std::mutex> lock(gate_mutex);
+      released = true;
+    }
+    gate.notify_all();
+  });
+
+  CaptureProbe probe;
+  const auto started = std::chrono::steady_clock::now();
+  const Status idle = broker_->Drain({&probe, Capture}, 4);
+  const auto elapsed = std::chrono::steady_clock::now() - started;
+
+  releaser.join();
+  holder.join();
+
+  EXPECT_TRUE(idle.ok()) << idle.message();
+  EXPECT_TRUE(probe.requests.empty());
+  EXPECT_LT(std::chrono::duration_cast<std::chrono::milliseconds>(elapsed)
+                .count(),
+            250)
+      << "idle drain blocked behind the in-flight dispatch";
+}
+
+// The lock-free idle path must not drop a request that arrives while a
+// dispatch is running.
+TEST_F(ExternalLaunchBrokerTest, DeliversARequestQueuedDuringADispatch) {
+  Start();
+  ASSERT_TRUE(broker_->QueueInitialRequest(Request(7101)).ok());
+
+  std::mutex gate_mutex;
+  std::condition_variable gate;
+  bool released = false;
+  std::atomic<bool> dispatching{false};
+
+  struct BlockingProbe {
+    std::mutex* gate_mutex;
+    std::condition_variable* gate;
+    bool* released;
+    std::atomic<bool>* dispatching;
+  } blocking{&gate_mutex, &gate, &released, &dispatching};
+
+  const ExternalLaunchSink blocking_sink{
+      &blocking,
+      [](void* context, const RobloxExperienceLaunchRequest&) -> Status {
+        auto* probe = static_cast<BlockingProbe*>(context);
+        probe->dispatching->store(true, std::memory_order_release);
+        std::unique_lock<std::mutex> lock(*probe->gate_mutex);
+        probe->gate->wait(lock, [probe] { return *probe->released; });
+        return Status::Ok();
+      }};
+
+  std::thread holder([&] {
+    EXPECT_TRUE(broker_->Drain(blocking_sink, 1).ok());
+  });
+  while (!dispatching.load(std::memory_order_acquire)) {
+    std::this_thread::sleep_for(std::chrono::milliseconds(1));
+  }
+
+  ASSERT_TRUE(broker_->QueueInitialRequest(Request(7102)).ok());
+  EXPECT_EQ(broker_->pending_launch_count(), 1u);
+
+  {
+    std::lock_guard<std::mutex> lock(gate_mutex);
+    released = true;
+  }
+  gate.notify_all();
+  holder.join();
+
+  CaptureProbe probe;
+  ASSERT_TRUE(broker_->Drain({&probe, Capture}, 4).ok());
+  ASSERT_EQ(probe.requests.size(), 1u);
+  EXPECT_EQ(probe.requests[0].place_id, 7102);
+  EXPECT_EQ(broker_->pending_launch_count(), 0u);
+}
+
 }  // namespace
 }  // namespace runtime
 }  // namespace mocktail

tests/game_mode_test.cc

@@ -2,12 +2,61 @@
 
 #include <gtest/gtest.h>
 
+#include <sched.h>
+#include <sys/syscall.h>
+#include <unistd.h>
+
+#include <atomic>
+#include <cstddef>
+#include <initializer_list>
+#include <thread>
 #include <utility>
+#include <vector>
 
 namespace mocktail {
 namespace runtime {
 namespace {
 
+cpu_set_t MaskOf(std::initializer_list<int> cpus) {
+  cpu_set_t mask;
+  CPU_ZERO(&mask);
+  for (const int cpu : cpus) {
+    CPU_SET(cpu, &mask);
+  }
+  return mask;
+}
+
+// Each get() consumes the next entry of `reads`, repeating the last one once
+// the list runs out.
+struct AffinityProbe {
+  std::vector<cpu_set_t> reads;
+  std::size_t get_calls = 0;
+  int set_calls = 0;
+  int get_result = 0;
+  int set_result = 0;
+  cpu_set_t last_set{};
+};
+
+AffinityProbe* g_affinity = nullptr;
+
+int AffinityGet(cpu_set_t* mask) {
+  const std::size_t index = g_affinity->get_calls++;
+  if (g_affinity->get_result != 0 || g_affinity->reads.empty()) {
+    return g_affinity->get_result != 0 ? g_affinity->get_result : -1;
+  }
+  const std::size_t last = g_affinity->reads.size() - 1;
+  *mask = g_affinity->reads[index < last ? index : last];
+  return 0;
+}
+
+int AffinitySet(const cpu_set_t* mask) {
+  ++g_affinity->set_calls;
+  g_affinity->last_set = *mask;
+  return g_affinity->set_result;
+}
+
+CpuAffinityApi AffinityApi() { return CpuAffinityApi{&AffinityGet, &AffinitySet}; }
+
 struct ClientProbe {
   int query_result = 0;
   int start_result = 0;
@@ -173,6 +222,237 @@ TEST(GameModeSessionTest, StopFailureIsReportedOnlyOnce) {
   EXPECT_EQ(probe.end_calls, 1);
 }
 
+TEST(CpuAffinityNarrowedTest, ComparesPermittedCpuSets) {
+  const cpu_set_t all = MaskOf({0, 1, 2, 3});
+  EXPECT_TRUE(CpuAffinityNarrowed(all, MaskOf({1, 2})));
+  EXPECT_FALSE(CpuAffinityNarrowed(all, all));
+  EXPECT_FALSE(CpuAffinityNarrowed(all, MaskOf({0, 1, 2, 3, 4})));
+  // Same count, different CPUs: the daemon moved us without narrowing.
+  EXPECT_FALSE(CpuAffinityNarrowed(MaskOf({0, 1}), MaskOf({2, 3})));
+}
+
+// The daemon re-applies its pin every few seconds, so a session that pins is
+// dropped rather than corrected.
+TEST(HostCpuAffinityTest, RestoreReachesEveryThread) {
+  const CpuAffinityApi api = HostCpuAffinityApi();
+  ASSERT_NE(api.get, nullptr);
+  ASSERT_NE(api.set, nullptr);
+  cpu_set_t original;
+  CPU_ZERO(&original);
+  ASSERT_EQ(api.get(&original), 0);
+  if (CPU_COUNT(&original) < 2) {
+    GTEST_SKIP() << "needs at least two permitted CPUs";
+  }
+  int first = 0;
+  while (!CPU_ISSET(first, &original)) {
+    ++first;
+  }
+
+  std::atomic<pid_t> helper_tid{0};
+  std::atomic<int> helper_pin_result{0};
+  std::atomic<bool> release{false};
+  std::thread helper([&] {
+    const cpu_set_t pinned = MaskOf({first});
+    const pid_t tid = static_cast<pid_t>(::syscall(SYS_gettid));
+    // Published whatever the pin does: the waiter below would otherwise spin
+    // forever on a failure instead of reporting one.
+    helper_pin_result.store(sched_setaffinity(tid, sizeof(pinned), &pinned));
+    helper_tid.store(tid);
+    while (!release.load()) {
+      sched_yield();
+    }
+  });
+  while (helper_tid.load() == 0) {
+    sched_yield();
+  }
+  if (helper_pin_result.load() != 0) {
+    release.store(true);
+    helper.join();
+    FAIL() << "could not pin the helper thread to CPU " << first;
+  }
+
+  EXPECT_EQ(api.set(&original), 0);
+  cpu_set_t restored;
+  CPU_ZERO(&restored);
+  EXPECT_EQ(
+      sched_getaffinity(helper_tid.load(), sizeof(restored), &restored), 0);
+  release.store(true);
+  helper.join();
+
+  EXPECT_TRUE(CPU_EQUAL(&restored, &original))
+      << "restore left the helper thread pinned to CPU " << first;
+}
+
+TEST(GameModeSessionTest, DropsTheRequestWhenTheDaemonPinsCores) {
+  ClientProbe probe;
+  g_probe = &probe;
+  AffinityProbe affinity;
+  affinity.reads = {MaskOf({0, 1, 2, 3}), MaskOf({2, 3})};
+  g_affinity = &affinity;
+
+  GameModeSession session = GameModeSession::StartWithClientForTesting(
+      GameModePolicy::kAuto, Api(), AffinityApi());
+
+  EXPECT_EQ(session.state(), GameModeSessionState::kDeclinedCorePinning);
+  EXPECT_FALSE(session.active());
+  EXPECT_FALSE(session.owns_request());
+  EXPECT_EQ(probe.end_calls, 1);
+  // request_end releases the pin; the explicit restore only covers a daemon
+  // that leaves the mask behind.
+  EXPECT_EQ(affinity.set_calls, 1);
+  EXPECT_TRUE(CPU_EQUAL(&affinity.last_set, &affinity.reads[0]));
+}
+
+TEST(GameModeSessionTest, DroppedRequestIsNotEndedTwice) {
+  ClientProbe probe;
+  g_probe = &probe;
+  AffinityProbe affinity;
+  affinity.reads = {MaskOf({0, 1, 2, 3}), MaskOf({2, 3})};
+  g_affinity = &affinity;
+
+  GameModeSession session = GameModeSession::StartWithClientForTesting(
+      GameModePolicy::kAuto, Api(), AffinityApi());
+
+  ASSERT_EQ(probe.end_calls, 1);
+  EXPECT_TRUE(session.Stop().ok());
+  EXPECT_EQ(probe.end_calls, 1);
+}
+
+// A failed release leaves the daemon holding the request, so the session has
+// to keep owning it and retry at shutdown instead of reporting it released.
+TEST(GameModeSessionTest, KeepsAFailedReleaseForShutdown) {
+  ClientProbe probe;
+  probe.end_result = -1;
+  probe.error = "release failed";
+  g_probe = &probe;
+  AffinityProbe affinity;
+  affinity.reads = {MaskOf({0, 1, 2, 3}), MaskOf({2, 3})};
+  g_affinity = &affinity;
+
+  GameModeSession session = GameModeSession::StartWithClientForTesting(
+      GameModePolicy::kAuto, Api(), AffinityApi());
+
+  EXPECT_EQ(session.state(), GameModeSessionState::kDeclinedCorePinning);
+  EXPECT_TRUE(session.owns_request());
+  ASSERT_EQ(probe.end_calls, 1);
+  EXPECT_FALSE(session.Stop().ok());
+  EXPECT_EQ(probe.end_calls, 2);
+}
+
+TEST(GameModeSessionTest, KeepsTheRequestWhenAffinityIsUnchanged) {
+  ClientProbe probe;
+  g_probe = &probe;
+  AffinityProbe affinity;
+  affinity.reads = {MaskOf({0, 1, 2, 3})};
+  g_affinity = &affinity;
+
+  GameModeSession session = GameModeSession::StartWithClientForTesting(
+      GameModePolicy::kAuto, Api(), AffinityApi());
+
+  EXPECT_EQ(session.state(), GameModeSessionState::kActive);
+  EXPECT_TRUE(session.owns_request());
+  EXPECT_EQ(probe.end_calls, 0);
+  EXPECT_EQ(affinity.set_calls, 0);
+}
+
+// `on` is an explicit request for GameMode, so its pinning is accepted.
+TEST(GameModeSessionTest, ForcedPolicyKeepsAPinnedSession) {
+  ClientProbe probe;
+  g_probe = &probe;
+  AffinityProbe affinity;
+  affinity.reads = {MaskOf({0, 1, 2, 3}), MaskOf({2, 3})};
+  g_affinity = &affinity;
+
+  GameModeSession session = GameModeSession::StartWithClientForTesting(
+      GameModePolicy::kOn, Api(), AffinityApi());
+
+  EXPECT_EQ(session.state(), GameModeSessionState::kActive);
+  EXPECT_TRUE(session.owns_request());
+  EXPECT_EQ(probe.end_calls, 0);
+  EXPECT_EQ(affinity.set_calls, 0);
+}
+
+// A user's own taskset is in place before the request, so a daemon pin inside
+// it still counts as a narrowing and still drops the session.
+TEST(GameModeSessionTest, NarrowingADeliberateMaskAlsoDropsTheRequest) {
+  ClientProbe probe;
+  g_probe = &probe;
+  AffinityProbe affinity;
+  affinity.reads = {MaskOf({0, 1}), MaskOf({1})};
+  g_affinity = &affinity;
+
+  GameModeSession session = GameModeSession::StartWithClientForTesting(
+      GameModePolicy::kAuto, Api(), AffinityApi());
+
+  EXPECT_EQ(session.state(), GameModeSessionState::kDeclinedCorePinning);
+  EXPECT_TRUE(CPU_EQUAL(&affinity.last_set, &affinity.reads[0]));
+}
+
+TEST(GameModeSessionTest, RejectedRequestIsNotEvaluatedForPinning) {
+  ClientProbe probe;
+  probe.start_result = -1;
+  g_probe = &probe;
+  AffinityProbe affinity;
+  affinity.reads = {MaskOf({0, 1, 2, 3}), MaskOf({2, 3})};
+  g_affinity = &affinity;
+
+  GameModeSession session = GameModeSession::StartWithClientForTesting(
+      GameModePolicy::kOn, Api(), AffinityApi());
+
+  EXPECT_EQ(session.state(), GameModeSessionState::kRequestFailed);
+  EXPECT_EQ(probe.end_calls, 0);
+  EXPECT_EQ(affinity.set_calls, 0);
+}
+
+// Another component owns the request, so dropping it is not ours to do.
+TEST(GameModeSessionTest, AlreadyActiveProcessIsNotEvaluatedForPinning) {
+  ClientProbe probe;
+  probe.query_result = 2;
+  g_probe = &probe;
+  AffinityProbe affinity;
+  affinity.reads = {MaskOf({0, 1, 2, 3}), MaskOf({2, 3})};
+  g_affinity = &affinity;
+
+  GameModeSession session = GameModeSession::StartWithClientForTesting(
+      GameModePolicy::kAuto, Api(), AffinityApi());
+
+  EXPECT_EQ(session.state(), GameModeSessionState::kAlreadyActive);
+  EXPECT_EQ(probe.end_calls, 0);
+  EXPECT_EQ(affinity.set_calls, 0);
+}
+
+TEST(GameModeSessionTest, UnreadableAffinityKeepsTheRequest) {
+  ClientProbe probe;
+  g_probe = &probe;
+  AffinityProbe affinity;
+  affinity.reads = {MaskOf({0, 1})};
+  affinity.get_result = -1;
+  g_affinity = &affinity;
+
+  GameModeSession session = GameModeSession::StartWithClientForTesting(
+      GameModePolicy::kAuto, Api(), AffinityApi());
+
+  EXPECT_EQ(session.state(), GameModeSessionState::kActive);
+  EXPECT_EQ(probe.end_calls, 0);
+}
+
+TEST(GameModeSessionTest, MissingAffinityApiKeepsTheRequest) {
+  ClientProbe probe;
+  g_probe = &probe;
+
+  GameModeSession session = GameModeSession::StartWithClientForTesting(
+      GameModePolicy::kAuto, Api(), CpuAffinityApi{});
+
+  EXPECT_EQ(session.state(), GameModeSessionState::kActive);
+  EXPECT_EQ(probe.end_calls, 0);
+}
+
+TEST(GameModeSessionTest, NamesTheDeclinedState) {
+  EXPECT_STREQ(
+      GameModeSessionStateName(GameModeSessionState::kDeclinedCorePinning),
+      "declined-core-pinning");
+}
+
 }  // namespace
 }  // namespace runtime
 }  // namespace mocktail

tests/input_pump_pacing_runtime_test.cc

@@ -0,0 +1,60 @@
+// Drives the real PaceInputPump() against an SDL window, so the pacing
+// decision is exercised end to end rather than only as pacer arithmetic.
+// Gated like the other tests that need a real SDL video driver.
+#include <SDL3/SDL.h>
+#include <gtest/gtest.h>
+
+#include <cstdint>
+#include <cstdlib>
+#include <string>
+
+#include "window/input_pump_pacer.h"
+#include "window/window.h"
+
+namespace mocktail {
+namespace window {
+namespace {
+
+bool RealSdlWindowTestsEnabled() {
+  const char* enabled = std::getenv("MOCKTAIL_TEST_SDL_WINDOW");
+  return enabled != nullptr && std::string(enabled) == "1";
+}
+
+// Unthrottled presentation must not pace the main-thread pump.
+//
+// Roblox posts its per-frame main-thread step at a time of its own choosing
+// and nothing signals the host, so the pump is a poll. A frame that misses
+// its slot slips a whole period, and the engine's slack is under a
+// millisecond, so the pacer's 240 Hz cadence is far too coarse here. The rest
+// between polls is runtime/engine_pump_rest, bounded at 100 us.
+//
+// A throttled present blocks on vsync, so the pacer still runs there.
+TEST(InputPumpPacingRuntimeTest, UnthrottledPresentationDoesNotParkThePump) {
+  if (!RealSdlWindowTestsEnabled()) {
+    GTEST_SKIP() << "real SDL window test was not explicitly enabled";
+  }
+  ASSERT_EQ(setenv("MOCKTAIL_VSYNC", "off", 1), 0);
+  ASSERT_EQ(setenv("MOCKTAIL_ENABLE_TEST_GRAPHICS_STUBS", "1", 1), 0);
+  ASSERT_TRUE(Init(320, 180, "input pump pacing test"));
+  ASSERT_TRUE(UnthrottledPresentationRequested());
+
+  constexpr int kTicks = 240;
+  uint64_t slept_ns = 0;
+  for (int tick = 0; tick < kTicks; ++tick) {
+    PumpEvents();
+    slept_ns += PaceInputPump();
+  }
+  Shutdown();
+
+  EXPECT_EQ(slept_ns, 0U)
+      << "unthrottled ticks parked the main-thread pump for " << slept_ns
+      << " ns, which delays the engine's main-thread replies";
+}
+
+// The present mode policy is cached process-wide on first use, so a second
+// Init in this binary reports the mode selected above. The throttled cadence
+// is covered by the pacer's own arithmetic tests.
+
+}  // namespace
+}  // namespace window
+}  // namespace mocktail

tests/jnivm_test.cc

@@ -3,6 +3,7 @@
 
 #include <gtest/gtest.h>
 
+#include <chrono>
 #include <condition_variable>
 #include <cstdarg>
 #include <cstdint>
@@ -1087,6 +1088,99 @@ TEST_F(JniVmTest, FloatArrayElementsAreMutable) {
   env->ReleaseFloatArrayElements(array, elements, 0);
 }
 
+constexpr int kMoreThanHandleCapacity = 150000;
+
+TEST_F(JniVmTest, RepeatedFindClassDoesNotExhaustHandles) {
+  JNIEnv *env = vm_->GetJNIEnv();
+  for (int i = 0; i < kMoreThanHandleCapacity; ++i) {
+    jclass cls = env->FindClass("android/view/Surface");
+    ASSERT_NE(cls, nullptr) << "iteration " << i;
+    env->DeleteLocalRef(cls);
+  }
+  jstring text = env->NewStringUTF("still allocatable");
+  ASSERT_NE(text, nullptr);
+  env->DeleteLocalRef(text);
+}
+
+TEST_F(JniVmTest, RepeatedGetObjectClassDoesNotExhaustHandles) {
+  JNIEnv *env = vm_->GetJNIEnv();
+  jclass surface_class = env->FindClass("android/view/Surface");
+  jobject surface = env->AllocObject(surface_class);
+  ASSERT_NE(surface, nullptr);
+  for (int i = 0; i < kMoreThanHandleCapacity; ++i) {
+    jclass cls = env->GetObjectClass(surface);
+    ASSERT_NE(cls, nullptr) << "iteration " << i;
+    env->DeleteLocalRef(cls);
+  }
+  env->DeleteLocalRef(surface);
+}
+
+TEST_F(JniVmTest, ClassHandlesStayValidAfterDeleteLocalRef) {
+  JNIEnv *env = vm_->GetJNIEnv();
+  jclass first = env->FindClass("android/view/Surface");
+  env->DeleteLocalRef(first);
+  jclass second = env->FindClass("android/view/Surface");
+  ASSERT_NE(second, nullptr);
+  EXPECT_NE(env->GetMethodID(second, "isValid", "()Z"), nullptr);
+  jobject surface = env->AllocObject(second);
+  ASSERT_NE(surface, nullptr);
+  EXPECT_TRUE(env->IsInstanceOf(surface, second));
+  env->DeleteLocalRef(surface);
+}
+
+TEST_F(JniVmTest, LocalRefsDeletedInCreationOrderFreeTheirSlots) {
+  JNIEnv *env = vm_->GetJNIEnv();
+  const auto start = std::chrono::steady_clock::now();
+  for (int round = 0; round < 3; ++round) {
+    std::vector<jstring> strings;
+    strings.reserve(60000);
+    for (int i = 0; i < 60000; ++i) {
+      jstring text = env->NewStringUTF("x");
+      ASSERT_NE(text, nullptr) << "round " << round << " string " << i;
+      strings.push_back(text);
+    }
+    for (jstring text : strings) {
+      env->DeleteLocalRef(text);
+    }
+  }
+  EXPECT_LT(std::chrono::steady_clock::now() - start, std::chrono::seconds(5));
+}
+
+TEST_F(JniVmTest, FullHandleTableReportsLiveObjectsByClassOnce) {
+  JNIEnv *env = vm_->GetJNIEnv();
+  std::vector<jstring> strings;
+  ::testing::internal::CaptureStderr();
+  for (int i = 0; i < kMoreThanHandleCapacity; ++i) {
+    jstring text = env->NewStringUTF("fill");
+    if (text == nullptr) {
+      break;
+    }
+    strings.push_back(text);
+  }
+  EXPECT_EQ(env->NewStringUTF("still full"), nullptr);
+  const std::string output = ::testing::internal::GetCapturedStderr();
+  for (jstring text : strings) {
+    env->DeleteLocalRef(text);
+  }
+  EXPECT_LT(strings.size(), static_cast<std::size_t>(kMoreThanHandleCapacity));
+  const std::size_t report = output.find("[JNI] handle table full");
+  ASSERT_NE(report, std::string::npos) << output;
+  EXPECT_NE(output.find("java/lang/String", report), std::string::npos)
+      << output;
+  EXPECT_EQ(output.find("[JNI] handle table full", report + 1),
+            std::string::npos);
+  EXPECT_NE(env->NewStringUTF("free again"), nullptr);
+}
+
+TEST_F(JniVmTest, PopLocalFrameFreesLocalsCreatedInsideIt) {
+  JNIEnv *env = vm_->GetJNIEnv();
+  for (int i = 0; i < kMoreThanHandleCapacity; ++i) {
+    ASSERT_EQ(env->PushLocalFrame(4), JNI_OK);
+    ASSERT_NE(env->NewStringUTF("frame local"), nullptr) << "iteration " << i;
+    env->PopLocalFrame(nullptr);
+  }
+}
+
 TEST_F(JniVmTest, ObjectMethodCanReturnMockClassLoader) {
   JNIEnv *env = vm_->GetJNIEnv();
   jclass cls = env->FindClass("java/lang/Object");
@@ -2701,5 +2795,86 @@ TEST_F(JniVmTest, NativeQuoteInterfaceReportsKeystoreUnavailable) {
   EXPECT_NE(message.find("AndroidKeyStore"), std::string::npos);
 }
 
+TEST_F(JniVmTest, DetachCurrentThreadReleasesThatThreadsLocalRefs) {
+  JavaVM *java_vm = vm_->GetJavaVM();
+  for (int round = 0; round < 4; ++round) {
+    bool all_allocated = true;
+    std::thread worker([java_vm, &all_allocated]() {
+      JNIEnv *env = nullptr;
+      if (java_vm->AttachCurrentThread(reinterpret_cast<void **>(&env), nullptr) !=
+          JNI_OK) {
+        all_allocated = false;
+        return;
+      }
+      for (int i = 0; i < 40000; ++i) {
+        if (env->NewStringUTF("thread local") == nullptr) {
+          all_allocated = false;
+          break;
+        }
+      }
+      java_vm->DetachCurrentThread();
+    });
+    worker.join();
+    ASSERT_TRUE(all_allocated) << "round " << round;
+  }
+}
+
+TEST_F(JniVmTest, DetachCurrentThreadKeepsVmOwnedObjectsAlive) {
+  JavaVM *java_vm = vm_->GetJavaVM();
+  jobject implementation = nullptr;
+  jobject params = nullptr;
+  std::thread worker([java_vm, &implementation, &params]() {
+    JNIEnv *env = nullptr;
+    if (java_vm->AttachCurrentThread(reinterpret_cast<void **>(&env), nullptr) !=
+        JNI_OK) {
+      return;
+    }
+    jclass gl_class =
+        env->FindClass("com/roblox/engine/jni/NativeGLJavaInterface");
+    implementation = env->CallStaticObjectMethod(
+        gl_class,
+        env->GetStaticMethodID(gl_class, "getImplementation",
+                               "()Lcom/roblox/engine/jni/EngineJavaCallback2;"));
+    params = env->CallStaticObjectMethod(
+        gl_class,
+        env->GetStaticMethodID(
+            gl_class, "getDeviceStaticParams",
+            "()Lcom/roblox/engine/jni/model/DeviceStaticParams;"));
+    java_vm->DetachCurrentThread();
+  });
+  worker.join();
+  ASSERT_NE(implementation, nullptr);
+  ASSERT_NE(params, nullptr);
+
+  JNIEnv *env = vm_->GetJNIEnv();
+  for (int i = 0; i < 64; ++i) {
+    EXPECT_NE(reinterpret_cast<jobject>(env->NewStringUTF("reused slot")),
+              implementation);
+  }
+  jclass params_class =
+      env->FindClass("com/roblox/engine/jni/model/DeviceStaticParams");
+  jfieldID os_version =
+      env->GetFieldID(params_class, "osVersion", "Ljava/lang/String;");
+  EXPECT_EQ(ReadJavaString(env, static_cast<jstring>(
+                                    env->GetObjectField(params, os_version))),
+            "Android 13");
+}
+
+TEST_F(JniVmTest, DeletedHighIndexStringHandleReadsAsEmpty) {
+  JNIEnv *env = vm_->GetJNIEnv();
+  std::vector<jstring> strings;
+  for (int i = 0; i < 8000; ++i) {
+    strings.push_back(env->NewStringUTF("filler"));
+  }
+  jstring high = strings.back();
+  ASSERT_GT(reinterpret_cast<uintptr_t>(high), uintptr_t{0x10000000});
+  for (jstring text : strings) {
+    env->DeleteLocalRef(text);
+  }
+  EXPECT_EQ(env->GetStringUTFLength(high), 0);
+  EXPECT_STREQ(env->GetStringUTFChars(high, nullptr), "");
+  EXPECT_EQ(env->GetStringLength(high), 0);
+}
+
 } // namespace
 } // namespace jnivm

tests/platform_graphics_foundation_test.cc

@@ -2,6 +2,7 @@
 #include <gtest/gtest.h>
 
 #include <cstdlib>
+#include <string>
 #include <vector>
 
 #include "mocktail/graphics/android_vulkan_wsi_adapter.h"
@@ -118,6 +119,24 @@ TEST(SdlWindowIconTest, AppliesEmbeddedPngToRealWindow) {
       SDL_CreateWindow("Mocktail icon test", 64, 64, SDL_WINDOW_HIDDEN);
   ASSERT_NE(window, nullptr) << SDL_GetError();
 
+  // Setting a window icon needs compositor support: on Wayland that is the
+  // xdg_toplevel_icon_v1 protocol, which many compositors do not implement.
+  // Probe with a throwaway surface so this covers the embedded PNG wherever
+  // icons work, instead of failing on a platform limitation the callers of
+  // ApplySdlWindowIcon already treat as non-fatal.
+  SDL_Surface* probe = SDL_CreateSurface(1, 1, SDL_PIXELFORMAT_RGBA32);
+  ASSERT_NE(probe, nullptr) << SDL_GetError();
+  SDL_ClearError();
+  const bool icons_supported = SDL_SetWindowIcon(window, probe);
+  const std::string probe_error = icons_supported ? std::string() : SDL_GetError();
+  SDL_DestroySurface(probe);
+  if (!icons_supported) {
+    SDL_DestroyWindow(window);
+    SDL_Quit();
+    GTEST_SKIP() << "this video driver cannot set a window icon: "
+                 << probe_error;
+  }
+
   const Status status = platform::ApplySdlWindowIcon(window);
   EXPECT_TRUE(status.ok()) << status.message();
 

tests/roblox_input_router_test.cc

@@ -233,16 +233,17 @@ TEST_F(RobloxInputRouterTest, RoutesMouseMotionButtonAndVerticalWheel) {
   EXPECT_FLOAT_EQ(probe_.mouse_buttons[0].y, 80.0f);
   EXPECT_EQ(probe_.mouse_buttons[0].button, 1);
   ASSERT_EQ(probe_.mouse_wheels.size(), 1U);
-  EXPECT_FLOAT_EQ(probe_.mouse_wheels[0].x, 0.0f);
-  EXPECT_FLOAT_EQ(probe_.mouse_wheels[0].y, 0.0f);
+  // A wheel event without a usable position keeps the pointer where it was.
+  EXPECT_FLOAT_EQ(probe_.mouse_wheels[0].x, 100.0f);
+  EXPECT_FLOAT_EQ(probe_.mouse_wheels[0].y, 80.0f);
   EXPECT_FLOAT_EQ(probe_.mouse_wheels[0].delta_y, -2.0f);
 }
 
-TEST_F(RobloxInputRouterTest,
-       KeepsRelativeMotionResponsiveAfterOvershootingViewportEdge) {
-  // Relative-mode motion reports zero absolute coordinates, so the router
-  // accumulates deltas. The accumulator stays inside the viewport: a reversal
-  // moves the pointer on the next event, however far the overshoot ran.
+TEST_F(RobloxInputRouterTest, HoldsPointerPositionDuringRelativeMotion) {
+  // Relative-mode motion reports zero absolute coordinates. The pointer stays
+  // where it was captured while the deltas pass through, so a long camera
+  // turn neither walks the reported position to the viewport edge nor
+  // swallows the reversal. The next absolute event moves the pointer again.
   ASSERT_TRUE(
       router_
           .HandleEvent(Event(platform::MouseMotionEvent{640.0f, 360.0f, 0.0f,
@@ -256,13 +257,111 @@ TEST_F(RobloxInputRouterTest,
   ASSERT_TRUE(
       router_
           .HandleEvent(Event(platform::MouseMotionEvent{0.0f, 0.0f, -100.0f,
+                                                        40.0f, 0}))
+          .dispatched());
+  ASSERT_TRUE(
+      router_
+          .HandleEvent(Event(platform::MouseMotionEvent{200.0f, 100.0f, 3.0f,
+                                                        3.0f, 0}))
+          .dispatched());
+
+  ASSERT_EQ(probe_.mouse_moves.size(), 4U);
+  EXPECT_FLOAT_EQ(probe_.mouse_moves[1].x, 640.0f);
+  EXPECT_FLOAT_EQ(probe_.mouse_moves[1].y, 360.0f);
+  EXPECT_FLOAT_EQ(probe_.mouse_moves[1].delta_x, 2000.0f);
+  EXPECT_FLOAT_EQ(probe_.mouse_moves[2].x, 640.0f);
+  EXPECT_FLOAT_EQ(probe_.mouse_moves[2].y, 360.0f);
+  EXPECT_FLOAT_EQ(probe_.mouse_moves[2].delta_x, -100.0f);
+  EXPECT_FLOAT_EQ(probe_.mouse_moves[2].delta_y, 40.0f);
+  EXPECT_FLOAT_EQ(probe_.mouse_moves[3].x, 200.0f);
+  EXPECT_FLOAT_EQ(probe_.mouse_moves[3].y, 100.0f);
+}
+
+TEST_F(RobloxInputRouterTest,
+       AnchorsUnknownPointerAtViewportCenterForRelativeMotion) {
+  // No absolute position has been seen yet, so the held position is the
+  // viewport center rather than the top-left corner.
+  ASSERT_TRUE(
+      router_
+          .HandleEvent(Event(platform::MouseMotionEvent{0.0f, 0.0f, 25.0f,
+                                                        -10.0f, 0}))
+          .dispatched());
+  ASSERT_TRUE(
+      router_
+          .HandleEvent(Event(platform::MouseMotionEvent{0.0f, 0.0f, 300.0f,
                                                         0.0f, 0}))
           .dispatched());
 
-  ASSERT_EQ(probe_.mouse_moves.size(), 3U);
-  EXPECT_FLOAT_EQ(probe_.mouse_moves[1].x, 1279.0f);
-  EXPECT_FLOAT_EQ(probe_.mouse_moves[2].x, 1179.0f);
-  EXPECT_FLOAT_EQ(probe_.mouse_moves[2].delta_x, -100.0f);
+  ASSERT_EQ(probe_.mouse_moves.size(), 2U);
+  EXPECT_FLOAT_EQ(probe_.mouse_moves[0].x, 639.5f);
+  EXPECT_FLOAT_EQ(probe_.mouse_moves[0].y, 359.5f);
+  EXPECT_FLOAT_EQ(probe_.mouse_moves[0].delta_x, 25.0f);
+  EXPECT_FLOAT_EQ(probe_.mouse_moves[0].delta_y, -10.0f);
+  EXPECT_FLOAT_EQ(probe_.mouse_moves[1].x, 639.5f);
+  EXPECT_FLOAT_EQ(probe_.mouse_moves[1].y, 359.5f);
+}
+
+TEST_F(RobloxInputRouterTest, ClampsHeldPointerToViewportAfterResize) {
+  ASSERT_TRUE(
+      router_
+          .HandleEvent(Event(platform::MouseMotionEvent{1200.0f, 700.0f, 0.0f,
+                                                        0.0f, 0}))
+          .dispatched());
+  ASSERT_EQ(router_
+                .HandleEvent(Event(
+                    platform::WindowResizedEvent{800, 600, 800, 600, 1.0F}))
+                .state,
+            RobloxInputDispatchState::kStateUpdated);
+  ASSERT_TRUE(
+      router_
+          .HandleEvent(Event(platform::MouseMotionEvent{0.0f, 0.0f, 50.0f,
+                                                        0.0f, 0}))
+          .dispatched());
+
+  ASSERT_EQ(probe_.mouse_moves.size(), 2U);
+  EXPECT_FLOAT_EQ(probe_.mouse_moves[1].x, 799.0f);
+  EXPECT_FLOAT_EQ(probe_.mouse_moves[1].y, 599.0f);
+  EXPECT_FLOAT_EQ(probe_.mouse_moves[1].delta_x, 50.0f);
+}
+
+TEST_F(RobloxInputRouterTest,
+       KeepsHeldPointerAcrossZeroCoordinateWheelAndButtonEvents) {
+  // While the pointer is captured, wheel and button events also arrive with
+  // zero coordinates. None of them may move the held position.
+  ASSERT_TRUE(
+      router_
+          .HandleEvent(Event(platform::MouseMotionEvent{640.0f, 360.0f, 0.0f,
+                                                        0.0f, 0}))
+          .dispatched());
+  ASSERT_TRUE(router_
+                  .HandleEvent(Event(
+                      platform::MouseWheelEvent{0.0f, -1.0f, 0.0f, 0.0f}))
+                  .dispatched());
+  ASSERT_TRUE(router_
+                  .HandleEvent(Event(platform::MouseButtonEvent{
+                      true, SDL_BUTTON_LEFT, 1, 0.0f, 0.0f}))
+                  .dispatched());
+  ASSERT_TRUE(router_
+                  .HandleEvent(Event(platform::MouseButtonEvent{
+                      false, SDL_BUTTON_LEFT, 1, 0.0f, 0.0f}))
+                  .dispatched());
+  ASSERT_TRUE(
+      router_
+          .HandleEvent(Event(platform::MouseMotionEvent{0.0f, 0.0f, -500.0f,
+                                                        0.0f, 0}))
+          .dispatched());
+
+  ASSERT_EQ(probe_.mouse_wheels.size(), 1U);
+  EXPECT_FLOAT_EQ(probe_.mouse_wheels[0].x, 640.0f);
+  EXPECT_FLOAT_EQ(probe_.mouse_wheels[0].y, 360.0f);
+  ASSERT_EQ(probe_.mouse_buttons.size(), 2U);
+  EXPECT_FLOAT_EQ(probe_.mouse_buttons[0].x, 640.0f);
+  EXPECT_FLOAT_EQ(probe_.mouse_buttons[0].y, 360.0f);
+  EXPECT_FLOAT_EQ(probe_.mouse_buttons[1].x, 640.0f);
+  EXPECT_FLOAT_EQ(probe_.mouse_buttons[1].y, 360.0f);
+  ASSERT_EQ(probe_.mouse_moves.size(), 2U);
+  EXPECT_FLOAT_EQ(probe_.mouse_moves[1].x, 640.0f);
+  EXPECT_FLOAT_EQ(probe_.mouse_moves[1].y, 360.0f);
 }
 
 // A fractionally scaled X11 desktop: the buffer is 1:1 with logical units
@@ -298,9 +397,14 @@ TEST_F(RobloxInputRouterTest, RawMouseSendsLookDeltasUnscaled) {
   ASSERT_EQ(probe_.mouse_moves.size(), 1U);
   EXPECT_FLOAT_EQ(probe_.mouse_moves[0].delta_x, 10.0f);
   EXPECT_FLOAT_EQ(probe_.mouse_moves[0].delta_y, -6.0f);
-  // The reported position stays in guest units whatever the delta carries.
-  EXPECT_NEAR(probe_.mouse_moves[0].x, 8.727f, 0.01f);
-  EXPECT_FLOAT_EQ(probe_.mouse_moves[0].y, 0.0f);
+  // The reported position stays in guest units whatever the delta carries:
+  // with no absolute position seen, it is the guest viewport center.
+  const platform::SurfaceCoordinateTransform transform = {1624, 811, 1624, 811,
+                                                          1.145833F};
+  EXPECT_NEAR(probe_.mouse_moves[0].x, (transform.guest_width() - 1.0F) / 2.0F,
+              0.01f);
+  EXPECT_NEAR(probe_.mouse_moves[0].y,
+              (transform.guest_height() - 1.0F) / 2.0F, 0.01f);
 }
 
 TEST_F(RobloxInputRouterTest,

tests/runtime_config_file_test.cc

@@ -168,7 +168,11 @@ TEST(RuntimeConfigBootstrapTest,
            "button targets that server.\n      enabled: true",
            "# Boolean (default: true): never expose private or reserved "
            "joins.\n      public_servers_only: true",
-           "#   playing: \"{place_name}\"\n    #   state: Playing Roblox",
+           "#   playing: \"Playing {place_name}\"\n    #   state: \"by "
+           "{creator_name}\"",
+           "#   title: Roblox",
+           "#   large: \"{place_icon}\"\n    #   large_text: \"{place_name}\"\n"
+           "    #   small: roblox_small\n    #   small_text: Roblox",
             "# Integer (default: 1280): initial window width in logical desktop "
             "units.\n  "
             "width: 1280",
@@ -356,6 +360,11 @@ integrations:
       playing: "Inside {place_name}"
       state: Playing Roblox on Linux
       unknown_place: Unknown world
+      title: "{place_name}"
+    images:
+      large: ""
+      small: nightcap_logo
+      small_text: On Linux
 updates:
   automatic: true
 )yaml");
@@ -405,6 +414,78 @@ updates:
   EXPECT_EQ(loaded.config.discord_rpc().text.state,
             "Playing Roblox on Linux");
   EXPECT_EQ(loaded.config.discord_rpc().text.unknown_place, "Unknown world");
+  EXPECT_EQ(loaded.config.discord_rpc().text.title, "{place_name}");
+  EXPECT_TRUE(loaded.config.discord_rpc().images.large.empty());
+  EXPECT_EQ(loaded.config.discord_rpc().images.large_text, "{place_name}");
+  EXPECT_EQ(loaded.config.discord_rpc().images.small, "nightcap_logo");
+  EXPECT_EQ(loaded.config.discord_rpc().images.small_text, "On Linux");
+  EXPECT_TRUE(loaded.config.discord_rpc_valid());
+}
+
+TEST(RuntimeConfigFileTest, RejectsControlBytesInDiscordPresenceFields) {
+  TemporaryDirectory temporary;
+  const std::filesystem::path file = temporary.Write(R"yaml(
+version: 1
+integrations:
+  discord_rpc:
+    images:
+      small_text: "bad\x01text"
+)yaml");
+
+  const RuntimeConfigLoadResult loaded =
+      LoadRuntimeConfig(MapEnvironment(), file);
+
+  EXPECT_FALSE(loaded);
+  EXPECT_NE(loaded.error.find("integrations.discord_rpc.images.small_text"),
+            std::string::npos);
+  EXPECT_NE(loaded.error.find("control bytes"), std::string::npos)
+      << loaded.error;
+}
+
+TEST(RuntimeConfigFileTest, EmptyDiscordStateLoadsAsHidden) {
+  TemporaryDirectory temporary;
+  const std::filesystem::path file = temporary.Write(R"yaml(
+version: 1
+integrations:
+  discord_rpc:
+    text:
+      state: ""
+)yaml");
+
+  const RuntimeConfigLoadResult loaded =
+      LoadRuntimeConfig(MapEnvironment(), file);
+
+  ASSERT_TRUE(loaded) << loaded.error;
+  EXPECT_TRUE(loaded.config.discord_rpc().text.state.empty());
+  EXPECT_TRUE(loaded.config.discord_rpc_valid());
+}
+
+TEST(RuntimeConfigFileTest, ExportsDiscordPresenceFieldsIncludingEmptyValues) {
+  std::string error;
+  const RuntimeConfig configured = RuntimeConfig::FromEnvironment(
+      MapEnvironment({{"MOCKTAIL_DISCORD_RPC_TEXT_TITLE", "Nightcap"},
+                      {"MOCKTAIL_DISCORD_RPC_TEXT_STATE", ""},
+                      {"MOCKTAIL_DISCORD_RPC_IMAGE_LARGE", ""},
+                      {"MOCKTAIL_DISCORD_RPC_IMAGE_SMALL", "linux"}}));
+  ASSERT_TRUE(ExportRuntimeConfigEnvironment(configured, &error)) << error;
+
+  const RuntimeConfig exported =
+      RuntimeConfig::FromEnvironment(ProcessEnvironment());
+  EXPECT_EQ(exported.discord_rpc().text.title, "Nightcap");
+  EXPECT_TRUE(exported.discord_rpc().text.state.empty());
+  EXPECT_TRUE(exported.discord_rpc_valid());
+  EXPECT_TRUE(exported.discord_rpc().images.large.empty());
+  EXPECT_EQ(exported.discord_rpc().images.large_text, "{place_name}");
+  EXPECT_EQ(exported.discord_rpc().images.small, "linux");
+  EXPECT_EQ(exported.discord_rpc().images.small_text, "Roblox");
+  for (const char* variable :
+       {"MOCKTAIL_DISCORD_RPC_TEXT_TITLE", "MOCKTAIL_DISCORD_RPC_TEXT_STATE",
+        "MOCKTAIL_DISCORD_RPC_IMAGE_LARGE",
+        "MOCKTAIL_DISCORD_RPC_IMAGE_LARGE_TEXT",
+        "MOCKTAIL_DISCORD_RPC_IMAGE_SMALL",
+        "MOCKTAIL_DISCORD_RPC_IMAGE_SMALL_TEXT"}) {
+    unsetenv(variable);
+  }
 }
 
 TEST(RuntimeConfigFileTest, EnvironmentOverridesYaml) {

tests/runtime_config_test.cc

@@ -84,9 +84,14 @@ TEST(RuntimeConfigTest, UsesSupportedDefaults) {
   EXPECT_EQ(config.discord_rpc().application_id, "1549428231927500843");
   EXPECT_EQ(config.discord_rpc().text.browsing, "Browsing experiences");
   EXPECT_EQ(config.discord_rpc().text.joining, "Joining an experience");
-  EXPECT_EQ(config.discord_rpc().text.playing, "{place_name}");
-  EXPECT_EQ(config.discord_rpc().text.state, "Playing Roblox");
+  EXPECT_EQ(config.discord_rpc().text.playing, "Playing {place_name}");
+  EXPECT_EQ(config.discord_rpc().text.state, "by {creator_name}");
   EXPECT_EQ(config.discord_rpc().text.unknown_place, "Unknown experience");
+  EXPECT_EQ(config.discord_rpc().text.title, "Roblox");
+  EXPECT_EQ(config.discord_rpc().images.large, "{place_icon}");
+  EXPECT_EQ(config.discord_rpc().images.large_text, "{place_name}");
+  EXPECT_EQ(config.discord_rpc().images.small, "roblox_small");
+  EXPECT_EQ(config.discord_rpc().images.small_text, "Roblox");
   EXPECT_TRUE(config.discord_rpc_valid());
   EXPECT_FALSE(config.has_unsafe_detached_thread_overrides());
   EXPECT_TRUE(config.unsafe_detached_thread_overrides().empty());
@@ -121,6 +126,10 @@ TEST(RuntimeConfigTest, ReadsTypedRuntimeValues) {
       {"MOCKTAIL_DISCORD_RPC_JOIN_BUTTON_LABEL", "Play Together"},
       {"MOCKTAIL_DISCORD_APPLICATION_ID", "123456789012345678"},
       {"MOCKTAIL_DISCORD_RPC_TEXT_PLAYING", "In {place_name}"},
+      {"MOCKTAIL_DISCORD_RPC_TEXT_TITLE", "Nightcap"},
+      {"MOCKTAIL_DISCORD_RPC_IMAGE_LARGE", ""},
+      {"MOCKTAIL_DISCORD_RPC_IMAGE_SMALL", "linux"},
+      {"MOCKTAIL_DISCORD_RPC_IMAGE_SMALL_TEXT", "On Linux"},
   });
   const RuntimeConfig config = RuntimeConfig::FromEnvironment(environment);
 
@@ -162,6 +171,11 @@ TEST(RuntimeConfigTest, ReadsTypedRuntimeValues) {
   EXPECT_EQ(config.discord_rpc().join_button_label, "Play Together");
   EXPECT_EQ(config.discord_rpc().application_id, "123456789012345678");
   EXPECT_EQ(config.discord_rpc().text.playing, "In {place_name}");
+  EXPECT_EQ(config.discord_rpc().text.title, "Nightcap");
+  EXPECT_TRUE(config.discord_rpc().images.large.empty());
+  EXPECT_EQ(config.discord_rpc().images.large_text, "{place_name}");
+  EXPECT_EQ(config.discord_rpc().images.small, "linux");
+  EXPECT_EQ(config.discord_rpc().images.small_text, "On Linux");
   EXPECT_TRUE(config.discord_rpc_valid());
 }
 

tests/summarize_profile_trace_test.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+# Copyright 2026 Mocktail Project Authors
+# Licensed under the Apache License, Version 2.0.
+
+from __future__ import annotations
+
+import contextlib
+import importlib.util
+import io
+import json
+from pathlib import Path
+import sys
+import tempfile
+import unittest
+
+
+SCRIPT = Path(__file__).parents[1] / "scripts/summarize_profile_trace.py"
+SPEC = importlib.util.spec_from_file_location("summarize_profile_trace",
+                                              SCRIPT)
+assert SPEC is not None and SPEC.loader is not None
+summary = importlib.util.module_from_spec(SPEC)
+# Dataclasses resolve their module through sys.modules.
+sys.modules[SPEC.name] = summary
+SPEC.loader.exec_module(summary)
+
+
+def frame(ts_us: int, interval_ms: float) -> dict:
+    return {"name": "frame interval (ms)", "ph": "C", "ts": ts_us,
+            "pid": 1, "tid": 1, "args": {"value": interval_ms}}
+
+
+def slice_event(name: str, dur_us: int, ts_us: int = 0) -> dict:
+    return {"name": name, "cat": "test", "ph": "X", "ts": ts_us,
+            "dur": dur_us, "pid": 1, "tid": 1}
+
+
+class SummarizeTest(unittest.TestCase):
+
+    def test_frame_interval_percentiles_use_nearest_rank(self) -> None:
+        events = [frame(index, float(index)) for index in range(1, 101)]
+
+        result = summary.summarize(events)
+
+        frames = result.frames
+        self.assertEqual(frames.count, 100)
+        self.assertAlmostEqual(frames.mean, 50.5)
+        self.assertEqual(frames.p50, 50.0)
+        self.assertEqual(frames.p95, 95.0)
+        self.assertEqual(frames.p99, 99.0)
+        self.assertEqual(frames.max, 100.0)
+
+    def test_slices_are_grouped_by_name_in_milliseconds(self) -> None:
+        events = [
+            slice_event("vkQueuePresentKHR", 2_000),
+            slice_event("vkQueuePresentKHR", 4_000),
+            slice_event("vkCreateGraphicsPipelines", 30_000),
+        ]
+
+        result = summary.summarize(events)
+
+        present = result.slices["vkQueuePresentKHR"]
+        self.assertEqual(present.count, 2)
+        self.assertAlmostEqual(present.total, 6.0)
+        self.assertAlmostEqual(present.mean, 3.0)
+        self.assertAlmostEqual(present.max, 4.0)
+        self.assertEqual(result.slices["vkCreateGraphicsPipelines"].count, 1)
+
+    def test_other_events_are_ignored(self) -> None:
+        events = [
+            {"name": "thread", "ph": "M", "ts": 0, "pid": 1, "tid": 1},
+            {"name": "other counter", "ph": "C", "ts": 0, "pid": 1, "tid": 1,
+             "args": {"value": 5.0}},
+        ]
+
+        result = summary.summarize(events)
+
+        self.assertIsNone(result.frames)
+        self.assertEqual(result.slices, {})
+
+    def test_markdown_puts_each_trace_in_its_own_column(self) -> None:
+        before = summary.summarize([frame(1, 20.0), slice_event("a", 1_000)])
+        after = summary.summarize([frame(1, 10.0), slice_event("a", 500)])
+
+        table = summary.to_markdown([("before.json", before),
+                                     ("after.json", after)])
+
+        lines = table.splitlines()
+        self.assertEqual(lines[0], "| metric | before.json | after.json |")
+        self.assertIn("| frame interval p50 (ms) | 20.00 | 10.00 |", lines)
+        self.assertIn("| a mean (ms) | 1.00 | 0.50 |", lines)
+
+    def test_markdown_marks_missing_values(self) -> None:
+        with_slice = summary.summarize([slice_event("a", 1_000)])
+        without = summary.summarize([])
+
+        table = summary.to_markdown([("one", with_slice), ("two", without)])
+
+        self.assertIn("| a count | 1 | - |", table.splitlines())
+        self.assertIn("| frames | - | - |", table.splitlines())
+
+    def test_main_reads_trace_files(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "trace.json"
+            path.write_text(json.dumps([frame(1, 16.0),
+                                        slice_event("b", 2_000)]))
+            output = io.StringIO()
+
+            with contextlib.redirect_stdout(output):
+                code = summary.main([str(path)])
+
+        self.assertEqual(code, 0)
+        self.assertIn("| frame interval p99 (ms) | 16.00 |",
+                      output.getvalue())
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/texture_override_test.cc

@@ -98,6 +98,56 @@ TEST(TextureOverrideTest, ResampleAveragesSourceBoxes) {
   }
 }
 
+// Rounded mean of the source box [x*sw/w, (x+1)*sw/w) per axis, at least one
+// texel wide.
+std::vector<std::uint8_t> ReferenceBoxResample(const RgbaImage& source,
+                                               std::uint32_t width,
+                                               std::uint32_t height) {
+  std::vector<std::uint8_t> out(static_cast<std::size_t>(width) * height * 4);
+  const auto span = [](std::uint32_t i, std::uint32_t from, std::uint32_t to) {
+    const std::uint64_t first = static_cast<std::uint64_t>(i) * from / to;
+    const std::uint64_t last =
+        std::max<std::uint64_t>(first + 1, (i + 1ULL) * from / to);
+    return std::pair{first, last};
+  };
+  for (std::uint32_t y = 0; y < height; ++y) {
+    const auto [y0, y1] = span(y, source.height, height);
+    for (std::uint32_t x = 0; x < width; ++x) {
+      const auto [x0, x1] = span(x, source.width, width);
+      for (int channel = 0; channel < 4; ++channel) {
+        std::uint64_t sum = 0;
+        for (std::uint64_t sy = y0; sy < y1; ++sy) {
+          for (std::uint64_t sx = x0; sx < x1; ++sx) {
+            sum += source.pixels[(sy * source.width + sx) * 4 + channel];
+          }
+        }
+        const std::uint64_t count = (y1 - y0) * (x1 - x0);
+        out[(static_cast<std::size_t>(y) * width + x) * 4 + channel] =
+            static_cast<std::uint8_t>((sum + count / 2) / count);
+      }
+    }
+  }
+  return out;
+}
+
+TEST(TextureOverrideTest, ResampleMatchesBoxFilterForMixedSizes) {
+  const std::pair<std::uint32_t, std::uint32_t> sources[] = {
+      {1, 1}, {3, 5}, {48, 48}, {60, 33}, {64, 17}};
+  const std::pair<std::uint32_t, std::uint32_t> targets[] = {
+      {1, 1}, {2, 7}, {5, 3}, {48, 48}, {192, 192}, {240, 132}, {31, 200}};
+  for (const auto& [source_width, source_height] : sources) {
+    const RgbaImage source = Gradient(source_width, source_height);
+    for (const auto& [width, height] : targets) {
+      std::vector<std::uint8_t> actual(
+          static_cast<std::size_t>(width) * height * 4, 0);
+      ResampleRgba(source, width, height, actual.data());
+      ASSERT_EQ(actual, ReferenceBoxResample(source, width, height))
+          << source_width << "x" << source_height << " -> " << width << "x"
+          << height;
+    }
+  }
+}
+
 TEST(TextureOverrideTest, LookupFindsPngNamedByHashAndCachesMisses) {
   TempDir dir;
   ASSERT_FALSE(dir.path().empty());

tests/vulkan_etc2_emulation_test.cc

@@ -127,6 +127,10 @@ VkExtent3D g_copied_extent{};
 VkDeviceSize g_created_buffer_size = 0;
 std::uintptr_t g_next_image = 0x100;
 std::uint32_t g_copy_image_calls = 0;
+std::uint32_t g_create_buffer_calls = 0;
+std::uint32_t g_allocate_memory_calls = 0;
+std::uint32_t g_destroy_buffer_calls = 0;
+std::uint32_t g_free_memory_calls = 0;
 VkImageBlit g_blit{};
 VkFilter g_blit_filter = VK_FILTER_NEAREST;
 
@@ -159,6 +163,7 @@ VKAPI_ATTR VkResult VKAPI_CALL FakeCreateBuffer(VkDevice,
                                                 const VkAllocationCallbacks*,
                                                 VkBuffer* buffer) {
   g_created_buffer_size = info->size;
+  ++g_create_buffer_calls;
   *buffer = FakeHandle<VkBuffer>(kStagingBuffer);
   return VK_SUCCESS;
 }
@@ -173,6 +178,7 @@ VKAPI_ATTR VkResult VKAPI_CALL FakeAllocateMemory(
     VkDevice, const VkMemoryAllocateInfo*, const VkAllocationCallbacks*,
     VkDeviceMemory* memory) {
   *memory = FakeHandle<VkDeviceMemory>(kStagingMemory);
+  ++g_allocate_memory_calls;
   return VK_SUCCESS;
 }
 
@@ -193,9 +199,13 @@ VKAPI_ATTR VkResult VKAPI_CALL FakeMapMemory(VkDevice, VkDeviceMemory memory,
 
 VKAPI_ATTR void VKAPI_CALL FakeUnmapMemory(VkDevice, VkDeviceMemory) {}
 VKAPI_ATTR void VKAPI_CALL FakeDestroyBuffer(VkDevice, VkBuffer,
-                                             const VkAllocationCallbacks*) {}
+                                             const VkAllocationCallbacks*) {
+  ++g_destroy_buffer_calls;
+}
 VKAPI_ATTR void VKAPI_CALL FakeFreeMemory(VkDevice, VkDeviceMemory,
-                                          const VkAllocationCallbacks*) {}
+                                          const VkAllocationCallbacks*) {
+  ++g_free_memory_calls;
+}
 VKAPI_ATTR void VKAPI_CALL FakeCopyBufferToImage(
     VkCommandBuffer, VkBuffer, VkImage, VkImageLayout, std::uint32_t count,
     const VkBufferImageCopy* regions) {
@@ -528,6 +538,135 @@ TEST(VulkanEtc2EmulationTest, FillsScaledMipsFromLevelZero) {
   emulation.ReleaseCommandBuffer(command_buffer);
 }
 
+// Level 0 carries the texels every scaled mip is built from, so a mip
+// recorded ahead of it must still resolve against it.
+TEST(VulkanEtc2EmulationTest, FillsScaledMipsFromLevelZeroRecordedLast) {
+  const VkDevice device = FakeHandle<VkDevice>(0x16);
+  const VkBuffer source = FakeHandle<VkBuffer>(0x206);
+  const VkDeviceMemory source_memory = FakeHandle<VkDeviceMemory>(kSourceMemory);
+  const VkCommandBuffer command_buffer = FakeHandle<VkCommandBuffer>(0x706);
+  g_source.fill(0);
+  g_staging.fill(0xAA);
+  ASSERT_EQ(setenv("MOCKTAIL_SMALL_TEXTURE_UPSCALE", "2", 1), 0);
+
+  VkPhysicalDeviceMemoryProperties memory{};
+  memory.memoryTypeCount = 1;
+  memory.memoryTypes[0].propertyFlags = VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT |
+                                        VK_MEMORY_PROPERTY_HOST_COHERENT_BIT;
+  VulkanEtc2Emulation emulation;
+  ASSERT_EQ(unsetenv("MOCKTAIL_SMALL_TEXTURE_UPSCALE"), 0);
+  emulation.RegisterDevice(device, FakeHandle<VkPhysicalDevice>(0x26), true,
+                           memory, FakeGetDeviceProcAddr);
+
+  VkImageCreateInfo image_info{};
+  image_info.sType = VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO;
+  image_info.format = VK_FORMAT_ETC2_R8G8B8_UNORM_BLOCK;
+  image_info.imageType = VK_IMAGE_TYPE_2D;
+  image_info.extent = {4, 4, 1};
+  image_info.mipLevels = 3;
+  image_info.arrayLayers = 1;
+  VkImage image = VK_NULL_HANDLE;
+  ASSERT_EQ(emulation.CreateImage(device, &image_info, nullptr, &image),
+            VK_SUCCESS);
+  ASSERT_EQ(emulation.BindBufferMemory(device, source, source_memory, 0),
+            VK_SUCCESS);
+  void* mapped = nullptr;
+  ASSERT_EQ(emulation.MapMemory(device, source_memory, 0, g_source.size(), 0,
+                                &mapped),
+            VK_SUCCESS);
+
+  const std::array<std::uint8_t, 8> level0 = {0x81, 0x81, 0x81, 0x02,
+                                              0,    0,    0,    0};
+  const std::array<std::uint8_t, 8> level1 = {0x88, 0x88, 0x88, 0x00,
+                                              0,    0,    0,    0};
+  std::memcpy(g_source.data(), level0.data(), level0.size());
+  std::memcpy(g_source.data() + 8, level1.data(), level1.size());
+
+  // Level 1 is recorded first, so its staging bytes lead the batch.
+  std::array<VkBufferImageCopy, 2> regions{};
+  regions[0].imageSubresource.aspectMask = VK_IMAGE_ASPECT_COLOR_BIT;
+  regions[0].imageSubresource.layerCount = 1;
+  regions[0].bufferOffset = 8;
+  regions[0].imageSubresource.mipLevel = 1;
+  regions[0].imageExtent = {2, 2, 1};
+  regions[1] = regions[0];
+  regions[1].bufferOffset = 0;
+  regions[1].imageSubresource.mipLevel = 0;
+  regions[1].imageExtent = {4, 4, 1};
+  emulation.CmdCopyBufferToImage(device, command_buffer, source, image,
+                                 VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 2,
+                                 regions.data());
+  emulation.PrepareSubmit(&command_buffer, 1);
+
+  RgbaImage level0_texels;
+  level0_texels.width = 4;
+  level0_texels.height = 4;
+  level0_texels.pixels.resize(4 * 4 * 4);
+  ASSERT_TRUE(DecodeEtcImage(EtcFormat::kEtc2Rgb8, level0.data(),
+                             level0.size(), 4, 4, level0_texels.pixels.data(),
+                             level0_texels.pixels.size()));
+  std::array<std::uint8_t, 4 * 4 * 4> expected{};
+  ResampleRgba(level0_texels, 4, 4, expected.data());
+  for (std::size_t index = 0; index < expected.size(); ++index) {
+    ASSERT_EQ(g_staging[index], expected[index]) << index;
+  }
+  emulation.ReleaseCommandBuffer(command_buffer);
+}
+
+TEST(VulkanEtc2EmulationTest, ReusesStagingBuffersAcrossCommandBuffers) {
+  const VkDevice device = FakeHandle<VkDevice>(0x17);
+  const VkBuffer source = FakeHandle<VkBuffer>(0x207);
+  const VkDeviceMemory source_memory = FakeHandle<VkDeviceMemory>(kSourceMemory);
+  g_source.fill(0);
+
+  VkPhysicalDeviceMemoryProperties memory{};
+  memory.memoryTypeCount = 1;
+  memory.memoryTypes[0].propertyFlags = VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT |
+                                        VK_MEMORY_PROPERTY_HOST_COHERENT_BIT;
+  VulkanEtc2Emulation emulation;
+  emulation.RegisterDevice(device, FakeHandle<VkPhysicalDevice>(0x27), true,
+                           memory, FakeGetDeviceProcAddr);
+
+  VkImageCreateInfo image_info{};
+  image_info.sType = VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO;
+  image_info.format = VK_FORMAT_ETC2_R8G8B8_UNORM_BLOCK;
+  image_info.extent = {4, 4, 1};
+  VkImage image = VK_NULL_HANDLE;
+  ASSERT_EQ(emulation.CreateImage(device, &image_info, nullptr, &image),
+            VK_SUCCESS);
+  ASSERT_EQ(emulation.BindBufferMemory(device, source, source_memory, 0),
+            VK_SUCCESS);
+  void* mapped = nullptr;
+  ASSERT_EQ(emulation.MapMemory(device, source_memory, 0, g_source.size(), 0,
+                                &mapped),
+            VK_SUCCESS);
+
+  g_create_buffer_calls = 0;
+  g_allocate_memory_calls = 0;
+  g_destroy_buffer_calls = 0;
+  g_free_memory_calls = 0;
+  VkBufferImageCopy region{};
+  region.imageSubresource.aspectMask = VK_IMAGE_ASPECT_COLOR_BIT;
+  region.imageSubresource.layerCount = 1;
+  region.imageExtent = {4, 4, 1};
+  for (std::uintptr_t frame = 0; frame < 8; ++frame) {
+    const VkCommandBuffer command_buffer =
+        FakeHandle<VkCommandBuffer>(0x780 + frame);
+    emulation.CmdCopyBufferToImage(device, command_buffer, source, image,
+                                   VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 1,
+                                   &region);
+    emulation.PrepareSubmit(&command_buffer, 1);
+    emulation.ReleaseCommandBuffer(command_buffer);
+  }
+  EXPECT_EQ(g_create_buffer_calls, 1u);
+  EXPECT_EQ(g_allocate_memory_calls, 1u);
+  EXPECT_EQ(g_destroy_buffer_calls, 0u);
+
+  emulation.DestroyDevice(device);
+  EXPECT_EQ(g_destroy_buffer_calls, 1u);
+  EXPECT_EQ(g_free_memory_calls, 1u);
+}
+
 // Copies out of a scaled image cover its host bounds and shrink back onto
 // an unscaled destination, which a plain copy cannot do.
 TEST(VulkanEtc2EmulationTest, BlitsCopiesThatTouchScaledImages) {
@@ -591,5 +730,80 @@ TEST(VulkanEtc2EmulationTest, BlitsCopiesThatTouchScaledImages) {
   EXPECT_EQ(g_copy_image_calls, 1u);
 }
 
+// bufferRowLength counts texels of source pitch, not of the copied region, so
+// a padded row holds blocks the region does not cover.
+TEST(VulkanEtc2EmulationTest, ReadsCompressedRowsAtTheRequestedStride) {
+  const VkDevice device = FakeHandle<VkDevice>(0x18);
+  const VkBuffer source = FakeHandle<VkBuffer>(0x208);
+  const VkDeviceMemory source_memory = FakeHandle<VkDeviceMemory>(kSourceMemory);
+  const VkCommandBuffer command_buffer = FakeHandle<VkCommandBuffer>(0x708);
+  g_source.fill(0);
+  g_staging.fill(0xAA);
+  ASSERT_EQ(setenv("MOCKTAIL_SMALL_TEXTURE_UPSCALE", "1", 1), 0);
+
+  VkPhysicalDeviceMemoryProperties memory{};
+  memory.memoryTypeCount = 1;
+  memory.memoryTypes[0].propertyFlags = VK_MEMORY_PROPERTY_HOST_VISIBLE_BIT |
+                                        VK_MEMORY_PROPERTY_HOST_COHERENT_BIT;
+  VulkanEtc2Emulation emulation;
+  ASSERT_EQ(unsetenv("MOCKTAIL_SMALL_TEXTURE_UPSCALE"), 0);
+  emulation.RegisterDevice(device, FakeHandle<VkPhysicalDevice>(0x28), true,
+                           memory, FakeGetDeviceProcAddr);
+
+  VkImageCreateInfo image_info{};
+  image_info.sType = VK_STRUCTURE_TYPE_IMAGE_CREATE_INFO;
+  image_info.format = VK_FORMAT_ETC2_R8G8B8_UNORM_BLOCK;
+  image_info.imageType = VK_IMAGE_TYPE_2D;
+  image_info.extent = {8, 8, 1};
+  image_info.mipLevels = 1;
+  image_info.arrayLayers = 1;
+  VkImage image = VK_NULL_HANDLE;
+  ASSERT_EQ(emulation.CreateImage(device, &image_info, nullptr, &image),
+            VK_SUCCESS);
+  ASSERT_EQ(g_created_extent.width, 8u);
+  ASSERT_EQ(emulation.BindBufferMemory(device, source, source_memory, 0),
+            VK_SUCCESS);
+  void* mapped = nullptr;
+  ASSERT_EQ(emulation.MapMemory(device, source_memory, 0, g_source.size(), 0,
+                                &mapped),
+            VK_SUCCESS);
+
+  // Differential block: every texel decodes to 134.
+  const std::array<std::uint8_t, 8> covered = {0x81, 0x81, 0x81, 0x02,
+                                               0,    0,    0,    0};
+  // Individual block: every texel decodes to 138.
+  const std::array<std::uint8_t, 8> padding = {0x88, 0x88, 0x88, 0x00,
+                                               0,    0,    0,    0};
+  // 16 texels of pitch is 4 blocks per row; the 8x8 region covers the first 2.
+  const std::array<const std::uint8_t*, 6> layout = {
+      covered.data(), covered.data(), padding.data(),
+      padding.data(), covered.data(), covered.data()};
+  for (std::size_t block = 0; block < layout.size(); ++block) {
+    std::memcpy(g_source.data() + block * 8, layout[block], 8);
+  }
+
+  VkBufferImageCopy region{};
+  region.imageSubresource.aspectMask = VK_IMAGE_ASPECT_COLOR_BIT;
+  region.imageSubresource.layerCount = 1;
+  region.imageExtent = {8, 8, 1};
+  region.bufferRowLength = 16;
+  emulation.CmdCopyBufferToImage(device, command_buffer, source, image,
+                                 VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 1,
+                                 &region);
+  emulation.PrepareSubmit(&command_buffer, 1);
+
+  std::array<std::uint8_t, 32> packed{};
+  for (std::size_t block = 0; block < 4; ++block) {
+    std::memcpy(packed.data() + block * 8, covered.data(), covered.size());
+  }
+  std::array<std::uint8_t, 8 * 8 * 4> expected{};
+  ASSERT_TRUE(DecodeEtcImage(EtcFormat::kEtc2Rgb8, packed.data(), packed.size(),
+                             8, 8, expected.data(), expected.size()));
+  for (std::size_t index = 0; index < expected.size(); ++index) {
+    ASSERT_EQ(g_staging[index], expected[index]) << "byte " << index;
+  }
+  emulation.ReleaseCommandBuffer(command_buffer);
+}
+
 }  // namespace
 }  // namespace mocktail::graphics

textures/README.md

@@ -0,0 +1,42 @@
+# Texture overrides
+
+Optional PNGs you can drop into your own override directory. Nothing here is
+installed or loaded automatically.
+
+## Using one
+
+Copy the file into the override directory, keeping its name:
+
+```sh
+mkdir -p ~/.config/mocktail/textures
+cp textures/75dcd1166a6cbaa9.png ~/.config/mocktail/textures/
+```
+
+Restart the game. The log line `[vulkan] texture override loaded: <path>`
+confirms it was picked up.
+
+To remove it, delete the file again.
+
+`MOCKTAIL_TEXTURE_OVERRIDE_DIR` points the lookup somewhere else.
+
+## What is here
+
+| File | Replaces |
+| --- | --- |
+| `75dcd1166a6cbaa9.png` | The in-game crosshair, as a thin dot-and-ticks reticle (128x128). |
+
+## Naming
+
+The file name is the 16 hex digit FNV-1a hash of the texture's level-0
+compressed ETC2 bytes, which is what the override lookup keys on. A texture
+Roblox re-encodes gets a new hash, so an override can stop matching after a
+client update.
+
+To find the hash of a texture you want to replace, set
+`MOCKTAIL_TEXTURE_DUMP_DIR` to an empty directory and play until the texture
+appears. Every uploaded texture is written there once as
+`<hash>_<width>x<height>.png`. Rename the one you want to `<hash>.png` and put
+it in the override directory.
+
+Overrides are resampled to the size the game asked for, so the replacement does
+not have to match the original's dimensions.